# Video Chapter Class
# Models video chapter markers (YouTube chapters, manual/auto-generated sections)
#
# Part of Heritage Custodian Ontology v0.9.10
#
# STRUCTURE:
# VideoChapter (this class)
#     - chapter_title, chapter_index
#     - start/end times (via VideoTimeSegment composition)
#     - auto_generated flag
#     - thumbnail references
#
# USE CASES:
# - YouTube video chapters (manual creator-defined)
# - Auto-generated chapters (YouTube AI, third-party tools)
# - Museum virtual tour sections
# - Conservation documentation phases
# - Interview segments
#
# ONTOLOGY ALIGNMENT:
# - Schema.org Clip for media segments
# - W3C Media Fragments for temporal addressing
# - CIDOC-CRM E52_Time-Span for temporal extent

id: https://nde.nl/ontology/hc/class/VideoChapter
name: video_chapter_class
title: Video Chapter Class

imports:
  - linkml:types
  - ./VideoTimeSegment

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  # Chapter (division of a book/document)
    
    slots:
      # Chapter identification
      - chapter_id
      - chapter_title
      - chapter_index
      - chapter_description
      
      # Temporal boundaries (composition with VideoTimeSegment)
      - chapter_start_seconds
      - chapter_end_seconds
      - chapter_start_time
      - chapter_end_time
      
      # Generation metadata
      - auto_generated
      - chapter_source
      
      # Visual
      - chapter_thumbnail_url
      - chapter_thumbnail_timestamp
      
      # Hierarchy
      - parent_chapter_id
      - nesting_level
    
    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"
      
      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"
    
    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/"


  # ==========================================================================
  # Supporting Class: VideoChapterList
  # ==========================================================================
  
  VideoChapterList:
    class_uri: schema:ItemList
    description: |
      A collection of chapters for a video.
      
      Groups all chapters for a video with metadata about the chapter set.
      
      Enables bulk operations on chapters:
      - Import/export of chapter lists
      - Validation of chapter coverage
      - Source tracking for entire chapter set
    
    exact_mappings:
      - schema:ItemList
    
    slots:
      - video_id
      - chapters
      - total_chapters
      - chapters_source
      - chapters_generated_at
      - covers_full_video
    
    slot_usage:
      video_id:
        slot_uri: schema:isPartOf
        description: Reference to the parent video
        range: string
        required: true
      
      chapters:
        slot_uri: schema:itemListElement
        description: Ordered list of chapters
        range: VideoChapter
        multivalued: true
        required: true
        inlined_as_list: true
      
      total_chapters:
        slot_uri: hc:totalChapters
        description: Total number of chapters
        range: integer
        required: false
        minimum_value: 0
      
      chapters_source:
        slot_uri: prov:wasAttributedTo
        description: Primary source for this chapter list
        range: ChapterSourceEnum
        required: false
      
      chapters_generated_at:
        slot_uri: prov:generatedAtTime
        description: When chapters were generated/extracted
        range: datetime
        required: false
      
      covers_full_video:
        slot_uri: hc:coversFullVideo
        description: |
          Whether chapters cover the entire video duration.
          
          - true: No gaps, first chapter at 0:00, last ends at video end
          - false: Partial coverage (gaps between chapters)
        range: boolean
        required: false

# ============================================================================
# Enumerations
# ============================================================================

enums:
  
  ChapterSourceEnum:
    description: |
      Source or method that created video chapters.
    permissible_values:
      MANUAL:
        description: Creator manually defined chapters in video description
      YOUTUBE_AI:
        description: YouTube auto-chapters feature (AI-generated)
      WHISPER_CHAPTERS:
        description: Generated from Whisper transcript analysis
      SCENE_DETECTION:
        description: Based on visual scene change detection
      TRANSCRIPT_ANALYSIS:
        description: Topic segmentation from transcript
      THIRD_PARTY:
        description: External tool or service
      IMPORTED:
        description: Imported from another platform/format
      UNKNOWN:
        description: Chapter source not determined

# ============================================================================
# Slot Definitions
# ============================================================================

slots:
  chapter_id:
    description: Unique identifier for chapter
    range: string
  
  chapter_title:
    description: Display title of chapter
    range: string
  
  chapter_index:
    description: Zero-based index in chapter sequence
    range: integer
  
  chapter_description:
    description: Detailed description of chapter content
    range: string
  
  chapter_start_seconds:
    description: Start time in seconds
    range: float
  
  chapter_end_seconds:
    description: End time in seconds
    range: float
  
  chapter_start_time:
    description: Start time as ISO 8601 duration
    range: string
  
  chapter_end_time:
    description: End time as ISO 8601 duration
    range: string
  
  auto_generated:
    description: Whether chapter was auto-generated by AI
    range: boolean
  
  chapter_source:
    description: Source that created this chapter
    range: ChapterSourceEnum
  
  chapter_thumbnail_url:
    description: URL to chapter thumbnail image
    range: uri
  
  chapter_thumbnail_timestamp:
    description: Timestamp of thumbnail frame
    range: float
  
  parent_chapter_id:
    description: Reference to parent chapter for nesting
    range: string
  
  nesting_level:
    description: Depth level in chapter hierarchy
    range: integer
  
  # VideoChapterList slots
  video_id:
    description: Reference to parent video
    range: string
  
  chapters:
    description: Ordered list of video chapters
    range: VideoChapter
    multivalued: true
  
  total_chapters:
    description: Total number of chapters
    range: integer
  
  chapters_source:
    description: Primary source for chapter list
    range: ChapterSourceEnum
  
  chapters_generated_at:
    description: When chapters were generated
    range: datetime
  
  covers_full_video:
    description: Whether chapters cover entire video
    range: boolean