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

package/src/node/export.ts

@@ -0,0 +1,331 @@
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { open } from 'node:fs/promises'
+import { createRequire } from 'node:module'
+import { dirname, join, resolve } from 'node:path'
+import { build, Compiler, playwrightChromium, serveDirectory } from '@lincyaw/compiler'
+import { ABSOLUTE_URL, aigcLabel, aigcString, deckLocale, errorMessage } from '@lincyaw/kernel'
+import type { CanonicalSource } from '@lincyaw/kernel'
+import { ffmpegInstallCommand, findFfmpeg } from '@lincyaw/kernel/node'
+import { audioSegments, clockText, defaultTrack, LECTURE_MESSAGES, parseTrack, trackDuration } from '../domain/index.ts'
+import type { LectureTrack } from '../domain/index.ts'
+import { ffmpegEncodes, startFfmpeg, videoFormat } from './ffmpeg.ts'
+import type { FfmpegEncoder, VideoFormat } from './ffmpeg.ts'
+
+export interface ExportOptions {
+  deckDir: string
+  /** Refuse to render if the fresh compilation differs from the requested canonical document. */
+  source?: CanonicalSource
+  track?: string
+  /** `.mp4` (H.264, AAC; needs FFmpeg) or `.webm`; MP4 when FFmpeg is there, else WebM. */
+  out?: string
+  width?: number
+  height?: number
+  fps?: number
+  /** Draws the captions in this language on the frames (the soft subtitle tracks are always there). */
+  burn?: string
+  log?: (line: string) => void
+  /** How many of the video's frames are drawn. */
+  progress?: (done: number, total: number) => void
+  /** Stops the export between two frames; it then rejects with the signal's reason. */
+  signal?: AbortSignal
+}
+
+export interface ExportResult {
+  file: string
+  track: string
+  frames: number
+  duration: number
+  /** The captions written next to the video, a WebVTT file a language. */
+  captions: { lang: string, file: string }[]
+  warnings: string[]
+}
+
+const ENCODER = `<!doctype html><meta charset="utf-8"><title>presmium-lecture export</title>
+<script type="module">
+import { AudioBufferSource, CanvasSource, canEncodeAudio, getFirstEncodableVideoCodec, Output, QUALITY_HIGH, StreamTarget, TextSubtitleSource, WebMOutputFormat } from './mediabunny.mjs'
+const RATE = 48000
+let output, video, audio, canvas, context, fps, total, done = 0, clips = [], subtitled = []
+const base64 = (bytes) => {
+  let text = ''
+  for (let i = 0; i < bytes.length; i += 0x8000) text += String.fromCharCode(...bytes.subarray(i, i + 0x8000))
+  return btoa(text)
+}
+const bytes = (text) => Uint8Array.from(atob(text), c => c.charCodeAt(0))
+async function decode(url) {
+  const response = await fetch(url)
+  if (!response.ok) throw new Error(url + ': HTTP ' + response.status)
+  const buffer = await new OfflineAudioContext(1, 1, RATE).decodeAudioData(await response.arrayBuffer())
+  if (buffer.numberOfChannels > 2) throw new Error('the media has more than two audio channels')
+  return Array.from({ length: buffer.numberOfChannels }, (_, channel) => buffer.getChannelData(channel))
+}
+/** The lecture's audio from ms a to ms b. */
+function mix(a, b) {
+  const length = Math.max(1, Math.round((b - a) * RATE / 1000))
+  const buffer = new AudioBuffer({ length, numberOfChannels: 2, sampleRate: RATE })
+  for (const clip of clips) {
+    if (clip.start >= b || clip.end <= a || clip.muted || clip.volume === 0) continue
+    const first = Math.round(clip.sourceStartMs * RATE / 1000)
+    const from = Math.round((a - clip.start + clip.sourceStartMs) * RATE / 1000)
+    const last = Math.min(clip.samples[0].length, first + Math.round((clip.end - clip.start) * RATE / 1000))
+    for (let channel = 0; channel < 2; channel++) {
+      const data = buffer.getChannelData(channel), samples = clip.samples[channel] ?? clip.samples[0]
+      for (let i = Math.max(0, first - from); i < length && from + i < last; i++) data[i] += samples[from + i] * clip.volume
+    }
+  }
+  for (let channel = 0; channel < 2; channel++) { const data = buffer.getChannelData(channel); for (let i = 0; i < data.length; i++) data[i] = Math.max(-1, Math.min(1, data[i])) }
+  return buffer
+}
+async function load(list) {
+  const decoded = new Map()
+  for (const a of list) if (!decoded.has(a.url)) decoded.set(a.url, await decode(a.url))
+  clips = list.map(a => ({ start: a.start, end: a.start + a.duration, sourceStartMs: a.sourceStartMs ?? 0, volume: a.volume ?? 1, muted: a.muted ?? false, samples: decoded.get(a.url) }))
+}
+async function audioUntil(ms) {
+  while (audio && done < Math.min(ms, total)) {
+    const next = Math.min(done + 1000, total)
+    await audio.add(mix(done, next))
+    done = next
+  }
+}
+window.presmiumEncoder = {
+  async start(options) {
+    fps = options.fps
+    total = options.duration
+    canvas = new OffscreenCanvas(options.width, options.height)
+    context = canvas.getContext('2d')
+    const writable = new WritableStream({ write: chunk => window.presmiumWrite(chunk.position, base64(chunk.data)) })
+    output = new Output({ format: new WebMOutputFormat(), target: new StreamTarget(writable, { chunked: true, chunkSize: 4 * 1024 * 1024 }) })
+    const codec = await getFirstEncodableVideoCodec(['vp9', 'vp8'], { width: options.width, height: options.height })
+    if (!codec) throw new Error('this browser encodes neither VP9 nor VP8 video')
+    // Slides are text and thin lines: the bitrate is set for that, not for camera footage (QUALITY_HIGH gives 720p VP9 about 0.6 Mbit/s).
+    const bitrate = Math.round(options.width * options.height * fps * 0.12)
+    video = new CanvasSource(canvas, { codec, bitrate, keyFrameInterval: 10, latencyMode: 'quality', contentHint: 'text' })
+    output.addVideoTrack(video, { frameRate: fps })
+    if (options.audio.length > 0) {
+      if (!(await canEncodeAudio('opus'))) throw new Error('this browser encodes no Opus audio')
+      audio = new AudioBufferSource({ codec: 'opus', bitrate: QUALITY_HIGH })
+      output.addAudioTrack(audio)
+      await load(options.audio)
+    }
+    const subtitles = options.subtitles.map(({ language, name, vtt }) => {
+      const source = new TextSubtitleSource('webvtt')
+      output.addSubtitleTrack(source, { ...language ? { languageCode: language } : {}, name })
+      return { source, vtt }
+    })
+    if (options.metadata) output.setMetadataTags(options.metadata)
+    await output.start()
+    // The muxer interleaves the cues with the frames as they come, so the cues are not awaited here.
+    subtitled = subtitles.map(({ source, vtt }) => source.add(vtt))
+  },
+  async frame(png, index) {
+    const bitmap = await createImageBitmap(new Blob([bytes(png)], { type: 'image/png' }))
+    context.drawImage(bitmap, 0, 0, canvas.width, canvas.height)
+    bitmap.close()
+    await video.add(index / fps, 1 / fps)
+    await audioUntil((index + 1) * 1000 / fps)
+  },
+  async finish() {
+    await audioUntil(total)
+    await Promise.all(subtitled)
+    await output.finalize()
+  },
+  /** The whole mix as 16-bit stereo PCM at 48 kHz, written a second at a time (FFmpeg encodes it). */
+  async mixdown(options) {
+    await load(options.audio)
+    let position = 0
+    for (let a = 0; a < options.duration; a += 1000) {
+      const buffer = mix(a, Math.min(a + 1000, options.duration)), left = buffer.getChannelData(0), right = buffer.getChannelData(1)
+      const pcm = new Int16Array(left.length * 2)
+      for (let i = 0; i < left.length; i++) { pcm[2 * i] = left[i] * 32767; pcm[2 * i + 1] = right[i] * 32767 }
+      const data = new Uint8Array(pcm.buffer)
+      await window.presmiumWrite(position, base64(data))
+      position += data.length
+    }
+  },
+}
+window.presmiumEncoderReady = true
+</script>`
+
+interface Hooks {
+  presmiumLecture: { duration: number, advance(t: number): Promise<void> }
+  presmiumEncoder: { start(options: unknown): Promise<void>, frame(png: string, index: number): Promise<void>, finish(): Promise<void>, mixdown(options: unknown): Promise<void> }
+}
+
+interface Page {
+  goto(url: string): Promise<unknown>
+  waitForFunction(fn: string, arg?: unknown, options?: { timeout?: number }): Promise<unknown>
+  evaluate<R, A>(fn: (arg: A) => R | Promise<R>, arg: A): Promise<R>
+  exposeFunction(name: string, fn: (...args: never[]) => unknown): Promise<void>
+  screenshot(options: { type: 'png' }): Promise<Buffer>
+  on(event: 'console' | 'pageerror', listener: (value: { text?(): string, message?: string }) => void): void
+}
+
+interface Chromium {
+  launch(): Promise<{
+    newContext(options: Record<string, unknown>): Promise<{ newPage(): Promise<Page> }>
+    close(): Promise<void>
+  }>
+}
+
+// ISO 639-2/T codes of the languages a lecture's captions are likely in (Matroska names a track's language so).
+const ISO_639_2: Record<string, string> = { zh: 'zho', en: 'eng', ja: 'jpn', ko: 'kor', fr: 'fra', de: 'deu', es: 'spa', it: 'ita', pt: 'por', ru: 'rus', ar: 'ara', hi: 'hin', vi: 'vie' }
+
+/** The ISO 639-2 code of a caption language: a three-letter language as it is, a two-letter one by the table. */
+function subtitleLanguage(lang: string): string | undefined {
+  const primary = lang.split('-')[0]!.toLowerCase()
+  return /^[a-z]{3}$/.test(primary) ? primary : ISO_639_2[primary]
+}
+
+interface CaptionFile {
+  lang: string
+  vtt: string
+}
+
+/** The captions the lecture renderer wrote for each language of the lecture. */
+function captionFiles(dir: string, langs: string[]): CaptionFile[] {
+  return langs.map(lang => ({ lang, vtt: readFileSync(join(dir, `captions.${lang}.vtt`), 'utf8') }))
+}
+
+function localAudio(track: LectureTrack, base: string): { url: string, start: number, duration: number, sourceStartMs?: number, volume?: number, muted?: boolean }[] {
+  return audioSegments(track).filter(segment => !ABSOLUTE_URL.test(segment.src)).map(({ src, ...segment }) => ({ url: `${base}${src}`, ...segment }))
+}
+
+/** The format of a lecture video whose file is not named: MP4 when FFmpeg can write it, else WebM from the browser. */
+export function defaultVideoFormat(): VideoFormat {
+  const ffmpeg = findFfmpeg()
+  return ffmpeg && ffmpegEncodes(ffmpeg, 'mp4') ? 'mp4' : 'webm'
+}
+
+export async function exportVideo(options: ExportOptions): Promise<ExportResult> {
+  const deckDir = resolve(options.deckDir)
+  const log = options.log ?? (() => {})
+  const [width, height, fps] = [options.width ?? 1920, options.height ?? 1080, options.fps ?? 30]
+  const work = join(deckDir, '.presmium', 'lecture-export')
+  rmSync(work, { recursive: true, force: true })
+  try {
+    log('building the web form and the lectures…')
+    const compilation = await new Compiler(deckDir).compile()
+    const actual = compilation.doc.source
+    if (options.source && (!actual || actual.documentId !== options.source.documentId || actual.version !== options.source.version || actual.fingerprint !== options.source.fingerprint)) throw new Error('job-source-changed')
+    const report = await build(compilation, { outDir: work, to: ['web', 'lecture'] })
+    const errors = report.findings.filter(f => f.severity === 'error')
+    // The first reason first: a one-line summary (a workbench shows it) says what to fix.
+    if (errors.length > 0) throw new Error(`${errors[0]!.message}${errors.length > 1 ? ` (and ${errors.length - 1} more)` : ''}\n${errors.map(f => `  ${f.message}`).join('\n')}`)
+    const warnings = report.findings.filter(f => f.severity === 'warning').map(f => f.message)
+    const web = report.outputs.find(o => o.renderer === 'web')
+    const lectures = report.outputs.find(o => o.renderer === 'lecture')
+    if (!web || !lectures) throw new Error('the web form or the lectures were not built')
+    const index = JSON.parse(readFileSync(join(lectures.outDir, 'index.json'), 'utf8')) as { id: string, captions?: string[] }[]
+    const ids = index.map(entry => entry.id)
+    const id = options.track ?? defaultTrack(ids)
+    if (!id || !ids.includes(id)) throw new Error(ids.length ? `name the lecture with --track: ${ids.join(', ')}` : LECTURE_MESSAGES[deckLocale(compilation.doc.meta.lang)].production.noPreparedLecture)
+    const track = parseTrack(JSON.parse(readFileSync(join(lectures.outDir, id, 'track.json'), 'utf8'))).track!
+    const file = resolve(options.out ?? join(deckDir, 'dist', `${id}.${defaultVideoFormat()}`))
+    mkdirSync(dirname(file), { recursive: true })
+    const format = videoFormat(file), found = findFfmpeg()
+    const ffmpeg = found && ffmpegEncodes(found, format) ? found : undefined
+    if (!ffmpeg && format === 'mp4') throw new Error(`an MP4 video needs FFmpeg with libx264 and aac: install it (${ffmpegInstallCommand()}) or set PRESMIUM_FFMPEG to its file`)
+    if (!ffmpeg) warnings.push(`FFmpeg was not found, so the browser encoded the video as WebM at a lower quality; install it for MP4 at a higher quality: ${ffmpegInstallCommand()}`)
+    const captions = captionFiles(join(lectures.outDir, id), index.find(entry => entry.id === id)?.captions ?? [])
+    if (options.burn && !captions.some(c => c.lang === options.burn)) throw new Error(`lecture ${id} has no captions in ${options.burn}: ${captions.map(c => c.lang).join(', ') || 'none'}`)
+    for (const { lang } of captions) {
+      if (!subtitleLanguage(lang)) warnings.push(`the subtitle track of the captions in ${lang} has no language code: its ISO 639-2 code is not known`)
+    }
+
+    const mediabunny = join(dirname(createRequire(import.meta.url).resolve('mediabunny')), 'mediabunny.min.mjs')
+    const server = await serveDirectory(work, {
+      extra: {
+        '/__export/encoder.html': { body: ENCODER, type: 'text/html; charset=utf-8' },
+        '/__export/mediabunny.mjs': { file: mediabunny, type: 'text/javascript' },
+      },
+    })
+    try {
+      const browser = await (await playwrightChromium<Chromium>(deckDir, import.meta.url)).launch()
+      try {
+        // With FFmpeg the encoder page only mixes the sound, into this file; without it, it writes the video.
+        const pcm = join(work, 'export-audio.pcm')
+        const handle = await open(ffmpeg ? pcm : file, 'w')
+        let native: FfmpegEncoder | undefined
+        try {
+          const context = await browser.newContext({ viewport: { width, height }, deviceScaleFactor: 1, reducedMotion: 'reduce', serviceWorkers: 'block' })
+          const [player, encoder] = [await context.newPage(), await context.newPage()]
+          const failures: string[] = []
+          for (const page of [player, encoder]) page.on('pageerror', error => failures.push(String(error.message)))
+          await player.goto(`${server.url}${web.base}?view=lecture&track=${encodeURIComponent(id)}&export${options.burn ? `&captions=${encodeURIComponent(options.burn)}` : ''}`)
+          await player.waitForFunction('Boolean(window.presmiumLecture)', undefined, { timeout: 120_000 })
+          const duration = Math.max(trackDuration(track), await player.evaluate(() => (window as unknown as Hooks).presmiumLecture.duration, undefined))
+          const frames = Math.max(1, Math.ceil(duration * fps / 1000))
+          await encoder.exposeFunction('presmiumWrite', async (position: number, data: string) => {
+            const bytes = Buffer.from(data, 'base64')
+            await handle.write(bytes, 0, bytes.length, position)
+          })
+          await encoder.goto(`${server.url}/__export/encoder.html`)
+          await encoder.waitForFunction('window.presmiumEncoderReady === true', undefined, { timeout: 60_000 })
+          const voice = track.voice
+          const label = voice.kind === 'synthetic' ? aigcLabel(voice.provider ?? voice.engine, id) : undefined
+          const audio = localAudio(track, `${server.url}${lectures.base}${encodeURIComponent(id)}/`)
+          const title = compilation.doc.meta.title
+          if (ffmpeg) {
+            if (audio.length > 0) await encoder.evaluate(options => (window as unknown as Hooks).presmiumEncoder.mixdown(options), { audio, duration: frames * 1000 / fps })
+            const subtitles = captions.map(({ lang, vtt }) => {
+              const caption = join(work, `export-captions.${lang}.vtt`)
+              writeFileSync(caption, vtt)
+              const language = subtitleLanguage(lang)
+              return { file: caption, name: lang, ...language ? { language } : {} }
+            })
+            native = startFfmpeg(ffmpeg, {
+              out: file,
+              fps,
+              ...audio.length > 0 ? { audio: pcm } : {},
+              subtitles,
+              metadata: { ...title ? { title } : {}, ...label ? { comment: aigcString(label), AIGC: JSON.stringify(label) } : {} },
+            })
+          } else {
+            await encoder.evaluate(options => (window as unknown as Hooks).presmiumEncoder.start(options), {
+              width,
+              height,
+              fps,
+              duration: frames * 1000 / fps,
+              audio,
+              subtitles: captions.map(({ lang, vtt }) => ({ language: subtitleLanguage(lang), name: lang, vtt })),
+              metadata: { title, ...label ? { comment: aigcString(label), raw: { AIGC: JSON.stringify(label) } } : {} },
+            })
+          }
+          log(`playing lecture ${id}: ${frames} frames at ${fps} fps, ${width}x${height}, ${ffmpeg ? `${format.toUpperCase()} by FFmpeg` : 'WebM by the browser'}`)
+          for (let i = 0; i < frames; i++) {
+            options.signal?.throwIfAborted()
+            const at = Math.round(i * 1000 / fps)
+            await player.evaluate(t => (window as unknown as Hooks).presmiumLecture.advance(t), at).catch((error: unknown) => {
+              throw new Error(`the frame at ${clockText(at)} cannot be drawn: ${errorMessage(error).replace(/^page\.evaluate: (Error: )?/, '')}`)
+            })
+            // PNG: a JPEG frame would blur the text before the encoder sees it.
+            const png = await player.screenshot({ type: 'png' })
+            if (native) await native.frame(png)
+            else await encoder.evaluate(([data, n]) => (window as unknown as Hooks).presmiumEncoder.frame(data, n), [png.toString('base64'), i] as [string, number])
+            if (failures.length) throw new Error(failures.join('\n'))
+            if ((i + 1) % Math.max(1, Math.round(frames / 10)) === 0) log(`  ${Math.round((i + 1) * 100 / frames)}%`)
+            options.progress?.(i + 1, frames)
+          }
+          if (native) await native.finish()
+          else await encoder.evaluate(() => (window as unknown as Hooks).presmiumEncoder.finish(), undefined)
+          // The captions go beside the video once the video is whole.
+          const sidecars = captions.map(({ lang, vtt }) => {
+            const sidecar = `${file.replace(/\.(webm|mp4)$/i, '')}.${lang}.vtt`
+            writeFileSync(sidecar, vtt)
+            return { lang, file: sidecar }
+          })
+          return { file, track: id, frames, duration: frames * 1000 / fps, captions: sidecars, warnings }
+        } finally {
+          native?.kill()
+          await handle.close()
+        }
+      } finally {
+        await browser.close()
+      }
+    } finally {
+      await server.close()
+    }
+  } finally {
+    rmSync(work, { recursive: true, force: true })
+  }
+}

package/src/node/ffmpeg.ts

@@ -0,0 +1,76 @@
+import { spawn } from 'node:child_process'
+import { once } from 'node:events'
+import type { Ffmpeg } from '@lincyaw/kernel/node'
+
+export type VideoFormat = 'mp4' | 'webm'
+
+const ENCODERS: Record<VideoFormat, string[]> = { mp4: ['libx264', 'aac'], webm: ['libvpx-vp9', 'libopus'] }
+
+export function videoFormat(file: string): VideoFormat {
+  return file.toLowerCase().endsWith('.webm') ? 'webm' : 'mp4'
+}
+
+/** Whether this FFmpeg has the encoders of the format. */
+export function ffmpegEncodes(ffmpeg: Ffmpeg, format: VideoFormat): boolean {
+  return ENCODERS[format].every(name => ffmpeg.encoders.has(name))
+}
+
+export interface FfmpegVideo {
+  out: string
+  fps: number
+  /** 16-bit stereo PCM at 48 kHz, the whole lecture's sound. */
+  audio?: string
+  subtitles: { file: string, name: string, language?: string }[]
+  metadata: Record<string, string>
+}
+
+export interface FfmpegEncoder {
+  frame(png: Buffer): Promise<void>
+  finish(): Promise<void>
+  kill(): void
+}
+
+/** An FFmpeg process that takes the frames as PNG on its input and writes the video with its sound and subtitle tracks. */
+export function startFfmpeg(ffmpeg: Ffmpeg, video: FfmpegVideo): FfmpegEncoder {
+  const format = videoFormat(video.out)
+  const args = ['-hide_banner', '-loglevel', 'error', '-y', '-f', 'image2pipe', '-c:v', 'png', '-framerate', String(video.fps), '-i', '-']
+  if (video.audio) args.push('-f', 's16le', '-ar', '48000', '-ac', '2', '-i', video.audio)
+  for (const { file } of video.subtitles) args.push('-i', file)
+  args.push('-map', '0:v')
+  if (video.audio) args.push('-map', '1:a')
+  video.subtitles.forEach((_, i) => args.push('-map', `${i + (video.audio ? 2 : 1)}:s`))
+  // Even sides for 4:2:0; slides are text, so the quality is set by a constant rate factor rather than a bitrate.
+  args.push('-vf', 'scale=trunc(iw/2)*2:trunc(ih/2)*2', '-pix_fmt', 'yuv420p', '-g', String(Math.round(video.fps * 10)))
+  // FFmpeg's AAC noise substitution turns some music into bursts above the source's true peak; it is off.
+  if (format === 'mp4') args.push('-c:v', 'libx264', '-preset', 'medium', '-crf', '18', '-c:a', 'aac', '-b:a', '192k', '-aac_pns', '0', '-c:s', 'mov_text', '-movflags', '+faststart+use_metadata_tags')
+  else args.push('-c:v', 'libvpx-vp9', '-crf', '24', '-b:v', '0', '-deadline', 'good', '-cpu-used', '2', '-row-mt', '1', '-c:a', 'libopus', '-b:a', '128k', '-c:s', 'webvtt')
+  video.subtitles.forEach(({ name, language }, i) => {
+    if (language) args.push(`-metadata:s:s:${i}`, `language=${language}`)
+    args.push(`-metadata:s:s:${i}`, `title=${name}`)
+  })
+  for (const [key, value] of Object.entries(video.metadata)) args.push('-metadata', `${key}=${value}`)
+  args.push(video.out)
+
+  const child = spawn(ffmpeg.file, args, { stdio: ['pipe', 'ignore', 'pipe'] })
+  let stderr = ''
+  child.stderr.setEncoding('utf8').on('data', (text: string) => { stderr = (stderr + text).slice(-4000) })
+  child.stdin.on('error', () => {})
+  const exited = new Promise<void>((resolve, reject) => {
+    child.on('error', reject)
+    child.on('close', (code, signal) => code === 0 ? resolve() : reject(new Error(`ffmpeg stopped (${code ?? signal}): ${stderr.trim() || 'no message'}`)))
+  })
+  exited.catch(() => {})
+  return {
+    async frame(png) {
+      if (child.exitCode !== null || !child.stdin.writable) return exited
+      if (!child.stdin.write(png)) await Promise.race([once(child.stdin, 'drain'), exited])
+    },
+    async finish() {
+      child.stdin.end()
+      await exited
+    },
+    kill() {
+      if (child.exitCode === null) child.kill('SIGKILL')
+    },
+  }
+}

package/src/node/latest-ir.ts

@@ -0,0 +1,54 @@
+import { resolve } from 'node:path'
+import { viewFor } from '@lincyaw/compiler'
+import { isRecord } from '@lincyaw/kernel'
+import type { IRDocument, IRPass } from '@lincyaw/kernel'
+import { configuredLectureVoice, LECTURE_ID, LECTURE_RENDERER, prepareNarrationVoices } from '../domain/index.ts'
+import { deckPlan } from './plan.ts'
+import { trackIds } from './store.ts'
+
+const views = new WeakMap<IRDocument, IRDocument>()
+
+export function lectureView(doc: IRDocument): IRDocument {
+  let view = views.get(doc)
+  if (!view) views.set(doc, view = viewFor(doc, LECTURE_RENDERER))
+  return view
+}
+
+const latest = new Map<string, IRDocument>()
+
+export function latestDoc(deckDir: string): IRDocument | undefined {
+  return latest.get(deckDir)
+}
+
+export function latestView(deckDir: string): IRDocument | undefined {
+  const doc = latest.get(deckDir)
+  return doc && lectureView(doc)
+}
+
+function rememberLatestIr(doc: IRDocument, deckDir: string): void {
+  const remembered = latest.get(deckDir)
+  const translation = Boolean(doc.meta.translationOf) || Object.values(remembered?.config.translations ?? {}).some(entry => resolve(deckDir, entry) === doc.meta.entry)
+  if (!translation) latest.set(deckDir, doc)
+}
+
+function writeLecturesFlag(doc: IRDocument, deckDir: string): void {
+  const own = isRecord(doc.config.presmium[LECTURE_ID]) ? doc.config.presmium[LECTURE_ID] as Record<string, unknown> : {}
+  const renderers = Object.keys(doc.config.renderers)
+  const built = renderers.length === 0 || renderers.includes(LECTURE_RENDERER)
+  const silent = deckPlan(doc).silent
+  const lectures = typeof own.url === 'string' || (built && (Boolean(configuredLectureVoice(doc)) || silent || trackIds(deckDir).length > 0))
+  doc.config.presmium = { ...doc.config.presmium, [LECTURE_ID]: { ...own, lectures } }
+}
+
+export const rememberLatestIrPass: IRPass = {
+  name: 'presmium.lecture.keep',
+  after: 'execute',
+  order: 1000,
+  run(doc, ctx) {
+    try { prepareNarrationVoices(doc) } catch (error) {
+      ctx.report({ checkId: LECTURE_ID, severity: 'error', message: error instanceof Error ? error.message : String(error), source: { file: doc.meta.entry, line: 1 } })
+    }
+    rememberLatestIr(doc, ctx.deckDir)
+    writeLecturesFlag(doc, ctx.deckDir)
+  },
+}

package/src/node/plan.ts

@@ -0,0 +1,35 @@
+import { isRecord } from '@lincyaw/kernel'
+import type { Finding, IRDocument } from '@lincyaw/kernel'
+import { configuredLectureVoice, LECTURE_ID, lectureGap, lecturePlan, lexiconOf, plannedUtterances } from '../domain/index.ts'
+import type { LecturePlan, LectureVoice } from '../domain/index.ts'
+import { productionDiagnostics } from '../domain/production.ts'
+
+export interface DeckPlan {
+  plan: LecturePlan
+  voice?: LectureVoice
+  silent: boolean
+  recorded: boolean
+  lang: string
+  lexicon?: Record<string, string>
+  gap: number
+  findings: Finding[]
+}
+
+export function lectureConfig(doc: IRDocument): Record<string, unknown> {
+  const config = doc.config.renderers.lecture
+  return isRecord(config) ? config : {}
+}
+
+export function deckPlan(doc: IRDocument): DeckPlan {
+  const config = lectureConfig(doc)
+  const findings: Finding[] = []
+  const plan = lecturePlan(doc)
+  findings.push(...plan.problems.filter(p => !p.reportedAtCompile).map((p): Finding => ({ checkId: LECTURE_ID, severity: 'warning', message: p.message, ...p.source ? { source: { file: p.source.file, line: p.source.line } } : {} })))
+  findings.push(...productionDiagnostics(doc, plan).map(issue => ({ checkId: LECTURE_ID, severity: issue.severity, message: issue.message, source: issue.sectionId ? doc.sections.find(section => section.id === issue.sectionId)?.source : { file: doc.meta.entry, line: 1 } })))
+  const silent = plannedUtterances(plan).length === 0 || Boolean(doc.production && [doc.production.defaults, ...Object.values(doc.production.sectionOverrides ?? {}), ...Object.values(doc.production.stepOverrides)].some(setting => setting.voiceSource?.type === 'none'))
+  const own = doc.config.presmium[LECTURE_ID]
+  const voice = configuredLectureVoice(doc)
+  const lexicon = lexiconOf(isRecord(own) ? own : undefined)
+  const recorded = plan.sections.some(section => section.recordings?.length)
+  return { plan, silent, recorded, ...voice ? { voice } : {}, lang: doc.meta.lang ?? 'zh-CN', ...lexicon ? { lexicon } : {}, gap: lectureGap(config), findings }
+}

package/src/node/presmium.ts

@@ -0,0 +1,59 @@
+import { createRequire } from 'node:module'
+import { basename, join } from 'node:path'
+import { PRODUCTION_AUDIO_AUTHORING, VOICEOVER, VOICEOVER_EXECUTION } from '@lincyaw/kernel'
+import type { Exporter, PresmiumNodePlugin } from '@lincyaw/kernel'
+import { LECTURE_ID } from '../domain/index.ts'
+import { lectureCheck } from './check.ts'
+import { defaultVideoFormat, exportVideo } from './export.ts'
+import { rememberLatestIrPass } from './latest-ir.ts'
+import { lectureRenderer } from './renderer.ts'
+import { cueRole, sayRole } from './roles.ts'
+import { lectureServer } from './routes/server.ts'
+import { LECTURE_DECK, lectureTools } from './tools.ts'
+import { productionAudioAuthoring } from './audio-authoring.ts'
+import { voiceoverExecution } from './voiceover-execution.ts'
+
+const { version } = createRequire(import.meta.url)('../../package.json') as { version: string }
+
+/** The narrated lecture as a WebM video with its captions, as `presmium-lecture export` makes it. */
+const videoExporter: Exporter = {
+  id: 'video',
+  label: { 'zh-CN': '讲授视频', 'en': 'Lecture video' },
+  available: (doc) => {
+    const named = Object.keys(doc.config.renderers)
+    return named.length === 0 || named.includes('lecture')
+  },
+  async run(ctx) {
+    ctx.progress('build')
+    if (!ctx.source) throw new Error('job-source-not-compiled')
+    const result = await exportVideo({
+      deckDir: ctx.deckDir,
+      source: ctx.source,
+      out: join(ctx.outDir, `lecture.${defaultVideoFormat()}`),
+      log: ctx.log,
+      progress: (done, total) => ctx.progress('frames', done, total),
+      signal: ctx.signal,
+    })
+    return {
+      files: [basename(result.file), ...result.captions.map(({ file }) => basename(file))],
+      captions: Object.fromEntries(result.captions.map(({ lang, file }) => [lang, basename(file)])),
+      warnings: result.warnings,
+    }
+  },
+}
+
+const plugin: PresmiumNodePlugin = {
+  id: LECTURE_ID,
+  version,
+  kernel: '^1.0.0',
+  checks: [lectureCheck],
+  renderer: lectureRenderer,
+  server: lectureServer,
+  roles: [cueRole, sayRole],
+  passes: [rememberLatestIrPass],
+  services: ctx => [[LECTURE_DECK, { deckDir: ctx.deckDir, workspaceRoot: ctx.workspaceRoot }], [VOICEOVER, { version: 1, preview: true }], [VOICEOVER_EXECUTION, voiceoverExecution(ctx)], [PRODUCTION_AUDIO_AUTHORING, productionAudioAuthoring(ctx)]],
+  tools: lectureTools,
+  exporters: [videoExporter],
+}
+
+export default plugin