id: https://nde.nl/ontology/hc/class/VideoChapter name: video_chapter_class title: Video Chapter Class imports: - linkml:types - ./VideoTimeSegment - ../slots/specificity_annotation - ./SpecificityAnnotation - ../slots/template_specificity - ./TemplateSpecificityScores # Enum imports - ../enums/ChapterSourceEnum # Slot imports - ../slots/auto_generated - ../slots/chapter_description - ../slots/chapter_end_seconds - ../slots/chapter_end_time - ../slots/chapter_id - ../slots/chapter_index - ../slots/chapter_source - ../slots/chapter_start_seconds - ../slots/chapter_start_time - ../slots/chapter_thumbnail_timestamp - ../slots/chapter_thumbnail_url - ../slots/chapter_title - ../slots/nesting_level - ../slots/parent_chapter_id prefixes: linkml: https://w3id.org/linkml/ hc: https://nde.nl/ontology/hc/ schema: http://schema.org/ dcterms: http://purl.org/dc/terms/ prov: http://www.w3.org/ns/prov# crm: http://www.cidoc-crm.org/cidoc-crm/ oa: http://www.w3.org/ns/oa# ma: http://www.w3.org/ns/ma-ont# wd: http://www.wikidata.org/entity/ default_prefix: hc classes: VideoChapter: class_uri: schema:Clip abstract: false description: | A named chapter or section within a video, defined by temporal boundaries. **DEFINITION**: VideoChapter represents a titled segment of video content, typically used for navigation and content organization. Chapters appear in video player interfaces (YouTube chapters, Vimeo chapters) allowing viewers to jump to specific sections. **PLATFORM SUPPORT**: | Platform | Chapter Support | Auto-Generated | Custom Thumbnails | |----------|-----------------|----------------|-------------------| | YouTube | Yes (2020+) | Yes | No (keyframe) | | Vimeo | Yes | No | Yes | | Facebook | Limited | No | No | | Wistia | Yes | No | Yes | **YOUTUBE CHAPTER REQUIREMENTS**: For YouTube to recognize chapters: - First chapter MUST start at 0:00 - Minimum 3 chapters required - Each chapter must be at least 10 seconds - Timestamps in description in `MM:SS` or `HH:MM:SS` format **HERITAGE INSTITUTION USE CASES**: | Content Type | Chapter Examples | |--------------|------------------| | Virtual tour | "Main Hall", "Dutch Masters", "Gift Shop" | | Conservation | "Assessment", "Cleaning", "Retouching", "Varnishing" | | Interview | "Introduction", "Early Career", "Major Works", "Legacy" | | Exhibition | "Curator Introduction", "Theme 1", "Theme 2", "Conclusion" | | Lecture | "Overview", "Case Study 1", "Case Study 2", "Q&A" | **AUTO-GENERATED VS MANUAL CHAPTERS**: | Source | Characteristics | Quality | |--------|-----------------|---------| | Manual (creator) | Semantic, meaningful titles | High | | YouTube AI | Scene-based, generic titles | Variable | | Third-party tools | Transcript-based, keyword titles | Medium | The `auto_generated` flag distinguishes these sources. **RELATIONSHIP TO VideoTimeSegment**: VideoChapter USES VideoTimeSegment for temporal boundaries rather than extending it. This composition pattern allows: - Reuse of segment validation (start < end) - Consistent time representation across schema - Separation of structural (chapter) and temporal (segment) concerns **MEDIA FRAGMENTS URI**: Chapters can be addressed via W3C Media Fragments: ``` https://youtube.com/watch?v=ABC123#t=120,300 ``` Corresponds to chapter starting at 2:00, ending at 5:00. **NESTED CHAPTERS**: Some platforms support hierarchical chapters (parent/child). Use `parent_chapter_id` for nested structure: ``` Chapter 1: Dutch Golden Age └─ 1.1: Rembrandt └─ 1.2: Vermeer Chapter 2: Modern Art ``` exact_mappings: - schema:Clip close_mappings: - ma:MediaFragment - crm:E52_Time-Span related_mappings: - wikidata:Q1454986 slots: - auto_generated - chapter_description - chapter_end_seconds - chapter_end_time - chapter_id - chapter_index - chapter_source - chapter_start_seconds - chapter_start_time - chapter_thumbnail_timestamp - chapter_thumbnail_url - chapter_title - nesting_level - parent_chapter_id - specificity_annotation - template_specificity slot_usage: chapter_id: slot_uri: dcterms:identifier description: | Unique identifier for this chapter. Dublin Core: identifier for unique identification. **Format**: Platform-specific or UUID - YouTube: No native chapter ID (use index) - Generated: `{video_id}_chapter_{index}` range: string required: true examples: - value: ABC123_chapter_0 description: First chapter of video ABC123 - value: 550e8400-e29b-41d4-a716-446655440000 description: UUID-based chapter ID chapter_title: slot_uri: schema:name description: | Title of the chapter as displayed to viewers. Schema.org: name for the chapter's title. **Best Practices**: - Keep titles concise (under 50 characters) - Use descriptive, meaningful titles - Avoid timestamps in title (redundant) **Auto-Generated Titles**: - YouTube AI: Often generic ("Introduction", "Main Content") - May need manual refinement for heritage content range: string required: true examples: - value: De Nachtwacht (The Night Watch) description: Chapter about specific artwork - value: 'Curator Interview: Conservation Process' description: Interview segment chapter chapter_index: slot_uri: hc:chapterIndex description: | Zero-based index of this chapter within the video. **Ordering**: - 0: First chapter (typically starts at 0:00) - Subsequent chapters in temporal order Used for: - Reconstruction of chapter sequence - Navigation (previous/next) - Display ordering range: integer required: true minimum_value: 0 examples: - value: 0 description: First chapter - value: 5 description: Sixth chapter (zero-indexed) chapter_description: slot_uri: schema:description description: | Optional detailed description of chapter content. Schema.org: description for chapter details. Longer-form description than title. May include: - Topics covered - Featured artworks - Key points discussed Not all platforms display chapter descriptions. range: string required: false examples: - value: Dr. Dibbits discusses the restoration of Rembrandt's masterpiece, including the controversial 2019 operation. description: Detailed chapter description chapter_start_seconds: slot_uri: ma:hasStartTime description: | Start time of chapter in seconds from video beginning. Media Ontology: hasStartTime for temporal start. **First Chapter Rule**: For YouTube chapters to be recognized, the first chapter MUST start at 0.0 seconds. Floating point for millisecond precision. range: float required: true minimum_value: 0.0 examples: - value: 0.0 description: First chapter starts at video beginning - value: 120.5 description: Chapter starts at 2:00.5 chapter_end_seconds: slot_uri: ma:hasEndTime description: | End time of chapter in seconds from video beginning. Media Ontology: hasEndTime for temporal end. **Chapter Boundaries**: - End time of chapter N = start time of chapter N+1 - Last chapter ends at video duration - No gaps between chapters (continuous coverage) range: float required: false minimum_value: 0.0 examples: - value: 120.0 description: Chapter ends at 2:00 chapter_start_time: slot_uri: hc:chapterStartTime description: | Start time as ISO 8601 duration for display/serialization. Derived from chapter_start_seconds. **Format**: ISO 8601 duration (e.g., "PT2M30S" = 2:30) range: string required: false pattern: ^PT(\d+H)?(\d+M)?(\d+(\.\d+)?S)?$ examples: - value: PT0S description: Start of video - value: PT10M30S description: 10 minutes 30 seconds chapter_end_time: slot_uri: hc:chapterEndTime description: | End time as ISO 8601 duration for display/serialization. Derived from chapter_end_seconds. range: string required: false pattern: ^PT(\d+H)?(\d+M)?(\d+(\.\d+)?S)?$ examples: - value: PT5M0S description: 5 minutes is_auto_generated: slot_uri: hc:autoGenerated description: | Whether this chapter was auto-generated by AI/ML. **Sources**: - true: YouTube AI chapters, third-party tools, ASR-based - false: Manual creator-defined chapters Auto-generated chapters may have: - Generic titles - Less semantic meaning - Scene-based rather than topic-based boundaries range: boolean required: false examples: - value: false description: Manual creator-defined chapter - value: true description: YouTube AI auto-generated chapter_source: slot_uri: prov:wasAttributedTo description: | Source or method that created this chapter. PROV-O: wasAttributedTo for attribution. **Common Values**: - MANUAL: Creator-defined in video description - YOUTUBE_AI: YouTube auto-chapters feature - WHISPER_CHAPTERS: Generated from Whisper transcript - SCENE_DETECTION: Based on visual scene changes - THIRD_PARTY: External tool (specify in notes) range: ChapterSourceEnum required: false examples: - value: MANUAL description: Creator manually added chapters chapter_thumbnail_url: slot_uri: schema:thumbnailUrl description: | URL to thumbnail image for this chapter. Schema.org: thumbnailUrl for preview image. **Platform Behavior**: - YouTube: Auto-selects keyframe from chapter start - Vimeo: Allows custom chapter thumbnails Thumbnail helps viewers preview chapter content. range: uri required: false examples: - value: https://i.ytimg.com/vi/ABC123/hq1.jpg description: YouTube chapter thumbnail chapter_thumbnail_timestamp: slot_uri: hc:thumbnailTimestamp description: | Timestamp (in seconds) of frame used for thumbnail. May differ slightly from chapter_start_seconds if a more visually representative frame was selected. range: float required: false minimum_value: 0.0 examples: - value: 122.5 description: Thumbnail from 2:02.5 parent_chapter_id: slot_uri: dcterms:isPartOf description: | Reference to parent chapter for hierarchical chapters. Dublin Core: isPartOf for containment relationship. Enables nested chapter structure: ``` Chapter 1: Dutch Masters └─ 1.1: Rembrandt └─ 1.2: Vermeer ``` null/empty for top-level chapters. range: string required: false examples: - value: ABC123_chapter_0 description: This is a sub-chapter of chapter 0 nesting_level: slot_uri: hc:nestingLevel description: | Depth level in chapter hierarchy. - 0: Top-level chapter - 1: First-level sub-chapter - 2: Second-level sub-chapter - etc. Most platforms only support level 0 (flat chapters). range: integer required: false minimum_value: 0 examples: - value: 0 description: Top-level chapter - value: 1 description: Sub-chapter specificity_annotation: range: SpecificityAnnotation inlined: true template_specificity: range: TemplateSpecificityScores inlined: true comments: - Models video chapters for navigation (YouTube chapters, etc.) - Supports both manual and auto-generated chapters - Temporal boundaries via composition with VideoTimeSegment pattern - Hierarchical chapters supported via parent_chapter_id - Schema.org Clip alignment for semantic web compatibility see_also: - https://support.google.com/youtube/answer/9884579 - https://schema.org/Clip - https://www.w3.org/TR/media-frags/