621 lines
19 KiB
YAML
621 lines
19 KiB
YAML
# 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
|