id: https://nde.nl/ontology/hc/class/VideoTimeSegment
name: video_time_segment_class
title: Video Time Segment Class
imports:
- linkml:types
- ../slots/confidence
- ../slots/end_seconds
- ../slots/end_time
- ../slots/segment_index
- ../slots/segment_text
- ../slots/speaker_id
- ../slots/speaker_label
- ../slots/specificity_annotation
- ../slots/start_seconds
- ../slots/start_time
- ../slots/template_specificity
- ./SpecificityAnnotation
- ./TemplateSpecificityScores
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#
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:
    - confidence
    - end_seconds
    - end_time
    - segment_index
    - segment_text
    - speaker_id
    - speaker_label
    - specificity_annotation
    - start_seconds
    - start_time
    - template_specificity
    slot_usage:
      start_time:
        slot_uri: ma:hasStartTime
        description: |
          Start time of segment as ISO 8601 duration from video beginning.

          Media Ontology: hasStartTime for temporal start.

          **Format**: ISO 8601 duration (e.g., "PT0M30S" = 30 seconds from start)

          **Common Patterns**:
          - PT0S = Start of video (0 seconds)
          - PT30S = 30 seconds
          - PT1M30S = 1 minute 30 seconds
          - PT1H15M30S = 1 hour 15 minutes 30 seconds
        range: string
        required: false
        pattern: ^PT(\d+H)?(\d+M)?(\d+(\.\d+)?S)?$
        examples:
        - value: PT0M30S
          description: 30 seconds from video start
        - value: PT1H15M30S
          description: 1 hour 15 minutes 30 seconds
      end_time:
        slot_uri: ma:hasEndTime
        description: |
          End time of segment as ISO 8601 duration from video beginning.

          Media Ontology: hasEndTime for temporal end.

          Must be greater than or equal to start_time.
        range: string
        required: false
        pattern: ^PT(\d+H)?(\d+M)?(\d+(\.\d+)?S)?$
        examples:
        - value: PT0M35S
          description: 35 seconds from video start
      start_seconds:
        slot_uri: hc:startSeconds
        description: |
          Start time in seconds (floating point) from video beginning.

          **PRIMARY for computation**. Use for:
          - Video player synchronization
          - Duration calculations
          - Time-based sorting and filtering

          Precision to milliseconds (3 decimal places) is typical.
        range: float
        required: true
        minimum_value: 0.0
        examples:
        - value: 30.0
          description: 30 seconds from start
        - value: 30.5
          description: 30.5 seconds (millisecond precision)
      end_seconds:
        slot_uri: hc:endSeconds
        description: |
          End time in seconds (floating point) from video beginning.

          Must be greater than start_seconds.

          For single-frame annotations (e.g., object detection in one frame),
          end_seconds may equal start_seconds or be slightly greater.
        range: float
        required: true
        minimum_value: 0.0
        examples:
        - value: 35.0
          description: 35 seconds from start
      segment_text:
        slot_uri: oa:bodyValue
        description: |
          Text content for this segment.

          Web Annotation: bodyValue for textual content.

          **Usage by content type**:
          - Subtitles: Displayed caption text
          - Transcripts: Spoken words during this segment
          - Annotations: Description of detected content
          - Chapters: Chapter title/description
        range: string
        required: false
        examples:
        - value: Welkom bij het Rijksmuseum
          description: Dutch subtitle text
        - value: The curator explains the painting's history
          description: Transcript segment
      segment_index:
        slot_uri: hc:segmentIndex
        description: |
          Sequential index of this segment within the parent content.

          Zero-based index for ordering segments:
          - Subtitle: Order in which captions appear
          - Annotation: Detection sequence

          Enables reconstruction of segment order when times overlap
          or for stable sorting.
        range: integer
        required: false
        minimum_value: 0
        examples:
        - value: 0
          description: First segment
        - value: 42
          description: 43rd segment (zero-indexed)
      confidence:
        slot_uri: hc:confidence
        description: |
          Confidence score for AI-generated content.

          Range: 0.0 (no confidence) to 1.0 (complete certainty)

          **Applies to**:
          - ASR-generated transcript/subtitle segments
          - CV-detected scene or object annotations
          - OCR-extracted text from video frames

          **Thresholds** (suggested):
          - > 0.9: High confidence, suitable for display
          - 0.7-0.9: Medium, may need review
          - < 0.7: Low, flag for human verification
        range: float
        required: false
        minimum_value: 0.0
        maximum_value: 1.0
        examples:
        - value: 0.95
          description: High confidence ASR segment
        - value: 0.72
          description: Medium confidence, may contain errors
      speaker_id:
        slot_uri: hc:speakerId
        description: |
          Identifier for the speaker during this segment.

          For transcripts with speaker diarization:
          - Links to identified speaker (e.g., "SPEAKER_01")
          - May be resolved to actual person identity

          Enables multi-speaker transcript navigation.
        range: string
        required: false
        examples:
        - value: SPEAKER_01
          description: First identified speaker
        - value: curator_taco_dibbits
          description: Resolved speaker identity
      speaker_label:
        slot_uri: hc:speakerLabel
        description: |
          Human-readable label for the speaker.

          Display name for the speaker during this segment:
          - May be generic ("Narrator", "Interviewer")
          - May be specific ("Dr. Taco Dibbits, Museum Director")

          Distinguished from speaker_id which is a machine identifier.
        range: string
        required: false
        examples:
        - value: Narrator
          description: Generic speaker label
        - value: Dr. Taco Dibbits, Museum Director
          description: Specific identified speaker
      specificity_annotation:
        range: SpecificityAnnotation
        inlined: true
      template_specificity:
        range: TemplateSpecificityScores
        inlined: true
    rules:
    - postconditions:
        description: end_seconds must be >= start_seconds
    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
    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
slots:
  start_time:
    description: Start time as ISO 8601 duration from video beginning
    range: string
  end_time:
    description: End time as ISO 8601 duration from video beginning
    range: string
  start_seconds:
    description: Start time in seconds (float) from video beginning
    range: float
  end_seconds:
    description: End time in seconds (float) from video beginning
    range: float
  segment_text:
    description: Text content for this time segment
    range: string
  segment_index:
    description: Sequential index of segment within parent
    range: integer
  speaker_id:
    description: Identifier for speaker during this segment
    range: string
  speaker_label:
    description: Human-readable label for speaker
    range: string