id: https://nde.nl/ontology/hc/class/VideoSubtitle
name: video_subtitle_class
title: Video Subtitle Class
imports:
- linkml:types
- ./VideoTranscript
- ./VideoTimeSegment
- ../slots/has_average_entry_duration_seconds
- ../slots/default_position
- ../slots/entry_count
- ../slots/includes_music_description
- ../slots/includes_sound_description
- ../slots/includes_speaker_identification
- ../slots/is_or_was_created_through  # MIGRATED: was ../slots/is_auto_generated (2026-01-15)
- ../slots/is_closed_caption
- ../slots/is_sdh
- ../slots/raw_subtitle_content
- ../slots/specificity_annotation
- ../slots/subtitle_format
- ../slots/template_specificity
- ../slots/has_or_had_identifier  # MIGRATED: was ../slots/track_id (2026-01-14)
- ./TrackIdentifier  # Added for has_or_had_identifier migration
- ../slots/has_or_had_label  # was: track_name - migrated per Rule 53
- ./SpecificityAnnotation
- ./TemplateSpecificityScores
- ./AutoGeneration  # Added for is_or_was_created_through migration (2026-01-15)
- ../enums/SubtitlePositionEnum
- ../enums/SubtitleFormatEnum
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/
  skos: http://www.w3.org/2004/02/skos/core#
  ma: http://www.w3.org/ns/ma-ont#
default_prefix: hc
classes:
  VideoSubtitle:
    is_a: VideoTranscript
    class_uri: hc:VideoSubtitle
    abstract: false
    description: 'Time-coded caption/subtitle content for video.


      **DEFINITION**:


      VideoSubtitle represents caption/subtitle tracks that provide time-coded

      text synchronized with video playback. It extends VideoTranscript because

      subtitles contain complete transcription PLUS temporal synchronization.


      **INHERITANCE FROM VideoTranscript**:


      VideoSubtitle inherits all transcript capabilities:

      - `full_text`: Complete subtitle text concatenated

      - `segments`: Time-coded entries (REQUIRED for subtitles)

      - `includes_timestamps`: Always true for subtitles

      - `content_language`: Language of subtitle text

      - All provenance from VideoTextContent


      And adds subtitle-specific properties:

      - `subtitle_format`: SRT, VTT, TTML, SBV, ASS

      - `is_closed_caption`: CC vs regular subtitles

      - `is_sdh`: Subtitles for Deaf/Hard-of-Hearing

      - `includes_sound_descriptions`: Non-speech audio descriptions


      **SCHEMA.ORG ALIGNMENT**:


      Maps to `schema:caption` property:

      > "For downloadable machine formats (closed caption, subtitles etc.)

      >  use the MediaObject.encodingFormat property."


      **SUBTITLE vs CAPTION vs TRANSCRIPT**:


      | Type | Time-coded | Purpose | Audience |

      |------|------------|---------|----------|

      | Transcript | Optional | Reading, search | Everyone |

      | Subtitle | Required | Language translation | Hearing viewers |

      | Caption (CC) | Required | Accessibility | Deaf/HoH viewers |

      | SDH | Required | Full accessibility | Deaf viewers, noisy environments |


      **SDH (Subtitles for Deaf/Hard-of-Hearing)**:


      SDH differs from regular subtitles by including:

      - Speaker identification: "(John) Hello"

      - Sound effects: "[door slams]", "[music playing]"

      - Music descriptions: "♪ upbeat jazz ♪"

      - Emotional cues: "[laughing]", "[whispering]"


      **SUBTITLE FORMATS**:


      | Format | Extension | Features | Use Case |

      |--------|-----------|----------|----------|

      | SRT | .srt | Simple, universal | Most video players |

      | VTT | .vtt | W3C standard, styling | HTML5 video, web |

      | TTML | .ttml/.dfxp | XML, rich styling | Broadcast, streaming |

      | SBV | .sbv | YouTube native | YouTube uploads |

      | ASS | .ass | Advanced styling | Anime, complex layouts |


      **SRT FORMAT EXAMPLE**:


      ```

      1

      00:00:00,000 --> 00:00:03,500

      Welcome to the Rijksmuseum.


      2

      00:00:03,500 --> 00:00:08,200

      Today we''ll explore the Night Watch gallery.

      ```


      **VTT FORMAT EXAMPLE**:


      ```

      WEBVTT


      00:00:00.000 --> 00:00:03.500

      Welcome to the Rijksmuseum.


      00:00:03.500 --> 00:00:08.200

      Today we''ll explore the Night Watch gallery.

      ```


      **HERITAGE INSTITUTION CONTEXT**:


      Subtitles are critical for heritage video accessibility:


      1. **Accessibility Compliance**: WCAG 2.1, Section 508

      2. **Multilingual Access**: Translate for international audiences

      3. **Silent Viewing**: Social media, public displays, quiet spaces

      4. **Search Discovery**: Subtitle text is indexed by platforms

      5. **Preservation**: Text outlasts video format obsolescence


      **YOUTUBE API INTEGRATION**:


      Subtitle tracks from YouTube API populate:

      - `subtitle_format`: Typically VTT or SRT

      - `generation_method`: PLATFORM_PROVIDED or ASR_AUTOMATIC

      - `content_language`: From track language code

      - `is_or_was_created_through`: YouTube auto-caption flag


      **SEGMENTS ARE REQUIRED**:


      Unlike VideoTranscript where segments are optional, VideoSubtitle

      REQUIRES the `segments` slot to be populated with VideoTimeSegment

      entries that include start_seconds, end_seconds, and segment_text.

      '
    exact_mappings:
    - schema:caption
    close_mappings:
    - ma:CaptioningFormat
    related_mappings:
    - schema:transcript
    slots:
    - has_average_entry_duration_seconds
    - default_position
    - entry_count
    - includes_music_description
    - includes_sound_description
    - includes_speaker_identification
    - is_or_was_created_through  # MIGRATED: was is_auto_generated (2026-01-15)
    - is_closed_caption
    - is_sdh
    - raw_subtitle_content
    - specificity_annotation
    - subtitle_format
    - template_specificity
    - has_or_had_identifier  # MIGRATED: was track_id (2026-01-14)
    - has_or_had_label  # was: track_name
    slot_usage:
      has_or_had_segment:
        required: true
      includes_timestamp:
        ifabsent: 'true'
      subtitle_format:
        range: SubtitleFormatEnum
        required: true
        examples:
        - value: VTT
          description: WebVTT format (W3C standard)
        - value: SRT
          description: SubRip format (most common)
      raw_subtitle_content:
        range: string
        required: false
        examples:
        - value: 'WEBVTT


            00:00:00.000 --> 00:00:03.500

            Welcome to the museum.

            '
          description: Complete VTT file content
      is_closed_caption:
        range: boolean
        required: false
        ifabsent: 'false'
        examples:
        - value: true
          description: This is a closed caption track
      is_sdh:
        range: boolean
        required: false
        ifabsent: 'false'
        examples:
        - value: true
          description: SDH subtitle track
      includes_sound_description:
        range: boolean
        required: false
        ifabsent: 'false'
        examples:
        - value: true
          description: Contains sound effect descriptions
      includes_music_description:
        range: boolean
        required: false
        ifabsent: 'false'
        examples:
        - value: true
          description: Contains music descriptions
      includes_speaker_identification:
        range: boolean
        required: false
        ifabsent: 'false'
        examples:
        - value: true
          description: Subtitle text includes speaker labels
      is_or_was_created_through:  # MIGRATED: was is_auto_generated (2026-01-15)
        description: Whether this subtitle was auto-generated (e.g., YouTube ASR)
        range: boolean
        required: false
        ifabsent: 'false'
        examples:
        - value: true
          description: YouTube auto-generated caption
      has_or_had_label:  # was: track_name
        range: string
        required: false
        examples:
        - value: English (auto-generated)
          description: YouTube auto-caption track name
      track_id:
        description: Platform-specific identifier for this subtitle track (DEPRECATED - use has_or_had_identifier)
        range: string
        deprecated: "Use has_or_had_identifier with TrackIdentifier range instead"
        required: false
        examples:
        - value: en.3OWxR1w4QfE
          description: YouTube caption track ID
      has_or_had_identifier:  # MIGRATED from track_id (2026-01-14)
        description: Platform-specific identifier for this subtitle track
        range: TrackIdentifier
        required: false
        inlined: true
        examples:
        - value: '{"platform": "YouTube", "has_or_had_code": "en.3OWxR1w4QfE"}'
          description: YouTube caption track identifier
      default_position:
        range: SubtitlePositionEnum
        required: false
        ifabsent: string(BOTTOM)
        examples:
        - value: BOTTOM
          description: Standard bottom caption position
      entry_count:
        range: integer
        required: false
        minimum_value: 0
        examples:
        - value: 127
          description: 127 caption cues in this track
      has_average_entry_duration_seconds:
        range: float
        required: false
        minimum_value: 0.0
        examples:
        - value: 3.2
          description: Average 3.2 seconds per caption
    rules:
    - postconditions:
        description: 'segments must be populated for VideoSubtitle.

          This is enforced by making segments required in slot_usage.

          '
    comments:
    - Time-coded caption/subtitle content
    - Extends VideoTranscript - subtitles ARE transcripts plus time codes
    - 'Supports multiple formats: SRT, VTT, TTML, SBV, ASS'
    - 'Accessibility metadata: CC, SDH, sound/music descriptions'
    - Critical for heritage video accessibility compliance
    see_also:
    - https://schema.org/caption
    - https://www.w3.org/TR/webvtt1/
    - https://developer.mozilla.org/en-US/docs/Web/API/WebVTT_API
    - https://www.3playmedia.com/learn/popular-topics/closed-captioning/