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

package/src/domain/vtt.ts

@@ -0,0 +1,68 @@
+import { timedEvents, trackChapters } from './timing.ts'
+import type { LectureTrack, Utterance } from './track.ts'
+import { trackDuration } from './track.ts'
+import { isStale } from './translation.ts'
+import { trackCaptionGroups } from './captions.ts'
+
+export function vttTime(ms: number): string {
+  const total = Math.max(0, Math.round(ms))
+  const pad = (n: number, width = 2) => String(n).padStart(width, '0')
+  return `${pad(Math.floor(total / 3_600_000))}:${pad(Math.floor(total / 60_000) % 60)}:${pad(Math.floor(total / 1000) % 60)}.${pad(total % 1000, 3)}`
+}
+
+function cueText(text: string): string {
+  return text.replace(/\r?\n\s*\n/g, '\n').replace(/-->/g, '->').trim()
+}
+
+export function captionLanguages(track: LectureTrack): string[] {
+  return [...new Set([track.lang, ...track.utterances.flatMap(u => Object.keys(u.translations ?? {}))])]
+}
+
+/** A sentence's caption in a language: its text, or its translation; undefined when it has none in that language. */
+export function captionText(track: LectureTrack, utterance: Utterance, lang: string): string | undefined {
+  return lang === track.lang ? utterance.text : utterance.translations?.[lang]?.text
+}
+
+export interface Captions {
+  lang: string
+  vtt: string
+  missing: string[]
+  stale: string[]
+}
+
+export function captionsVtt(track: LectureTrack, lang: string): Captions {
+  const cues: string[] = []
+  const missing: string[] = []
+  const stale: string[] = []
+  for (const u of track.utterances) {
+    const original = lang === track.lang
+    const text = captionText(track, u, lang)
+    if (text === undefined) {
+      missing.push(u.id)
+      continue
+    }
+    if (!original && isStale(u, lang)) {
+      stale.push(u.id)
+      cues.push(`NOTE stale: the original of ${u.id} changed after it was translated`)
+    }
+    if (!original) cues.push(`${u.id}\n${vttTime(u.t)} --> ${vttTime(u.t + Math.max(u.d, 1))}\n${cueText(text)}`)
+  }
+  if (lang === track.lang) for (const group of trackCaptionGroups(track)) cues.push(`${group.id}\n${vttTime(group.t)} --> ${vttTime(group.t + Math.max(group.d, 1))}\n${cueText(group.text)}`)
+  return { lang, vtt: `WEBVTT\n\n${cues.join('\n\n')}\n`, missing, stale }
+}
+
+export function chaptersVtt(track: LectureTrack, titles: (section: string) => string | undefined = () => undefined): string {
+  const list = trackChapters(timedEvents(track), titles)
+  const end = trackDuration(track)
+  const cues = list.map((chapter, i) => {
+    const until = Math.max(list[i + 1]?.t ?? end, chapter.t + 1)
+    return `${vttTime(chapter.t)} --> ${vttTime(until)}\n${cueText(chapter.title)}`
+  })
+  return `WEBVTT\n\n${cues.join('\n\n')}\n`
+}
+
+export function eventsVtt(track: LectureTrack): string {
+  const json = (value: unknown) => JSON.stringify(value).replace(/-->/g, '--\\u003e')
+  const cues = timedEvents(track).map(event => `${vttTime(event.t)} --> ${vttTime(event.t + 1)}\n${json({ type: event.type, data: event.data })}`)
+  return `WEBVTT\n\n${cues.join('\n\n')}\n`
+}

package/src/domain/words.ts

@@ -0,0 +1,114 @@
+import { isCjk, splitWords } from '@lincyaw/kernel'
+import type { SpeechWord } from '@lincyaw/kernel'
+import type { Utterance, Word } from './track.ts'
+
+export function isWide(char: string | undefined): boolean {
+  return Boolean(char && (isCjk(char) || /[　-〿＀-￯]/u.test(char)))
+}
+
+export function locate(words: readonly string[], text: string): ({ start: number, end: number } | undefined)[] {
+  const places: ({ start: number, end: number } | undefined)[] = []
+  let at = 0
+  let lost = false
+  for (const word of words) {
+    const index = lost || !word ? -1 : text.indexOf(word, at)
+    if (index < 0) {
+      lost = true
+      places.push(undefined)
+      continue
+    }
+    places.push({ start: index, end: at = index + word.length })
+  }
+  return places
+}
+
+export function wordIndexAt(words: readonly { offset?: number }[], offset: number, length: number): number {
+  if (words.every(w => w.offset !== undefined)) {
+    const index = words.findIndex(w => w.offset! >= offset)
+    return index === -1 ? words.length : index
+  }
+  return Math.min(words.length, Math.round(words.length * offset / Math.max(1, length)))
+}
+
+export function charOffset(text: string, offset: number): number {
+  return [...text.slice(0, offset)].length
+}
+
+export function trackWords(words: readonly SpeechWord[], t: number): Word[] {
+  return words.map((w): Word => {
+    const start = Math.round(t + w.start * 1000), end = Math.round(t + w.end * 1000)
+    return [start, Math.max(0, end - start), w.text]
+  })
+}
+
+function common(a: readonly string[], b: readonly string[]): [number, number][] {
+  const table = Array.from({ length: a.length + 1 }, () => new Array<number>(b.length + 1).fill(0))
+  for (let i = a.length - 1; i >= 0; i--) {
+    for (let j = b.length - 1; j >= 0; j--) table[i]![j] = a[i] === b[j] ? table[i + 1]![j + 1]! + 1 : Math.max(table[i + 1]![j]!, table[i]![j + 1]!)
+  }
+  const pairs: [number, number][] = []
+  for (let i = 0, j = 0; i < a.length && j < b.length;) {
+    if (a[i] === b[j]) pairs.push([i++, j++])
+    else if (table[i + 1]![j]! >= table[i]![j + 1]!) i++
+    else j++
+  }
+  return pairs
+}
+
+export function realign(utterance: Utterance, text: string): { utterance: Utterance, anchor: (offset: number) => number } {
+  const before = utterance.words ?? []
+  const next = splitWords(text)
+  if (before.length === 0) {
+    const [from, to] = [Math.max(1, [...utterance.text].length), Math.max(1, [...text].length)]
+    return { utterance: { ...utterance, text, alignment: 'proportional' }, anchor: offset => Math.round(offset * to / from) }
+  }
+  const pairs = common(before.map(w => w[2]), next.map(w => w.text))
+  const kept = new Map(pairs.map(([i, j]) => [j, i]))
+  const end = utterance.t + utterance.d
+  const words: Word[] = []
+  for (let j = 0; j < next.length;) {
+    const old = kept.get(j)
+    if (old !== undefined) {
+      words.push([before[old]![0], before[old]![1], next[j]!.text])
+      j++
+      continue
+    }
+    let k = j
+    while (k < next.length && !kept.has(k)) k++
+    const from = words.length ? words.at(-1)![0] + words.at(-1)![1] : utterance.t
+    const until = k < next.length ? before[kept.get(k)!]![0] : end
+    const span = Math.max(0, until - from)
+    const chars = next.slice(j, k).map(w => [...w.text].length)
+    const total = chars.reduce((a, b) => a + b, 0)
+    let at = from
+    for (let n = j; n < k; n++) {
+      const d = Math.round(span * chars[n - j]! / total)
+      words.push([at, d, next[n]!.text])
+      at += d
+    }
+    j = k
+  }
+  const anchor = (offset: number) => {
+    if (offset >= before.length) return next.length
+    const pair = pairs.find(([i]) => i >= offset)
+    if (pair && pair[0] === offset) return pair[1]
+    const previous = [...pairs].reverse().find(([i]) => i < offset)
+    return Math.min(next.length, previous ? previous[1] + 1 : 0)
+  }
+  return { utterance: { ...utterance, text, words, alignment: 'proportional' }, anchor }
+}
+
+export function reanchor(text: string, before: readonly Word[], after: readonly Word[]): (offset: number) => number {
+  const old = locate(before.map(w => w[2]), text)
+  const now = locate(after.map(w => w[2]), text)
+  return (offset) => {
+    if (offset >= before.length) return after.length
+    const place = old[offset]
+    if (!place || !now.every(Boolean)) return Math.min(offset, after.length)
+    let index = 0
+    now.forEach((p, i) => {
+      if (p!.start <= place.start) index = i
+    })
+    return index
+  }
+}

package/src/domain/writeback.ts

@@ -0,0 +1,129 @@
+import { irBlocks } from '@lincyaw/kernel'
+import type { IRDocument, SourceRange } from '@lincyaw/kernel'
+import type { LecturePlan } from './plan.ts'
+import { anchorOf } from './timing.ts'
+import type { LectureTrack, Utterance } from './track.ts'
+import { isWide, locate } from './words.ts'
+
+function optionValue(value: string): string {
+  return /^[^\s"'{}=]+$/.test(value) ? value : `"${value.replace(/"/g, '\'')}"`
+}
+
+function formatCue(command: string, options: Record<string, string | number | undefined> = {}): string {
+  const written = Object.entries(options).filter(([, v]) => v !== undefined && v !== '').map(([key, v]) => ` ${key}=${optionValue(String(v))}`).join('')
+  return `{cue${written}}\`${command}\``
+}
+
+const text = (value: unknown) => (typeof value === 'string' && value ? value : undefined)
+
+function blockIdOf(key: unknown): string | undefined {
+  const value = text(key)
+  return value?.includes('/') ? value.slice(value.indexOf('/') + 1) : undefined
+}
+
+const SELECTOR = /^\[data-section="[^"]*"\] \.pm-block\[data-block="([^"]+)"\]\s*(.*)$/
+
+export function cueFor(type: string, data: Record<string, unknown>, at: { section?: string, step: number }): string | undefined {
+  const block = blockIdOf(data.block)
+  switch (type) {
+    case 'go':
+      return data.section === at.section && typeof data.step === 'number' && data.step > at.step ? formatCue('next') : undefined
+    case 'spot':
+    case 'hint': {
+      const selected = SELECTOR.exec(text(data.selector) ?? '')
+      if (selected) return formatCue(type, { to: selected[1], sel: selected[2] })
+      return block ? formatCue(type, { to: block, lines: text(data.lines) }) : undefined
+    }
+    case 'point':
+      return block ? formatCue('point', { to: block, lines: typeof data.line === 'number' ? data.line : undefined }) : undefined
+    case 'ink':
+      return block && !data.clear ? formatCue('ink', { to: block, lines: text(data.lines) }) : undefined
+    case 'run':
+      return text(data.block) ? formatCue('run', { to: text(data.block) }) : undefined
+    case 'click':
+      return block && text(data.action) ? formatCue(`click ${text(data.action)}`, { to: block }) : undefined
+    case 'mark':
+      return text(data.label) ? formatCue(`mark ${text(data.label)}`) : undefined
+    case 'pause':
+      return typeof data.ms === 'number' && data.ms > 0 && !data.hold ? formatCue(`pause ${Math.round(data.ms)}ms`) : undefined
+    default:
+      return undefined
+  }
+}
+
+function textOffsetAt(u: Utterance, offset: number): number {
+  const words = u.words ?? []
+  if (words.length === 0) return [...u.text].slice(0, Math.max(0, offset)).join('').length
+  if (offset >= words.length) return u.text.length
+  const located = locate(words.map(w => w[2]), u.text)[Math.max(0, offset)]
+  return located?.start ?? Math.round(u.text.length * offset / words.length)
+}
+
+function joined(parts: string[]): string {
+  return parts.reduce((all, part) => (!all ? part : isWide(all.at(-1)) || isWide(part[0]) ? all + part : `${all} ${part}`), '')
+}
+
+export interface DraftStep {
+  step: number
+  draft: string
+  utterances: string[]
+}
+
+export interface DraftSection {
+  section: string
+  steps: DraftStep[]
+}
+
+export interface NarrationDraft {
+  sections: DraftSection[]
+  skipped: number
+}
+
+export function narrationDraft(track: LectureTrack, section?: string): NarrationDraft {
+  const utterances = new Map(track.utterances.map(u => [u.id, u]))
+  const cues = new Map<string, { offset: number, role: string, index: number }[]>()
+  let skipped = 0
+  track.events.forEach(([, type, data], index) => {
+    const at = anchorOf(data)
+    const u = at && utterances.get(at[0])
+    if (!u) return
+    const role = cueFor(type, data, { section: u.section, step: u.step ?? 0 })
+    if (!role) {
+      if (type !== 'go') skipped++
+      return
+    }
+    cues.set(u.id, [...cues.get(u.id) ?? [], { offset: textOffsetAt(u, at![1]), role, index }])
+  })
+  const said = (u: Utterance) => (cues.get(u.id) ?? [])
+    .sort((a, b) => b.offset - a.offset || b.index - a.index)
+    .reduce((written, cue) => written.slice(0, cue.offset) + cue.role + written.slice(cue.offset), u.text)
+  const sections: DraftSection[] = []
+  for (const u of [...track.utterances].sort((a, b) => a.t - b.t)) {
+    if (!u.section || (section && u.section !== section)) continue
+    let entry = sections.find(s => s.section === u.section)
+    if (!entry) sections.push(entry = { section: u.section, steps: [] })
+    const step = u.step ?? 0
+    let at = entry.steps.find(s => s.step === step)
+    if (!at) entry.steps.push(at = { step, draft: '', utterances: [] })
+    at.utterances.push(u.id)
+    at.draft = joined([at.draft, said(u)])
+  }
+  for (const entry of sections) entry.steps.sort((a, b) => a.step - b.step)
+  return { sections, skipped }
+}
+
+export interface NarrationSource {
+  narration: SourceRange[]
+  after?: SourceRange & { block: string }
+}
+
+export function narrationSource(doc: IRDocument, plan: LecturePlan, section: string, step: number): NarrationSource {
+  const planned = plan.sections.find(s => s.id === section)
+  const ir = doc.sections.find(s => s.id === section)
+  if (!planned || !ir) return { narration: [] }
+  const range = (source: { file: string, line: number, endLine?: number }): SourceRange => ({ file: source.file, startLine: source.line, endLine: source.endLine ?? source.line })
+  const narration = planned.paragraphs.filter(p => p.source && planned.webStep(p.step) === step).map(p => range(p.source!))
+  if (narration.length > 0) return { narration }
+  const block = [...irBlocks(ir.blocks)].filter(b => b.role === 'visual' && planned.webStep(b.at) <= step).at(-1)
+  return { narration, ...block ? { after: { block: block.id, ...range(block.source) } } : {} }
+}

package/src/node/audio-authoring.ts

@@ -0,0 +1,53 @@
+import { ProductionAudioRefusal } from '@lincyaw/kernel'
+import type { NodeServiceContext, ProductionAudioAuthoring } from '@lincyaw/kernel'
+import { irRevision } from '@lincyaw/kernel/node'
+import { placeProductionAudio } from '../domain/production-audio.ts'
+import { latestDoc } from './latest-ir.ts'
+import { inspectProductionAsset, inspectProductionAssets, inspectProductionAudioBytes } from './production-assets.ts'
+import { productionSnapshot } from './production.ts'
+import { createServedDeck, RouteRefusal } from './routes/served-deck.ts'
+import { assertVoiceSource, VoiceSourceRefusal } from './voice-source.ts'
+
+/** The workspace owns authoring and history; this service supplies real media and timing judgments. */
+export function productionAudioAuthoring(ctx: NodeServiceContext): ProductionAudioAuthoring {
+  const served = createServedDeck({ ...ctx, service: token => ctx.service?.(token) })
+  return {
+    inspectBytes: inspectProductionAudioBytes,
+    async inspectAsset(asset, signal) {
+      return (await inspectProductionAsset({ productionAssets: { [asset.id]: asset } }, ctx.deckDir, asset.id, signal)).asset
+    },
+    async readPlan(query, signal) {
+      try {
+        const doc = latestDoc(ctx.deckDir)
+        if (!doc) throw new ProductionAudioRefusal(503, 'production-document-unavailable')
+        const revision = irRevision(doc)
+        if (query.irRevision !== undefined && query.irRevision !== revision) throw new ProductionAudioRefusal(409, 'production-revision-changed')
+        return (await productionSnapshot(served, { source: query.source, irRevision: revision }, signal)).plan
+      }
+      catch (error) {
+        if (error instanceof RouteRefusal) throw new ProductionAudioRefusal(error.status, error.message)
+        if (error instanceof VoiceSourceRefusal) throw new ProductionAudioRefusal(409, error.message)
+        throw error
+      }
+    },
+    async validateClips(binding, clips, assets, signal) {
+      try {
+        const snapshot = await productionSnapshot(served, { source: binding.source, irRevision: binding.irRevision }, signal)
+        if (snapshot.plan.binding.planId !== binding.planId) throw new ProductionAudioRefusal(409, 'production-plan-changed')
+        const doc = latestDoc(ctx.deckDir)
+        if (!doc || irRevision(doc) !== binding.irRevision) throw new ProductionAudioRefusal(409, 'production-revision-changed')
+        const candidate = { ...doc, production: { defaults: {}, stepOverrides: {}, ...doc.production, mediaClips: clips }, productionAssets: assets }
+        const inspected = await inspectProductionAssets(candidate, ctx.deckDir, signal)
+        const placed = placeProductionAudio(candidate, snapshot.plan.pages, new Map([...inspected.assets].map(([id, file]) => [id, file.asset])), inspected.errors)
+        if (placed.issues.length) throw new ProductionAudioRefusal(422, placed.issues[0]!.code)
+        await assertVoiceSource(doc, ctx.deckDir, binding.source)
+        if (latestDoc(ctx.deckDir) !== doc) throw new ProductionAudioRefusal(409, 'production-revision-changed')
+        signal?.throwIfAborted()
+      } catch (error) {
+        if (error instanceof RouteRefusal) throw new ProductionAudioRefusal(error.status, error.message)
+        if (error instanceof VoiceSourceRefusal) throw new ProductionAudioRefusal(409, error.message)
+        throw error
+      }
+    },
+  }
+}

package/src/node/check.ts

@@ -0,0 +1,93 @@
+import { deckLocale, errorMessage, SPEECH } from '@lincyaw/kernel'
+import type { Check, CheckContext, Finding, IRDocument, Severity } from '@lincyaw/kernel'
+import { blockOf, clockText, eventDrift, eventLine, LECTURE_ID, LECTURE_MESSAGES, plannedUtterances, unchanged } from '../domain/index.ts'
+import type { EventDrift } from '../domain/index.ts'
+import { lectureView } from './latest-ir.ts'
+import { deckPlan } from './plan.ts'
+import { readTrack, trackIds } from './store.ts'
+import { synthesizeClip, synthesizeLecture } from './synthesize.ts'
+
+const SEVERITY: Record<EventDrift['grade'], Severity> = { exact: 'info', moved: 'info', fuzzy: 'warning', lost: 'warning' }
+
+const HINTS: Partial<Record<EventDrift['grade'], string>> = {
+  lost: 'playback skips this event; give blocks a lecture refers to a label, or record the section again',
+  moved: 'playback follows the block to its new place',
+}
+
+function what(type: string, drift: EventDrift): string {
+  const target = drift.block ?? (typeof drift.data.section === 'string' ? `section ${drift.data.section}` : '')
+  switch (drift.reason) {
+    case 'section': return `${type} goes to ${target}, which the deck no longer has (lost)`
+    case 'steps': return `${type} goes to step ${String(drift.data.step)} of ${target}, which has fewer steps now`
+    case 'lines': return `${type} on ${target} names lines (${String(drift.data.lines ?? drift.data.line)}) the block no longer has (lost)`
+    case 'at': return `${type} is bound to utterance ${String((drift.data.at as unknown[])[0])}, which the track no longer has`
+    default:
+      if (drift.grade === 'moved') return `${type} on ${target}: the block moved to ${blockOf(drift.data)}`
+      if (drift.grade === 'fuzzy') return `${type} on ${target}: the block changed since the recording (fuzzy)`
+      return `${type} on ${target}, which the deck no longer has (lost)`
+  }
+}
+
+export function trackFindings(deckDir: string, id: string, doc: IRDocument): Finding[] {
+  let stored
+  try {
+    stored = readTrack(deckDir, id)
+  } catch (error) {
+    return [{ checkId: LECTURE_ID, severity: 'error', message: `lecture ${id}: ${errorMessage(error)}` }]
+  }
+  if (!stored) return []
+  const { track, text, file, problems } = stored
+  const findings: Finding[] = problems.map(message => ({ checkId: LECTURE_ID, severity: 'warning', message: `lecture ${id}: ${message}`, source: { file } }))
+  if (unchanged(track, doc)) return findings
+  for (const drift of eventDrift(track, doc)) {
+    if (drift.grade === 'exact') continue
+    const [t, type] = track.events[drift.index]!
+    findings.push({
+      checkId: LECTURE_ID,
+      severity: SEVERITY[drift.grade],
+      message: `lecture ${id} at ${clockText(t)} (${t} ms): ${what(type, drift)}`,
+      source: { file, line: eventLine(text, drift.index) },
+      ...HINTS[drift.grade] ? { hint: HINTS[drift.grade] } : {},
+    })
+  }
+  return findings
+}
+
+async function planFindings(ctx: CheckContext): Promise<Finding[]> {
+  const view = lectureView(ctx.ir)
+  const deck = deckPlan(view)
+  const findings = [...deck.findings]
+  const prepared = view.production?.mediaClips.length || Object.keys(view.production?.captionTimings ?? {}).length || deck.recorded ? await synthesizeLecture(view, ctx.deckDir, ctx.service?.(SPEECH), undefined, { cacheOnly: true }) : undefined
+  findings.push(...(prepared?.mediaDiagnostics ?? []).map(issue => ({ checkId: LECTURE_ID, severity: issue.severity, message: issue.message, source: { file: ctx.ir.meta.entry, line: 1 } })))
+  findings.push(...(prepared?.captionDiagnostics ?? []).map(issue => ({ checkId: LECTURE_ID, severity: issue.severity, message: issue.message, source: { file: ctx.ir.meta.entry, line: 1 } })))
+  if (!deck.voice) return findings
+  const speech = ctx.service?.(SPEECH)
+  const source = { file: ctx.ir.meta.entry, line: 1 }, t = LECTURE_MESSAGES[deckLocale(ctx.ir.meta.lang)].production
+  if (!speech) {
+    findings.push({ checkId: LECTURE_ID, severity: 'error', message: t.missingSpeech, source })
+    return findings
+  }
+  for (const u of plannedUtterances(deck.plan)) {
+    if (u.sourceKind === 'none' || u.sourceKind === 'recording') continue
+    try {
+      if (u.voiceIssue) throw new Error(u.voiceIssue)
+      if (prepared) { const failure = prepared.failures.find(failure => failure.id === u.id); if (failure) throw new Error(failure.reason) }
+      else await synthesizeClip(speech, u, { voice: u.voice ?? deck.voice, lang: deck.lang, ...deck.lexicon ? { lexicon: deck.lexicon } : {}, cacheOnly: true })
+    } catch (error) {
+      const text = u.text.length > 40 ? `${u.text.slice(0, 40)}…` : u.text
+      findings.push({
+        checkId: LECTURE_ID,
+        severity: 'error',
+        message: t.cacheMissing(text, u.section, t.reasons[errorMessage(error)] ?? t.reasonGeneric),
+        source: u.source ? { file: u.source.file, line: u.source.line } : source,
+        hint: t.generateHint,
+      })
+    }
+  }
+  return findings
+}
+
+export const lectureCheck: Check = {
+  id: LECTURE_ID,
+  run: async ctx => [...trackIds(ctx.deckDir).flatMap(id => trackFindings(ctx.deckDir, id, ctx.ir)), ...await planFindings(ctx)],
+}

package/src/node/cli.ts

@@ -0,0 +1,82 @@
+import { existsSync, statSync } from 'node:fs'
+import { isAbsolute, join, relative } from 'node:path'
+import { parseArgs } from 'node:util'
+import { DECK_ENTRY } from '@lincyaw/compiler'
+import { errorMessage } from '@lincyaw/kernel'
+import { clockText } from '../domain/index.ts'
+import { exportVideo } from './export.ts'
+
+const USAGE = `Usage: presmium-lecture export [deckDir] [--track <id>] [--out <file.mp4|file.webm>] [--size <width>x<height>] [--fps <n>] [--burn <lang>]
+
+Builds the deck's web form and lectures, plays the lecture in Chromium
+(playwright-chromium) a frame at a time and writes it with its audio and a
+subtitle track for each language of its captions, and the captions next to it
+(<file>.<lang>.vtt). With FFmpeg (on the path, or PRESMIUM_FFMPEG) the video is
+MP4 (H.264, AAC) or WebM (VP9, Opus) as --out names it; without it the browser
+writes WebM only, at a lower quality, and the export says how to install it. The
+animations follow the lecture's time frame by frame. --track names the
+lecture (default: the synthesized one, else the only recorded one); --out the
+file (default <deckDir>/dist/<track>.mp4, .webm without FFmpeg); --size the window (default
+1920x1080); --fps the frames a second (default 30); --burn draws the captions
+in that language on the picture.`
+
+function shown(file: string): string {
+  const rel = relative(process.cwd(), file)
+  return rel.startsWith('..') || isAbsolute(rel) ? file : rel
+}
+
+export async function main(argv: string[]): Promise<number> {
+  let args
+  try {
+    args = parseArgs({
+      args: argv,
+      allowPositionals: true,
+      options: { track: { type: 'string' }, out: { type: 'string', short: 'o' }, size: { type: 'string' }, fps: { type: 'string' }, burn: { type: 'string' }, help: { type: 'boolean', short: 'h' } },
+    })
+  } catch (error) {
+    console.error(`${errorMessage(error)}\n\n${USAGE}`)
+    return 2
+  }
+  const { values, positionals } = args
+  if (values.help) {
+    console.log(USAGE)
+    return 0
+  }
+  const [command, deck = '.', ...rest] = positionals
+  if (command !== 'export' || rest.length > 0) {
+    console.error(USAGE)
+    return 2
+  }
+  const size = values.size === undefined ? undefined : /^(\d+)x(\d+)$/.exec(values.size)
+  const fps = values.fps === undefined ? undefined : Number(values.fps)
+  if (size === null || (fps !== undefined && !(fps > 0 && fps <= 60))) {
+    console.error(`--size takes <width>x<height> and --fps a number from 1 to 60\n\n${USAGE}`)
+    return 2
+  }
+  if (values.out && !/\.(mp4|webm)$/i.test(values.out)) {
+    console.error(`presmium-lecture export writes MP4 or WebM (--out <file>.mp4 or <file>.webm)`)
+    return 2
+  }
+  if (!existsSync(deck) || !statSync(deck).isDirectory() || !existsSync(join(deck, DECK_ENTRY))) {
+    console.error(`no ${DECK_ENTRY} in ${deck}\n\n${USAGE}`)
+    return 2
+  }
+  try {
+    const result = await exportVideo({
+      deckDir: deck,
+      ...values.track ? { track: values.track } : {},
+      ...values.out ? { out: values.out } : {},
+      ...size ? { width: Number(size[1]), height: Number(size[2]) } : {},
+      ...fps ? { fps } : {},
+      ...values.burn ? { burn: values.burn } : {},
+      log: line => console.error(line),
+    })
+    result.warnings.forEach(w => console.error(`warning: ${w}`))
+    console.log(`exported ${shown(result.file)} (lecture ${result.track}, ${clockText(result.duration)}, ${result.frames} frames)`)
+    for (const { file } of result.captions) console.log(`captions ${shown(file)}`)
+    return 0
+  } catch (error) {
+    console.error(`presmium-lecture: ${errorMessage(error)}`)
+    return 2
+  }
+}

package/src/node/clips.ts

@@ -0,0 +1,10 @@
+import { basename } from 'node:path'
+import type { SpeechService, Synthesis } from '@lincyaw/kernel'
+import { CLIP_FILE } from '../domain/index.ts'
+
+export async function cachedClip(speech: SpeechService, name: string, signal?: AbortSignal): Promise<(Synthesis & { audio: string }) | undefined> {
+  if (!CLIP_FILE.test(name)) return undefined
+  if (!speech.cached) throw new Error('the speech service cannot look a clip up in its cache')
+  const found = await speech.cached(name.replace(/\.\w+$/, ''), signal)
+  return found && typeof found.audio === 'string' && basename(found.audio) === name ? { ...found, audio: found.audio } : undefined
+}

package/src/node/engines.ts

@@ -0,0 +1,43 @@
+import { isRecord, speechEngineId } from '@lincyaw/kernel'
+import type { IRDocument, SpeechEngineInfo, SpeechService } from '@lincyaw/kernel'
+
+export function sameEngine(a: string, b: string): boolean {
+  return speechEngineId(a) === speechEngineId(b)
+}
+
+function speechConfig(doc: IRDocument | undefined): Record<string, unknown> {
+  const config = doc?.config.presmium['presmium.speech']
+  return isRecord(config) ? config : {}
+}
+
+function setting(doc: IRDocument | undefined, key: 'transcribe' | 'engine'): string | undefined {
+  const value = speechConfig(doc)[key]
+  return typeof value === 'string' && value.length > 0 ? value : undefined
+}
+
+/**
+ * The engine that transcribes the document's recordings: the one presmium.speech.transcribe names, else
+ * its default engine (presmium.speech.engine) when that one transcribes, else the first that does.
+ */
+export async function transcriptionEngine(speech: SpeechService, doc: IRDocument | undefined): Promise<SpeechEngineInfo | undefined> {
+  const engines = (await speech.engines()).filter(e => e.stt)
+  const named = setting(doc, 'transcribe')
+  if (named) return engines.find(e => sameEngine(e.id, named))
+  const preferred = setting(doc, 'engine')
+  return (preferred && engines.find(e => sameEngine(e.id, preferred))) || engines[0]
+}
+
+/** Why the document has no transcription engine. */
+export function whyNoTranscriptionEngine(doc: IRDocument | undefined): string {
+  const named = setting(doc, 'transcribe')
+  return named
+    ? `presmium.speech.transcribe names speech engine "${named}", which is not defined or does not transcribe; name an engine that transcribes`
+    : 'no speech engine transcribes: the operator defines one (PRESMIUM_SPEECH_<ID>_URL and _PROVIDER)'
+}
+
+export async function synthesisEngine(speech: SpeechService, doc: IRDocument | undefined, engine?: string): Promise<SpeechEngineInfo | undefined> {
+  const config = speechConfig(doc)
+  const named = [engine, config.engine].find((v): v is string => typeof v === 'string' && v.length > 0)
+  const engines = (await speech.engines()).filter(e => e.tts)
+  return named ? engines.find(e => sameEngine(e.id, named)) : engines[0]
+}