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

package/src/node/cache.ts

@@ -0,0 +1,280 @@
+import { createHash, randomBytes } from 'node:crypto'
+import { closeSync, constants, fstatSync, mkdirSync, openSync, readFileSync, readSync, realpathSync, renameSync, writeFileSync } from 'node:fs'
+import { join, relative, sep } from 'node:path'
+import type { AigcLabel, DocumentFiles, SpeechWord, SynthesisRequest } from '@lincyaw/kernel'
+import { isRecord, speechEngineId } from '@lincyaw/kernel'
+import { fileVersion } from '@lincyaw/kernel/node'
+import { applyLexicon } from '../domain/index.ts'
+import type { CacheProfile } from './backend.ts'
+import type { SynthesisResult } from './backend.ts'
+
+export function cacheKey(request: SynthesisRequest & { engine: string }, spoken: string): string {
+  const parts = ['presmium.speech/1', speechEngineId(request.engine), request.voice, request.lang, request.rate ?? 1, request.style ?? '', request.text, spoken]
+  return createHash('sha256').update(JSON.stringify(parts)).digest('hex').slice(0, 32)
+}
+
+export function profileCacheKey(requestKey: string, profile: string): string {
+  return createHash('sha256').update(JSON.stringify(['presmium.speech/2', requestKey, profile])).digest('hex').slice(0, 32)
+}
+
+const KEY = /^[0-9a-f]{32}$/
+const SHA = /^[0-9a-f]{64}$/
+const MAX_LOCK_ENTRIES = 16_384
+const MAX_LOCK_BYTES = 4_194_304
+const LOCK_WRITES = new Map<string, Promise<unknown>>()
+
+export interface CacheRecord {
+  key: string
+  audio: string
+  mime: string
+  duration: number
+  words?: SpeechWord[]
+  engine: string
+  model: string
+  voice: string
+  provider: string
+  cloned: boolean
+  lang: string
+  text: string
+  synthetic: true
+  AIGC: AigcLabel
+  sha256: string
+  /** Opaque, credential-free configuration identity. Absent on legacy locked records. */
+  profile?: string
+  requestKey?: string
+  request?: { spoken: string, rate: number, style: string }
+}
+
+interface LockFile {
+  version: 1
+  synthesis: Record<string, { audio: string, sha256: string, requestKey?: string, profile?: string }>
+}
+
+interface LockSnapshot {
+  version: string
+  lock: Readonly<{ version: 1, synthesis: Readonly<LockFile['synthesis']> }>
+  requests: ReadonlyMap<string, string | undefined>
+}
+
+const OPEN_FLAGS = constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0)
+
+function readRegular(file: string, maxBytes = Infinity): Buffer | undefined {
+  let fd: number
+  try {
+    fd = openSync(file, OPEN_FLAGS)
+  } catch {
+    return undefined
+  }
+  try {
+    const stat = fstatSync(fd)
+    if (!stat.isFile() || stat.size > maxBytes) return undefined
+    const bytes = readFileSync(fd)
+    return bytes.length <= maxBytes ? bytes : undefined
+  } catch {
+    return undefined
+  } finally {
+    closeSync(fd)
+  }
+}
+
+function wordsOf(value: unknown): value is SpeechWord[] {
+  return Array.isArray(value) && value.every(word => isRecord(word) && typeof word.text === 'string' && Number.isFinite(word.start) && Number.isFinite(word.end) && (word.start as number) >= 0 && (word.end as number) >= (word.start as number))
+}
+
+function writeAtomic(file: string, data: string | Uint8Array): void {
+  const temporary = `${file}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`
+  writeFileSync(temporary, data, { flag: 'wx' })
+  renameSync(temporary, file)
+}
+
+export class SynthesisCache {
+  readonly dir: string
+  readonly lockFile: string
+
+  readonly #deckDir: string
+  readonly #workspaceRoot: string
+  readonly #files: () => DocumentFiles | undefined
+  #lockSnapshot?: LockSnapshot
+
+  constructor(deckDir: string, workspaceRoot = deckDir, files: () => DocumentFiles | undefined = () => undefined) {
+    this.#deckDir = deckDir
+    this.#workspaceRoot = workspaceRoot
+    this.#files = files
+    this.dir = join(deckDir, '.presmium', 'speech')
+    this.lockFile = join(deckDir, '.presmium', 'speech.lock.json')
+  }
+
+  async #put(file: string, data: string | Uint8Array): Promise<void> {
+    const files = this.#files()
+    if (!files) return writeAtomic(file, data)
+    await files.write([{ path: relative(this.#workspaceRoot, file).split(sep).join('/'), content: typeof data === 'string' ? Buffer.from(data) : data }])
+  }
+
+  #contained(): boolean {
+    const deck = realpathSync(this.#deckDir)
+    const dir = realpathSync(this.dir)
+    return dir === join(deck, '.presmium', 'speech')
+  }
+
+  async find(key: string): Promise<{ record: CacheRecord, file: string, audio: Buffer } | undefined> {
+    if (!KEY.test(key)) return undefined
+    let found: { record: CacheRecord, file: string, audio: Buffer }
+    try {
+      if (!this.#contained()) return undefined
+      const json = readRegular(join(this.dir, `${key}.json`), 1_048_576)
+      const record = json && JSON.parse(json.toString('utf8')) as CacheRecord
+      if (!isRecord(record) || record.key !== key || typeof record.audio !== 'string') return undefined
+      if (record.audio !== `${key}.wav` && record.audio !== `${key}.ogg`) return undefined
+      if (!['engine', 'model', 'voice', 'provider', 'lang', 'text', 'mime'].every(field => typeof record[field] === 'string') || !Number.isFinite(record.duration) || record.duration <= 0 || !SHA.test(record.sha256) || record.synthetic !== true || !isRecord(record.AIGC) || record.AIGC.ProduceID !== key || record.AIGC.ContentProducer !== record.provider) return undefined
+      if (record.words !== undefined && !wordsOf(record.words)) return undefined
+      if (record.profile !== undefined || record.requestKey !== undefined || record.request !== undefined) {
+        if (!SHA.test(record.profile ?? '') || !KEY.test(record.requestKey ?? '') || !isRecord(record.request) || typeof record.request.spoken !== 'string' || typeof record.request.style !== 'string' || !Number.isFinite(record.request.rate)) return undefined
+        if (cacheKey({ engine: record.engine, voice: record.voice, lang: record.lang, text: record.text, rate: record.request.rate, style: record.request.style }, record.request.spoken) !== record.requestKey || profileCacheKey(record.requestKey!, record.profile!) !== key) return undefined
+      }
+      const file = join(this.dir, record.audio)
+      const audio = readRegular(file)
+      if (!audio || createHash('sha256').update(audio).digest('hex') !== record.sha256) return undefined
+      found = { record, file, audio }
+    } catch {
+      return undefined
+    }
+    return found
+  }
+
+  /** Offline reuse requires an explicit lock; a read never creates or repairs that lock. */
+  locked(record: CacheRecord): boolean {
+    const entry = this.#readLock()?.lock.synthesis[record.key]
+    return !!entry && entry.audio === record.audio && entry.sha256 === record.sha256 && entry.profile === record.profile && entry.requestKey === record.requestKey
+  }
+
+  resolveRequest(requestKey: string): string | undefined {
+    if (!KEY.test(requestKey)) return undefined
+    return this.#readLock()?.requests.get(requestKey)
+  }
+
+  async write(result: SynthesisResult, request: SynthesisRequest): Promise<{ record: CacheRecord, file: string }> {
+    const spoken = applyLexicon(request.text, request.lexicon)
+    if (!SHA.test(result.profile ?? '') || cacheKey({ ...request, engine: result.engine }, spoken) !== result.requestKey || profileCacheKey(result.requestKey!, result.profile!) !== result.key) throw new Error('synthesis cache identity does not match the generated request')
+    if (!this.#files()) {
+      mkdirSync(this.dir, { recursive: true })
+      if (!this.#contained()) throw new Error(`the synthesis cache ${this.dir} resolves outside the deck`)
+    }
+    const audio = `${result.key}.${result.ext}`
+    const file = join(this.dir, audio)
+    const record: CacheRecord = {
+      key: result.key,
+      audio,
+      mime: result.mime,
+      duration: result.duration,
+      ...result.words ? { words: result.words } : {},
+      engine: result.engine,
+      model: result.model,
+      voice: result.voice,
+      provider: result.provider,
+      cloned: result.cloned,
+      lang: request.lang,
+      text: request.text,
+      synthetic: true,
+      AIGC: result.AIGC,
+      sha256: createHash('sha256').update(result.audio).digest('hex'),
+      profile: result.profile,
+      requestKey: result.requestKey,
+      request: { spoken, rate: request.rate ?? 1, style: request.style ?? '' },
+    }
+    await this.#put(file, result.audio)
+    await this.#put(join(this.dir, `${result.key}.json`), `${JSON.stringify(record, null, 2)}\n`)
+    await this.#lock(result.key, record)
+    return { record, file }
+  }
+
+  readAlignment(record: CacheRecord, lang: string, transcriber: CacheProfile): SpeechWord[] | undefined {
+    const key = record.key
+    if (!KEY.test(key)) return undefined
+    try {
+      if (!this.#contained()) return undefined
+      const value: unknown = JSON.parse(readRegular(join(this.dir, `${key}.align.json`), 1_048_576)?.toString('utf8') ?? '')
+      if (!isRecord(value) || value.key !== key || value.sha256 !== record.sha256 || value.profile !== (record.profile ?? null) || value.lang !== lang || typeof value.transcriber !== 'string' || !SHA.test(value.transcriber) || !wordsOf(value.words)) return undefined
+      if (transcriber.status === 'unavailable' || transcriber.status === 'configured' && value.transcriber !== transcriber.profile) return undefined
+      return value.words
+    } catch {
+      return undefined
+    }
+  }
+
+  async writeAlignment(record: CacheRecord, lang: string, transcriber: string, words: SpeechWord[]): Promise<void> {
+    await this.#put(join(this.dir, `${record.key}.align.json`), `${JSON.stringify({ key: record.key, sha256: record.sha256, profile: record.profile ?? null, lang, transcriber, words }, null, 2)}\n`)
+  }
+
+  async pruneLock(keep: ReadonlySet<string>): Promise<number> {
+    return this.#updateLock(async lock => {
+      const kept = Object.keys(lock.synthesis).filter(key => keep.has(key))
+      const dropped = Object.keys(lock.synthesis).length - kept.length
+      if (dropped > 0) await this.#writeLock(Object.fromEntries(kept.map(key => [key, lock.synthesis[key]!])))
+      return dropped
+    })
+  }
+
+  async #lock(key: string, record: CacheRecord): Promise<void> {
+    await this.#updateLock(async lock => {
+      const entry = { audio: record.audio, sha256: record.sha256, requestKey: record.requestKey, profile: record.profile }
+      if (JSON.stringify(lock.synthesis[key]) === JSON.stringify(entry)) return
+      lock.synthesis[key] = entry
+      await this.#writeLock(lock.synthesis)
+    })
+  }
+
+  async #updateLock<T>(update: (lock: LockFile) => Promise<T>): Promise<T> {
+    const before = LOCK_WRITES.get(this.lockFile) ?? Promise.resolve()
+    const pending = before.catch(() => undefined).then(() => update({ version: 1, synthesis: { ...this.#readLock()?.lock.synthesis } }))
+    LOCK_WRITES.set(this.lockFile, pending)
+    try { return await pending }
+    finally { if (LOCK_WRITES.get(this.lockFile) === pending) LOCK_WRITES.delete(this.lockFile) }
+  }
+
+  #readLock(): LockSnapshot | undefined {
+    let fd: number | undefined
+    try {
+      fd = openSync(this.lockFile, OPEN_FLAGS)
+      const before = fstatSync(fd, { bigint: true })
+      if (!before.isFile() || before.size > BigInt(MAX_LOCK_BYTES)) throw new Error('invalid speech lock size')
+      const version = fileVersion(before)
+      if (this.#lockSnapshot?.version === version) return this.#lockSnapshot
+      // Read at most the observed extent plus one byte, and reject an in-place change while reading.
+      const bytes = Buffer.alloc(Number(before.size) + 1)
+      let length = 0
+      while (length < bytes.length) {
+        const count = readSync(fd, bytes, length, bytes.length - length, length)
+        if (!count) break
+        length += count
+      }
+      if (length !== Number(before.size) || fileVersion(fstatSync(fd, { bigint: true })) !== version) throw new Error('speech lock changed while reading')
+      const read: unknown = JSON.parse(bytes.subarray(0, length).toString('utf8'))
+      if (!isRecord(read) || read.version !== 1 || !isRecord(read.synthesis)) throw new Error('invalid speech lock')
+      const entries = Object.entries(read.synthesis)
+      if (entries.length > MAX_LOCK_ENTRIES || !entries.every(([key, entry]) => KEY.test(key) && isRecord(entry) && (entry.audio === `${key}.ogg` || entry.audio === `${key}.wav`) && typeof entry.sha256 === 'string' && SHA.test(entry.sha256) && (entry.profile === undefined && entry.requestKey === undefined || typeof entry.profile === 'string' && SHA.test(entry.profile) && typeof entry.requestKey === 'string' && KEY.test(entry.requestKey)))) throw new Error('invalid speech lock entries')
+      const lock = read as unknown as LockFile, requests = new Map<string, string | undefined>()
+      for (const [key, entry] of Object.entries(lock.synthesis)) {
+        const requestKey = entry.requestKey ?? key
+        requests.set(requestKey, requests.has(requestKey) ? undefined : key)
+        Object.freeze(entry)
+      }
+      Object.freeze(lock.synthesis)
+      Object.freeze(lock)
+      return this.#lockSnapshot = { version, lock, requests }
+    } catch {
+      this.#lockSnapshot = undefined
+      return undefined
+    } finally {
+      if (fd !== undefined) closeSync(fd)
+    }
+  }
+
+  async #writeLock(synthesis: LockFile['synthesis']): Promise<void> {
+    if (Object.keys(synthesis).length > MAX_LOCK_ENTRIES) throw new Error('synthesis lock exceeds its entry limit')
+    const entries = Object.keys(synthesis).sort().map(k => `    ${JSON.stringify(k)}: ${JSON.stringify(synthesis[k])}`)
+    const text = `{\n  "version": 1,\n  "synthesis": {${entries.length ? `\n${entries.join(',\n')}\n  ` : ''}}\n}\n`
+    if (Buffer.byteLength(text) > MAX_LOCK_BYTES) throw new Error('synthesis lock exceeds its byte limit')
+    await this.#put(this.lockFile, text)
+    this.#lockSnapshot = undefined
+  }
+}

package/src/node/cached-speech.ts

@@ -0,0 +1,156 @@
+import { DOCUMENT_FILES, speechEngineId } from '@lincyaw/kernel'
+import type { NodeServiceContext, SpeechWord, SynthesisRequest, TranscriptionRequest, VoiceCatalog } from '@lincyaw/kernel'
+import type { DeckSpeechConfig } from '../domain/index.ts'
+import { applyLexicon, deckSpeechConfig } from '../domain/index.ts'
+import type { CloneInput, SpeechBackend, SynthesisResult } from './backend.ts'
+import { cacheKey, profileCacheKey, SynthesisCache } from './cache.ts'
+import type { SpeechCore } from './core.ts'
+import { speechCore } from './core.ts'
+import { SpeechError } from './errors.ts'
+
+export class CachedSpeech implements SpeechBackend {
+  readonly #inner: SpeechBackend
+  readonly #defaults: DeckSpeechConfig
+  readonly cache: SynthesisCache
+
+  constructor(inner: SpeechBackend, cache: SynthesisCache, defaults: DeckSpeechConfig) {
+    this.#inner = inner
+    this.cache = cache
+    this.#defaults = defaults
+  }
+
+  listEngines(lang?: string) {
+    return this.#inner.listEngines(lang)
+  }
+
+  async defaultSynthesisEngine() {
+    return this.#defaults.engine ?? this.#inner.defaultSynthesisEngine()
+  }
+
+  cacheProfile(engine: string | undefined, use: 'synthesize' | 'transcribe', lang?: string) {
+    return this.#inner.cacheProfile(engine, use, lang)
+  }
+
+  /** Resolves the cache identity locally, including document defaults, without generating audio. */
+  async synthesisKey(request: SynthesisRequest): Promise<string | undefined> {
+    const engine = request.engine ?? await this.defaultSynthesisEngine()
+    if (!engine) return undefined
+    const requestKey = cacheKey({ ...request, engine: speechEngineId(engine) }, applyLexicon(request.text, request.lexicon))
+    const profile = await this.cacheProfile(engine, 'synthesize')
+    return profile.status === 'configured' ? profileCacheKey(requestKey, profile.profile) : profile.status === 'absent' ? this.cache.resolveRequest(requestKey) : undefined
+  }
+
+  /** Every consumer, including direct clip playback and alignment, uses this identity/SHA gate. */
+  async cached(key: string) {
+    const hit = await this.cache.find(key)
+    if (!hit) return undefined
+    const current = await this.cacheProfile(hit.record.engine, 'synthesize', hit.record.lang)
+    if (current.status === 'configured') return hit.record.profile === current.profile && hit.record.model === current.model && hit.record.provider === current.provider ? hit : undefined
+    return current.status === 'absent' && this.cache.locked(hit.record) ? hit : undefined
+  }
+
+  async lookup(request: SynthesisRequest) {
+    const engine = request.engine ?? await this.defaultSynthesisEngine()
+    const key = await this.synthesisKey({ ...request, engine })
+    const hit = key ? await this.cached(key) : undefined
+    return hit && hit.record.engine === speechEngineId(engine!) && hit.record.text === request.text && hit.record.lang === request.lang && hit.record.voice === request.voice ? hit : undefined
+  }
+
+  /** The engine that transcribes without one named: the deck's transcription engine, else its default engine when that one transcribes. */
+  async #transcriptionEngine(): Promise<string | undefined> {
+    if (this.#defaults.transcribe) return this.#defaults.transcribe
+    const named = this.#defaults.engine
+    if (!named) return undefined
+    const { engines } = await this.#inner.listEngines()
+    return engines.find(engine => engine.id === speechEngineId(named))?.stt ? named : undefined
+  }
+
+  voices(engine: string | undefined, lang?: string, signal?: AbortSignal) {
+    return this.#inner.voices(engine ?? this.#defaults.engine, lang, signal)
+  }
+
+  async voiceCatalog(engine: string | undefined, lang?: string, signal?: AbortSignal): Promise<VoiceCatalog> {
+    return this.#inner.voiceCatalog?.(engine ?? this.#defaults.engine, lang, signal) ?? { status: 'unavailable', reason: 'unknown', voices: [] }
+  }
+
+  async synthesizeThroughCache(request: SynthesisRequest, signal?: AbortSignal): Promise<{ result: SynthesisResult, file: string }> {
+    const engine = request.engine ?? await this.defaultSynthesisEngine()
+    if (!engine) return this.#write(await this.#inner.synthesize(request, signal), request)
+    const hit = await this.lookup({ ...request, engine })
+    if (hit) {
+      const { record, file, audio } = hit
+      await this.#inner.consent(record.engine, record.voice, record.cloned === true, signal)
+      const result: SynthesisResult = {
+        audio: new Uint8Array(audio),
+        mime: record.mime,
+        ext: record.audio.split('.').at(-1)!,
+        duration: record.duration,
+        ...record.words ? { words: record.words } : {},
+        engine: record.engine,
+        model: record.model,
+        voice: record.voice,
+        provider: record.provider,
+        cloned: record.cloned,
+        key: record.key,
+        ...record.profile ? { profile: record.profile, requestKey: record.requestKey } : {},
+        AIGC: record.AIGC,
+      }
+      return { result, file }
+    }
+    return this.#write(await this.#inner.synthesize({ ...request, engine }, signal), request)
+  }
+
+  async #write(result: SynthesisResult, request: SynthesisRequest): Promise<{ result: SynthesisResult, file: string }> {
+    return { result, file: (await this.cache.write(result, request)).file }
+  }
+
+  async synthesize(request: SynthesisRequest, signal?: AbortSignal): Promise<SynthesisResult> {
+    return (await this.synthesizeThroughCache(request, signal)).result
+  }
+
+  async alignWords(key: string, options: { lang: string, transcribe?: boolean }, signal?: AbortSignal): Promise<SpeechWord[] | undefined> {
+    const hit = await this.cached(key)
+    if (!hit) return undefined
+    const engine = await this.#transcriptionEngine()
+    const transcriber = await this.cacheProfile(engine, 'transcribe')
+    const kept = this.cache.readAlignment(hit.record, options.lang, transcriber)
+    if (kept) return kept
+    if (options.transcribe === false || transcriber.status !== 'configured') return undefined
+    try {
+      const transcript = await this.#inner.transcribe({ audio: new Blob([new Uint8Array(hit.audio)], { type: hit.record.mime }), lang: options.lang, engine }, signal)
+      const words = transcript.segments.flatMap(segment => segment.words)
+      if (words.length === 0) return undefined
+      await this.cache.writeAlignment(hit.record, options.lang, transcriber.profile, words)
+      return words
+    } catch {
+      return undefined
+    }
+  }
+
+  consent(engine: string, voice: string, recorded: boolean, signal?: AbortSignal): Promise<void> {
+    return this.#inner.consent(engine, voice, recorded, signal)
+  }
+
+  async cloneVoice(input: CloneInput, signal?: AbortSignal) {
+    if (!this.#inner.cloneVoice) throw new SpeechError(400, 'this speech service cannot clone voices')
+    return this.#inner.cloneVoice({ ...input, engine: input.engine ?? this.#defaults.engine }, signal)
+  }
+
+  async cloneStatus(engine: string | undefined, voice: string, signal?: AbortSignal) {
+    if (!this.#inner.cloneStatus) throw new SpeechError(400, 'this speech service cannot clone voices')
+    return this.#inner.cloneStatus(engine ?? this.#defaults.engine, voice, signal)
+  }
+
+  async transcribe(request: TranscriptionRequest, signal?: AbortSignal) {
+    const engine = request.engine ?? await this.#transcriptionEngine()
+    return this.#inner.transcribe({ ...request, ...engine ? { engine } : {} }, signal)
+  }
+}
+
+export type DeckSpeechContext = Pick<NodeServiceContext, 'deckDir' | 'workspaceRoot' | 'config' | 'settings' | 'operatorDir' | 'log' | 'secret' | 'service'>
+
+export function createDeckSpeech(ctx: DeckSpeechContext): { core: SpeechCore, speech: CachedSpeech } {
+  const core = speechCore({ names: () => [...new Set([...Object.keys(process.env), ...ctx.secret('PRESMIUM_SPEECH_VOLCENGINE_KEY') ? ['PRESMIUM_SPEECH_VOLCENGINE_KEY'] : []])], secret: name => ctx.secret(name), settings: ctx.settings, operatorDir: ctx.operatorDir, log: ctx.log })
+  const cache = new SynthesisCache(ctx.deckDir, ctx.workspaceRoot, () => ctx.service?.(DOCUMENT_FILES))
+  return { core, speech: new CachedSpeech(core, cache, deckSpeechConfig(ctx.config).config) }
+}

package/src/node/cli.ts

@@ -0,0 +1,131 @@
+import { execFileSync } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { parseArgs } from 'node:util'
+import { operatorDir, workspaceSettings } from '@lincyaw/compiler'
+import { errorMessage } from '@lincyaw/kernel'
+import { SPEECH_ID } from '../domain/index.ts'
+import { writeConsent } from './consent.ts'
+import { speechCore } from './core.ts'
+import { startFakeEngine } from './fake-engine.ts'
+
+const USAGE = `Usage: presmium-speech <command> [options]
+
+Commands:
+  fake      the deterministic fake engine, an HTTP service of the OpenAI audio API shape;
+            define it with PRESMIUM_SPEECH_FAKE_URL=<the address it prints> and
+            PRESMIUM_SPEECH_FAKE_PROVIDER=<a name>
+            --port <n>     port (default: a free port)
+            --host <addr>  address (default: 127.0.0.1)
+  consent <engine> <voice> <record>
+            registers the consent record (JSON: speaker, scope, date, statementSha256) of a
+            cloned voice as <consentDir>/<engine>/<voice>.json of the operator directory
+            (consentDir from settings.presmium.speech of presmium.workspace.yaml, default consent)
+            --operator-dir <dir>  the operator directory (default: the workspace's in the
+                                  user's state directory, or PRESMIUM_OPERATOR_DIR)
+  clone <engine> <voice> <sample>
+            trains the cloned voice <voice> (Volcengine: a slot of the account, S_…, or a new
+            name for a pay-as-you-go voice) from a recording of its speaker (10–30 s, one voice,
+            WAV, MP3, Ogg or M4A), after registering their consent; training is paid for at the
+            provider. Needs settings.presmium.speech.cloned: true. Waits until it is trained
+            --speaker <name>      who speaks
+            --scope <text>        what the voice may be used for
+            --statement <file>    the speaker's recording of the consent statement
+            --lang <tag>          the sample's language (default zh-CN)
+            --text <text>         what the sample says, when known
+            --status              only show the state of an earlier training
+            --operator-dir <dir>  as for consent
+
+  -h, --help   show this help`
+
+function workspaceRoot(dir: string): string {
+  try {
+    return resolve(execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd: dir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim())
+  } catch {
+    return resolve(dir)
+  }
+}
+
+async function fake(args: string[]): Promise<number> {
+  const { values } = parseArgs({ args, options: { port: { type: 'string' }, host: { type: 'string' } } })
+  const port = values.port === undefined ? 0 : Number(values.port)
+  if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error(`--port takes a port number, not "${values.port}"`)
+  const engine = await startFakeEngine({ port, listenAddress: values.host })
+  process.stdout.write(`fake  ${engine.url}\n`)
+  await new Promise<void>((done) => {
+    process.once('SIGINT', done)
+    process.once('SIGTERM', done)
+  })
+  await engine.close()
+  return 0
+}
+
+function consent(args: string[]): number {
+  const { values, positionals } = parseArgs({ args, allowPositionals: true, options: { 'operator-dir': { type: 'string' } } })
+  const [engine, voice, file, ...more] = positionals
+  if (!engine || !voice || !file || more.length) throw new Error('consent takes <engine> <voice> <record>')
+  const record: unknown = JSON.parse(readFileSync(resolve(file), 'utf8'))
+  const root = workspaceRoot(process.cwd())
+  const { settings, problem } = workspaceSettings(root)
+  if (problem) throw new Error(problem)
+  const dir = operatorDir(root, values['operator-dir'] ?? process.env.PRESMIUM_OPERATOR_DIR)
+  const written = writeConsent(dir, settings[SPEECH_ID] ?? {}, engine, voice, record)
+  process.stdout.write(`consent  ${written}\n`)
+  return 0
+}
+
+const MIME: Record<string, string> = { wav: 'audio/wav', mp3: 'audio/mpeg', ogg: 'audio/ogg', m4a: 'audio/mp4', aac: 'audio/aac' }
+const mimeOf = (file: string) => MIME[file.split('.').at(-1)?.toLowerCase() ?? ''] ?? 'application/octet-stream'
+
+async function clone(args: string[]): Promise<number> {
+  const { values, positionals } = parseArgs({ args, allowPositionals: true, options: {
+    speaker: { type: 'string' }, scope: { type: 'string' }, statement: { type: 'string' }, lang: { type: 'string' }, text: { type: 'string' },
+    status: { type: 'boolean' }, 'operator-dir': { type: 'string' },
+  } })
+  const [engine, voice, sample, ...more] = positionals
+  if (!engine || !voice || (!values.status && !sample) || more.length) throw new Error('clone takes <engine> <voice> <sample> (or <engine> <voice> --status)')
+  const root = workspaceRoot(process.cwd())
+  const { settings, problem } = workspaceSettings(root)
+  if (problem) throw new Error(problem)
+  const say = (...parts: unknown[]) => process.stderr.write(`${parts.map(String).join(' ')}\n`)
+  const core = speechCore({
+    names: () => Object.keys(process.env),
+    secret: name => process.env[name],
+    settings: settings[SPEECH_ID] ?? {},
+    operatorDir: operatorDir(root, values['operator-dir'] ?? process.env.PRESMIUM_OPERATOR_DIR),
+    log: { debug: () => {}, info: say, warn: say, error: say },
+  })
+  let status = values.status
+    ? await core.cloneStatus(engine, voice)
+    : await (async () => {
+      if (!values.speaker || !values.scope || !values.statement) throw new Error('clone needs --speaker, --scope and --statement: the speaker\'s consent comes first')
+      return core.cloneVoice({
+        engine, voice, sample: readFileSync(resolve(sample!)), sampleMime: mimeOf(sample!), lang: values.lang ?? 'zh-CN', ...values.text ? { text: values.text } : {},
+        consent: { speaker: values.speaker, scope: values.scope, statement: readFileSync(resolve(values.statement)), statementMime: mimeOf(values.statement) },
+      })
+    })()
+  for (let polls = 0; !values.status && status.state === 'training' && polls < 200; polls++) {
+    process.stdout.write(`training  ${voice}\n`)
+    await new Promise(done => setTimeout(done, 3000))
+    status = await core.cloneStatus(engine, voice)
+  }
+  process.stdout.write(`${status.state}  ${voice}${status.trainingsLeft === undefined ? '' : `  (${status.trainingsLeft} trainings left)`}\n`)
+  return status.state === 'failed' ? 1 : 0
+}
+
+export async function main(argv: string[]): Promise<number> {
+  const [command, ...args] = argv
+  try {
+    if (command === 'fake') return await fake(args)
+    if (command === 'consent') return consent(args)
+    if (command === 'clone') return await clone(args)
+    if (command === '-h' || command === '--help' || command === undefined) {
+      process.stdout.write(`${USAGE}\n`)
+      return command === undefined ? 2 : 0
+    }
+    throw new Error(`unknown command "${command}"`)
+  } catch (error) {
+    process.stderr.write(`presmium-speech: ${errorMessage(error)}\n\n${USAGE}\n`)
+    return 2
+  }
+}

package/src/node/clone-route.ts

@@ -0,0 +1,51 @@
+import { jsonResponse, problemResponse } from '@lincyaw/kernel'
+import type { CloneInput } from './backend.ts'
+import { errorResponse } from './errors.ts'
+
+/** The clone route's body: a sample and a recorded consent statement, each at most this size. */
+export const MAX_CLONE_AUDIO = 10 * 1024 * 1024
+
+const field = (form: FormData, name: string) => {
+  const value = form.get(name)
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined
+}
+
+/**
+ * `clone` (POST, multipart): `voice`, `speaker`, `scope`, `confirmed=1` and the files `sample` and `statement`;
+ * optionally `engine`, `lang` and `text`. The consent is registered first, then the provider trains, which costs
+ * money, hence the explicit confirmation. `clone/status` (GET `?engine=&voice=`): the training's state.
+ */
+export async function cloneRoute(request: Request, rest: string, speech: { cloneVoice(input: CloneInput, signal?: AbortSignal): Promise<unknown>, cloneStatus(engine: string | undefined, voice: string, signal?: AbortSignal): Promise<unknown> }): Promise<Response> {
+  try {
+    if (rest === 'status') {
+      if (request.method !== 'GET') return problemResponse(405, 'GET clone/status?engine=&voice=')
+      const query = new URL(request.url).searchParams
+      const voice = query.get('voice')?.trim()
+      if (!voice) return problemResponse(400, 'clone/status needs ?voice=')
+      return jsonResponse(await speech.cloneStatus(query.get('engine')?.trim() || undefined, voice, request.signal))
+    }
+    if (rest) return problemResponse(404, 'the routes are clone and clone/status')
+    if (request.method !== 'POST') return problemResponse(405, 'POST multipart form data to clone')
+    const form = await request.formData().catch(() => undefined)
+    if (!form) return problemResponse(400, 'clone takes multipart form data')
+    if (form.get('confirmed') !== '1') return problemResponse(409, 'training a cloned voice is paid for at the provider: send confirmed=1 once the owner has confirmed it')
+    const voice = field(form, 'voice'), speaker = field(form, 'speaker'), scope = field(form, 'scope')
+    const sample = form.get('sample'), statement = form.get('statement')
+    if (!voice || !speaker || !scope) return problemResponse(400, 'clone needs voice, speaker and scope')
+    if (!(sample instanceof Blob) || !(statement instanceof Blob)) return problemResponse(400, 'clone needs the files sample (the voice to learn) and statement (the speaker reading the consent statement)')
+    if (sample.size > MAX_CLONE_AUDIO || statement.size > MAX_CLONE_AUDIO) return problemResponse(413, 'each recording is at most 10 MB')
+    const bytes = async (blob: Blob) => new Uint8Array(await blob.arrayBuffer())
+    const engine = field(form, 'engine'), lang = field(form, 'lang'), text = field(form, 'text')
+    return jsonResponse(await speech.cloneVoice({
+      ...engine ? { engine } : {},
+      voice,
+      sample: await bytes(sample),
+      sampleMime: sample.type,
+      ...lang ? { lang } : {},
+      ...text ? { text } : {},
+      consent: { speaker, scope, statement: await bytes(statement), statementMime: statement.type },
+    }, request.signal))
+  } catch (error) {
+    return errorResponse(error)
+  }
+}

package/src/node/config-pass.ts

@@ -0,0 +1,22 @@
+import { readFileSync } from 'node:fs'
+import type { IRPass } from '@lincyaw/kernel'
+import { deckSpeechConfig, SPEECH_ID } from '../domain/index.ts'
+
+function configLine(file: string): number {
+  try {
+    const index = readFileSync(file, 'utf8').split('\n').findIndex(line => /presmium\.speech\b/.test(line))
+    return index >= 0 ? index + 1 : 1
+  } catch {
+    return 1
+  }
+}
+
+export const speechConfigPass: IRPass = {
+  name: 'presmium.speech.config',
+  run(doc, ctx) {
+    const { problems } = deckSpeechConfig(ctx.config)
+    if (problems.length === 0) return
+    const source = { file: doc.meta.entry, line: configLine(doc.meta.entry) }
+    for (const { severity, message } of problems) ctx.report({ checkId: SPEECH_ID, severity, message, source })
+  },
+}