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

package/src/node/routes/served-deck.ts

@@ -0,0 +1,61 @@
+import { DOCUMENT_FILES, SPEECH } from '@lincyaw/kernel'
+import type { ServerContext, SpeechService } from '@lincyaw/kernel'
+import { configuredLectureVoice } from '../../domain/index.ts'
+import type { LectureTrack, LectureVoice } from '../../domain/index.ts'
+import { latestDoc } from '../latest-ir.ts'
+import { deckFiles, mediaPolicy, readTrack, trackDir } from '../store.ts'
+import type { DeckFiles, MediaPolicy } from '../store.ts'
+
+export class RouteRefusal extends Error {
+  readonly status: number
+
+  constructor(status: number, message: string) {
+    super(message)
+    this.status = status
+  }
+}
+
+export interface ServedDeck {
+  ctx: ServerContext
+  deckDir: string
+  files: DeckFiles
+  policy: MediaPolicy
+  speech(): SpeechService
+  configuredVoice(): LectureVoice | undefined
+  findStoredTrack(id: string): LectureTrack | undefined
+  getStoredTrack(id: string): LectureTrack
+}
+
+export function createServedDeck(ctx: ServerContext): ServedDeck {
+  const { deckDir } = ctx
+  const findStoredTrack = (id: string) => (trackDir(deckDir, id) ? readTrack(deckDir, id)?.track : undefined)
+  return {
+    ctx,
+    deckDir,
+    files: deckFiles(ctx.workspaceRoot, () => ctx.service(DOCUMENT_FILES)),
+    policy: mediaPolicy(ctx.settings),
+    speech() {
+      const found = ctx.service(SPEECH)
+      if (!found) throw new RouteRefusal(503, 'no speech service: add @lincyaw/addon-speech to the deck\'s plugins')
+      return found
+    },
+    configuredVoice() {
+      const doc = latestDoc(deckDir)
+      return doc ? configuredLectureVoice(doc) : undefined
+    },
+    findStoredTrack,
+    getStoredTrack(id) {
+      const track = findStoredTrack(id)
+      if (!track) throw new RouteRefusal(404, `no lecture ${id}`)
+      return track
+    },
+  }
+}
+
+export function decodedPath(segments: string[]): string {
+  try {
+    return segments.map(decodeURIComponent).join('/')
+  } catch {
+    return ''
+  }
+}

package/src/node/routes/server.ts

@@ -0,0 +1,12 @@
+import type { ServerContext, ServerContribution } from '@lincyaw/kernel'
+import { productionRoutes } from './production.ts'
+import { recordingRoutes } from './recordings.ts'
+import { createServedDeck } from './served-deck.ts'
+import { trackRoutes } from './tracks.ts'
+import { voiceoverRoutes } from './voiceover.ts'
+
+export function lectureServer(ctx: ServerContext): ServerContribution {
+  const served = createServedDeck(ctx)
+  const voiceover = voiceoverRoutes(served)
+  return { routes: { ...trackRoutes(served), ...productionRoutes(served), ...recordingRoutes(served), ...voiceover.routes }, close: voiceover.close }
+}

package/src/node/routes/tracks.ts

@@ -0,0 +1,98 @@
+import { existsSync } from 'node:fs'
+import { irRevision } from '@lincyaw/kernel/node'
+import { errorMessage, jsonResponse, problemResponse } from '@lincyaw/kernel'
+import type { Route } from '@lincyaw/kernel'
+import { CLIPS_DIR, SCRIPT_TRACK, trackDuration } from '../../domain/index.ts'
+import type { LectureTrack, MediaSegment } from '../../domain/index.ts'
+import { cachedClip } from '../clips.ts'
+import { latestDoc } from '../latest-ir.ts'
+import { mediaFile, publishedMedia, trackIds } from '../store.ts'
+import { productionSnapshot } from '../production.ts'
+import { deckPlan } from '../plan.ts'
+import { serveFile } from './serve-file.ts'
+import { decodedPath, RouteRefusal } from './served-deck.ts'
+import type { ServedDeck } from './served-deck.ts'
+
+const RECENT_CLIP_SETS = 8
+
+export function trackRoutes(served: ServedDeck): Record<string, Route> {
+  const { deckDir } = served
+
+  const recentClipSets = new Map<string, Set<string>>()
+  const synthesizeScriptTrack = async (request: Request): Promise<LectureTrack> => {
+    const planId = new URL(request.url).searchParams.get('planId')
+    const doc = latestDoc(deckDir)
+    const expected = planId && doc?.source ? { planId, source: doc.source, irRevision: irRevision(doc) } : undefined
+    const snapshot = await productionSnapshot(served, expected, request.signal)
+    if (snapshot.plan.diagnostics.some(issue => issue.severity === 'error')) throw new RouteRefusal(409, 'production-plan-unavailable')
+    const names = snapshot.track.utterances.flatMap(utterance => utterance.clip ?? []), key = names.join('\n')
+    recentClipSets.delete(key); recentClipSets.set(key, new Set(names))
+    if (recentClipSets.size > RECENT_CLIP_SETS) recentClipSets.delete(recentClipSets.keys().next().value!)
+    return snapshot.track
+  }
+
+  const serveClip = async (id: string, name: string, request: Request): Promise<Response> => {
+    const said = id === SCRIPT_TRACK && served.configuredVoice()
+      ? [...recentClipSets.values()].some(names => names.has(name))
+      : served.findStoredTrack(id)?.utterances.some(u => u.clip === name)
+    if (!said) return problemResponse(404, `no clip ${name} in the lecture ${id}`)
+    let clip
+    try {
+      clip = await cachedClip(served.speech(), name)
+    } catch (error) {
+      if (error instanceof RouteRefusal) return problemResponse(error.status, error.message)
+      return problemResponse(403, `the clip ${name} may not be given: ${errorMessage(error)}`)
+    }
+    if (!clip) return problemResponse(404, `the clip ${name} is not in the synthesis cache`)
+    return serveFile(deckDir, clip.audio, request)
+  }
+
+  const withPublishedMedia = (track: LectureTrack): LectureTrack => {
+    const isLocal = (segment: MediaSegment) => {
+      const file = mediaFile(deckDir, track.id, segment.src)
+      return Boolean(file && existsSync(file))
+    }
+    const audio = publishedMedia(track.audio, track.id, served.policy, isLocal)
+    const video = publishedMedia(track.video, track.id, served.policy, isLocal)
+    return { ...track, ...audio ? { audio } : {}, ...video ? { video } : {} }
+  }
+
+  const serveTrackFile = (id: string, path: string[], request: Request): Promise<Response> | Response => {
+    if (path[0] === CLIPS_DIR && path.length === 2) return serveClip(id, decodedPath(path.slice(1)), request)
+    return serveFile(deckDir, mediaFile(deckDir, id, decodedPath(path)), request)
+  }
+
+  return {
+    'tracks': {
+      role: 'reader',
+      handle() {
+        const doc = latestDoc(deckDir)
+        const voice = served.configuredVoice()
+        const silent = doc && deckPlan(doc).silent
+        const synthetic = (voice || silent) && doc && !deckPlan(doc).findings.some(finding => finding.severity === 'error') ? [{ id: SCRIPT_TRACK, lang: doc.meta.lang ?? 'zh-CN', voice: voice ? { kind: 'synthetic', ...voice } : { kind: 'silent' } }] : []
+        return jsonResponse([...synthetic, ...trackIds(deckDir).filter(id => !((voice || silent) && id === SCRIPT_TRACK)).flatMap((id) => {
+          try {
+            const track = served.findStoredTrack(id)
+            return track ? [{ id, lang: track.lang, voice: track.voice, duration: trackDuration(track), utterances: track.utterances.length }] : []
+          } catch {
+            return []
+          }
+        })])
+      },
+    },
+    'tracks/*': {
+      role: 'reader',
+      async handle(request, { rest }) {
+        const [id = '', ...path] = rest.split('/')
+        try {
+          if (path.length > 0) return await serveTrackFile(id, path, request)
+          if (id === SCRIPT_TRACK && (served.configuredVoice() || latestDoc(deckDir) && deckPlan(latestDoc(deckDir)!).silent)) return jsonResponse(await synthesizeScriptTrack(request))
+          const track = served.findStoredTrack(id)
+          return track ? jsonResponse(withPublishedMedia(track)) : problemResponse(404, `no lecture ${id}`)
+        } catch (error) {
+          return problemResponse(error instanceof RouteRefusal ? error.status : 500, errorMessage(error))
+        }
+      },
+    },
+  }
+}

package/src/node/routes/voiceover.ts

@@ -0,0 +1,23 @@
+import { DOCUMENT_VOICE_TASKS } from '@lincyaw/kernel'
+import type { DocumentVoiceTasks, ServerContribution } from '@lincyaw/kernel'
+import { createVoiceoverOwner, createVoiceoverRoutes } from '@lincyaw/kernel/node'
+import { voiceoverExecution } from '../voiceover-execution.ts'
+import type { ServedDeck } from './served-deck.ts'
+
+/** Workspace contributions borrow its owner; standalone servers own the same coordinator factory. */
+export function voiceoverRoutes(served: ServedDeck): ServerContribution {
+  const borrowed = served.ctx.service(DOCUMENT_VOICE_TASKS)
+  if (borrowed) return { routes: createVoiceoverRoutes(borrowed) }
+  const owner = createVoiceoverOwner(), execution = voiceoverExecution(served.ctx), load = async () => execution
+  const service: DocumentVoiceTasks = {
+    snapshot: (_document, query, _member, signal) => owner.snapshot(query, load, signal),
+    listJobs: async document => ({ document, jobs: owner.list().map(job => ({ ...job, current: 'unknown' as const })), idempotency: 'process', limits: owner.limits }),
+    getJob: async (_document, query) => ({ ...owner.get(query), current: 'unknown' }),
+    start: (_document, request, _member, signal) => owner.start(request, load, signal),
+    cancel: async (_document, query) => owner.cancel(query),
+    quotePreview: (_document, query, _member, signal) => owner.quote(query, load, signal),
+    preview: (_document, request, _member, signal) => owner.preview(request, signal),
+    readPreview: async (_document, id) => owner.readPreview(id),
+  }
+  return { routes: createVoiceoverRoutes(service), close: () => owner.close() }
+}

package/src/node/store.ts

@@ -0,0 +1,192 @@
+import { createHash } from 'node:crypto'
+import { closeSync, constants, createReadStream, existsSync, fstatSync, mkdirSync, openSync, readdirSync, readFileSync, readlinkSync, realpathSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { open } from 'node:fs/promises'
+import { dirname, join, relative, sep } from 'node:path'
+import { ABSOLUTE_URL } from '@lincyaw/kernel'
+import type { DocumentFiles } from '@lincyaw/kernel'
+import { isInside } from '@lincyaw/kernel/node'
+import { formatTrack, LECTURES_DIR, parseTrack, TRACK_ID } from '../domain/index.ts'
+import type { LectureTrack, MediaSegment } from '../domain/index.ts'
+
+export interface DeckFiles {
+  write(file: string, content: string | Uint8Array, at?: number): Promise<void>
+  remove(file: string): Promise<void>
+}
+
+export function deckFiles(workspaceRoot: string, documentFiles: () => DocumentFiles | undefined): DeckFiles {
+  const path = (file: string) => relative(workspaceRoot, file).split(sep).join('/')
+  const bytes = (content: string | Uint8Array) => (typeof content === 'string' ? Buffer.from(content) : content)
+  return {
+    async write(file, content, at) {
+      const files = documentFiles()
+      if (files) return files.write([{ path: path(file), content: bytes(content), ...at !== undefined ? { at } : {} }])
+      mkdirSync(dirname(file), { recursive: true })
+      if (at === undefined) return writeFileSync(file, content)
+      const handle = await open(file, existsSync(file) ? 'r+' : 'w+')
+      try {
+        const data = bytes(content)
+        await handle.write(data, 0, data.byteLength, at)
+      } finally {
+        await handle.close()
+      }
+    },
+    async remove(file) {
+      const files = documentFiles()
+      if (files) return files.write([{ path: path(file), remove: true }])
+      rmSync(file, { force: true })
+    },
+  }
+}
+
+export const TRACK_FILE = 'track.json'
+
+const MEDIA_PATH = /^(audio|video)\/[^/\\]+\.(ogg|opus|webm|mp4|m4a|wav|mp3)$/
+
+export function lecturesDir(deckDir: string): string {
+  return join(deckDir, LECTURES_DIR)
+}
+
+export function trackDir(deckDir: string, id: string): string | undefined {
+  return TRACK_ID.test(id) ? join(lecturesDir(deckDir), id) : undefined
+}
+
+export function mediaFile(deckDir: string, id: string, path: string): string | undefined {
+  const dir = trackDir(deckDir, id)
+  if (!dir || !MEDIA_PATH.test(path) || path.split('/').some(part => part === '..' || part.startsWith('.'))) return undefined
+  const file = join(dir, path)
+  return relative(dir, file).split(sep)[0] === path.split('/')[0] ? file : undefined
+}
+
+export interface StoredTrack {
+  track: LectureTrack
+  text: string
+  file: string
+  problems: string[]
+}
+
+const OPEN_FLAGS = constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0)
+
+function openedPath(fd: number, expected: string): string | undefined {
+  try {
+    return readlinkSync(`/proc/self/fd/${fd}`)
+  } catch {
+    try {
+      const opened = fstatSync(fd)
+      const now = statSync(expected)
+      return realpathSync(expected) === expected && now.dev === opened.dev && now.ino === opened.ino ? expected : undefined
+    } catch {
+      return undefined
+    }
+  }
+}
+
+export function openInDeck(deckDir: string, file: string): number | undefined {
+  let expected: string
+  try {
+    const rel = relative(deckDir, file)
+    if (!rel || !isInside(file, deckDir) || rel.split(sep).includes('.git')) return undefined
+    expected = join(realpathSync(deckDir), rel)
+  } catch {
+    return undefined
+  }
+  let fd: number
+  try {
+    fd = openSync(file, OPEN_FLAGS)
+  } catch {
+    return undefined
+  }
+  try {
+    if (fstatSync(fd).isFile() && openedPath(fd, expected) === expected) return fd
+  } catch {
+  }
+  closeSync(fd)
+  return undefined
+}
+
+export function readInDeck(deckDir: string, file: string): Buffer | undefined {
+  const fd = openInDeck(deckDir, file)
+  if (fd === undefined) return undefined
+  try {
+    return readFileSync(fd)
+  } catch {
+    return undefined
+  } finally {
+    closeSync(fd)
+  }
+}
+
+export function readTrack(deckDir: string, id: string): StoredTrack | undefined {
+  const dir = trackDir(deckDir, id)
+  const file = dir && join(dir, TRACK_FILE)
+  const bytes = file ? readInDeck(deckDir, file) : undefined
+  if (!file || !bytes) return undefined
+  const text = bytes.toString('utf8')
+  const { track, problems } = parseTrack(JSON.parse(text))
+  if (!track) throw new Error(`${relative(deckDir, file)}: ${problems.join('; ')}`)
+  return { track, text, file, problems }
+}
+
+export function trackIds(deckDir: string): string[] {
+  const dir = lecturesDir(deckDir)
+  if (!existsSync(dir)) return []
+  return readdirSync(dir, { withFileTypes: true })
+    .filter(entry => entry.isDirectory() && TRACK_ID.test(entry.name) && existsSync(join(dir, entry.name, TRACK_FILE)))
+    .map(entry => entry.name)
+    .sort()
+}
+
+export async function writeTrack(files: DeckFiles, deckDir: string, track: LectureTrack): Promise<string> {
+  const dir = trackDir(deckDir, track.id)
+  if (!dir) throw new Error(`invalid lecture id ${track.id}`)
+  const file = join(dir, TRACK_FILE)
+  await files.write(file, formatTrack(track))
+  return file
+}
+
+export function newTrackId(deckDir: string, now = new Date()): string {
+  const day = now.toISOString().slice(0, 10)
+  const taken = new Set(existsSync(lecturesDir(deckDir)) ? readdirSync(lecturesDir(deckDir)) : [])
+  if (!taken.has(day)) return day
+  let n = 2
+  while (taken.has(`${day}-${n}`)) n++
+  return `${day}-${n}`
+}
+
+export function freeMediaPath(deckDir: string, id: string, folder: 'audio' | 'video', stem: string, ext: string): string {
+  const dir = trackDir(deckDir, id)!
+  let path = `${folder}/${stem}.${ext}`
+  for (let n = 2; existsSync(join(dir, path)); n++) path = `${folder}/${stem}-${n}.${ext}`
+  return path
+}
+
+export async function sha256File(deckDir: string, file: string): Promise<string | undefined> {
+  const fd = openInDeck(deckDir, file)
+  if (fd === undefined) return undefined
+  const hash = createHash('sha256')
+  for await (const chunk of createReadStream('', { fd })) hash.update(chunk as Buffer)
+  return hash.digest('hex')
+}
+
+export type MediaPolicy = { kind: 'ignore' } | { kind: 'lfs' } | { kind: 'url', prefix: string }
+
+export function mediaPolicy(settings: Record<string, unknown>): MediaPolicy {
+  const audio = settings.audio
+  if (audio === 'lfs') return { kind: 'lfs' }
+  if (typeof audio === 'string' && /^https?:\/\//.test(audio)) return { kind: 'url', prefix: audio.endsWith('/') ? audio : `${audio}/` }
+  return { kind: 'ignore' }
+}
+
+export function publishedMedia<T extends MediaSegment>(segments: T[] | undefined, id: string, policy: MediaPolicy, local: (segment: T) => boolean = () => false): T[] | undefined {
+  if (!segments || policy.kind !== 'url') return segments
+  return segments.map(segment => (ABSOLUTE_URL.test(segment.src) || local(segment) ? segment : { ...segment, src: `${policy.prefix}${id}/${segment.src}` }))
+}
+
+export async function writeGitFiles(files: DeckFiles, dir: string, policy: MediaPolicy): Promise<void> {
+  if (policy.kind === 'lfs') {
+    await files.write(join(dir, '.gitattributes'), 'audio/** filter=lfs diff=lfs merge=lfs -text\nvideo/** filter=lfs diff=lfs merge=lfs -text\n')
+    await files.remove(join(dir, '.gitignore'))
+    return
+  }
+  const why = policy.kind === 'url' ? `published under ${policy.prefix}` : 'kept on this machine'
+  await files.write(join(dir, '.gitignore'), `# Recorded audio and video are ${why} (settings.presmium.lecture.audio).\naudio/\nvideo/\n`)
+}

package/src/node/synthesize.ts

@@ -0,0 +1,190 @@
+import { createHash } from 'node:crypto'
+import { createReadStream } from 'node:fs'
+import { stat } from 'node:fs/promises'
+import { basename, relative } from 'node:path'
+import { errorMessage, recordingSourceRange, remapWords } from '@lincyaw/kernel'
+import type { IRDocument, ProductionDiagnostic, SpeechService, SynthesisRequest, WordSpan, WrittenWord } from '@lincyaw/kernel'
+import { irHash, plannedUtterances, referencedBlocks, SCRIPT_TRACK, scriptTrack, sectionHashes } from '../domain/index.ts'
+import type { Clip, CutAnimation, LecturePlan, LectureTrack, LectureVoice, RecordingClip, Voice } from '../domain/index.ts'
+import type { DeckPlan } from './plan.ts'
+import { deckPlan } from './plan.ts'
+import { applyCaptionTimings } from '../domain/caption-timing.ts'
+import { projectProductionPlan } from '../domain/production.ts'
+import { placeProductionAudio, productionAudioMessage } from '../domain/production-audio.ts'
+import { inspectProductionAssets } from './production-assets.ts'
+import type { ProductionAssetFile } from './production-assets.ts'
+
+export interface SynthesisOptions {
+  voice?: LectureVoice
+  lang: string
+  lexicon?: Record<string, string>
+  alignByTranscription?: boolean
+  cacheOnly?: boolean
+  /** Author generation verifies the canonical source; renderers omit this and remain IR/cache-only. */
+  assertCurrent?: () => Promise<void>
+}
+
+const audioStamp = async (path: string) => { const s = await stat(path); return [s.dev, s.ino, s.size, s.mtimeMs, s.ctimeMs].join(':') }
+
+export interface SynthesizedClip extends Clip {
+  stamp: string
+  path: string
+  key: string
+  engine: string
+  model: string
+  voice: string
+  provider: string
+}
+
+export async function synthesizeClip(speech: SpeechService, said: { text: string, spoken: string, spans: WordSpan[] }, options: SynthesisOptions, signal?: AbortSignal): Promise<SynthesizedClip> {
+  const { voice } = options
+  if (!voice) throw new Error('voice-unset')
+  const request: SynthesisRequest = {
+    ...voice.engine ? { engine: voice.engine } : {},
+    voice: voice.voice,
+    text: said.spoken,
+    lang: options.lang,
+    ...voice.rate !== undefined ? { rate: voice.rate } : {},
+    ...voice.style ? { style: voice.style } : {},
+    ...options.lexicon ? { lexicon: options.lexicon } : {},
+  }
+  const synthesis = options.cacheOnly ? await speech.lookup?.(request, signal) : await speech.synthesize(request, signal)
+  if (!synthesis) throw new Error('voiceover-not-generated')
+  if (typeof synthesis.audio !== 'string') throw new Error('voiceover-cache-missing')
+  const engineWords = synthesis.words?.length
+    ? synthesis.words
+    : await speech.alignWords?.(synthesis.key, { lang: options.lang, transcribe: !options.cacheOnly && options.alignByTranscription !== false }, signal)
+  const words: WrittenWord[] | undefined = engineWords && remapWords(engineWords, said.text, said.spoken, said.spans)
+  const stamp = await audioStamp(synthesis.audio), digest = createHash('sha256')
+  for await (const chunk of createReadStream(synthesis.audio, { signal })) digest.update(chunk)
+  if (await audioStamp(synthesis.audio) !== stamp) throw new Error('production-media-changed')
+  return {
+    stamp, sha256: digest.digest('hex'),
+    file: basename(synthesis.audio),
+    path: synthesis.audio,
+    duration: synthesis.duration,
+    ...words ? { words } : {},
+    key: synthesis.key,
+    engine: synthesis.engine,
+    model: synthesis.model,
+    voice: synthesis.voice,
+    provider: synthesis.provider,
+    speech: { kind: 'synthetic', engine: synthesis.engine, model: synthesis.model, voice: synthesis.voice, provider: synthesis.provider },
+  }
+}
+
+export function clipVoice(clips: Iterable<SynthesizedClip>, fallback: LectureVoice | undefined): Voice {
+  const first = clips[Symbol.iterator]().next().value as SynthesizedClip | undefined
+  if (!first && !fallback) return { kind: 'silent' }
+  return {
+    kind: 'synthetic',
+    engine: first?.engine ?? fallback?.engine ?? '',
+    ...first?.model ? { model: first.model } : {},
+    voice: first?.voice ?? fallback?.voice ?? '',
+    ...first?.provider ? { provider: first.provider } : {},
+  }
+}
+
+export interface SynthesisFailure {
+  id: string
+  section: string
+  text: string
+  source?: { file: string, line: number }
+  reason: string
+}
+
+async function each<T>(items: readonly T[], work: (item: T) => Promise<void>, limit = 4): Promise<void> {
+  let next = 0
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, async () => {
+    while (next < items.length) await work(items[next++]!)
+  }))
+}
+
+export async function synthesizePlan(speech: SpeechService, plan: LecturePlan, options: SynthesisOptions, signal?: AbortSignal): Promise<{ clips: Map<string, SynthesizedClip>, failures: SynthesisFailure[] }> {
+  const clips = new Map<string, SynthesizedClip>()
+  const failures: SynthesisFailure[] = []
+  await each(plannedUtterances(plan), async (u) => {
+    if (u.sourceKind === 'none' || u.sourceKind === 'recording') return
+    await options.assertCurrent?.()
+    if (options.assertCurrent) signal?.throwIfAborted()
+    try {
+      signal?.throwIfAborted()
+      if (u.voiceIssue) throw new Error(u.voiceIssue)
+      const clip = await synthesizeClip(speech, u, { ...options, voice: u.voice ?? options.voice }, signal)
+      await options.assertCurrent?.()
+      if (options.assertCurrent) signal?.throwIfAborted()
+      clips.set(u.id, clip)
+    } catch (error) {
+      await options.assertCurrent?.()
+      if (options.assertCurrent) signal?.throwIfAborted()
+      failures.push({ id: u.id, section: u.section, text: u.text, ...u.source ? { source: { file: u.source.file, line: u.source.line } } : {}, reason: errorMessage(error) })
+    }
+  }, options.assertCurrent ? 1 : 4)
+  await options.assertCurrent?.()
+  if (options.assertCurrent) signal?.throwIfAborted()
+  failures.sort((a, b) => Number(a.id.slice(1)) - Number(b.id.slice(1)))
+  return { clips, failures }
+}
+
+export interface SynthesizedLecture {
+  captionDiagnostics?: ProductionDiagnostic[]
+  deck: DeckPlan
+  /** The lecture, every sentence said; none when one could not be. */
+  track?: LectureTrack
+  /** The lecture to play while some sentences could not be said: those are silent (`Utterance.unsaid`). */
+  preview?: LectureTrack
+  clips: Map<string, SynthesizedClip>
+  failures: SynthesisFailure[]
+  /** Where `{cue}next` moves on before an animation has played. */
+  cuts: CutAnimation[]
+  assets?: Map<string, ProductionAssetFile>
+  mediaDiagnostics?: ProductionDiagnostic[]
+}
+
+export async function synthesizeLecture(doc: IRDocument, deckDir: string, speech: SpeechService | undefined, signal?: AbortSignal, options: Pick<SynthesisOptions, 'cacheOnly' | 'assertCurrent'> = {}): Promise<SynthesizedLecture> {
+  const deck = deckPlan(doc)
+  const clips = new Map<string, SynthesizedClip>()
+  if (!options.cacheOnly && deck.findings.some(finding => finding.severity === 'error')) return { deck, clips, failures: [], cuts: [] }
+  const units = plannedUtterances(deck.plan)
+  const synthesized = speech ? await synthesizePlan(speech, deck.plan, { voice: deck.voice, lang: deck.lang, ...deck.lexicon ? { lexicon: deck.lexicon } : {}, cacheOnly: options.cacheOnly, assertCurrent: options.assertCurrent }, signal) : { clips, failures: units.filter(unit => unit.sourceKind !== 'none' && unit.sourceKind !== 'recording').map(unit => ({ id: unit.id, section: unit.section, text: unit.text, reason: unit.voiceIssue ?? 'speech-unavailable' })) }
+  const assets = await inspectProductionAssets(doc, deckDir, signal)
+  const recordings = new Map<string, RecordingClip>(), recordingDiagnostics: ProductionDiagnostic[] = []
+  for (const section of deck.plan.sections) for (const recording of section.recordings ?? []) {
+    const file = assets.assets.get(recording.assetId)
+    if (!file) {
+      const code = assets.errors.get(recording.assetId) ?? 'production.asset-missing'
+      recordingDiagnostics.push({ code, severity: 'error', message: productionAudioMessage(doc, code), sectionId: section.id, stepId: recording.stepId, assetId: recording.assetId })
+    } else if (!recording.issue) {
+      const range = recordingSourceRange({ type: 'recording', assetId: recording.assetId, sourceRange: recording.sourceRange }, file.asset.durationMs)
+      if (!range) recordingDiagnostics.push({ code: 'production.media-range', severity: 'error', message: productionAudioMessage(doc, 'production.media-range'), sectionId: section.id, stepId: recording.stepId, assetId: recording.assetId })
+      else recordings.set(recording.id, { assetId: recording.assetId, clipId: file.asset.mediaId, src: `audio/${file.asset.mediaId}.${file.extension}`, sha256: file.asset.sha256, durationMs: range.endMs - range.startMs, sourceRange: range })
+    }
+  }
+  const unsaid = new Map(synthesized.failures.map(failure => [failure.id, failure.reason]))
+  const { track, cuts } = scriptTrack(deck.plan, synthesized.clips, {
+    id: SCRIPT_TRACK,
+    doc: relative(deckDir, doc.meta.entry) || doc.meta.entry,
+    lang: deck.lang,
+    ir: { hash: irHash(doc), sections: sectionHashes(doc) },
+    voice: recordings.size && !synthesized.clips.size ? { kind: 'recorded' } : units.every(unit => unit.sourceKind === 'none') ? { kind: 'silent' } : clipVoice(units.flatMap(unit => synthesized.clips.get(unit.id) ?? []), deck.voice),
+    gap: deck.gap,
+  }, events => referencedBlocks(doc, events), unsaid, new Set(units.filter(unit => unit.sourceKind === 'none').map(unit => unit.id)), recordings)
+  const base = projectProductionPlan(doc, deck.plan, track, new Map(), synthesized.failures, recordingDiagnostics)
+  const media = placeProductionAudio(doc, base.pages, new Map([...assets.assets].map(([id, file]) => [id, file.asset])), assets.errors)
+  const captionDiagnostics = applyCaptionTimings(doc, track, base.pages)
+  const mediaDiagnostics: ProductionDiagnostic[] = [...recordingDiagnostics, ...media.issues.map(issue => ({ ...issue, severity: 'error' as const, message: productionAudioMessage(doc, issue.code) }))]
+  if (media.clips.length) track.audio = [...track.audio ?? [], ...media.clips.map(clip => {
+    const file = assets.assets.get(clip.assetId)!
+    return { section: clip.sectionId, start: clip.startMs / 1000, duration: (clip.endMs - clip.startMs) / 1000, src: `audio/${clip.mediaId}.${file.extension}`, clipId: clip.mediaId, assetId: clip.assetId, mediaClipId: clip.id, sourceStartMs: clip.sourceRange.startMs, volume: clip.volume, muted: clip.muted, sha256: file.asset.sha256 }
+  })]
+  await options.assertCurrent?.()
+  signal?.throwIfAborted()
+  const common = { deck, captionDiagnostics, preview: track, clips: synthesized.clips, failures: synthesized.failures, assets: assets.assets, mediaDiagnostics }
+  if (synthesized.failures.length > 0 || mediaDiagnostics.length || deck.findings.some(finding => finding.severity === 'error')) return { ...common, cuts: [] }
+  return { ...common, track, cuts }
+}
+
+export function synthesisFailureMessage(failure: SynthesisFailure, cacheOnly = false): string {
+  const text = failure.text.length > 40 ? `${failure.text.slice(0, 40)}…` : failure.text
+  return `lecture ${SCRIPT_TRACK}: 「${text}」 (section ${failure.section}) ${cacheOnly ? 'has no usable voiceover in the synthesis cache' : 'could not be said from the synthesis cache nor synthesized'}: ${failure.reason}`
+}