id: https://nde.nl/ontology/hc/class/VideoSubtitle
name: video_subtitle_class
title: Video Subtitle Class
imports:
  - linkml:types
  - ../enums/SubtitleFormatEnum
  - ../enums/SubtitlePositionEnum
  - ../slots/has_alignment
  - ../slots/has_caption
  - ../slots/has_format
  - ../slots/identified_by
  - ../slots/has_label
  - ../slots/has_mean
  - ../slots/has_quantity
  - ../slots/has_score
  - ../slots/has_segment
  - ../slots/has_measurement_unit
  - ../slots/has_music
  - ../slots/has_sound
  - ../slots/identify
  - ../slots/created_through
  - ../slots/has_raw_data
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#
  rdfs: http://www.w3.org/2000/01/rdf-schema#
  org: http://www.w3.org/ns/org#
  xsd: http://www.w3.org/2001/XMLSchema#
default_prefix: hc
classes:
  VideoSubtitle:
    is_a: VideoTranscript
    class_uri: hc:VideoSubtitle
    abstract: false
    description: "Time-coded caption/subtitle content for video.\n\n**DEFINITION**:\n\nVideoSubtitle represents caption/subtitle tracks that provide time-coded\ntext synchronized with video playback. It extends VideoTranscript because\nsubtitles contain complete transcription PLUS temporal synchronization.\n\n**INHERITANCE FROM VideoTranscript**:\n\nVideoSubtitle inherits all transcript capabilities:\n- `full_text`: Complete subtitle text concatenated\n- `segments`: Time-coded entries (REQUIRED for subtitles)\n- `includes_timestamps`: Always true for subtitles\n- `content_language`: Language of subtitle text\n- All provenance from VideoTextContent\n\nAnd adds subtitle-specific properties:\n- `has_format`: SRT, VTT, TTML, SBV, ASS\n- `is_closed_caption`: CC vs regular subtitles\n- `is_sdh`: Subtitles for Deaf/Hard-of-Hearing\n- `includes_sound_descriptions`: Non-speech audio descriptions\n\n**SCHEMA.ORG ALIGNMENT**:\n\nMaps to `schema:caption` property:\n> \"For downloadable machine\
      \ formats (closed caption, subtitles etc.)\n>  use the MediaObject.encodingFormat property.\"\n\n**SUBTITLE vs CAPTION vs TRANSCRIPT**:\n\n| Type | Time-coded | Purpose | Audience |\n|------|------------|---------|----------|\n| Transcript | Optional | Reading, search | Everyone |\n| Subtitle | Required | Language translation | Hearing viewers |\n| Caption (CC) | Required | Accessibility | Deaf/HoH viewers |\n| SDH | Required | Full accessibility | Deaf viewers, noisy environments |\n\n**SDH (Subtitles for Deaf/Hard-of-Hearing)**:\n\nSDH differs from regular subtitles by including:\n- Speaker identification: \"(John) Hello\"\n- Sound effects: \"[door slams]\", \"[music playing]\"\n- Music descriptions: \"\u266A upbeat jazz \u266A\"\n- Emotional cues: \"[laughing]\", \"[whispering]\"\n\n**SUBTITLE FORMATS**:\n\n| Format | Extension | Features | Use Case |\n|--------|-----------|----------|----------|\n| SRT | .srt | Simple, universal | Most video players |\n| VTT | .vtt | W3C standard,\
      \ styling | HTML5 video, web |\n| TTML | .ttml/.dfxp | XML, rich styling | Broadcast, streaming |\n| SBV | .sbv | YouTube native | YouTube uploads |\n| ASS | .ass | Advanced styling | Anime, complex layouts |\n\n**SRT FORMAT EXAMPLE**:\n\n```\n1\n00:00:00,000 --> 00:00:03,500\nWelcome to the Rijksmuseum.\n\n2\n00:00:03,500 --> 00:00:08,200\nToday we'll explore the Night Watch gallery.\n```\n\n**VTT FORMAT EXAMPLE**:\n\n```\nWEBVTT\n\n00:00:00.000 --> 00:00:03.500\nWelcome to the Rijksmuseum.\n\n00:00:03.500 --> 00:00:08.200\nToday we'll explore the Night Watch gallery.\n```\n\n**HERITAGE INSTITUTION CONTEXT**:\n\nSubtitles are critical for heritage video accessibility:\n\n1. **Accessibility Compliance**: WCAG 2.1, Section 508\n2. **Multilingual Access**: Translate for international audiences\n3. **Silent Viewing**: Social media, public displays, quiet spaces\n4. **Search Discovery**: Subtitle text is indexed by platforms\n5. **Preservation**: Text outlasts video format obsolescence\n\
      \n**YOUTUBE API INTEGRATION**:\n\nSubtitle tracks from YouTube API populate:\n- `has_format`: Typically VTT or SRT\n- `generation_method`: PLATFORM_PROVIDED or ASR_AUTOMATIC\n- `content_language`: From track language code\n- `created_through`: YouTube auto-caption flag\n\n**SEGMENTS ARE REQUIRED**:\n\nUnlike VideoTranscript where segments are optional, VideoSubtitle\nREQUIRES the `segments` slot to be populated with VideoTimeSegment\nentries that include start_seconds, end_seconds, and segment_text.\n"
    close_mappings:
    - schema:caption
    - ma:CaptioningFormat
    related_mappings:
    - schema:transcript
    slots:
    - has_mean
    - has_measurement_unit
    - has_caption
    - has_alignment
    - has_quantity
    - has_music
    - has_sound
    - identify
    - created_through
    - has_caption
    - has_caption
    - has_raw_data
    - has_format
    - has_score
    - identified_by
    - has_label
    slot_usage:
      has_segment:
        required: true
      identified_by:
        ifabsent: 'true'
      has_format:
        range: SubtitleFormatEnum
        required: true
        examples:
        - value: VTT
        - value: SRT
      has_raw_data:
#         range: string
        required: false
        examples:
        - value: 'WEBVTT


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

            Welcome to the museum.

            '
      has_caption:
        range: boolean
        required: false
        ifabsent: 'false'
        examples:
        - value: true
      has_caption:
        range: boolean
        required: false
        ifabsent: 'false'
        examples:
        - value: true
      has_sound:
        range: boolean
        required: false
        ifabsent: 'false'
        examples:
        - value: true
      has_music:
        range: boolean
        required: false
        ifabsent: 'false'
        examples:
        - value: true
      identify:
        range: boolean
        required: false
        ifabsent: 'false'
        examples:
        - value: true
      created_through:
        range: boolean
        required: false
        ifabsent: 'false'
        examples:
        - value: true
      has_label:
#         range: string
        required: false
        deprecated: Use identified_by with TrackIdentifier range instead
        examples:
        - value: English (auto-generated)
      identified_by:
        range: TrackIdentifier
        required: false
        inlined: true
        examples:
        - value: '{"platform": "YouTube", "has_code": "en.3OWxR1w4QfE"}'
      has_caption:
        range: Caption
        inlined: true
        required: false
      has_alignment:
        range: Alignment
        inlined: true
        required: false
      has_quantity:
        range: integer
        required: false
        inlined: false # Fixed invalid inline for primitive type
        examples:
        - value:
            has_measurement_unit:
              has_label: entries
      has_mean:
        range: MeanValue
        inlined: true
        examples:
        - value:
            has_value: 3.2
            has_measurement_unit:
              has_label: seconds
    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/
    annotations:
      specificity_score: 0.1
      specificity_rationale: Generic utility class/slot created during migration
      custodian_types: "['*']"