podcast-annotations

Every podcast episode is full of references — cars, people, places, concepts — that exist only as sound. Transcripts capture the words, but not the structure. There's no way for apps or tools to know what's being talked about at any given moment.

podcast-annotations is the reference implementation of the Podcast Annotation Format — an open spec for timestamped, typed entity annotations on audio. Think X-Ray for podcasts, but open and format-level instead of locked inside one platform.

Hit play and see:

• "LS Engine" appears at 0:45 as the host discusses it
• "Turbocharger" pops up at 2:00 with a link to learn more
• A timeline shows every topic in the episode — click to jump

All synced to playback. Framework-agnostic vanilla JavaScript — zero dependencies. Built for Car Curious.

Features

• Annotation Overlay — Auto-trigger contextual content at specific moments during audio playback
• Transcript Sync — Highlight the active transcript segment with auto-scroll and user-interrupt detection
• Annotation Timeline — Visual markers showing where annotations appear, with a playhead and click-to-seek
• DAI Alignment — Remap canonical transcripts to variant audio with dynamic ad insertion, with gap-aware sync that pauses during ad breaks

Each module works independently. Use one, two, or all three.

Handling timing, overlaps, ad insertion gaps, and transcript sync correctly is surprisingly tricky. This library provides a minimal, battle-tested implementation so you don't have to rebuild it.

Install

npm install podcast-annotations

Or use a CDN:

<script type="module">
  import { AnnotationOverlay, TranscriptSync, AnnotationTimeline } from 'https://esm.sh/podcast-annotations'
</script>

Quick Start

import { AnnotationOverlay, TranscriptSync, AnnotationTimeline } from 'podcast-annotations'

const audio = document.querySelector('audio')

// Annotations auto-trigger during playback
const overlay = new AnnotationOverlay(audio, {
  annotations: [
    { startTime: 45, endTime: 75, type: 'car', title: 'LS Engine' },
    { startTime: 120, endTime: 150, type: 'part', title: 'Turbocharger' }
  ],
  onAnnotationChange(annotation) {
    document.querySelector('#overlay').innerHTML = annotation
      ? `<strong>${annotation.title}</strong>`
      : ''
  },
  onUpcomingChange(upcoming) {
    document.querySelector('#coming-up').innerHTML = upcoming
      .map(a => `<span>${a.title} at ${Math.floor(a.startTime)}s</span>`)
      .join('')
  }
})

// Transcript from a VTT file — renders and syncs automatically
const transcript = await TranscriptSync.fromURL(audio, '/episode.vtt', {
  container: document.querySelector('#transcript'),
  activeClass: 'highlight',
  onAutoScrollPause() {
    document.querySelector('#resume-btn').hidden = false
  }
})

// Or from existing DOM elements (data-start-time attributes)
// const transcript = new TranscriptSync(audio, {
//   container: document.querySelector('#transcript'),
//   segmentSelector: '[data-start-time]'
// })

// Timeline with markers (style via CSS using data-type attributes)
const timeline = new AnnotationTimeline(audio, {
  container: document.querySelector('#timeline'),
  annotations: overlay.annotations,
  onSeek(time) { audio.currentTime = time }
})

API

AnnotationOverlay(audio, options)

Option	Type	Default	Description
annotations	Array	[]	[{ startTime, endTime, data }]
overlayElement	HTMLElement	—	Element to add/remove activeClass/hiddenClass
activeClass	string	'active'	Class when annotation is visible
hiddenClass	string	'hidden'	Class when no annotation
onAnnotationChange	Function	—	(annotation | null) => void
onUpcomingChange	Function	—	(upcoming[]) => void
upcomingLimit	number	3	Max upcoming annotations
leadTime	number	2	Seconds before startTime to trigger
transitionBuffer	number	5	Gap between consecutive annotations
maxExtension	number	60	Max seconds to extend past endTime

Methods: setAnnotations(annotations), destroy() Getters: currentAnnotation, upcoming

Static factories:

• AnnotationOverlay.fromURL(audio, url, options) — Fetch a .annotations.json file and create a synced overlay. Returns { overlay, annotationSet } where annotationSet contains episode metadata, speakers, transcripts, and ad breaks.

const { overlay, annotationSet } = await AnnotationOverlay.fromURL(audio, '/episode.annotations.json', {
  onAnnotationChange(annotation) { ... }
})
// annotationSet.speakers, annotationSet.adBreaks, etc. available for additional UI

Standalone fetch:

• fetchAnnotationSet(url) — Fetch and parse a .annotations.json file without creating an overlay.

TranscriptSync(audio, options)

Option	Type	Default	Description
container	HTMLElement	—	Scrollable transcript container
segmentSelector	string	'[data-start-time]'	CSS selector for segments
startTimeAttribute	string	'data-start-time'	Attribute with time in seconds
activeClass	string	'active'	Current segment class
pastClass	string	'past'	Past segments class
futureClass	string	'future'	Future segments class
autoScroll	boolean	true	Auto-scroll to active segment
scrollBehavior	string	'smooth'	Scroll behavior
onSegmentChange	Function	—	(element, index) => void
onAutoScrollPause	Function	—	Called when user scrolls away
onAutoScrollResume	Function	—	Called when auto-scroll resumes

Methods: resumeAutoScroll(), refresh(), destroy() Getters: isAutoScrolling

Static factories:

• TranscriptSync.fromVTT(audio, vttString, options) — Parse a VTT/SRT string, render segments into container, return a synced instance.
• TranscriptSync.fromURL(audio, url, options) — Fetch a VTT/SRT file, render, and return a synced instance (async).
• options.renderSegment(cue, element) — Custom renderer for VTT cues. Default renders speaker name + text.

AnnotationTimeline(audio, options)

Option	Type	Default	Description
container	HTMLElement	—	Timeline container element
annotations	Array	[]	Annotation data
duration	number	—	Total seconds (auto-detected if omitted)
onSeek	Function	—	(timeInSeconds) => void
markerClass	string	'pa-timeline-marker'	CSS class for markers
playheadClass	string	'pa-timeline-playhead'	CSS class for playhead
renderMarker	Function	—	(annotation, element) => void

Markers get data-type attributes for CSS-based styling. Style with:

.pa-timeline-marker[data-type="car"] { background: #60a5fa; }
.pa-timeline-marker[data-type="term"] { background: #c084fc; }

Methods: setAnnotations(annotations), destroy()

ChapterSync(audio, chapters, options)

Syncs Podcasting 2.0 JSON chapters with audio playback.

// From a URL
const chapters = await ChapterSync.fromURL(audio, '/chapters.json', {
  container: document.querySelector('#chapters'),
  onChapterChange(chapter) { updateNowPlaying(chapter?.title) }
})

// From a JSON object
const chapters = ChapterSync.fromJSON(audio, chaptersData, options)

// From an array directly
const chapters = new ChapterSync(audio, chaptersArray, options)

Option	Type	Default	Description
container	HTMLElement	—	Container for rendered chapter list
activeClass	string	'active'	Class for current chapter
autoplay	boolean	false	Start playback when a chapter is clicked
chapterClass	string	'pa-chapter'	CSS class for chapter elements
onChapterChange	Function	—	(chapter | null, index) => void
onSeek	Function	—	(timeInSeconds) => void
renderChapter	Function	—	(chapter, element) => void

Methods: setChapters(chapters), destroy() Getters: currentChapter Static: ChapterSync.fromJSON(audio, json, options), ChapterSync.fromURL(audio, url, options)

AlignedTranscript(canonicalCues, mapping)

Handles DAI (Dynamic Ad Insertion) alignment — takes a canonical transcript and an alignment mapping, produces a timeline with remapped timestamps and gap regions for inserted ads/promos.

import { AlignedTranscript } from 'podcast-annotations'

const aligned = new AlignedTranscript(canonicalCues, {
  confidence: 0.95,
  ranges: [
    { canonicalStart: 0, canonicalEnd: 120, variantStart: 0, variantEnd: 120 },
    { canonicalStart: 120, canonicalEnd: 300, variantStart: 150, variantEnd: 330 }
  ],
  gaps: [
    { variantStart: 120, variantEnd: 150, label: 'ad' }
  ]
})

// Interleaved content + gap segments, sorted by variant time
aligned.segments.forEach(seg => {
  if (seg.type === 'content') {
    renderCue(seg.cue, seg.variantStart, seg.variantEnd)
  } else {
    renderAdBreak(seg.gap.label, seg.gap.variantStart)
  }
})

// Feed remapped cues into TranscriptSync with gap awareness
const transcript = TranscriptSync.fromVTT(audio, vttString, {
  container: document.querySelector('#transcript'),
  gaps: aligned.gaps,
  onGapEnter(gap) { showAdIndicator(gap.label) },
  onGapExit() { hideAdIndicator() }
})

Getters: segments, remappedCues, gaps, confidence, isSyncReliable Methods: isInGap(variantTime)

TranscriptSync gap options

When using TranscriptSync with DAI content, these additional options pause highlighting during ad breaks:

Option	Type	Default	Description
gaps	AlignmentGap[]	[]	Gap ranges where highlighting pauses
gapClass	string	'gap'	Class applied to gap elements
onGapEnter	Function	—	(gap) => void — called when playback enters a gap
onGapExit	Function	—	() => void — called when playback leaves a gap

Methods: setGaps(gaps) — update gap ranges dynamically Getters: isInGap — whether current playback position is inside a gap

Types

interface AlignmentMapping {
  variantHash?: string       // Hash of the variant audio file
  confidence: number         // Confidence score 0–1
  ranges: AlignmentRange[]   // Matched content ranges
  gaps: AlignmentGap[]       // Unmapped gap ranges (ads, promos, etc)
}

interface AlignmentRange {
  canonicalStart: number     // Start time in the canonical transcript
  canonicalEnd: number       // End time in the canonical transcript
  variantStart: number       // Start time in the variant audio
  variantEnd: number         // End time in the variant audio
}

interface AlignmentGap {
  variantStart: number       // Start time in variant audio
  variantEnd: number         // End time in variant audio
  label?: string             // e.g. "ad", "transition", "unknown"
  position?: string          // "pre-roll", "mid-roll", or "post-roll"
}

Timing utilities

import { enrichAnnotationsWithTiming, selectCurrentAnnotation, upcomingAnnotations } from 'podcast-annotations'

Low-level functions if you want full control over the timing logic.

Prior Art

The DAI alignment model was informed by Marco Arment's discussion of transcript synchronization with dynamic ad insertion in Overcast (ATP #683), which helped shape how we combined our existing offset and signature work into the alignment API.

License

MIT