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

package/src/node/consent.ts

@@ -0,0 +1,106 @@
+import { mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { jsonResponse, problemResponse } from '@lincyaw/kernel'
+import type { VoiceInfo } from '@lincyaw/kernel'
+import { isInside } from '@lincyaw/kernel/node'
+import { consentPath, consentProblem, DEFAULT_CONSENT_DIR, safeName } from '../domain/index.ts'
+import { SpeechError } from './errors.ts'
+
+export function consentDir(operatorDir: string, settings: Record<string, unknown>): string {
+  const configured = typeof settings.consentDir === 'string' && settings.consentDir.trim() ? settings.consentDir.trim() : DEFAULT_CONSENT_DIR
+  const dir = resolve(operatorDir, configured)
+  if (!isInside(dir, resolve(operatorDir))) {
+    throw new SpeechError(500, `settings.presmium.speech.consentDir (${configured}) leads out of the operator directory`)
+  }
+  return dir
+}
+
+function assertSafeNames(engine: string, voice: string): void {
+  if (!safeName(engine) || !safeName(voice)) throw new SpeechError(400, `"${engine}/${voice}" is not an engine id and a voice id (letters, digits, ".", "_", "-")`)
+}
+
+export function checkConsent(operatorDir: string | undefined, settings: Record<string, unknown>, engine: string, voice: string): void {
+  const what = `voice "${voice}" of engine "${engine}" is a cloned voice`
+  if (settings.cloned !== true) {
+    throw new SpeechError(403, `${what}, which the operator has not allowed: cloned voices need settings.presmium.speech.cloned: true in presmium.workspace.yaml and a consent record`)
+  }
+  if (!operatorDir) throw new SpeechError(403, `${what}, and this process has no operator directory to hold its consent record`)
+  assertSafeNames(engine, voice)
+  const file = join(consentDir(operatorDir, settings), consentPath(engine, voice))
+  let text: string
+  try {
+    text = readFileSync(file, 'utf8')
+  } catch {
+    throw new SpeechError(403, `${what} without a consent record: ${file} is missing (records in the deck are not read); the owner registers it through the route consent/${engine}/${voice}, or the operator runs presmium-speech consent ${engine} ${voice} <record>`)
+  }
+  let record: unknown
+  try {
+    record = JSON.parse(text)
+  } catch {
+    record = undefined
+  }
+  const problem = consentProblem(record)
+  if (problem) throw new SpeechError(403, `${what} whose consent record ${file} is not valid: ${problem}`)
+}
+
+function writeAtomic(file: string, data: string | Uint8Array): void {
+  const temporary = `${file}.${process.pid}.tmp`
+  writeFileSync(temporary, data, { mode: 0o600 })
+  renameSync(temporary, file)
+}
+
+/**
+ * Writes a consent record; with `statement`, also the speaker's recording of the consent statement beside it
+ * (`<voice>.statement.<ext>`), whose sha256 the record holds, so the record can be checked against it later.
+ */
+export function writeConsent(operatorDir: string | undefined, settings: Record<string, unknown>, engine: string, voice: string, record: unknown, statement?: { bytes: Uint8Array, ext: string }): string {
+  if (!operatorDir) throw new SpeechError(409, 'this process has no operator directory to hold consent records')
+  assertSafeNames(engine, voice)
+  const problem = consentProblem(record)
+  if (problem) throw new SpeechError(400, problem)
+  const file = join(consentDir(operatorDir, settings), consentPath(engine, voice))
+  mkdirSync(dirname(file), { recursive: true, mode: 0o700 })
+  if (statement) writeAtomic(file.replace(/\.json$/, `.statement.${statement.ext}`), statement.bytes)
+  writeAtomic(file, `${JSON.stringify(record, null, 2)}\n`)
+  return file
+}
+
+/** The voices of an engine that have a valid consent record, named by their speaker: cloned voices the operator can use. */
+export function consentedVoices(operatorDir: string | undefined, settings: Record<string, unknown>, engine: string): VoiceInfo[] {
+  if (!operatorDir || settings.cloned !== true || !safeName(engine)) return []
+  let names: string[]
+  try {
+    names = readdirSync(join(consentDir(operatorDir, settings), engine))
+  } catch {
+    return []
+  }
+  return names.flatMap((name) => {
+    const voice = name.endsWith('.json') && !name.includes('.statement.') ? name.slice(0, -'.json'.length) : ''
+    if (!voice || !safeName(voice)) return []
+    try {
+      const record: unknown = JSON.parse(readFileSync(join(consentDir(operatorDir, settings), engine, name), 'utf8'))
+      if (consentProblem(record)) return []
+      return [{ id: voice, label: (record as { speaker: string }).speaker, lang: [], cloned: true }]
+    } catch {
+      return []
+    }
+  })
+}
+
+export async function consentRoute(request: Request, rest: string, register: (engine: string, voice: string, record: unknown) => string): Promise<Response> {
+  if (request.method !== 'POST' && request.method !== 'PUT') return problemResponse(405, 'POST the consent record (JSON) to consent/<engine>/<voice>')
+  const [engine, voice, ...more] = rest.split('/').filter(Boolean)
+  if (!engine || !voice || more.length) return problemResponse(404, 'the route is consent/<engine>/<voice>')
+  let record: unknown
+  try {
+    record = JSON.parse(await request.text())
+  } catch {
+    return problemResponse(400, 'the body is the consent record as JSON { speaker, scope, date, statementSha256 }')
+  }
+  try {
+    register(engine, voice, record)
+    return jsonResponse({ engine, voice, registered: consentPath(engine, voice) })
+  } catch (error) {
+    return problemResponse(error instanceof SpeechError ? error.status : 500, error instanceof Error ? error.message : String(error))
+  }
+}

package/src/node/core.ts

@@ -0,0 +1,263 @@
+import { createHash } from 'node:crypto'
+import { aigcLabel, remapWords, speechEngineId } from '@lincyaw/kernel'
+import type { Logger, SpeechWord, SynthesisRequest, TranscriptionRequest, VoiceCatalog, VoiceCloneStatus, VoiceInfo } from '@lincyaw/kernel'
+import type { EngineDefinition, EngineUse, LexiconText } from '../domain/index.ts'
+import { applyLexiconWithSpans, whyEngineCannot, engineDoes, engineInfo, howToDefine, operatorEngines, providerName } from '../domain/index.ts'
+import { audioMime, labelAudio } from './audio/label.ts'
+import type { CloneInput, SpeechBackend, SynthesisResult } from './backend.ts'
+import { cacheKey, profileCacheKey } from './cache.ts'
+import { checkConsent, consentedVoices, writeConsent } from './consent.ts'
+import { engineAdapter } from './engines/index.ts'
+import type { EngineAdapter } from './engines/index.ts'
+import { speaks } from './engines/types.ts'
+import { SpeechError } from './errors.ts'
+
+function writtenWords(words: SpeechWord[], written: string, spoken: LexiconText): SpeechWord[] {
+  if (spoken.spans.length === 0) return words
+  return remapWords(words, written, spoken.text, spoken.spans).map(({ text, start, end }) => ({ text: text.trim(), start, end }))
+}
+
+export interface CoreOptions {
+  names(): Iterable<string>
+  secret(name: string): string | undefined
+  settings: Record<string, unknown>
+  operatorDir?: string
+  log: Logger
+}
+
+export interface SpeechCore extends SpeechBackend {
+  registerConsent(engine: string, voice: string, record: unknown): string
+  cloneVoice(input: CloneInput, signal?: AbortSignal): Promise<VoiceCloneStatus>
+  cloneStatus(engine: string | undefined, voice: string, signal?: AbortSignal): Promise<VoiceCloneStatus>
+}
+
+interface CatalogLoad {
+  promise: Promise<VoiceCatalog>
+  controller: AbortController
+  borrowers: number
+  settled: boolean
+}
+
+export function speechCore(options: CoreOptions): SpeechCore {
+  let defined: ReturnType<typeof operatorEngines> | undefined
+  let definitionKey: string | undefined
+  const engines = () => {
+    const next = operatorEngines(options.names(), options.secret)
+    const key = createHash('sha256').update(JSON.stringify(next)).digest('hex')
+    if (key !== definitionKey) {
+      definitionKey = key; defined = next
+      for (const list of lists.values()) list.controller.abort()
+      lists.clear(); known.clear(); unlisted.clear(); adapters = new WeakMap()
+      for (const warning of defined.warnings) options.log.warn(warning)
+    }
+    return defined!
+  }
+  const profileOf = (engine: EngineDefinition, use: EngineUse) => createHash('sha256').update(JSON.stringify([
+    'presmium.speech-profile/1', engine.id, engine.kind, engine.url, engine.provider, use,
+    use === 'synthesize' ? engine.model : engine.transcribeModel,
+  ])).digest('hex')
+  let adapters = new WeakMap<EngineDefinition, EngineAdapter>()
+  const adapter = (engine: EngineDefinition) => {
+    let found = adapters.get(engine)
+    if (!found) adapters.set(engine, found = engineAdapter(engine, options.log))
+    return found
+  }
+  const lists = new Map<string, CatalogLoad>()
+  const known = new Map<string, VoiceInfo[]>()
+  const unlisted = new Set<string>()
+  const allCatalog = (engine: EngineDefinition, signal?: AbortSignal): Promise<VoiceCatalog> => {
+    signal?.throwIfAborted()
+    let list = lists.get(engine.id)
+    if (!list) {
+      const own = adapter(engine), controller = new AbortController(), requestSignal = AbortSignal.any([controller.signal, AbortSignal.timeout(30_000)])
+      const created: CatalogLoad = { controller, borrowers: 0, settled: false, promise: Promise.resolve().then(async () => {
+        try {
+          const catalog = await own.voiceCatalog(undefined, requestSignal)
+          requestSignal.throwIfAborted()
+          if (lists.get(engine.id) === created) known.set(engine.id, catalog.voices)
+          return catalog
+        } catch (error) {
+          if (lists.get(engine.id) === created) lists.delete(engine.id)
+          if (controller.signal.aborted) throw controller.signal.reason
+          throw new SpeechError(502, `the voices of speech engine "${engine.id}" are not known, so a cloned voice cannot be told: ${error instanceof Error ? error.message : String(error)}`)
+        } finally { created.settled = true }
+      }) }
+      lists.set(engine.id, list = created)
+    }
+    const borrowed = list
+    borrowed.borrowers++
+    return new Promise((resolve, reject) => {
+      let finished = false
+      const release = () => {
+        if (finished) return false
+        finished = true
+        signal?.removeEventListener('abort', abort)
+        borrowed.borrowers--
+        if (!borrowed.borrowers && !borrowed.settled) {
+          if (lists.get(engine.id) === borrowed) lists.delete(engine.id)
+          borrowed.controller.abort()
+        }
+        return true
+      }
+      const abort = () => { if (release()) reject(signal!.reason) }
+      signal?.addEventListener('abort', abort, { once: true })
+      borrowed.promise.then(catalog => { if (release()) resolve(catalog) }, error => { if (release()) reject(error) })
+      if (signal?.aborted) abort()
+    })
+  }
+  // Cloned voices with a consent record are the operator's to use even when the engine does not list them (no
+  // console credentials, or a voice trained moments ago): they join the engine's list, read fresh each time.
+  const withConsented = (engine: EngineDefinition, catalog: VoiceCatalog): VoiceCatalog => {
+    const extra = consentedVoices(options.operatorDir, options.settings, engine.id).filter(voice => !catalog.voices.some(own => own.id === voice.id))
+    return extra.length && catalog.status === 'available' ? { ...catalog, voices: [...catalog.voices, ...extra] } : catalog
+  }
+  const allVoices = async (engine: EngineDefinition, signal?: AbortSignal) => {
+    const catalog = withConsented(engine, await allCatalog(engine, signal))
+    signal?.throwIfAborted()
+    return catalog.voices
+  }
+  const cloning = (id: string | undefined) => {
+    const engine = pick(id, 'synthesize'), own = adapter(engine)
+    if (!own.clone || !own.cloneStatus) throw new SpeechError(400, `speech engine "${engine.id}" cannot train cloned voices`)
+    if (options.settings.cloned !== true) throw new SpeechError(403, 'cloned voices are off: the operator allows them with settings.presmium.speech.cloned: true in presmium.workspace.yaml')
+    return { engine, own: own as Required<Pick<EngineAdapter, 'clone' | 'cloneStatus'>> }
+  }
+
+  // Without a name, the first engine that does the use: an engine only for saying text is not asked to transcribe.
+  const pick = (id: string | undefined, use: EngineUse): EngineDefinition => {
+    const { engines: list, unavailable } = engines()
+    if (!id) {
+      const first = list.find(engine => engineDoes(engine, use))
+      if (first) return first
+      if (list.length > 0) throw new SpeechError(400, `no speech engine ${use === 'synthesize' ? 'synthesizes' : 'transcribes'}: ${list.map(engine => whyEngineCannot(engine, use)).join('; ')}`)
+      throw new SpeechError(400, 'no speech engine is defined, so none was asked: the operator defines one in the environment (PRESMIUM_SPEECH_<ID>_URL and PRESMIUM_SPEECH_<ID>_PROVIDER, or PRESMIUM_SPEECH_VOLCENGINE_KEY)')
+    }
+    const found = list.find(engine => engine.id === speechEngineId(id))
+    if (found && !engineDoes(found, use)) throw new SpeechError(400, whyEngineCannot(found, use))
+    if (found) return found
+    const reason = unavailable.find(engine => engine.id === speechEngineId(id))?.reason
+    throw new SpeechError(400, reason ? `speech engine "${id}" is unavailable: ${reason}` : `speech engine "${id}" is not defined; ${howToDefine(id)}`)
+  }
+
+  return {
+    async listEngines(lang) {
+      const { engines: list, unavailable } = engines()
+      return { engines: list.map(engine => ({ ...engineInfo(engine, lang), model: engine.model, transcribeModel: engine.transcribeModel })), unavailable }
+    },
+
+    async defaultSynthesisEngine() {
+      return engines().engines.find(engine => engine.synthesizes)?.id
+    },
+
+    async cacheProfile(id, use, lang) {
+      const { engines: list, unavailable } = engines()
+      const engine = id ? list.find(own => own.id === speechEngineId(id)) : list.find(own => engineDoes(own, use))
+      if (engine) return engineDoes(engine, use) ? { status: 'configured', profile: profileOf(engine, use), model: use === 'synthesize' ? engine.model : engine.transcribeModel, provider: providerName(engine, lang) } : { status: 'unavailable' }
+      return { status: (id ? unavailable.some(own => own.id === speechEngineId(id)) : unavailable.length > 0) ? 'unavailable' : 'absent' }
+    },
+
+    async voices(id, lang, signal) {
+      return (await allVoices(pick(id, 'synthesize'), signal)).filter(voice => speaks(voice, lang))
+    },
+
+    async voiceCatalog(id, lang, signal) {
+      signal?.throwIfAborted()
+      const engine = id ? pick(id, 'synthesize') : engines().engines.find(engine => engine.synthesizes)
+      if (!engine) return { status: 'unavailable', reason: 'not-configured', voices: [] }
+      const catalog = withConsented(engine, await allCatalog(engine, signal))
+      signal?.throwIfAborted()
+      return { ...catalog, voices: catalog.voices.filter(voice => speaks(voice, lang)) }
+    },
+
+    async synthesize(request: SynthesisRequest, signal): Promise<SynthesisResult> {
+      const engine = pick(request.engine, 'synthesize')
+      const listed = (await allVoices(engine, signal)).find(voice => voice.id === request.voice)
+      const cloned = listed?.cloned === true || adapter(engine).cloned?.(request.voice) === true
+      if (cloned) checkConsent(options.operatorDir, options.settings, engine.id, request.voice)
+      const spoken = applyLexiconWithSpans(request.text, request.lexicon)
+      const requestKey = cacheKey({ ...request, engine: engine.id }, spoken.text)
+      const profile = profileOf(engine, 'synthesize')
+      const key = profileCacheKey(requestKey, profile)
+      const produced = await adapter(engine).synthesize({ voice: request.voice, text: spoken.text, lang: request.lang, rate: request.rate, style: request.style }, signal)
+      const provider = providerName(engine, request.lang)
+      const label = aigcLabel(provider, key)
+      const labeled = labelAudio(produced.audio, label)
+      const words = produced.words?.length ? writtenWords(produced.words, request.text, spoken) : undefined
+      return {
+        audio: labeled.audio,
+        mime: labeled.mime,
+        ext: labeled.ext,
+        duration: labeled.duration || produced.duration || words?.at(-1)?.end || 0,
+        ...words ? { words } : {},
+        engine: engine.id,
+        model: engine.model,
+        voice: request.voice,
+        provider,
+        cloned,
+        key,
+        requestKey,
+        profile,
+        AIGC: label,
+      }
+    },
+
+    async transcribe(request: TranscriptionRequest, signal) {
+      const engine = pick(request.engine, 'transcribe')
+      const audio = new Uint8Array(await request.audio.arrayBuffer())
+      return adapter(engine).transcribe({ audio, mime: audioMime(audio, request.audio.type), lang: request.lang, hints: request.hints }, signal)
+    },
+
+    async consent(engine, voice, recorded, signal) {
+      signal?.throwIfAborted()
+      if (!recorded) {
+        const defined = engines().engines.find(own => own.id === speechEngineId(engine))
+        if (!defined) return
+        if (adapter(defined).cloned?.(voice) !== true) {
+          const voices = known.get(defined.id) ?? (unlisted.has(defined.id)
+            ? []
+            : await allVoices(defined, signal).catch(() => {
+              signal?.throwIfAborted()
+              if (engines().engines.includes(defined)) unlisted.add(defined.id)
+              return []
+            }))
+          if (!voices.some(own => own.id === voice && own.cloned === true)) return
+        }
+      }
+      checkConsent(options.operatorDir, options.settings, speechEngineId(engine), voice)
+    },
+
+    async cloneVoice(input: CloneInput, signal): Promise<VoiceCloneStatus> {
+      const { engine, own } = cloning(input.engine)
+      // Consent before anything leaves the machine: the record names the speaker and the scope, and holds the sha256
+      // of their recorded statement, which is kept beside it.
+      const statementMime = audioMime(input.consent.statement, input.consent.statementMime)
+      const record = { speaker: input.consent.speaker.trim(), scope: input.consent.scope.trim(), date: new Date().toISOString(), statementSha256: createHash('sha256').update(input.consent.statement).digest('hex') }
+      const file = writeConsent(options.operatorDir, options.settings, engine.id, input.voice, record, { bytes: input.consent.statement, ext: statementMime.split('/')[1]?.replace('mpeg', 'mp3').replace(/[^a-z0-9]/g, '') || 'bin' })
+      options.log.info(`consent record of voice ${input.voice} of engine ${engine.id} registered: ${file}`)
+      const status = await own.clone({ voice: input.voice, audio: input.sample, mime: audioMime(input.sample, input.sampleMime), ...input.lang ? { lang: input.lang } : {}, ...input.text ? { text: input.text } : {} }, signal)
+      lists.delete(engine.id)
+      return { engine: engine.id, voice: input.voice, ...status }
+    },
+
+    async cloneStatus(id, voice, signal): Promise<VoiceCloneStatus> {
+      const { engine, own } = cloning(id)
+      // Only voices trained through Presmium, with their consent, are asked about.
+      checkConsent(options.operatorDir, options.settings, engine.id, voice)
+      const status = await own.cloneStatus(voice, signal)
+      if (status.state === 'ready') lists.delete(engine.id)
+      return { engine: engine.id, voice, ...status }
+    },
+
+    registerConsent(engine, voice, record) {
+      const file = writeConsent(options.operatorDir, options.settings, engine, voice, record)
+      options.log.info(`consent record of voice ${voice} of engine ${engine} registered: ${file}`)
+      return file
+    },
+  }
+}
+
+export async function reportEngines(core: SpeechBackend, log: Logger): Promise<void> {
+  const { engines, unavailable } = await core.listEngines('en')
+  if (engines.length) log.info(`speech engines: ${engines.map(engine => `${engine.id} (${engine.provider})`).join(', ')}`)
+  for (const { id, reason } of unavailable) log.warn(`speech engine ${id} is unavailable: ${reason}`)
+}

package/src/node/engines/index.ts

@@ -0,0 +1,12 @@
+import type { Logger } from '@lincyaw/kernel'
+import type { EngineDefinition } from '../../domain/index.ts'
+import { openaiEngine } from './openai.ts'
+import type { EngineAdapter } from './types.ts'
+import { volcengineEngine } from './volcengine.ts'
+
+export type { EngineAdapter, EngineCloneRequest, EngineCloneStatus, EngineSynthesisRequest, EngineSynthesisResult, EngineTranscriptionRequest } from './types.ts'
+export { blobOf } from './openai.ts'
+
+export function engineAdapter(engine: EngineDefinition, log?: Logger): EngineAdapter {
+  return engine.kind === 'volcengine' ? volcengineEngine(engine, log) : openaiEngine(engine)
+}

package/src/node/engines/openai.ts

@@ -0,0 +1,132 @@
+import type { SpeechWord, Transcript, VoiceCatalog, VoiceInfo } from '@lincyaw/kernel'
+import { isRecord } from '@lincyaw/kernel'
+import type { EngineDefinition } from '../../domain/index.ts'
+import { oneSegment, wordsIntoSegments } from '../../domain/index.ts'
+import { SpeechError, upstreamError } from '../errors.ts'
+import type { EngineAdapter, EngineCloneStatus, EngineSynthesisRequest, EngineSynthesisResult, EngineTranscriptionRequest } from './types.ts'
+import { speaks } from './types.ts'
+
+export function blobOf(bytes: Uint8Array, type: string): Blob {
+  return new Blob([new Uint8Array(bytes)], { type })
+}
+
+function timedWords(value: unknown): SpeechWord[] {
+  if (!Array.isArray(value)) return []
+  return value.flatMap((word) => {
+    if (!isRecord(word) || typeof word.start !== 'number' || typeof word.end !== 'number') return []
+    const text = typeof word.text === 'string' ? word.text : typeof word.word === 'string' ? word.word : ''
+    return text.trim() ? [{ text: text.trim(), start: word.start, end: word.end }] : []
+  })
+}
+
+function cloneStatusOf(value: unknown): EngineCloneStatus {
+  if (!isRecord(value)) return { state: 'unknown' }
+  const state = value.state === 'training' || value.state === 'ready' || value.state === 'failed' ? value.state : 'unknown'
+  return { state, ...typeof value.trainingsLeft === 'number' ? { trainingsLeft: value.trainingsLeft } : {} }
+}
+
+function voiceOf(value: unknown): VoiceInfo | undefined {
+  if (typeof value === 'string') return { id: value, label: value, lang: [] }
+  if (!isRecord(value)) return undefined
+  const id = [value.id, value.voice_id, value.name].find((v): v is string => typeof v === 'string' && v.length > 0)
+  if (!id) return undefined
+  const langs = [value.lang, value.language, value.languages].flat().filter((v): v is string => typeof v === 'string')
+  return { id, label: typeof value.label === 'string' ? value.label : typeof value.name === 'string' ? value.name : id, lang: langs, ...value.cloned === true ? { cloned: true } : {} }
+}
+
+export function openaiEngine(engine: EngineDefinition): EngineAdapter {
+  let timestamps = true
+  const call = (path: string, init: RequestInit, signal?: AbortSignal) => fetch(`${engine.url}/${path}`, {
+    ...init,
+    headers: { ...engine.key ? { Authorization: `Bearer ${engine.key}` } : {}, ...init.headers as Record<string, string> },
+    redirect: 'error',
+    signal,
+  })
+  const what = `speech engine "${engine.id}" (${engine.provider})`
+
+  const voiceCatalog = async (lang?: string, signal?: AbortSignal): Promise<VoiceCatalog> => {
+    const response = await call('audio/voices', { method: 'GET' }, signal)
+    if (response.status === 404 || response.status === 405) return { status: 'unavailable', reason: 'unsupported', voices: [] }
+    if (!response.ok) throw await upstreamError(response, what)
+    const body: unknown = await response.json().catch(() => undefined)
+    const list = isRecord(body) ? body.voices ?? body.data : body
+    if (!Array.isArray(list)) throw new SpeechError(502, `${what} answered audio/voices without a list of voices`)
+    return { status: 'available', source: 'provider', voices: list.flatMap(item => voiceOf(item) ?? []).filter(voice => speaks(voice, lang)) }
+  }
+
+  // OpenAI's audio API has no cloning; Presmium's fake engine extends it with audio/voices/clone so the whole
+  // clone flow can be tried without a provider account.
+  const cloning: Pick<EngineAdapter, 'clone' | 'cloneStatus'> = engine.kind !== 'fake' ? {} : {
+    async clone(request, signal) {
+      const form = new FormData()
+      form.set('file', blobOf(request.audio, request.mime), 'sample')
+      form.set('voice', request.voice)
+      if (request.lang) form.set('language', request.lang)
+      if (request.text) form.set('text', request.text)
+      const response = await call('audio/voices/clone', { method: 'POST', body: form }, signal)
+      if (!response.ok) throw await upstreamError(response, what)
+      return cloneStatusOf(await response.json())
+    },
+    async cloneStatus(voice, signal) {
+      const response = await call(`audio/voices/clone?voice=${encodeURIComponent(voice)}`, { method: 'GET' }, signal)
+      if (!response.ok) throw await upstreamError(response, what)
+      return cloneStatusOf(await response.json())
+    },
+  }
+
+  return {
+    voiceCatalog,
+    async voices(lang, signal) { return (await voiceCatalog(lang, signal)).voices },
+    ...cloning,
+
+    async synthesize(request: EngineSynthesisRequest, signal): Promise<EngineSynthesisResult> {
+      const body = JSON.stringify({
+        model: engine.model,
+        voice: request.voice,
+        input: request.text,
+        response_format: 'opus',
+        language: request.lang,
+        ...request.rate ? { speed: request.rate } : {},
+        ...request.style ? { instructions: request.style } : {},
+      })
+      const headers = { 'Content-Type': 'application/json' }
+      if (timestamps) {
+        const response = await call('audio/speech/timestamps', { method: 'POST', headers, body }, signal)
+        if (response.ok) {
+          const answer = await response.json() as { audio?: unknown, duration?: unknown, words?: unknown }
+          if (typeof answer.audio !== 'string') throw new SpeechError(502, `${what} gave no audio`)
+          return { audio: new Uint8Array(Buffer.from(answer.audio, 'base64')), words: timedWords(answer.words), ...typeof answer.duration === 'number' ? { duration: answer.duration } : {} }
+        }
+        if (response.status !== 404 && response.status !== 405) throw await upstreamError(response, what)
+        timestamps = false
+      }
+      const response = await call('audio/speech', { method: 'POST', headers, body }, signal)
+      if (!response.ok) throw await upstreamError(response, what)
+      return { audio: new Uint8Array(await response.arrayBuffer()), contentType: response.headers.get('content-type') ?? undefined }
+    },
+
+    async transcribe(input: EngineTranscriptionRequest, signal): Promise<Transcript> {
+      const form = new FormData()
+      form.set('file', blobOf(input.audio, input.mime), `audio.${input.mime.includes('ogg') ? 'ogg' : input.mime.includes('wav') ? 'wav' : 'bin'}`)
+      form.set('model', engine.transcribeModel)
+      form.set('response_format', 'verbose_json')
+      form.append('timestamp_granularities[]', 'word')
+      form.append('timestamp_granularities[]', 'segment')
+      if (input.lang) form.set('language', input.lang.split('-')[0]!.toLowerCase())
+      if (input.hints?.length) form.set('prompt', input.hints.join(', '))
+      const response = await call('audio/transcriptions', { method: 'POST', body: form }, signal)
+      if (!response.ok) throw await upstreamError(response, what)
+      const answer = await response.json() as Record<string, unknown>
+      const text = typeof answer.text === 'string' ? answer.text.trim() : ''
+      const words = timedWords(answer.words)
+      const duration = typeof answer.duration === 'number' ? answer.duration : words.at(-1)?.end ?? 0
+      const lang = input.lang ?? (typeof answer.language === 'string' ? answer.language : 'und')
+      const segments = Array.isArray(answer.segments)
+        ? answer.segments.flatMap(s => (isRecord(s) && typeof s.start === 'number' && typeof s.end === 'number' ? [{ start: s.start, end: s.end, text: typeof s.text === 'string' ? s.text : '', words: timedWords(s.words) }] : []))
+        : []
+      if (segments.length === 0) return oneSegment(text, words, lang, duration)
+      const placed = segments.some(s => s.words.length) ? segments : wordsIntoSegments(segments, words)
+      return { lang, duration, text, segments: placed }
+    },
+  }
+}

package/src/node/engines/types.ts

@@ -0,0 +1,54 @@
+import type { SpeechWord, Transcript, VoiceCatalog, VoiceCloneState, VoiceInfo } from '@lincyaw/kernel'
+
+export interface EngineSynthesisRequest {
+  voice: string
+  text: string
+  lang: string
+  rate?: number
+  style?: string
+}
+
+export interface EngineSynthesisResult {
+  audio: Uint8Array
+  contentType?: string
+  words?: SpeechWord[]
+  duration?: number
+}
+
+export interface EngineTranscriptionRequest {
+  audio: Uint8Array
+  mime: string
+  lang?: string
+  hints?: string[]
+}
+
+export interface EngineCloneRequest {
+  voice: string
+  audio: Uint8Array
+  mime: string
+  lang?: string
+  text?: string
+}
+
+export interface EngineCloneStatus {
+  state: VoiceCloneState
+  trainingsLeft?: number
+  message?: string
+}
+
+export interface EngineAdapter {
+  voices(lang?: string, signal?: AbortSignal): Promise<VoiceInfo[]>
+  voiceCatalog(lang?: string, signal?: AbortSignal): Promise<VoiceCatalog>
+  cloned?(voice: string): boolean
+  synthesize(request: EngineSynthesisRequest, signal?: AbortSignal): Promise<EngineSynthesisResult>
+  transcribe(input: EngineTranscriptionRequest, signal?: AbortSignal): Promise<Transcript>
+  /** Trains `voice` from a sample; absent when the engine cannot clone. */
+  clone?(request: EngineCloneRequest, signal?: AbortSignal): Promise<EngineCloneStatus>
+  cloneStatus?(voice: string, signal?: AbortSignal): Promise<EngineCloneStatus>
+}
+
+export function speaks(voice: VoiceInfo, lang: string | undefined): boolean {
+  if (!lang || voice.lang.length === 0) return true
+  const primary = (tag: string) => tag.toLowerCase().split('-')[0]
+  return voice.lang.some(tag => primary(tag) === primary(lang))
+}

package/src/node/engines/volcengine-console.ts

@@ -0,0 +1,66 @@
+import type { VoiceInfo } from '@lincyaw/kernel'
+import { ListSpeakersCommand, SPEECHSAASPRODClient } from '@volcengine/speechsaasprod'
+import { BatchListMegaTTSTrainStatusCommand, SPEECHSAASPROD20250521Client } from '@volcengine/speechsaasprod20250521'
+
+// The account side of Volcengine speech, through its official SDK (speech_saas_prod on open.volcengineapi.com):
+// the voices the model offers and the account's own cloned voices. It signs with the operator's IAM access key
+// pair, which is separate from the speech API key, and only with that pair: the clients get the keys explicitly,
+// so the SDK never falls back to its default credential chain (VOLCENGINE_* variables, CLI profiles, instance
+// metadata), and a credential reaches no address but Volcengine's own.
+
+export interface ConsoleCredentials { accessKeyId: string, secretAccessKey: string, project: string }
+
+const HOST = 'open.volcengineapi.com'
+const REGION = 'cn-beijing'
+const PAGE = 100
+
+/** Volcengine's language codes (zh-cn, en, ja …) as BCP 47 tags. */
+export function languageTag(code: string): string {
+  const [primary = '', region] = code.trim().split(/[-_]/)
+  return region ? `${primary.toLowerCase()}-${region.toUpperCase()}` : primary.toLowerCase()
+}
+
+/** The states of a trained voice that can be synthesized. */
+const USABLE = ['Success', 'Active']
+
+/** The SDK's errors carry Volcengine's own code and message in the response metadata: name them. */
+function explained(error: unknown): Error {
+  const meta = (error as { data?: { ResponseMetadata?: { Error?: { Code?: string, Message?: string } } } } | undefined)?.data?.ResponseMetadata?.Error
+  if (meta?.Code) return new Error(`${meta.Code}: ${meta.Message ?? ''}`.trim())
+  return error instanceof Error ? error : new Error(String(error))
+}
+
+export function volcengineConsole(credentials: ConsoleCredentials) {
+  const config = { host: HOST, region: REGION, protocol: 'https' as const, accessKeyId: credentials.accessKeyId, secretAccessKey: credentials.secretAccessKey, autoRetry: false }
+  const voices = new SPEECHSAASPRODClient(config)
+  const clones = new SPEECHSAASPROD20250521Client(config)
+  return {
+    /** Every voice of the model (`resource`), page by page. */
+    async speakers(resource: string, signal?: AbortSignal): Promise<VoiceInfo[]> {
+      const found: VoiceInfo[] = []
+      for (let page = 1; ; page++) {
+        const answer = await voices.send(new ListSpeakersCommand({ ResourceIDs: [resource], Page: page, Limit: String(PAGE) }), { abortSignal: signal, timeout: 20_000 }).catch((error: unknown) => { throw explained(error) })
+        const speakers = answer.Result?.Speakers ?? []
+        for (const speaker of speakers) {
+          if (!speaker.VoiceType) continue
+          const lang = [...new Set((speaker.Languages ?? []).flatMap(language => (language.Language ? [languageTag(language.Language)] : [])))]
+          found.push({ id: speaker.VoiceType, label: speaker.Name || speaker.VoiceType, lang })
+        }
+        if (speakers.length < PAGE || found.length >= (answer.Result?.Total ?? 0)) return found
+      }
+    },
+    /** The account's cloned voices that can be used now, in the operator's project. */
+    async cloned(signal?: AbortSignal): Promise<VoiceInfo[]> {
+      const found: VoiceInfo[] = []
+      for (const state of USABLE) {
+        for (let page = 1; ; page++) {
+          const answer = await clones.send(new BatchListMegaTTSTrainStatusCommand({ ProjectName: credentials.project, State: state, PageNumber: page, PageSize: PAGE }), { abortSignal: signal, timeout: 20_000 }).catch((error: unknown) => { throw explained(error) })
+          const statuses = answer.Result?.Statuses ?? []
+          for (const status of statuses) if (status.SpeakerID) found.push({ id: status.SpeakerID, label: status.Alias || status.SpeakerID, lang: [], cloned: true })
+          if (statuses.length < PAGE) break
+        }
+      }
+      return found
+    },
+  }
+}