@lincyaw/addon-lecture 0.0.0-stage → 1.0.0-rc.1

package/src/domain/script-track.ts

@@ -0,0 +1,176 @@
+import type { SourcePos, TimeRange, TrackEvent, WrittenWord } from '@lincyaw/kernel'
+import type { LecturePlan, PlannedCue } from './plan.ts'
+import { wordTime } from './timing.ts'
+import type { LectureTrack, MediaSegment, TrackBlock, Utterance, Voice } from './track.ts'
+import { sortEvents, spokenDuration, TRACK_VERSION } from './track.ts'
+import { charOffset, trackWords, wordIndexAt } from './words.ts'
+
+export interface Clip {
+  file: string
+  duration: number
+  words?: WrittenWord[]
+  speech?: Voice
+  sha256?: string
+}
+
+export interface RecordingClip {
+  assetId: string
+  clipId: string
+  src: string
+  sha256: string
+  durationMs: number
+  sourceRange?: TimeRange
+}
+
+export interface ScriptHead {
+  id: string
+  doc: string
+  lang: string
+  ir: LectureTrack['ir']
+  voice: Voice
+  gap: number
+}
+
+/** A `{cue}next` that moved on before the animation of its step had played. */
+export interface CutAnimation {
+  section: string
+  /** The step whose animation the cue cut short (as the plan counts steps). */
+  step: number
+  /** How much of the animation was left (ms). */
+  left: number
+  source?: SourcePos
+}
+
+function anchorAt(utterance: Utterance, words: readonly WrittenWord[] | undefined, offset: number): number {
+  return words?.length ? wordIndexAt(words, offset, utterance.text.length) : charOffset(utterance.text, offset)
+}
+
+/**
+ * The synthesized lecture's timeline. A step lasts as long as its longest animation, except where the
+ * narration says `{cue}next` before then: the cue keeps the word it is bound to, and `cuts` list it.
+ */
+/**
+ * The lecture of `plan` said with `clips`. `unsaid`: the sentences without a clip, by id, with the reason; each plays
+ * silent for the time it would take to say, so that a preview keeps the lecture's timeline.
+ */
+export function scriptTrack(plan: LecturePlan, clips: ReadonlyMap<string, Clip>, head: ScriptHead, blocks: (events: TrackEvent[]) => Record<string, TrackBlock>, unsaid: ReadonlyMap<string, string> = new Map(), silent: ReadonlySet<string> = new Set(), recordings: ReadonlyMap<string, RecordingClip> = new Map()): { track: LectureTrack, cuts: CutAnimation[] } {
+  const cuts: CutAnimation[] = []
+  const events: TrackEvent[] = []
+  const utterances: Utterance[] = []
+  const audio: MediaSegment[] = []
+  let t = 0
+  let inked = false
+  for (const section of plan.sections) {
+    let current = 0
+    let since = t
+    const go = (at: number, step: number) => events.push([at, 'go', { section: section.id, step: section.webStep(step) }])
+    // A step lasts as long as its longest animation: the lecture waits for it before it moves on.
+    const hold = () => {
+      const until = since + (section.holds[current] ?? 0)
+      if (until <= t) return
+      events.push([t, 'pause', { ms: until - t, hold: true }])
+      t = until
+    }
+    go(t, 0)
+    if (inked) events.push([t, 'ink', { clear: true }])
+    inked = false
+    for (let step = 0; step <= section.steps; step++) {
+      if (step > current) {
+        hold()
+        go(t, step)
+        current = step
+        since = t
+      }
+      const paragraphs = section.paragraphs.filter(p => p.step === step)
+      const recording = section.recordings?.find(recording => recording.step === step)
+      if (recording) {
+        const clip = recordings.get(recording.id)
+        if (clip && !recording.issue) {
+          if (recording.mode === 'after') hold()
+          audio.push({ section: section.id, role: 'recording', stepId: recording.stepId, narrationIds: recording.narrationIds, start: t / 1000, duration: clip.durationMs / 1000, sourceStartMs: clip.sourceRange?.startMs ?? 0, src: clip.src, clipId: clip.clipId, assetId: clip.assetId, sha256: clip.sha256 })
+          if (recording.text) utterances.push({ id: recording.id, t, d: clip.durationMs, text: recording.text, section: section.id, step: section.webStep(step), narrationIds: recording.narrationIds, recording: true, voice: { kind: 'recorded' } })
+          for (const cue of recording.cues) { if (cue.name === 'ink') inked = true; events.push([t, cue.name, cue.data]) }
+          t += clip.durationMs
+        }
+        if (!section.trailingPauseMs && paragraphs.length) t += head.gap
+      } else for (const paragraph of paragraphs) {
+        if (paragraph.mode === 'after') hold()
+        for (const piece of paragraph.pieces) {
+          const clip = piece.id ? clips.get(piece.id) : undefined
+          let utterance: Utterance | undefined
+          if (piece.id && clip) {
+            utterance = { id: piece.id, t, d: Math.round(clip.duration * 1000), text: piece.text, section: section.id, step: section.webStep(current), clip: clip.file }
+            if (clip.speech) utterance.voice = clip.speech
+            if (clip.sha256) utterance.audioSha256 = clip.sha256
+            if (clip.words?.length) { utterance.words = trackWords(clip.words, t); utterance.alignment = 'words' }
+            else utterance.alignment = 'proportional'
+            utterances.push(utterance)
+          } else if (piece.id && silent.has(piece.id)) {
+            utterance = { id: piece.id, t, d: 0, text: piece.text, section: section.id, step: section.webStep(current), silent: true }
+            utterances.push(utterance)
+          } else if (piece.id && unsaid.has(piece.id)) {
+            utterance = { id: piece.id, t, d: spokenDuration(piece.text, head.lang), text: piece.text, section: section.id, step: section.webStep(current), unsaid: unsaid.get(piece.id)! }
+            utterances.push(utterance)
+          }
+          if (utterance && paragraph.narrationId) utterance.narrationIds = [paragraph.narrationId]
+          const cue = (c: PlannedCue, data: Record<string, unknown>): number => {
+            if (c.name === 'ink') inked = true
+            if (!utterance) {
+              events.push([t, c.name === 'next' ? 'go' : c.name, data])
+              return t
+            }
+            const at = anchorAt(utterance, clip?.words, c.offset)
+            const time = wordTime(utterance, at)
+            events.push([time, c.name === 'next' ? 'go' : c.name, { ...data, at: [utterance.id, at] }])
+            return time
+          }
+          for (const c of piece.cues) {
+            if (c.name === 'next') {
+              if (current >= section.steps) continue
+              const end = since + (section.holds[current] ?? 0)
+              current++
+              since = cue(c, { section: section.id, step: section.webStep(current) })
+              if (since < end) cuts.push({ section: section.id, step: current - 1, left: end - since, ...paragraph.source ? { source: paragraph.source } : {} })
+            } else {
+              cue(c, c.data)
+            }
+          }
+          if (utterance) t += utterance.d
+          if (piece.pause) t += piece.pause
+        }
+        if (!section.trailingPauseMs) t += head.gap
+      }
+      if (section.trailingPauseMs) { hold(); t += section.trailingPauseMs[step] ?? head.gap }
+      else if (paragraphs.length === 0) t += head.gap
+    }
+    hold()
+  }
+  const ordered = sortEvents(events)
+  const combined: Utterance[] = []
+  for (const utterance of utterances) {
+    const previous = combined.at(-1)
+    if (utterance.silent && previous?.silent && previous.t === utterance.t && previous.section === utterance.section && previous.step === utterance.step) {
+      previous.text += `\n\n${utterance.text}`
+      previous.narrationIds = [...new Set([...(previous.narrationIds ?? []), ...(utterance.narrationIds ?? [])])]
+    } else combined.push(utterance)
+  }
+  for (const [index, utterance] of combined.entries()) if (utterance.silent) {
+    const boundary = ordered.find(([at, type, data]) => type === 'go' && at > utterance.t && (data.section !== utterance.section || Number(data.step ?? 0) !== utterance.step))?.[0] ?? t
+    const next = combined[index + 1]?.t ?? t
+    utterance.d = Math.max(0, Math.min(boundary, next) - utterance.t)
+  }
+  const track: LectureTrack = {
+    track: TRACK_VERSION,
+    id: head.id,
+    doc: head.doc,
+    lang: head.lang,
+    ir: head.ir,
+    voice: head.voice,
+    blocks: blocks(events),
+    durationMs: t,
+    utterances: combined,
+    ...audio.length ? { audio } : {},
+    events: ordered,
+  }
+  return { track, cuts }
+}

package/src/domain/timing.ts

@@ -0,0 +1,107 @@
+import type { LectureTrack, Utterance } from './track.ts'
+
+export interface TimedEvent {
+  t: number
+  type: string
+  data: Record<string, unknown>
+  index: number
+}
+
+export function wordTime(utterance: Utterance, offset: number): number {
+  const words = utterance.words
+  if (words?.length) {
+    if (offset >= words.length) return words.at(-1)![0] + words.at(-1)![1]
+    return words[Math.max(0, offset)]![0]
+  }
+  const length = Math.max(1, [...utterance.text].length)
+  return utterance.t + Math.round(utterance.d * Math.max(0, Math.min(offset, length)) / length)
+}
+
+export function anchorOf(data: Record<string, unknown>): [string, number] | undefined {
+  const at = data.at
+  return Array.isArray(at) && typeof at[0] === 'string' && typeof at[1] === 'number' ? [at[0], at[1]] : undefined
+}
+
+export function timedEvents(track: LectureTrack): TimedEvent[] {
+  const utterances = new Map(track.utterances.map(u => [u.id, u]))
+  return track.events
+    .map(([t, type, data], index): TimedEvent => {
+      const at = anchorOf(data)
+      const utterance = at && utterances.get(at[0])
+      return { t: utterance ? wordTime(utterance, at![1]) : t, type, data, index }
+    })
+    .sort((a, b) => a.t - b.t || a.index - b.index)
+}
+
+export interface TextPiece {
+  text: string
+  t?: number
+}
+
+export function textPieces(utterance: Utterance): TextPiece[] | undefined {
+  if (!utterance.words?.length) return undefined
+  const pieces: TextPiece[] = []
+  let at = 0
+  for (const [t, , word] of utterance.words) {
+    const index = word ? utterance.text.indexOf(word, at) : -1
+    if (index < 0) return undefined
+    if (index > at) pieces.push({ text: utterance.text.slice(at, index) })
+    pieces.push({ text: word, t })
+    at = index + word.length
+  }
+  if (at < utterance.text.length) pieces.push({ text: utterance.text.slice(at) })
+  return pieces
+}
+
+export function utteranceAt(track: LectureTrack, t: number): Utterance | undefined {
+  return track.utterances.find(u => u.t <= t && t < u.t + u.d)
+}
+
+export function lastIndexAt(events: readonly { t: number }[], t: number): number {
+  let low = 0
+  let high = events.length
+  while (low < high) {
+    const mid = (low + high) >> 1
+    if (events[mid]!.t <= t) low = mid + 1
+    else high = mid
+  }
+  return low - 1
+}
+
+export interface TrackChapter {
+  t: number
+  section?: string
+  title: string
+}
+
+export function trackChapters(events: readonly TimedEvent[], titles: (section: string) => string | undefined = () => undefined): TrackChapter[] {
+  const list: TrackChapter[] = []
+  let section: string | undefined
+  for (const event of events) {
+    if (event.type === 'go' && typeof event.data.section === 'string' && event.data.section !== section) {
+      section = event.data.section
+      list.push({ t: event.t, section, title: titles(section) ?? section })
+    } else if (event.type === 'mark' && typeof event.data.label === 'string') {
+      list.push({ t: event.t, title: event.data.label })
+    }
+  }
+  return list
+}
+
+export interface StepStop {
+  t: number
+  section: string
+  step: number
+}
+
+export function stepStops(events: readonly TimedEvent[]): StepStop[] {
+  const list: StepStop[] = []
+  for (const event of events) {
+    const { section, step } = event.data
+    if (event.type !== 'go' || typeof section !== 'string') continue
+    const at = typeof step === 'number' && Number.isFinite(step) ? step : 0
+    const last = list.at(-1)
+    if (!last || last.section !== section || last.step !== at) list.push({ t: event.t, section, step: at })
+  }
+  return list
+}

package/src/domain/track.ts

@@ -0,0 +1,302 @@
+import { DOCUMENT_ENTRY, isRecord } from '@lincyaw/kernel'
+import type { ProductionBinding, TrackEvent } from '@lincyaw/kernel'
+
+export const LECTURE_ID = 'presmium.lecture'
+
+export const LECTURE_RENDERER = 'lecture'
+
+export const PLAYER_RENDERER = 'web'
+
+export const TRACK_VERSION = 1
+
+export const LECTURES_DIR = 'lectures'
+
+export type Word = [t: number, d: number, text: string]
+
+export interface Translation {
+  text: string
+  source: string
+}
+
+export interface Utterance {
+  id: string
+  t: number
+  d: number
+  text: string
+  words?: Word[]
+  /** Genuine word boundaries are distinct from interpolated edits and unaligned text. */
+  alignment?: 'words' | 'proportional' | 'none'
+  section?: string
+  step?: number
+  translations?: Record<string, Translation>
+  clip?: string
+  clipId?: string
+  audioSha256?: string
+  narrationIds?: string[]
+  /** Authored no-audio narration; its range comes from actual step boundaries, never reading-speed estimates. */
+  recording?: true
+  silent?: true
+  /** Exact provider/voice metadata of this sentence, when a scripted track uses multiple voices. */
+  voice?: Voice
+  /**
+   * Why the sentence has no audio: a synthesized lecture whose engine could not say it. It plays silent for the length it
+   * would take to say (`spokenDuration`), its caption shown; only a lecture's preview has such sentences.
+   */
+  unsaid?: string
+}
+
+// The time a voice takes for a word, as the synthesized lectures of the example say theirs (about 0.34 s in Chinese).
+const WORD_MS = 360
+const MIN_SAID_MS = 500
+
+/** About how long a voice takes to say `text`: by its words, as `Intl.Segmenter` finds them in the language. */
+export function spokenDuration(text: string, lang: string): number {
+  const words = [...new Intl.Segmenter(lang, { granularity: 'word' }).segment(text)].filter(segment => segment.isWordLike).length
+  return Math.max(MIN_SAID_MS, words * WORD_MS)
+}
+
+export const CLIP_FILE = /^[0-9a-f]{32}\.(wav|ogg)$/
+
+export const CLIPS_DIR = 'clips'
+
+export const SCRIPT_TRACK = 'script'
+
+/** The lecture a video is made of when none is named: the narrated script, else the only recorded one. */
+export function defaultTrack(ids: readonly string[]): string | undefined {
+  return ids.includes(SCRIPT_TRACK) ? SCRIPT_TRACK : ids.length === 1 ? ids[0] : undefined
+}
+
+export interface MediaSegment {
+  role?: 'recording'
+  stepId?: string
+  narrationIds?: string[]
+  section: string
+  start: number
+  src: string
+  duration: number
+  sha256?: string
+  clipId?: string
+  assetId?: string
+  mediaClipId?: string
+  sourceStartMs?: number
+  volume?: number
+  muted?: boolean
+}
+
+export interface VideoSegment extends MediaSegment {
+  kind: 'camera' | 'screen'
+}
+
+export type Voice =
+  | { kind: 'silent' }
+  | { kind: 'recorded', speaker?: string }
+  | { kind: 'synthetic', engine: string, model?: string, voice: string, provider?: string }
+
+export interface TrackBlock {
+  fp: string
+  lines?: number
+}
+
+export interface LectureTrack {
+  track: typeof TRACK_VERSION
+  id: string
+  doc: string
+  lang: string
+  ir: { hash: string, sections?: Record<string, string> }
+  voice: Voice
+  binding?: ProductionBinding
+  durationMs?: number
+  audio?: MediaSegment[]
+  video?: VideoSegment[]
+  blocks: Record<string, TrackBlock>
+  utterances: Utterance[]
+  /** Derived author times; ordinary audio utterances remain unchanged. */
+  captionOverrides?: { section: string, step: number, stepId: string, startMs: number, endMs: number, groups: import('./captions.ts').CaptionGroup[] }[]
+  events: TrackEvent[]
+}
+
+export const TRACK_ID = /^[\w][\w.-]{0,79}$/
+
+function isNumber(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value)
+}
+
+function words(value: unknown): Word[] | undefined {
+  if (!Array.isArray(value)) return undefined
+  return value.filter((w): w is Word => Array.isArray(w) && isNumber(w[0]) && isNumber(w[1]) && typeof w[2] === 'string')
+}
+
+function utterance(value: unknown, problems: string[], i: number): Utterance | undefined {
+  if (!isRecord(value) || typeof value.id !== 'string' || !isNumber(value.t) || !isNumber(value.d) || typeof value.text !== 'string') {
+    problems.push(`utterance ${i} needs id, t, d and text`)
+    return undefined
+  }
+  const translations = isRecord(value.translations)
+    ? Object.fromEntries(Object.entries(value.translations).flatMap(([lang, tr]) => isRecord(tr) && typeof tr.text === 'string'
+      ? [[lang, { text: tr.text, source: typeof tr.source === 'string' ? tr.source : '' }]]
+      : []))
+    : undefined
+  return {
+    id: value.id,
+    t: value.t,
+    d: value.d,
+    text: value.text,
+    ...words(value.words) ? { words: words(value.words) } : {},
+    ...value.alignment === 'words' || value.alignment === 'proportional' || value.alignment === 'none' ? { alignment: value.alignment } : {},
+    ...typeof value.section === 'string' ? { section: value.section } : {},
+    ...isNumber(value.step) ? { step: value.step } : {},
+    ...translations ? { translations } : {},
+    ...typeof value.clipId === 'string' ? { clipId: value.clipId } : {},
+    ...typeof value.audioSha256 === 'string' ? { audioSha256: value.audioSha256 } : {},
+    ...Array.isArray(value.narrationIds) && value.narrationIds.every(id => typeof id === 'string') ? { narrationIds: value.narrationIds as string[] } : {},
+    ...value.recording === true ? { recording: true as const } : {},
+    ...value.silent === true ? { silent: true as const } : {},
+    ...typeof value.clip === 'string' && CLIP_FILE.test(value.clip) ? { clip: value.clip } : {},
+    ...isRecord(value.voice) ? { voice: voice(value.voice) } : {},
+    ...typeof value.unsaid === 'string' ? { unsaid: value.unsaid } : {},
+  }
+}
+
+function segment(value: unknown): MediaSegment | undefined {
+  if (!isRecord(value) || typeof value.section !== 'string' || !isNumber(value.start) || typeof value.src !== 'string' || !isNumber(value.duration)) return undefined
+  return { ...value.role === 'recording' ? { role: 'recording' as const } : {}, ...typeof value.stepId === 'string' ? { stepId: value.stepId } : {}, ...Array.isArray(value.narrationIds) && value.narrationIds.every(id => typeof id === 'string') ? { narrationIds: value.narrationIds as string[] } : {}, section: value.section, start: value.start, src: value.src, duration: value.duration, ...typeof value.sha256 === 'string' ? { sha256: value.sha256 } : {}, ...typeof value.clipId === 'string' ? { clipId: value.clipId } : {}, ...typeof value.assetId === 'string' ? { assetId: value.assetId } : {}, ...typeof value.mediaClipId === 'string' ? { mediaClipId: value.mediaClipId } : {}, ...isNumber(value.sourceStartMs) && value.sourceStartMs >= 0 ? { sourceStartMs: value.sourceStartMs } : {}, ...isNumber(value.volume) && value.volume >= 0 && value.volume <= 1 ? { volume: value.volume } : {}, ...typeof value.muted === 'boolean' ? { muted: value.muted } : {} }
+}
+
+function captionOverride(value: unknown): NonNullable<LectureTrack['captionOverrides']>[number] | undefined {
+  if (!isRecord(value) || typeof value.section !== 'string' || !isNumber(value.step) || typeof value.stepId !== 'string'
+    || !isNumber(value.startMs) || !isNumber(value.endMs) || value.endMs <= value.startMs || !Array.isArray(value.groups)) return
+  const start = value.startMs, end = value.endMs
+  let previous = start
+  for (const group of value.groups) {
+    if (!isRecord(group) || typeof group.id !== 'string' || typeof group.text !== 'string' || !isNumber(group.t) || !isNumber(group.d)
+      || group.d <= 0 || group.t < previous || group.t + group.d > end || group.alignment !== 'manual') return
+    previous = group.t + group.d
+  }
+  return value as unknown as NonNullable<LectureTrack['captionOverrides']>[number]
+}
+
+function irOf(value: unknown): LectureTrack['ir'] {
+  const hash = isRecord(value) && typeof value.hash === 'string' ? value.hash : ''
+  const sections = isRecord(value) && isRecord(value.sections)
+    ? Object.fromEntries(Object.entries(value.sections).filter((entry): entry is [string, string] => typeof entry[1] === 'string'))
+    : undefined
+  return sections ? { hash, sections } : { hash }
+}
+
+function voice(value: unknown): Voice {
+  if (isRecord(value) && value.kind === 'silent') return { kind: 'silent' }
+  if (isRecord(value) && value.kind === 'synthetic' && typeof value.engine === 'string' && typeof value.voice === 'string') {
+    return {
+      kind: 'synthetic',
+      engine: value.engine,
+      voice: value.voice,
+      ...typeof value.model === 'string' ? { model: value.model } : {},
+      ...typeof value.provider === 'string' ? { provider: value.provider } : {},
+    }
+  }
+  return { kind: 'recorded', ...isRecord(value) && typeof value.speaker === 'string' ? { speaker: value.speaker } : {} }
+}
+
+export function parseTrack(value: unknown): { track?: LectureTrack, problems: string[] } {
+  const problems: string[] = []
+  if (!isRecord(value) || value.track !== TRACK_VERSION || typeof value.id !== 'string') {
+    return { problems: [`not a lecture track of version ${TRACK_VERSION} with an id`] }
+  }
+  const events: TrackEvent[] = []
+  for (const [i, event] of (Array.isArray(value.events) ? value.events : []).entries()) {
+    if (Array.isArray(event) && isNumber(event[0]) && typeof event[1] === 'string' && isRecord(event[2])) events.push([event[0], event[1], event[2]])
+    else problems.push(`event ${i} is not [ms, type, data]`)
+  }
+  const utterances = (Array.isArray(value.utterances) ? value.utterances : []).flatMap((u, i) => utterance(u, problems, i) ?? [])
+  const blocks = isRecord(value.blocks)
+    ? Object.fromEntries(Object.entries(value.blocks).flatMap(([key, b]) => isRecord(b) && typeof b.fp === 'string' ? [[key, { fp: b.fp, ...isNumber(b.lines) ? { lines: b.lines } : {} }]] : []))
+    : {}
+  const audio = Array.isArray(value.audio) ? value.audio.flatMap(a => segment(a) ?? []) : undefined
+  const video = Array.isArray(value.video)
+    ? value.video.flatMap((v) => {
+        const base = segment(v)
+        return base && isRecord(v) && (v.kind === 'camera' || v.kind === 'screen') ? [{ ...base, kind: v.kind as VideoSegment['kind'] }] : []
+      })
+    : undefined
+  return {
+    track: {
+      track: TRACK_VERSION,
+      id: value.id,
+      doc: typeof value.doc === 'string' ? value.doc : DOCUMENT_ENTRY,
+      lang: typeof value.lang === 'string' ? value.lang : 'zh-CN',
+      ir: irOf(value.ir),
+      voice: voice(value.voice),
+      ...isNumber(value.durationMs) && value.durationMs >= 0 ? { durationMs: value.durationMs } : {},
+      ...isRecord(value.binding) && typeof value.binding.planId === 'string' && typeof value.binding.irRevision === 'string' && isRecord(value.binding.source) && typeof value.binding.source.documentId === 'string' && typeof value.binding.source.version === 'string' && typeof value.binding.source.fingerprint === 'string' ? { binding: value.binding as unknown as ProductionBinding } : {},
+      ...audio?.length ? { audio } : {},
+      ...video?.length ? { video } : {},
+      blocks,
+      ...Array.isArray(value.captionOverrides) ? { captionOverrides: value.captionOverrides.flatMap(value => captionOverride(value) ?? []) } : {},
+      utterances: utterances.sort((a, b) => a.t - b.t),
+      events: sortEvents(events),
+    },
+    problems,
+  }
+}
+
+export function sortEvents(events: TrackEvent[]): TrackEvent[] {
+  return events.map((event, i) => [event, i] as const).sort(([a, i], [b, j]) => a[0] - b[0] || i - j).map(([event]) => event)
+}
+
+export function formatTrack(track: LectureTrack): string {
+  const lines: string[] = []
+  const entries = Object.entries(track).filter(([, value]) => value !== undefined)
+  entries.forEach(([key, value], i) => {
+    const comma = i < entries.length - 1 ? ',' : ''
+    if (Array.isArray(value) && value.length > 0) {
+      lines.push(`  ${JSON.stringify(key)}: [`)
+      value.forEach((item, j) => lines.push(`    ${JSON.stringify(item)}${j < value.length - 1 ? ',' : ''}`))
+      lines.push(`  ]${comma}`)
+    } else if (key === 'blocks' && isRecord(value) && Object.keys(value).length > 0) {
+      const blocks = Object.entries(value)
+      lines.push(`  "blocks": {`)
+      blocks.forEach(([block, data], j) => lines.push(`    ${JSON.stringify(block)}: ${JSON.stringify(data)}${j < blocks.length - 1 ? ',' : ''}`))
+      lines.push(`  }${comma}`)
+    } else {
+      lines.push(`  ${JSON.stringify(key)}: ${JSON.stringify(value)}${comma}`)
+    }
+  })
+  return `{\n${lines.join('\n')}\n}\n`
+}
+
+export function eventLine(text: string, index: number): number | undefined {
+  const lines = text.split('\n')
+  const start = lines.findIndex(line => line.startsWith('  "events": ['))
+  return start === -1 || start + 1 + index >= lines.length ? undefined : start + 2 + index
+}
+
+export function utteranceLine(text: string, id: string): number | undefined {
+  const lines = text.split('\n')
+  const from = lines.findIndex(line => line.trimStart().startsWith('"utterances"'))
+  const at = lines.findIndex((line, i) => i > from && line.includes(`"id":${JSON.stringify(id)}`))
+  return from === -1 || at === -1 ? undefined : at + 1
+}
+
+export function trackDuration(track: LectureTrack): number {
+  return Math.max(
+    0, track.durationMs ?? 0,
+    ...(track.audio ?? []).map(a => (a.start + a.duration) * 1000),
+    ...track.utterances.map(u => u.t + u.d),
+    ...track.events.map(([t, type, data]) => (type === 'pause' && typeof data.ms === 'number' ? t + data.ms : t)),
+  )
+}
+
+export interface AudioSegment {
+  clipId?: string
+  src: string
+  start: number
+  duration: number
+  sourceStartMs?: number
+  volume?: number
+  muted?: boolean
+}
+
+export function audioSegments(track: LectureTrack): AudioSegment[] {
+  const said = track.utterances.filter(u => u.clip).map(u => ({ src: `${CLIPS_DIR}/${u.clip}`, start: u.t, duration: u.d, ...u.clipId ? { clipId: u.clipId } : {} }))
+  return [...said, ...(track.audio ?? []).map(a => ({ src: a.src, start: a.start * 1000, duration: a.duration * 1000, ...a.clipId ? { clipId: a.clipId } : {}, ...a.sourceStartMs !== undefined ? { sourceStartMs: a.sourceStartMs } : {}, ...a.volume !== undefined ? { volume: a.volume } : {}, ...a.muted !== undefined ? { muted: a.muted } : {} }))]
+}

package/src/domain/translation.ts

@@ -0,0 +1,34 @@
+import { sha256 } from '@noble/hashes/sha2.js'
+import { bytesToHex, utf8ToBytes } from '@noble/hashes/utils.js'
+import type { LectureTrack, Utterance } from './track.ts'
+
+export function translationDigest(text: string): string {
+  return `sha256:${bytesToHex(sha256(utf8ToBytes(text)))}`
+}
+
+export function isStale(utterance: Utterance, lang: string): boolean {
+  const translation = utterance.translations?.[lang]
+  return Boolean(translation && translation.source !== translationDigest(utterance.text))
+}
+
+export interface TranslationItem {
+  id: string
+  section?: string
+  text: string
+  source: string
+  translation?: string
+  stale?: boolean
+}
+
+export function translationItems(track: LectureTrack, lang: string): TranslationItem[] {
+  return track.utterances.map((u) => {
+    const done = u.translations?.[lang]
+    return {
+      id: u.id,
+      ...u.section ? { section: u.section } : {},
+      text: u.text,
+      source: translationDigest(u.text),
+      ...done ? { translation: done.text, stale: isStale(u, lang) } : {},
+    }
+  })
+}