id: https://nde.nl/ontology/hc/class/VideoTimeSegment
name: video_time_segment_class
title: Video Time Segment Class
imports:
  - linkml:types
  - ../slots/has_score
  - ../slots/has_time_interval
  - ../slots/generated_by
  - ../slots/indexed_as
  - ../slots/has_text
  - ../slots/has_speaker
  - ../slots/20260202_matang/speaker_label
prefixes:
  linkml: https://w3id.org/linkml/
  hc: https://nde.nl/ontology/hc/
  schema: http://schema.org/
  dcterms: http://purl.org/dc/terms/
  crm: http://www.cidoc-crm.org/cidoc-crm/
  oa: http://www.w3.org/ns/oa#
  ma: http://www.w3.org/ns/ma-ont#
  prov: http://www.w3.org/ns/prov#
  skos: http://www.w3.org/2004/02/skos/core#
  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:
  VideoTimeSegment:
    class_uri: crm:E52_Time-Span
    abstract: false
    description: 'A temporal segment within a video, defined by start and end times.


      **DEFINITION**:


      VideoTimeSegment represents a bounded temporal portion of video content.

      It is the foundational unit for time-coded content including:

      - Subtitle/caption entries (text displayed at specific times)

      - Annotation segments (detected scenes, objects, faces)

      - Chapter markers (user-defined content sections)


      **DUAL TIME REPRESENTATION**:


      Times are stored in two formats for different use cases:


      | Format | Example | Use Case |

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

      | ISO 8601 duration | PT0M30S | Human-readable, serialization |

      | Seconds (float) | 30.0 | Computation, synchronization |


      Both representations MUST be kept in sync. The seconds format is

      primary for computation; ISO 8601 is derived for display/storage.


      **MEDIA FRAGMENTS URI (W3C)**:


      VideoTimeSegment aligns with W3C Media Fragments URI 1.0 specification

      for addressing temporal fragments of video:


      ```

      https://example.com/video.mp4#t=30,35

      ```


      The `start_seconds` and `end_seconds` map directly to the `t=` parameter.


      **WEB ANNOTATION COMPATIBILITY**:


      When used as an annotation target selector:

      - Maps to `oa:FragmentSelector` with `conformsTo` Media Fragments

      - Enables interoperability with W3C Web Annotation Data Model


      **CIDOC-CRM E52_Time-Span**:


      In cultural heritage documentation:

      - E52_Time-Span is the extent of a time-span

      - Used for temporal properties of cultural objects

      - VideoTimeSegment extends this to media-specific temporal segments


      **CONFIDENCE SCORING**:


      For segments generated by ASR (speech recognition) or CV (computer vision):

      - `confidence`: 0.0-1.0 score for segment accuracy

      - Enables filtering by quality threshold

      - Critical for AI-generated transcripts and annotations


      **HERITAGE USE CASES**:


      | Use Case | Example | Start | End |

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

      | Subtitle entry | "Welcome to the museum" | 0:30 | 0:35 |

      | Scene annotation | "Exhibition hall panorama" | 1:00 | 1:30 |

      | Chapter marker | "Introduction" | 0:00 | 2:00 |

      | Object detection | "Painting: Night Watch" | 3:15 | 3:20 |

      | Speaker change | "Curator speaking" | 5:00 | 7:30 |

      '
    exact_mappings:
    - crm:E52_Time-Span
    - oa:FragmentSelector
    close_mappings:
    - ma:MediaFragment
    related_mappings:
    - schema:Clip
    slots:
    - has_time_interval
    - indexed_as
    - has_text
    - has_speaker
    - speaker_label
    - has_score
    - generated_by
    - begin_of_the_begin
    - begin_of_the_begin
    slot_usage:
      has_time_interval:
        range: TimeInterval
        required: true
        inlined: true
        examples:
        - value: null
      has_text:
#         range: string
        required: false
        examples:
        - value: Welkom bij het Rijksmuseum
        - value: The curator explains the painting's history
      indexed_as:
        range: integer
        required: false
        minimum_value: 0
        examples:
        - value: 0
        - value: 42
      generated_by:
        range: GenerationEvent
        required: false
        inlined: true
        description: 'Generation event containing confidence score for ASR/CV segment
          accuracy. MIGRATED 2026-01-19: Replaces confidence slot with structured
          pattern.'
        examples:
        - value:
            has_score:
              has_score: 0.95
              has_method: asr_transcription
        - value:
            has_score:
              has_score: 0.72
              has_method: cv_detection
      has_speaker:
#         range: string
        required: false
        examples:
        - value: SPEAKER_01
        - value: curator_taco_dibbits
      speaker_label:
#         range: string
        required: false
        examples:
        - value: Narrator
        - value: Dr. Taco Dibbits, Museum Director

    comments:
    - Reusable time segment for subtitles, annotations, chapters
    - 'Dual time format: ISO 8601 for serialization, seconds for computation'
    - Aligns with W3C Media Fragments URI specification
    - Confidence scoring for AI-generated content
    - Speaker diarization support for multi-speaker transcripts
    - 'MIGRATED 2026-01-19: confidence → generated_by + ConfidenceScore'
    see_also:
    - https://www.w3.org/TR/media-frags/
    - https://www.w3.org/TR/annotation-model/
    - https://www.w3.org/ns/ma-ont
    - http://www.cidoc-crm.org/cidoc-crm/E52_Time-Span
    annotations:
      specificity_score: 0.1
      specificity_rationale: Generic utility class/slot created during migration
      custodian_types: '[''*'']'