Zettle

0026-video-resource-class

2 min read

ADR-0026: Video transcript resource class

Status: Accepted Date: 2026-06-01

Context

The vault now contains captured YouTube transcripts under resources/Video/, produced by scripts/capture-video.py. The first needed atomization source is:

resources/Video/youtube/Worship Ministry Training/2026-06-01-major-misconceptions-about-worship-music.md

Before this ADR, CONTEXT.md had no Video citation grammar. The ingest workflow requires every atomized reference source to belong to a registered resource class, so atomics from this transcript would either violate the rulebook or need to be moved into the older generic Transcripts class. Moving would lose useful source provenance already encoded by platform and channel.

Decision

Add Video as a resource class rooted at /resources/Video/.

File structure:

resources/Video/{platform}/{channel}/{date}-{video-slug}.md

Citation form:

[[resources/Video/youtube/Worship Ministry Training/2026-06-01-major-misconceptions-about-worship-music#transcript|Transcript]]

The canonical anchor is the transcript heading. Timestamp ranges remain in quoted prose rather than as anchors unless a later cleanup pass adds stable timestamp headings to the source file.

Style profile:

Video transcripts are conversational. Atomization should deduplicate repeated speech, preserve speaker claims only when the exchange clarifies the idea, and keep timestamp ranges in prose because the anchor is transcript-level.

Quartz source filtering treats Video hierarchically as platform → channel → video.

Alternatives considered

  • Move video transcripts into /resources/Transcripts/: rejected because platform/channel/video metadata is useful provenance, and the capture script already writes a clear resources/Video/ layout.
  • Anchor every citation to timestamps: deferred. The current files do not expose timestamps as Markdown headings, and the pre-commit hook validates anchors against headings. Transcript-level anchors are coarse but valid; timestamp heading cleanup can be a separate source-normalization pass.
  • Inline URLs only: rejected because atomics need vault-resolvable wikilinks for Obsidian and Quartz.

Consequences

  • (+) Video transcripts can enter the lean ingest workflow without inventing ad hoc citations.
  • (+) Captured YouTube provenance stays visible in the path and resource frontmatter.
  • (+) Existing validation can resolve transcript-level anchors.
  • (-) Transcript-level citation anchors are less granular than section or timestamp anchors. Atomics must include timestamp ranges in prose until the source is sectioned.

Graph View