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

package/src/node/production-assets.ts

@@ -0,0 +1,112 @@
+import { createHash } from 'node:crypto'
+import { closeSync, createReadStream, fstatSync } from 'node:fs'
+import { Input, ALL_FORMATS, BufferSource } from 'mediabunny'
+import { productionAssetIds, ProductionAudioRefusal } from '@lincyaw/kernel'
+import type { IRDocument, ProductionAssetInspection } from '@lincyaw/kernel'
+import { productionAssetFile } from '@lincyaw/kernel/node'
+import { openInDeck } from './store.ts'
+
+export class ProductionAssetRefusal extends ProductionAudioRefusal {
+  constructor(code: string) { super(code === 'production.asset-changed' ? 409 : 422, code) }
+}
+export interface ProductionAssetFile { asset: ProductionAssetInspection, path: string, stamp: string, extension: string }
+const MAX_BYTES = 16 << 20
+const MAX_DURATION_MS = 10 * 60 * 1000
+const extensions: Record<string, string> = { 'audio/ogg': 'ogg', 'audio/wav': 'wav', 'audio/x-wav': 'wav', 'audio/mpeg': 'mp3', 'audio/mp4': 'm4a', 'audio/webm': 'webm' }
+const stamp = (file: ReturnType<typeof fstatSync>) => [file.dev, file.ino, file.size, file.mtimeMs, file.ctimeMs].join(':')
+
+async function readAudioFile(deckDir: string, file: string, signal?: AbortSignal): Promise<{ bytes: Buffer, identity: string }> {
+  signal?.throwIfAborted()
+  const fd = openInDeck(deckDir, file)
+  if (fd === undefined) throw new ProductionAssetRefusal('production.asset-file')
+  let bytes: Buffer, identity: string
+  try {
+    const before = fstatSync(fd)
+    if (!before.size || before.size > MAX_BYTES) throw new ProductionAssetRefusal('production.asset-size')
+    identity = stamp(before)
+    const chunks: Buffer[] = []
+    let length = 0
+    for await (const value of createReadStream('', { fd, autoClose: false, signal })) {
+      const chunk = Buffer.from(value)
+      length += chunk.length
+      if (length > MAX_BYTES) throw new ProductionAssetRefusal('production.asset-size')
+      chunks.push(chunk)
+    }
+    if (stamp(fstatSync(fd)) !== identity) throw new ProductionAssetRefusal('production.asset-changed')
+    bytes = Buffer.concat(chunks)
+  } catch (error) {
+    signal?.throwIfAborted()
+    if (error instanceof ProductionAssetRefusal) throw error
+    throw new ProductionAssetRefusal('production.asset-file')
+  } finally { closeSync(fd) }
+  signal?.throwIfAborted()
+  return { bytes, identity }
+}
+
+/** Uploads and already-declared files use the same actual-byte probe. No file is written here. */
+export async function inspectProductionAudioBytes(assetId: string, value: Uint8Array, signal?: AbortSignal): Promise<{ inspection: ProductionAssetInspection, extension: string }> {
+  signal?.throwIfAborted()
+  if (!value.byteLength || value.byteLength > MAX_BYTES) throw new ProductionAssetRefusal('production.asset-size')
+  const bytes = Buffer.from(value), sha256 = createHash('sha256').update(bytes).digest('hex')
+  const input = new Input({ formats: ALL_FORMATS, source: new BufferSource(bytes) })
+  const cancel = () => input.dispose()
+  signal?.addEventListener('abort', cancel, { once: true })
+  try {
+    signal?.throwIfAborted()
+    const audio = await input.getAudioTracks(), video = await input.getVideoTracks()
+    if (audio.length !== 1 || video.length || audio[0]!.numberOfChannels < 1 || audio[0]!.numberOfChannels > 2) throw new ProductionAssetRefusal('production.asset-format')
+    const mediaType = (await input.getMimeType()).split(';')[0]!.trim(), extension = extensions[mediaType]
+    if (!extension || !audio[0]!.codec) throw new ProductionAssetRefusal('production.asset-format')
+    const durationMs = Math.round(await input.computeDuration() * 1000)
+    if (!Number.isFinite(durationMs) || durationMs <= 0 || durationMs > MAX_DURATION_MS) throw new ProductionAssetRefusal('production.asset-duration')
+    signal?.throwIfAborted()
+    return { extension, inspection: { assetId, mediaId: createHash('sha256').update(JSON.stringify(['presmium.asset-audio', assetId, sha256])).digest('hex').slice(0, 32), kind: 'audio', sha256, durationMs, byteLength: bytes.length, mediaType, codec: audio[0]!.codec, sampleRate: audio[0]!.sampleRate, channels: audio[0]!.numberOfChannels } }
+  } catch (error) {
+    signal?.throwIfAborted()
+    if (error instanceof ProductionAssetRefusal) throw error
+    throw new ProductionAssetRefusal('production.asset-format')
+  } finally { signal?.removeEventListener('abort', cancel); input.dispose() }
+}
+
+/** Reads only a declared asset ID, through the same-document regular-file boundary. */
+export async function inspectProductionAsset(doc: Pick<IRDocument, 'productionAssets'>, deckDir: string, assetId: string, signal?: AbortSignal): Promise<ProductionAssetFile> {
+  signal?.throwIfAborted()
+  const declared = doc.productionAssets?.[assetId]
+  if (!declared) throw new ProductionAssetRefusal('production.asset-missing')
+  if (declared.kind !== 'audio') throw new ProductionAssetRefusal('production.asset-kind')
+  const file = productionAssetFile(deckDir, declared.location)
+  if (!file) throw new ProductionAssetRefusal('production.asset-path')
+  const { bytes, identity } = await readAudioFile(deckDir, file, signal)
+  const sha256 = createHash('sha256').update(bytes).digest('hex')
+  if (declared.fingerprint && declared.fingerprint.replace(/^sha256:/, '').toLowerCase() !== sha256) throw new ProductionAssetRefusal('production.asset-fingerprint')
+  const probed = await inspectProductionAudioBytes(assetId, bytes, signal)
+  return { path: file, stamp: identity, extension: probed.extension, asset: probed.inspection }
+}
+
+/** Snapshot bytes are checked before a response or published copy can adopt them. */
+export async function readProductionAssetFile(file: ProductionAssetFile, deckDir: string, signal?: AbortSignal): Promise<Buffer> {
+  const { bytes, identity } = await readAudioFile(deckDir, file.path, signal)
+  if (identity !== file.stamp || createHash('sha256').update(bytes).digest('hex') !== file.asset.sha256) throw new ProductionAssetRefusal('production.asset-changed')
+  return bytes
+}
+
+export function assertProductionAssetFile(file: ProductionAssetFile, deckDir: string): void {
+  const fd = openInDeck(deckDir, file.path)
+  if (fd === undefined) throw new ProductionAssetRefusal('production.asset-changed')
+  try { if (stamp(fstatSync(fd)) !== file.stamp) throw new ProductionAssetRefusal('production.asset-changed') }
+  finally { closeSync(fd) }
+}
+
+export async function inspectProductionAssets(doc: IRDocument, deckDir: string, signal?: AbortSignal): Promise<{ assets: Map<string, ProductionAssetFile>, errors: Map<string, string> }> {
+  const assets = new Map<string, ProductionAssetFile>(), errors = new Map<string, string>()
+  const ids = productionAssetIds(doc.production, doc.sections).sort()
+  if (ids.length > 32) { ids.forEach(id => errors.set(id, 'production.asset-count')); return { assets, errors } }
+  for (let offset = 0; offset < ids.length; offset += 2) await Promise.all(ids.slice(offset, offset + 2).map(async id => {
+    try { assets.set(id, await inspectProductionAsset(doc, deckDir, id, signal)) }
+    catch (error) { signal?.throwIfAborted(); if (!(error instanceof ProductionAssetRefusal)) throw error; errors.set(id, error.code) }
+  }))
+  if ([...assets.values()].reduce((bytes, file) => bytes + file.asset.durationMs / 1000 * 48000 * file.asset.channels * 4, 0) > 256 * 1024 * 1024) {
+    ids.forEach(id => errors.set(id, 'production.asset-decoded-size')); assets.clear()
+  }
+  return { assets, errors }
+}

package/src/node/production.ts

@@ -0,0 +1,102 @@
+import { createHash } from 'node:crypto'
+import { stat } from 'node:fs/promises'
+import type { CanonicalSource, IRDocument, ProductionAssetAnswer, ProductionAssetQuery, ProductionAudio, ProductionMediaQuery, ProductionPlan, ProductionPlanQuery } from '@lincyaw/kernel'
+import { irRevision } from '@lincyaw/kernel/node'
+import type { LectureTrack } from '../domain/index.ts'
+import { projectProductionPlan } from '../domain/production.ts'
+import { latestDoc, lectureView } from './latest-ir.ts'
+import { assertVoiceSource } from './voice-source.ts'
+import { synthesizeLecture } from './synthesize.ts'
+import type { SynthesizedClip } from './synthesize.ts'
+import type { ServedDeck } from './routes/served-deck.ts'
+import { RouteRefusal } from './routes/served-deck.ts'
+import { assertProductionAssetFile, inspectProductionAsset, readProductionAssetFile } from './production-assets.ts'
+import type { ProductionAssetFile } from './production-assets.ts'
+
+interface ClipFile { audio?: ProductionAudio, asset?: ProductionAssetFile, path: string, stamp: string }
+export interface ProductionSnapshot { plan: ProductionPlan, track: LectureTrack, clips: Map<string, ClipFile> }
+const recent = new WeakMap<ServedDeck, Map<string, ProductionSnapshot>>()
+const fileStamp = async (path: string) => { const value = await stat(path); return [value.dev, value.ino, value.size, value.mtimeMs, value.ctimeMs].join(':') }
+
+async function clipFile(clip: SynthesizedClip, signal?: AbortSignal): Promise<ClipFile> {
+  signal?.throwIfAborted()
+  const before = await fileStamp(clip.path)
+  if (before !== clip.stamp || !clip.sha256) throw new RouteRefusal(409, 'production-media-changed')
+  return { audio: { clipId: clip.key, key: clip.key, sha256: clip.sha256, durationMs: Math.round(clip.duration * 1000) }, path: clip.path, stamp: before }
+}
+
+async function current(served: ServedDeck, expected?: ProductionPlanQuery): Promise<{ doc: IRDocument, source: CanonicalSource, revision: string }> {
+  const doc = latestDoc(served.deckDir)
+  if (!doc) throw new RouteRefusal(503, 'production-document-unavailable')
+  const source = await assertVoiceSource(doc, served.deckDir, expected?.source), revision = irRevision(doc)
+  if (latestDoc(served.deckDir) !== doc || expected && expected.irRevision !== revision) throw new RouteRefusal(409, 'production-revision-changed')
+  return { doc, source, revision }
+}
+
+/** Cache-only derivation shared by the public plan and the existing lecture player. No provider generation occurs. */
+export async function productionSnapshot(served: ServedDeck, query?: ProductionPlanQuery & { planId?: string }, signal?: AbortSignal): Promise<ProductionSnapshot> {
+  signal?.throwIfAborted()
+  const now = await current(served, query)
+  if (query?.planId) {
+    const found = recent.get(served)?.get(query.planId)
+    // A source-bound Node service and a route can borrow different ServedDecks.
+    // Re-derive only the current cache-only snapshot; never invent a past plan.
+    if (!found) {
+      const fresh = await productionSnapshot(served, { source: now.source, irRevision: now.revision }, signal)
+      if (fresh.plan.binding.planId !== query.planId) throw new RouteRefusal(409, 'production-plan-changed')
+      return fresh
+    }
+    if (found.plan.binding.irRevision !== now.revision) throw new RouteRefusal(409, 'production-plan-changed')
+    await Promise.all([...found.clips.values()].map(async file => { if (file.asset) assertProductionAssetFile(file.asset, served.deckDir); else if (await fileStamp(file.path) !== file.stamp) throw new RouteRefusal(409, 'production-media-changed') }))
+    await current(served, found.plan.binding)
+    signal?.throwIfAborted()
+    return found
+  }
+  let speech
+  try { speech = served.speech() } catch { /* Explicit silence requires no speech service. */ }
+  const made = await synthesizeLecture(lectureView(now.doc), served.deckDir, speech, signal, { cacheOnly: true }), track = made.preview
+  if (!track) throw new RouteRefusal(409, 'production-plan-unavailable')
+  const clips = new Map<string, ClipFile>(), unique = [...new Map([...made.clips.values()].map(clip => [clip.key, clip])).values()].sort((a, b) => a.key.localeCompare(b.key))
+  for (let offset = 0; offset < unique.length; offset += 4) for (const file of await Promise.all(unique.slice(offset, offset + 4).map(clip => clipFile(clip, signal)))) clips.set(file.audio!.clipId, file)
+  for (const file of [...made.assets?.values() ?? []].sort((a, b) => a.asset.mediaId.localeCompare(b.asset.mediaId))) {
+    assertProductionAssetFile(file, served.deckDir)
+    clips.set(file.asset.mediaId, { asset: file, path: file.path, stamp: file.stamp })
+  }
+  for (const utterance of track.utterances) {
+    const clip = made.clips.get(utterance.id)
+    if (clip) utterance.clipId = clip.key
+  }
+  const projected = projectProductionPlan(now.doc, made.deck.plan, track, new Map([...clips].flatMap(([key, file]) => file.audio ? [[key, file.audio] as const] : [])), made.failures, [...made.mediaDiagnostics ?? [], ...made.captionDiagnostics ?? []], new Map([...made.assets ?? []].map(([id, file]) => [id, file.asset])))
+  const planId = createHash('sha256').update(JSON.stringify({ source: now.source, irRevision: now.revision, projected, track, audio: [...clips.values()].map(file => file.audio ?? file.asset!.asset) })).digest('hex').slice(0, 32)
+  const binding = { source: now.source, irRevision: now.revision, planId }, plan: ProductionPlan = { binding, ...projected }
+  track.binding = binding
+  await current(served, binding)
+  signal?.throwIfAborted()
+  const snapshot = { plan, track, clips }, plans = recent.get(served) ?? new Map<string, ProductionSnapshot>()
+  recent.set(served, plans); plans.set(planId, snapshot)
+  while (plans.size > 4) plans.delete(plans.keys().next().value!)
+  return snapshot
+}
+
+export async function productionAsset(served: ServedDeck, query: ProductionAssetQuery, signal?: AbortSignal): Promise<ProductionAssetAnswer> {
+  const now = await current(served, query), inspected = await inspectProductionAsset(now.doc, served.deckDir, query.assetId, signal)
+  await current(served, { source: now.source, irRevision: now.revision })
+  signal?.throwIfAborted()
+  return { source: now.source, irRevision: now.revision, asset: inspected.asset }
+}
+
+export async function productionMedia(served: ServedDeck, query: ProductionMediaQuery, signal?: AbortSignal): Promise<string | { bytes: Uint8Array<ArrayBuffer>, mediaType: string }> {
+  const snapshot = await productionSnapshot(served, query, signal), file = snapshot.clips.get(query.clipId)
+  if (!file) throw new RouteRefusal(404, 'production-clip-unknown')
+  if (file.asset) {
+    const bytes = await readProductionAssetFile(file.asset, served.deckDir, signal)
+    await current(served, query); signal?.throwIfAborted()
+    return { bytes: new Uint8Array(bytes), mediaType: file.asset.asset.mediaType }
+  }
+  const hit = await served.speech().cached?.(query.clipId, signal)
+  if (!hit || typeof hit.audio !== 'string' || hit.audio !== file.path || Math.round(hit.duration * 1000) !== file.audio!.durationMs) throw new RouteRefusal(409, 'production-media-changed')
+  if (await fileStamp(file.path) !== file.stamp) throw new RouteRefusal(409, 'production-media-changed')
+  await current(served, query)
+  signal?.throwIfAborted()
+  return file.path
+}

package/src/node/renderer.ts

@@ -0,0 +1,182 @@
+import { copyFileSync, existsSync, mkdirSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { workspaceSettings } from '@lincyaw/compiler'
+import { deckLocale, errorMessage, SPEECH } from '@lincyaw/kernel'
+import type { IRDocument, RenderContext, Renderer, SpeechService } from '@lincyaw/kernel'
+import { captionLanguages, captionsVtt, chaptersVtt, CLIPS_DIR, dropChangedSections, eventsVtt, formatTrack, LECTURE_ID, LECTURE_RENDERER, LECTURE_MESSAGES, plannedUtterances, SCRIPT_TRACK, trackDuration, trimToDeck, utteranceLine } from '../domain/index.ts'
+import type { LectureTrack } from '../domain/index.ts'
+import { cachedClip } from './clips.ts'
+import { latestDoc } from './latest-ir.ts'
+import { deckPlan } from './plan.ts'
+import { mediaFile, mediaPolicy, publishedMedia, readTrack, TRACK_FILE, trackIds } from './store.ts'
+import type { MediaPolicy } from './store.ts'
+import { productionMessages } from '../domain/production.ts'
+import { synthesizeLecture } from './synthesize.ts'
+import { readProductionAssetFile } from './production-assets.ts'
+import type { ProductionAssetFile } from './production-assets.ts'
+
+const clipsOf = (track: LectureTrack) => new Set(track.utterances.flatMap(u => u.clip ?? []))
+
+async function publishTrack(track: LectureTrack, text: string, file: string, doc: IRDocument, ctx: RenderContext, clipFiles: ReadonlyMap<string, string>, policy: MediaPolicy = { kind: 'ignore' }, assets: ReadonlyMap<string, ProductionAssetFile> = new Map()): Promise<void> {
+  const out = join(ctx.outDir, track.id)
+  mkdirSync(out, { recursive: true })
+  const audio = publishedMedia(track.audio, track.id, policy)
+  const video = publishedMedia(track.video, track.id, policy)
+  writeFileSync(join(out, TRACK_FILE), formatTrack({ ...track, ...audio ? { audio } : {}, ...video ? { video } : {} }))
+  for (const segment of policy.kind === 'url' ? [] : [...track.audio ?? [], ...track.video ?? []]) {
+    if (segment.assetId) {
+      const asset = assets.get(segment.assetId)
+      if (!asset || segment.sha256 !== asset.asset.sha256) throw new Error('production.asset-changed')
+      const bytes = await readProductionAssetFile(asset, ctx.deckDir)
+      mkdirSync(dirname(join(out, segment.src)), { recursive: true })
+      writeFileSync(join(out, segment.src), bytes)
+      continue
+    }
+    const source = mediaFile(ctx.deckDir, track.id, segment.src)
+    if (!source) continue
+    if (!existsSync(source)) {
+      ctx.report({ checkId: LECTURE_ID, severity: 'warning', message: `lecture ${track.id}: ${segment.src} is not in this checkout; the lecture plays without it`, source: { file } })
+      continue
+    }
+    mkdirSync(dirname(join(out, segment.src)), { recursive: true })
+    copyFileSync(source, join(out, segment.src))
+  }
+  for (const clip of clipsOf(track)) {
+    const source = clipFiles.get(clip)
+    if (!source || !existsSync(source)) {
+      ctx.report({ checkId: LECTURE_ID, severity: 'warning', message: `lecture ${track.id}: the clip ${clip} is not in the synthesis cache; its utterance plays silent`, source: { file } })
+      continue
+    }
+    mkdirSync(join(out, CLIPS_DIR), { recursive: true })
+    copyFileSync(source, join(out, CLIPS_DIR, clip))
+  }
+  for (const lang of captionLanguages(track)) {
+    const captions = captionsVtt(track, lang)
+    writeFileSync(join(out, `captions.${lang}.vtt`), captions.vtt)
+    for (const id of captions.stale) {
+      ctx.report({
+        checkId: LECTURE_ID,
+        severity: 'warning',
+        message: `lecture ${track.id}: the ${lang} translation of ${id} is stale: its original changed after it was translated`,
+        source: { file, line: utteranceLine(text, id) },
+        hint: 'translate the utterance again',
+      })
+    }
+    if (captions.missing.length > 0) {
+      ctx.report({
+        checkId: LECTURE_ID,
+        severity: 'warning',
+        message: `lecture ${track.id}: the ${lang} captions leave out ${captions.missing.join(', ')}, which have no ${lang} translation`,
+        source: { file, line: utteranceLine(text, captions.missing[0]!) },
+        hint: 'translate those utterances too',
+      })
+    }
+  }
+  const titles = new Map(doc.sections.map(s => [s.id, s.title]))
+  writeFileSync(join(out, 'chapters.vtt'), chaptersVtt(track, section => titles.get(section)))
+  writeFileSync(join(out, 'events.vtt'), eventsVtt(track))
+}
+
+async function publishSynthesized(doc: IRDocument, ctx: RenderContext, index: unknown[]): Promise<boolean> {
+  const source = { file: doc.meta.entry, line: 1 }, t = LECTURE_MESSAGES[deckLocale(doc.meta.lang)].production
+  const speech = ctx.service?.(SPEECH)
+  if (!speech && plannedUtterances(deckPlan(doc).plan).some(unit => unit.sourceKind !== 'none' && unit.sourceKind !== 'recording')) {
+    ctx.report({ checkId: LECTURE_ID, severity: 'error', message: t.missingSpeech, source })
+    return false
+  }
+  const synthesized = await synthesizeLecture(doc, ctx.deckDir, speech, undefined, { cacheOnly: true })
+  for (const issue of synthesized.mediaDiagnostics ?? []) ctx.report({ checkId: LECTURE_ID, severity: issue.severity, message: issue.message, source })
+  if (synthesized.mediaDiagnostics?.length) throw new Error(synthesized.mediaDiagnostics[0]!.message)
+  for (const issue of synthesized.captionDiagnostics ?? []) ctx.report({ checkId: LECTURE_ID, severity: issue.severity, message: issue.message, source })
+  for (const failure of synthesized.failures) {
+    ctx.report({ checkId: LECTURE_ID, severity: 'error', message: t.cacheMissing(failure.text.slice(0, 40), failure.section, failure.reason), source: failure.source ?? source, hint: t.generateHint })
+  }
+  for (const cut of synthesized.cuts) {
+    ctx.report({ checkId: LECTURE_ID, severity: 'warning', message: `lecture ${SCRIPT_TRACK}: {cue}\`next\` moves on ${Math.round(cut.left)} ms before the animation of step ${cut.step} of section ${cut.section} has played`, source: cut.source ?? source, hint: 'say the cue later, or shorten the animation (:durations:)' })
+  }
+  const { track } = synthesized
+  if (!track) return false
+  const clipFiles = new Map([...synthesized.clips.values()].map(clip => [clip.file, clip.path]))
+  await publishTrack(track, formatTrack(track), doc.meta.entry, doc, ctx, clipFiles, { kind: 'ignore' }, synthesized.assets)
+  index.push(summary(track))
+  return true
+}
+
+function publishedTrack(doc: IRDocument, deckDir: string): (track: LectureTrack) => LectureTrack | undefined {
+  const latest = latestDoc(deckDir)
+  const own = latest?.meta.entry === doc.meta.entry ? latest : doc
+  if (typeof own.meta.audience === 'string') return (track) => {
+    const kept = trimToDeck(track, own)
+    return kept && dropChangedSections(kept, own)
+  }
+  return track => trimToDeck(track, own)
+}
+
+async function recordedClipFiles(track: LectureTrack, speech: SpeechService | undefined): Promise<{ clipFiles: Map<string, string>, refused?: string }> {
+  const clipFiles = new Map<string, string>()
+  for (const clip of clipsOf(track)) {
+    if (!speech) return { clipFiles, refused: 'its clips are given through the speech service, which checks a cloned voice\'s consent, and no plugin provides it; add @lincyaw/addon-speech to plugins' }
+    try {
+      const found = await cachedClip(speech, clip)
+      if (found) clipFiles.set(clip, found.audio)
+    } catch (error) {
+      return { clipFiles, refused: `the clip ${clip} may not be published: ${errorMessage(error)}` }
+    }
+  }
+  return { clipFiles }
+}
+
+function summary(track: LectureTrack) {
+  return { id: track.id, lang: track.lang, voice: track.voice, duration: trackDuration(track), captions: captionLanguages(track) }
+}
+
+export const lectureRenderer: Renderer = {
+  id: LECTURE_RENDERER,
+  site: true,
+  support: () => 'full',
+  async build(doc, ctx) {
+    const index: unknown[] = []
+    const plan = deckPlan(doc)
+    plan.findings.forEach(ctx.report)
+    if (plan.findings.some(finding => finding.severity === 'error')) throw new Error(plan.findings.find(finding => finding.severity === 'error')!.message)
+    if (!plan.voice && !plan.silent && !plan.recorded && plannedUtterances(plan.plan).length) throw new Error(productionMessages(doc).unset)
+    const synthesize = Boolean(plan.voice || plan.silent || plan.recorded)
+    const policy = mediaPolicy(workspaceSettings(ctx.workspaceRoot).settings[LECTURE_ID] ?? {})
+    const published = publishedTrack(doc, ctx.deckDir)
+    const complete = !synthesize || await publishSynthesized(doc, ctx, index)
+    if (!complete) throw new Error(LECTURE_MESSAGES[deckLocale(doc.meta.lang)].production.incompleteCache)
+    for (const id of trackIds(ctx.deckDir)) {
+      if (synthesize && id === SCRIPT_TRACK) {
+        ctx.report({ checkId: LECTURE_ID, severity: 'warning', message: `lectures/${SCRIPT_TRACK} is not published: ${SCRIPT_TRACK} is the id of the synthesized lecture` })
+        continue
+      }
+      let stored
+      try {
+        stored = readTrack(ctx.deckDir, id)
+      } catch (error) {
+        ctx.report({ checkId: LECTURE_ID, severity: 'error', message: `lecture ${id}: ${errorMessage(error)}` })
+        continue
+      }
+      if (!stored) continue
+      const track = published(stored.track)
+      if (!track) continue
+      const { clipFiles, refused } = await recordedClipFiles(track, ctx.service?.(SPEECH))
+      if (refused) {
+        ctx.report({ checkId: LECTURE_ID, severity: 'error', message: `lecture ${id} is not published: ${refused}`, source: { file: stored.file } })
+        continue
+      }
+      await publishTrack(track, stored.text, stored.file, doc, ctx, clipFiles, policy)
+      index.push(summary(track))
+    }
+    mkdirSync(ctx.outDir, { recursive: true })
+    writeFileSync(join(ctx.outDir, 'index.json'), `${JSON.stringify(index, null, 2)}\n`)
+    return { outDir: ctx.outDir, skipped: [] }
+  },
+  async dev(_doc, ctx) {
+    return {
+      url: `${ctx.server?.url ?? ''}/__presmium/${LECTURE_ID}/tracks`,
+      update: async () => {},
+      close: async () => {},
+    }
+  },
+}

package/src/node/roles.ts

@@ -0,0 +1,23 @@
+import type { RoleSpec } from '@lincyaw/kernel'
+import { cueProblem, LECTURE_ID, parseCue } from '../domain/index.ts'
+
+export const cueRole: RoleSpec = {
+  name: 'cue',
+  options: { to: 'string', lines: 'string', sel: 'string' },
+  children(input, ctx) {
+    const parsed = parseCue(input.value)
+    if ('problem' in parsed) ctx.report({ checkId: LECTURE_ID, severity: 'warning', message: cueProblem(input.value, parsed.problem, ctx.lang) })
+    return []
+  },
+}
+
+export const sayRole: RoleSpec = {
+  name: 'say',
+  options: { alias: 'string' },
+  children(input, ctx) {
+    if (typeof input.options.alias !== 'string' || !input.options.alias.trim()) {
+      ctx.report({ checkId: LECTURE_ID, severity: 'warning', message: `{say}\`${input.value}\` has no alias="…" to say; the lecture says what it shows` })
+    }
+    return [{ type: 'text', value: input.value }]
+  },
+}

package/src/node/routes/production.ts

@@ -0,0 +1,51 @@
+import { errorMessage, jsonResponse } from '@lincyaw/kernel'
+import type { ProductionMediaQuery, ProductionPlanQuery, Route } from '@lincyaw/kernel'
+import { productionAsset, productionMedia, productionSnapshot } from '../production.ts'
+import { ProductionAssetRefusal } from '../production-assets.ts'
+import { canonicalSource, VoiceSourceRefusal } from '../voice-source.ts'
+import { serveFile } from './serve-file.ts'
+import { RouteRefusal } from './served-deck.ts'
+import type { ServedDeck } from './served-deck.ts'
+
+function audioBytes(bytes: Uint8Array<ArrayBuffer>, mediaType: string, request: Request): Response {
+  const size = bytes.byteLength, headers = { 'Content-Type': mediaType, 'Cache-Control': 'no-store', 'Accept-Ranges': 'bytes' }
+  const range = /^bytes=(\d*)-(\d*)$/.exec(request.headers.get('range') ?? '')
+  if (!range || !range[1] && !range[2]) return new Response(request.method === 'HEAD' ? null : bytes, { headers: { ...headers, 'Content-Length': String(size) } })
+  const start = range[1] ? Number(range[1]) : Math.max(0, size - Number(range[2]))
+  const end = range[1] && range[2] ? Math.min(size - 1, Number(range[2])) : size - 1
+  if (start >= size || start > end) return new Response(null, { status: 416, headers: { ...headers, 'Content-Range': `bytes */${size}` } })
+  return new Response(request.method === 'HEAD' ? null : bytes.subarray(start, end + 1), { status: 206, headers: { ...headers, 'Content-Length': String(end - start + 1), 'Content-Range': `bytes ${start}-${end}/${size}` } })
+}
+
+function query(request: Request, media = false): ProductionPlanQuery | ProductionMediaQuery {
+  const params = new URL(request.url).searchParams
+  let source: unknown
+  try { source = JSON.parse(params.get('source') ?? 'null') } catch { throw new RouteRefusal(400, 'production-query-invalid') }
+  const irRevision = params.get('irRevision')
+  if (!canonicalSource(source) || !irRevision || !/^[\da-f]{16}$/.test(irRevision)) throw new RouteRefusal(400, 'production-query-invalid')
+  if (!media) return { source, irRevision }
+  const planId = params.get('planId'), clipId = params.get('clipId')
+  if (!planId || !/^[\da-f]{32}$/.test(planId) || !clipId || !/^[\da-f]{32}$/.test(clipId)) throw new RouteRefusal(400, 'production-query-invalid')
+  return { source, irRevision, planId, clipId }
+}
+
+export function productionRoutes(served: ServedDeck): Record<string, Route> {
+  const read = (handle: (request: Request) => Promise<Response>): Route => ({ role: 'reader', async handle(request) {
+    try {
+      if (request.method !== 'GET' && request.method !== 'HEAD') throw new RouteRefusal(405, 'GET or HEAD')
+      return await handle(request)
+    } catch (error) { return jsonResponse({ error: errorMessage(error) }, error instanceof RouteRefusal ? error.status : error instanceof VoiceSourceRefusal ? 409 : error instanceof ProductionAssetRefusal ? error.code === 'production.asset-changed' ? 409 : 422 : 502) }
+  } })
+  return {
+    'production-plan': read(async request => jsonResponse((await productionSnapshot(served, query(request), request.signal)).plan)),
+    'production-asset': read(async request => {
+      const assetId = new URL(request.url).searchParams.get('assetId')
+      if (!assetId || assetId.length > 200) throw new RouteRefusal(400, 'production-query-invalid')
+      return jsonResponse(await productionAsset(served, { ...query(request), assetId }, request.signal))
+    }),
+    'production-media': read(async request => {
+      const media = await productionMedia(served, query(request, true) as ProductionMediaQuery, request.signal)
+      return typeof media === 'string' ? serveFile(served.deckDir, media, request) : audioBytes(media.bytes, media.mediaType, request)
+    }),
+  }
+}

package/src/node/routes/recordings.ts

@@ -0,0 +1,122 @@
+import { existsSync, statSync } from 'node:fs'
+import { errorMessage, isRecord, jsonResponse, problemResponse } from '@lincyaw/kernel'
+import type { Route } from '@lincyaw/kernel'
+import { fileStem, recordedTrack, spliceSection, trackDuration } from '../../domain/index.ts'
+import type { LectureTrack, MediaSegment, Recording, TrackHead } from '../../domain/index.ts'
+import { freeMediaPath, mediaFile, newTrackId, readTrack, sha256File, trackDir, writeGitFiles, writeTrack } from '../store.ts'
+import { decodedPath } from './served-deck.ts'
+import type { ServedDeck } from './served-deck.ts'
+
+const MAX_CHUNK = 64 * 1024 * 1024
+const MAX_FILE = 4 * 1024 * 1024 * 1024
+
+function withHashes<T extends MediaSegment>(deckDir: string, id: string, segments: T[]): Promise<T[]> {
+  return Promise.all(segments.map(async (segment) => {
+    const file = mediaFile(deckDir, id, segment.src)
+    const sha256 = file && await sha256File(deckDir, file)
+    return { ...segment, ...sha256 ? { sha256 } : {} }
+  }))
+}
+
+function toRecording(value: unknown): Recording | undefined {
+  if (!isRecord(value) || !Array.isArray(value.events)) return undefined
+  const list = (v: unknown) => (Array.isArray(v) ? v : [])
+  return {
+    events: value.events as Recording['events'],
+    audio: list(value.audio) as Recording['audio'],
+    video: list(value.video) as Recording['video'],
+    utterances: list(value.utterances) as Recording['utterances'],
+    duration: typeof value.duration === 'number' ? value.duration : 0,
+  }
+}
+
+function toTrackHead(value: unknown, id: string): TrackHead | undefined {
+  if (!isRecord(value) || typeof value.doc !== 'string' || typeof value.irHash !== 'string') return undefined
+  return {
+    id,
+    doc: value.doc,
+    lang: typeof value.lang === 'string' ? value.lang : 'zh-CN',
+    irHash: value.irHash,
+    sections: isRecord(value.sections) ? Object.fromEntries(Object.entries(value.sections).filter((entry): entry is [string, string] => typeof entry[1] === 'string')) : {},
+    voice: isRecord(value.voice) && value.voice.kind === 'recorded'
+      ? { kind: 'recorded', ...typeof value.voice.speaker === 'string' ? { speaker: value.voice.speaker } : {} }
+      : { kind: 'recorded' },
+    blocks: isRecord(value.blocks) ? value.blocks as TrackHead['blocks'] : {},
+  }
+}
+
+export function recordingRoutes(served: ServedDeck): Record<string, Route> {
+  const { ctx, deckDir, files, policy } = served
+
+  const finish = async (id: string, request: Request): Promise<Response> => {
+    const body: unknown = await request.json().catch(() => undefined)
+    const recording = isRecord(body) ? toRecording(body.recording) : undefined
+    const head = isRecord(body) ? toTrackHead(body.head, id) : undefined
+    if (!recording || !head) return problemResponse(400, 'expected { head, recording }')
+    const media = { ...recording, audio: await withHashes(deckDir, id, recording.audio), video: await withHashes(deckDir, id, recording.video) }
+    const section = isRecord(body) && typeof body.section === 'string' ? body.section : undefined
+    const stored = readTrack(deckDir, id)
+    let track: LectureTrack
+    if (section && stored) {
+      const spliced = spliceSection(stored.track, section, media, head)
+      track = spliced.track
+      for (const src of spliced.unused) {
+        const file = mediaFile(deckDir, id, src)
+        if (file) await files.remove(file)
+      }
+    } else {
+      track = recordedTrack(head, media)
+    }
+    await writeTrack(files, deckDir, track)
+    ctx.log.info(`lecture ${id}: ${track.events.length} events, ${(trackDuration(track) / 1000).toFixed(1)} s`)
+    return jsonResponse({ id, track })
+  }
+
+  return {
+    'recordings': {
+      async handle(request) {
+        if (request.method !== 'POST') return problemResponse(405, 'POST to start a recording')
+        const body: unknown = await request.json().catch(() => ({}))
+        const existing = isRecord(body) && typeof body.track === 'string' ? body.track : undefined
+        if (existing && !readTrack(deckDir, existing)) return problemResponse(404, `no lecture ${existing}`)
+        const id = existing ?? newTrackId(deckDir)
+        await writeGitFiles(files, trackDir(deckDir, id)!, policy)
+        return jsonResponse({ id })
+      },
+    },
+    'recordings/*': {
+      maxBody: MAX_CHUNK,
+      async handle(request, { rest }) {
+        const [id = '', action, ...path] = rest.split('/')
+        const dir = trackDir(deckDir, id)
+        if (!dir) return problemResponse(404, 'no such lecture')
+        try {
+          if (action === 'media' && request.method === 'POST') {
+            const body: unknown = await request.json().catch(() => undefined)
+            if (!isRecord(body) || (body.folder !== 'audio' && body.folder !== 'video') || typeof body.section !== 'string' || typeof body.ext !== 'string' || !/^(ogg|webm|mp4|m4a)$/.test(body.ext)) {
+              return problemResponse(400, 'expected { folder, section, ext }')
+            }
+            const stem = typeof body.kind === 'string' ? `${fileStem(body.section)}.${fileStem(body.kind)}` : fileStem(body.section)
+            return jsonResponse({ src: freeMediaPath(deckDir, id, body.folder, stem, body.ext) })
+          }
+          if (action === 'files' && request.method === 'PUT') {
+            const file = mediaFile(deckDir, id, decodedPath(path))
+            const at = Number(new URL(request.url).searchParams.get('at') ?? '0')
+            if (!file || !Number.isSafeInteger(at) || at < 0) return problemResponse(400, 'expected a media file of the lecture and ?at=<position>')
+            const size = existsSync(file) ? statSync(file).size : 0
+            if (at > size) return problemResponse(400, `?at=${at} is past the end of the file (${size} bytes)`)
+            const bytes = new Uint8Array(await request.arrayBuffer())
+            if (bytes.byteLength > MAX_CHUNK || at + bytes.byteLength > MAX_FILE) return problemResponse(413, 'chunk too large')
+            await files.write(file, bytes, at)
+            return jsonResponse({ written: bytes.byteLength })
+          }
+          if (action === 'finish' && request.method === 'POST') return await finish(id, request)
+        } catch (error) {
+          ctx.log.error(`lecture ${id}: ${errorMessage(error)}`)
+          return problemResponse(500, errorMessage(error))
+        }
+        return problemResponse(404, 'unknown recording action')
+      },
+    },
+  }
+}

package/src/node/routes/serve-file.ts

@@ -0,0 +1,38 @@
+import { closeSync, createReadStream, fstatSync } from 'node:fs'
+import { extname } from 'node:path'
+import { Readable } from 'node:stream'
+import { problemResponse } from '@lincyaw/kernel'
+import { openInDeck } from '../store.ts'
+
+const TYPES: Record<string, string> = {
+  '.ogg': 'audio/ogg',
+  '.opus': 'audio/ogg',
+  '.webm': 'video/webm',
+  '.mp4': 'video/mp4',
+  '.m4a': 'audio/mp4',
+  '.wav': 'audio/wav',
+  '.mp3': 'audio/mpeg',
+}
+
+export function serveFile(deckDir: string, file: string | undefined, request: Request): Response {
+  const fd = file === undefined ? undefined : openInDeck(deckDir, file)
+  if (fd === undefined) return problemResponse(404, 'no such file')
+  const { size } = fstatSync(fd)
+  const headers = { 'Content-Type': TYPES[extname(file!)] ?? 'application/octet-stream', 'Accept-Ranges': 'bytes', 'Cache-Control': 'no-store' }
+  const body = (start: number, end: number) => Readable.toWeb(createReadStream('', { fd, start, end })) as ReadableStream<Uint8Array>
+  const empty = (response: Response) => {
+    closeSync(fd)
+    return response
+  }
+  const range = /^bytes=(\d*)-(\d*)$/.exec(request.headers.get('range') ?? '')
+  if (!range || (!range[1] && !range[2])) {
+    if (size === 0 || request.method === 'HEAD') return empty(new Response(null, { headers: { ...headers, 'Content-Length': String(size) } }))
+    return new Response(body(0, size - 1), { headers: { ...headers, 'Content-Length': String(size) } })
+  }
+  const start = range[1] ? Number(range[1]) : Math.max(0, size - Number(range[2]))
+  const end = range[1] && range[2] ? Math.min(Number(range[2]), size - 1) : size - 1
+  if (start >= size || start > end) return empty(new Response(null, { status: 416, headers: { ...headers, 'Content-Range': `bytes */${size}` } }))
+  const partial = { ...headers, 'Content-Range': `bytes ${start}-${end}/${size}`, 'Content-Length': String(end - start + 1) }
+  if (request.method === 'HEAD') return empty(new Response(null, { status: 206, headers: partial }))
+  return new Response(body(start, end), { status: 206, headers: partial })
+}