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

package/src/node/engines/volcengine.ts

@@ -0,0 +1,255 @@
+import { randomUUID } from 'node:crypto'
+import type { Logger, SpeechWord, Transcript, TranscriptSegment, VoiceCloneState, VoiceInfo } from '@lincyaw/kernel'
+import { isRecord } from '@lincyaw/kernel'
+import type { EngineDefinition } from '../../domain/index.ts'
+import { audioMime } from '../audio/label.ts'
+import { SpeechError } from '../errors.ts'
+import type { EngineAdapter, EngineCloneRequest, EngineCloneStatus, EngineSynthesisRequest, EngineSynthesisResult, EngineTranscriptionRequest } from './types.ts'
+import { speaks } from './types.ts'
+import { volcengineConsole } from './volcengine-console.ts'
+import { VOLCENGINE_VOICES } from './volcengine-voices.ts'
+
+// Volcengine speech (豆包语音) over its HTTP API with the operator's API key: synthesis with the 2.0 model
+// (seed-tts-2.0; cloned voices on seed-icl-2.0), the flash recognizer, and voice cloning 2.0 (voice_clone,
+// get_voice). No SDK covers these; the account side (the voice list, the account's cloned voices) goes through the
+// official SDK in volcengine-console.ts when the operator also gives an IAM access key pair.
+
+const TTS = '/api/v3/tts/unidirectional'
+const ASR = '/api/v3/auc/bigmodel/recognize/flash'
+const CLONE = '/api/v3/tts/voice_clone'
+const VOICE = '/api/v3/tts/get_voice'
+const OK = 20000000
+const SILENT = '20000003'
+const TTS_MODEL = 'seed-tts-2.0'
+const CLONE_RESOURCE = 'seed-icl-2.0'
+
+/**
+ * Official voice ids follow the provider's naming (zh_…_uranus_bigtts, ICL_uranus_…_tob, BV…); a prepaid cloned
+ * voice is an S_… slot, and a postpaid one has a name of the operator's that Volcengine forbids from looking like
+ * either (no xx_, ICL_, MIX_, DiT_ or BV prefix, no _bigtts, _tob or _streaming suffix).
+ */
+const OFFICIAL = /^(ICL_|MIX_|DiT_|BV)|^[a-z]{2}_|_(bigtts|tob|streaming)$/
+export function volcengineCloned(voice: string): boolean {
+  return voice.startsWith('S_') || !OFFICIAL.test(voice)
+}
+
+/** A postpaid voice's own name, as Volcengine accepts it. */
+function customName(voice: string): boolean {
+  return /^[A-Za-z][A-Za-z0-9_-]{7,127}$/.test(voice) && !OFFICIAL.test(voice)
+}
+
+/**
+ * The language to fix, for text that is not Chinese. Chinese narration is left to the model, which reads the
+ * English words in it; fixing zh-cn risks dropping them, since text in another language than the fixed one is
+ * skipped.
+ */
+function explicitLanguage(lang: string): string | undefined {
+  const [primary = '', region = ''] = lang.toLowerCase().split('-')
+  if (!primary || primary === 'zh') return undefined
+  if ((primary === 'pt' && region === 'br') || (primary === 'es' && region === 'mx')) return `${primary}-${region}`
+  return primary
+}
+
+/** voice_clone's language numbers. */
+const CLONE_LANGUAGES: Record<string, number> = { zh: 0, en: 1, ja: 2, es: 3, id: 4, pt: 5, de: 6, fr: 7, ko: 8, it: 9, th: 10, vi: 11, ru: 12, fil: 13, ms: 14, ar: 15, pl: 19, tr: 20, sv: 21 }
+function cloneLanguage(lang: string | undefined): number {
+  const [primary = 'zh', region = ''] = (lang ?? 'zh').toLowerCase().split('-')
+  if (primary === 'es' && region === 'mx') return 16
+  if (primary === 'pt' && region === 'br') return 17
+  return CLONE_LANGUAGES[primary] ?? 0
+}
+
+/** get_voice's states: 0 not found, 1 training, 2 trained, 3 failed, 4 activated (trained and in use). */
+const STATES: VoiceCloneState[] = ['unknown', 'training', 'ready', 'failed', 'ready']
+
+const FORMATS: Record<string, string> = { 'audio/wav': 'wav', 'audio/x-wav': 'wav', 'audio/mpeg': 'mp3', 'audio/mp3': 'mp3', 'audio/ogg': 'ogg', 'audio/mp4': 'm4a', 'audio/x-m4a': 'm4a', 'audio/aac': 'aac' }
+const MAX_SAMPLE = 10 * 1024 * 1024
+
+function secondsOf(value: unknown): number {
+  return typeof value === 'number' ? value / 1000 : 0
+}
+
+function wordsOf(value: unknown, scale: (v: unknown) => number, key: [string, string]): SpeechWord[] {
+  if (!Array.isArray(value)) return []
+  return value.flatMap((word) => {
+    if (!isRecord(word)) return []
+    const text = typeof word.word === 'string' ? word.word : typeof word.text === 'string' ? word.text : ''
+    return text ? [{ text, start: scale(word[key[0]]), end: scale(word[key[1]]) }] : []
+  })
+}
+
+/** Volcengine answers too many concurrent requests (the default is 10 per model) with 45000000 and a quota message. */
+function failure(what: string, status: number, body: string): SpeechError {
+  if (/quota exceeded/i.test(body) && /concurrency/i.test(body)) return new SpeechError(429, `${what} is busy: more requests at once than the account's concurrency quota; try again shortly`)
+  return new SpeechError(502, `${what} answered ${status}: ${body.slice(0, 300)}`)
+}
+
+export function volcengineEngine(engine: EngineDefinition, log?: Logger): EngineAdapter {
+  const auth = (appHeader: string): Record<string, string> => (engine.appid
+    ? { [appHeader]: engine.appid, 'X-Api-Access-Key': engine.key ?? '' }
+    : { 'X-Api-Key': engine.key ?? '' })
+  const what = 'Volcengine (火山引擎)'
+  const account = engine.console ? volcengineConsole(engine.console) : undefined
+
+  const catalog = async (signal?: AbortSignal): Promise<{ source: 'provider' | 'bundled', voices: VoiceInfo[] }> => {
+    if (!account) return { source: 'bundled', voices: VOLCENGINE_VOICES }
+    try {
+      const [speakers, cloned] = await Promise.all([account.speakers(TTS_MODEL, signal), account.cloned(signal)])
+      const official = new Set(speakers.map(voice => voice.id))
+      return { source: 'provider', voices: [...speakers, ...cloned.filter(voice => !official.has(voice.id))] }
+    } catch (error) {
+      signal?.throwIfAborted()
+      // The account's list is a convenience: synthesis does not depend on it, so the bundled list stands in.
+      log?.warn(`${what}: the account's voice list is unavailable, so the bundled one is shown: ${error instanceof Error ? error.message : String(error)}`)
+      return { source: 'bundled', voices: VOLCENGINE_VOICES }
+    }
+  }
+
+  const cloneStatusOf = (answer: Record<string, unknown>): EngineCloneStatus => {
+    const state = typeof answer.status === 'number' ? STATES[answer.status] ?? 'unknown' : 'unknown'
+    return { state, ...typeof answer.available_training_times === 'number' ? { trainingsLeft: answer.available_training_times } : {} }
+  }
+  const cloneCall = async (path: string, body: Record<string, unknown>, signal?: AbortSignal): Promise<Record<string, unknown>> => {
+    const response = await fetch(`${engine.url}${path}`, {
+      method: 'POST',
+      headers: { ...auth('X-Api-App-Key'), 'X-Api-Request-Id': randomUUID(), 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+      redirect: 'error',
+      signal,
+    })
+    const text = await response.text()
+    if (!response.ok) throw failure(what, response.status, text)
+    let answer: unknown
+    try { answer = JSON.parse(text) } catch { throw new SpeechError(502, `${what} answered with no JSON: ${text.slice(0, 200)}`) }
+    if (!isRecord(answer)) throw new SpeechError(502, `${what} answered with no object`)
+    const code = typeof answer.code === 'number' ? answer.code : 0
+    if (code !== 0 && code !== OK) throw new SpeechError(502, `${what}: ${code} ${String(answer.message ?? '')}`)
+    return answer
+  }
+  const speaker = (voice: string) => (voice.startsWith('S_') ? { speaker_id: voice } : { speaker_id: 'custom_speaker_id', custom_speaker_id: voice })
+
+  return {
+    async voices(lang, signal) {
+      return (await catalog(signal)).voices.filter(voice => speaks(voice, lang))
+    },
+    async voiceCatalog(lang, signal) {
+      const { source, voices } = await catalog(signal)
+      return { status: 'available', source, voices: voices.filter(voice => speaks(voice, lang)) }
+    },
+
+    cloned: volcengineCloned,
+
+    async synthesize(request: EngineSynthesisRequest, signal): Promise<EngineSynthesisResult> {
+      const cloned = volcengineCloned(request.voice)
+      const additions: Record<string, unknown> = {}
+      const language = explicitLanguage(request.lang)
+      if (language) additions.explicit_language = language
+      // A style is an instruction to the model (context_texts); cloned voices take the expressive model instead.
+      if (request.style && !cloned) additions.context_texts = [request.style]
+      const rate = request.rate ? Math.max(-50, Math.min(100, Math.round((request.rate - 1) * 100))) : 0
+      const response = await fetch(`${engine.url}${TTS}`, {
+        method: 'POST',
+        headers: {
+          ...auth('X-Api-App-Id'),
+          'X-Api-Resource-Id': cloned ? CLONE_RESOURCE : engine.model,
+          'X-Api-Request-Id': randomUUID(),
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          user: { uid: 'presmium' },
+          req_params: {
+            text: request.text,
+            speaker: request.voice,
+            ...cloned ? { model: request.style ? 'seed-tts-2.0-expressive' : 'seed-tts-2.0-standard' } : {},
+            // Ogg/Opus only at 48 kHz in the 2.0 API.
+            audio_params: { format: 'ogg_opus', sample_rate: 48000, enable_subtitle: true, speech_rate: rate },
+            additions: JSON.stringify(additions),
+          },
+        }),
+        redirect: 'error',
+        signal,
+      })
+      const text = await response.text()
+      if (!response.ok) throw failure(what, response.status, text)
+      const chunks: Buffer[] = []
+      const words: SpeechWord[] = []
+      // Word times arrive in their own lines, possibly after later audio: read every line before finishing.
+      for (const line of text.split(/\r?\n/)) {
+        if (!line.trim()) continue
+        let event: Record<string, unknown>
+        try {
+          event = JSON.parse(line) as Record<string, unknown>
+        } catch {
+          continue
+        }
+        if (event.code !== 0 && event.code !== OK) throw failure(what, response.status, `${String(event.code)} ${String(event.message ?? '')}`)
+        if (typeof event.data === 'string' && event.data) chunks.push(Buffer.from(event.data, 'base64'))
+        if (isRecord(event.sentence)) words.push(...wordsOf(event.sentence.words, v => (typeof v === 'number' ? v : 0), ['startTime', 'endTime']))
+      }
+      if (chunks.length === 0) throw new SpeechError(502, `${what} gave no audio`)
+      return { audio: new Uint8Array(Buffer.concat(chunks)), contentType: 'audio/ogg', words, ...words.length ? { duration: words.at(-1)!.end } : {} }
+    },
+
+    async transcribe(input: EngineTranscriptionRequest, signal): Promise<Transcript> {
+      const format = input.mime.includes('wav') ? { format: 'wav' } : input.mime.includes('ogg') ? { format: 'ogg', codec: 'opus' } : input.mime.includes('mpeg') || input.mime.includes('mp3') ? { format: 'mp3' } : undefined
+      if (!format) throw new SpeechError(400, `Volcengine's recognition takes WAV, MP3 or Ogg/Opus, not ${input.mime}`)
+      const language = input.lang && !input.lang.toLowerCase().startsWith('zh') ? { language: input.lang } : {}
+      const response = await fetch(`${engine.url}${ASR}`, {
+        method: 'POST',
+        headers: {
+          ...auth('X-Api-App-Key'),
+          'X-Api-Resource-Id': engine.transcribeModel,
+          'X-Api-Request-Id': randomUUID(),
+          'X-Api-Sequence': '-1',
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          user: { uid: 'presmium' },
+          audio: { data: Buffer.from(input.audio).toString('base64'), ...format, ...language },
+          request: {
+            model_name: 'bigmodel',
+            enable_itn: true,
+            enable_punc: true,
+            show_utterances: true,
+            ...input.hints?.length ? { corpus: { context: JSON.stringify({ hotwords: input.hints.map(word => ({ word })) }) } } : {},
+          },
+        }),
+        redirect: 'error',
+        signal,
+      })
+      const status = response.headers.get('x-api-status-code')
+      const body = await response.text()
+      const lang = input.lang ?? 'zh-CN'
+      if (status === SILENT) return { lang, duration: 0, text: '', segments: [] }
+      if (!response.ok || (status && Number(status) !== OK)) throw new SpeechError(502, `${what} answered ${response.status} ${status ?? ''} ${response.headers.get('x-api-message') ?? ''}: ${body.slice(0, 300)}`)
+      const answer = JSON.parse(body) as { audio_info?: { duration?: number }, result?: { text?: string, utterances?: unknown[] } }
+      const segments: TranscriptSegment[] = (answer.result?.utterances ?? []).flatMap(u => (isRecord(u)
+        ? [{ start: secondsOf(u.start_time), end: secondsOf(u.end_time), text: typeof u.text === 'string' ? u.text : '', words: wordsOf(u.words, secondsOf, ['start_time', 'end_time']) }]
+        : []))
+      return { lang, duration: secondsOf(answer.audio_info?.duration) || (segments.at(-1)?.end ?? 0), text: answer.result?.text ?? segments.map(s => s.text).join(''), segments }
+    },
+
+    async clone(request: EngineCloneRequest, signal): Promise<EngineCloneStatus> {
+      if (!request.voice.startsWith('S_') && !customName(request.voice)) {
+        throw new SpeechError(400, `"${request.voice}" is neither a voice slot of the account (S_…) nor a name Volcengine accepts for a pay-as-you-go cloned voice: 8–128 letters, digits, "_" or "-", starting with a letter, not shaped like an official voice id`)
+      }
+      if (request.audio.byteLength > MAX_SAMPLE) throw new SpeechError(413, `the sample is ${Math.round(request.audio.byteLength / 1024 / 1024)} MB; Volcengine takes at most 10 MB`)
+      const format = FORMATS[audioMime(request.audio, request.mime).split(';')[0]!.trim()]
+      if (!format) throw new SpeechError(415, `Volcengine trains from WAV, MP3, Ogg, M4A or AAC, not ${request.mime || 'this file'}`)
+      const answer = await cloneCall(CLONE, {
+        ...speaker(request.voice),
+        audio: { data: Buffer.from(request.audio).toString('base64'), format },
+        ...request.text ? { text: request.text } : {},
+        language: cloneLanguage(request.lang),
+        extra_params: { enable_audio_denoise: true },
+      }, signal)
+      // The training answer may not carry a status yet: it has started.
+      const status = cloneStatusOf(answer)
+      return status.state === 'unknown' ? { ...status, state: 'training' } : status
+    },
+
+    async cloneStatus(voice, signal): Promise<EngineCloneStatus> {
+      return cloneStatusOf(await cloneCall(VOICE, speaker(voice), signal))
+    },
+  }
+}

package/src/node/errors.ts

@@ -0,0 +1,29 @@
+import { problemResponse } from '@lincyaw/kernel'
+
+export class SpeechError extends Error {
+  readonly status: number
+
+  constructor(status: number, message: string) {
+    super(message)
+    this.name = 'SpeechError'
+    this.status = status
+  }
+}
+
+export function errorResponse(error: unknown): Response {
+  if (error instanceof SpeechError) return problemResponse(error.status, error.message)
+  if (error instanceof Error && error.name === 'AbortError') return problemResponse(499, 'aborted')
+  return problemResponse(502, error instanceof Error ? error.message : String(error))
+}
+
+export async function upstreamError(response: Response, what: string): Promise<SpeechError> {
+  const text = await response.text().catch(() => '')
+  let message = text.slice(0, 500)
+  try {
+    const body = JSON.parse(text) as { error?: unknown, message?: unknown }
+    const error = body.error
+    message = typeof error === 'string' ? error : typeof (error as { message?: unknown })?.message === 'string' ? (error as { message: string }).message : typeof body.message === 'string' ? body.message : message
+  } catch {
+  }
+  return new SpeechError(502, `${what} answered ${response.status}${message ? `: ${message}` : ''}`)
+}

package/src/node/fake-engine.ts

@@ -0,0 +1,151 @@
+import { createServer } from 'node:http'
+import type { AddressInfo } from 'node:net'
+import type { SpeechWord, VoiceInfo } from '@lincyaw/kernel'
+import { isCjk, isRecord, splitWords } from '@lincyaw/kernel'
+import { bracketIPv6 } from '@lincyaw/kernel/node'
+import { oneSegment } from '../domain/index.ts'
+import { isWav, makeWav, wavChunks, wavDuration } from './audio/riff.ts'
+
+const RATE = 8000
+const CHUNK = 'pmfk'
+
+function fakeWords(text: string): { words: SpeechWord[], duration: number } {
+  const words: SpeechWord[] = []
+  let ms = 0
+  for (const { text: word } of splitWords(text)) {
+    const length = isCjk(word) ? 220 : 60 * [...word].length
+    if (words.length) ms += 80
+    words.push({ text: word, start: ms / 1000, end: (ms + length) / 1000 })
+    ms += length
+  }
+  return { words, duration: ms / 1000 }
+}
+
+export const FAKE_VOICES: VoiceInfo[] = [
+  { id: 'alpha', label: '假音色甲 Alpha', lang: ['zh-CN', 'en-US'] },
+  { id: 'beta', label: '假音色乙 Beta', lang: ['zh-CN', 'en-US'] },
+  { id: 'cloned-lin', label: '林老师（克隆音色）', lang: ['zh-CN'], cloned: true },
+]
+
+export interface FakeContent {
+  text: string
+  voice: string
+  lang: string
+  words: SpeechWord[]
+}
+
+export function fakeAudio(text: string, voice: string, lang: string): { audio: Uint8Array, words: SpeechWord[], duration: number } {
+  const { words, duration } = fakeWords(text)
+  const samples = new Int16Array(Math.round(duration * RATE))
+  for (const word of words) {
+    const frequency = 220 + (word.text.codePointAt(0)! % 64) * 8
+    for (let i = Math.round(word.start * RATE); i < Math.round(word.end * RATE); i++) samples[i] = Math.round(6000 * Math.sin((2 * Math.PI * frequency * i) / RATE))
+  }
+  const content: FakeContent = { text, voice, lang, words }
+  return { audio: makeWav(samples, RATE, [{ id: CHUNK, data: new TextEncoder().encode(JSON.stringify(content)) }]), words, duration }
+}
+
+export function fakeContent(bytes: Uint8Array): FakeContent | undefined {
+  if (!isWav(bytes)) return undefined
+  const chunk = wavChunks(bytes).find(c => c.id === CHUNK)
+  if (!chunk) return undefined
+  try {
+    return JSON.parse(new TextDecoder().decode(chunk.data)) as FakeContent
+  } catch {
+    return undefined
+  }
+}
+
+export interface FakeEngine {
+  url: string
+  close(): Promise<void>
+}
+
+interface Logged {
+  method: string
+  path: string
+  authorization: string | null
+}
+
+export async function startFakeEngine(options: { port?: number, listenAddress?: string } = {}): Promise<FakeEngine> {
+  const requests: Logged[] = []
+  // Voices trained through audio/voices/clone: training on the first status check, ready on the next.
+  const trained = new Map<string, { label: string, checks: number }>()
+  const voices = () => [...FAKE_VOICES, ...[...trained].filter(([, voice]) => voice.checks > 1).map(([id, voice]): VoiceInfo => ({ id, label: voice.label, lang: ['zh-CN'], cloned: true }))]
+  const answer = (status: number, body: unknown, type = 'application/json; charset=utf-8') => new Response(body instanceof Uint8Array ? new Blob([new Uint8Array(body)]) : JSON.stringify(body), { status, headers: { 'Content-Type': type } })
+
+  const route = async (request: Request, path: string): Promise<Response> => {
+    if (path === '/v1/audio/voices' && request.method === 'GET') return answer(200, { voices: voices() })
+    if (path === '/v1/audio/voices/clone' && request.method === 'POST') {
+      const form = await request.formData().catch(() => undefined)
+      const file = form?.get('file'), voice = form?.get('voice')
+      if (!(file instanceof Blob) || typeof voice !== 'string' || !voice) return answer(400, { error: { message: 'multipart form data with `file` and `voice` expected' } })
+      if (file.size < 1000) return answer(400, { error: { message: 'the sample is too short to train from' } })
+      trained.set(voice, { label: `${voice}（克隆音色）`, checks: 0 })
+      return answer(200, { voice, state: 'training', trainingsLeft: 9 })
+    }
+    if (path === '/v1/audio/voices/clone' && request.method === 'GET') {
+      const voice = new URL(request.url).searchParams.get('voice') ?? ''
+      const found = trained.get(voice)
+      if (!found) return answer(200, { voice, state: 'unknown' })
+      found.checks++
+      return answer(200, { voice, state: found.checks > 1 ? 'ready' : 'training', trainingsLeft: 9 })
+    }
+    if ((path === '/v1/audio/speech' || path === '/v1/audio/speech/timestamps') && request.method === 'POST') {
+      const body: unknown = await request.json().catch(() => undefined)
+      if (!isRecord(body) || typeof body.input !== 'string' || typeof body.voice !== 'string') return answer(400, { error: { message: '{ model, voice, input } expected' } })
+      if (!voices().some(voice => voice.id === body.voice)) return answer(400, { error: { message: `no voice "${body.voice}"; the fake engine has ${voices().map(v => v.id).join(', ')}` } })
+      const { audio, words, duration } = fakeAudio(body.input, body.voice, typeof body.language === 'string' ? body.language : 'zh-CN')
+      if (path === '/v1/audio/speech') return answer(200, audio, 'audio/wav')
+      return answer(200, { audio: Buffer.from(audio).toString('base64'), format: 'wav', duration, words })
+    }
+    if (path === '/v1/audio/transcriptions' && request.method === 'POST') {
+      const form = await request.formData().catch(() => undefined)
+      const file = form?.get('file')
+      if (!(file instanceof Blob)) return answer(400, { error: { message: 'multipart form data with `file` expected' } })
+      const bytes = new Uint8Array(await file.arrayBuffer())
+      const content = fakeContent(bytes)
+      const language = typeof form?.get('language') === 'string' ? form.get('language') as string : undefined
+      const duration = isWav(bytes) ? wavDuration(bytes) : 0
+      const transcript = oneSegment(content?.text ?? '', content?.words ?? [], language ?? content?.lang ?? 'zh-CN', duration)
+      return answer(200, { ...transcript, language: transcript.lang, words: content?.words ?? [] })
+    }
+    if (path === '/v1/models' && request.method === 'GET') return answer(200, { object: 'list', data: [{ id: 'fake-tts', object: 'model' }, { id: 'fake-stt', object: 'model' }] })
+    return answer(404, { error: { message: `no route ${request.method} ${path}` } })
+  }
+
+  const server = createServer((req, res) => {
+    const chunks: Buffer[] = []
+    req.on('data', (chunk: Buffer) => chunks.push(chunk))
+    req.on('end', () => {
+      const path = (req.url ?? '/').split('?')[0]!
+      const send = (response: Response) => response.arrayBuffer().then((body) => {
+        res.writeHead(response.status, Object.fromEntries(response.headers))
+        res.end(Buffer.from(body))
+      })
+      if (path === '/requests' && req.method === 'GET') {
+        void send(answer(200, { requests }))
+        return
+      }
+      requests.push({ method: req.method ?? 'GET', path, authorization: req.headers.authorization ?? null })
+      const headers = new Headers()
+      for (const [name, value] of Object.entries(req.headers)) if (typeof value === 'string') headers.set(name, value)
+      const method = req.method ?? 'GET'
+      const request = new Request(`http://fake${req.url ?? '/'}`, { method, headers, ...method === 'GET' || method === 'HEAD' ? {} : { body: Buffer.concat(chunks) } })
+      void route(request, path).catch((error: unknown) => answer(500, { error: { message: String(error) } })).then(send)
+    })
+  })
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', reject)
+    server.listen(options.port ?? 0, options.listenAddress ?? '127.0.0.1', () => resolve())
+  })
+  const { port } = server.address() as AddressInfo
+  const host = options.listenAddress && options.listenAddress !== '0.0.0.0' ? options.listenAddress : '127.0.0.1'
+  return {
+    url: `http://${bracketIPv6(host)}:${port}/v1`,
+    close: () => new Promise((resolve) => {
+      server.close(() => resolve())
+      server.closeAllConnections()
+    }),
+  }
+}

package/src/node/node-service.ts

@@ -0,0 +1,63 @@
+import { speechEngineId } from '@lincyaw/kernel'
+import type { NodeServiceContext, SpeechService, Synthesis } from '@lincyaw/kernel'
+import { createDeckSpeech } from './cached-speech.ts'
+
+export function nodeSpeech(ctx: NodeServiceContext): SpeechService {
+  const { speech } = createDeckSpeech(ctx)
+  const synthesisOf = async (hit: Awaited<ReturnType<typeof speech.cached>>, signal?: AbortSignal): Promise<Synthesis | undefined> => {
+    if (!hit) return undefined
+    const { record, file } = hit
+    await speech.consent(record.engine, record.voice, record.cloned === true, signal)
+    return {
+      audio: file, mime: record.mime, duration: record.duration,
+      ...record.words ? { words: record.words } : {},
+      key: record.key, engine: record.engine, model: record.model, voice: record.voice, provider: record.provider, synthetic: true,
+    }
+  }
+  return {
+    async engines() {
+      return (await speech.listEngines(ctx.lang)).engines.map(({ model: _model, transcribeModel: _transcribe, ...info }) => info)
+    },
+    async defaultSynthesisEngine() {
+      const selected = await speech.defaultSynthesisEngine()
+      return selected ? (await speech.listEngines()).engines.find(engine => engine.tts && engine.id === speechEngineId(selected))?.id : undefined
+    },
+    voices: (engine, lang) => speech.voices(engine, lang),
+    voiceCatalog: (engine, lang, signal) => speech.voiceCatalog(engine, lang, signal),
+    async synthesize(request, signal) {
+      const { result, file } = await speech.synthesizeThroughCache(request, signal)
+      return {
+        audio: file,
+        mime: result.mime,
+        duration: result.duration,
+        ...result.words ? { words: result.words } : {},
+        key: result.key,
+        engine: result.engine,
+        model: result.model,
+        voice: result.voice,
+        provider: result.provider,
+        synthetic: true,
+      }
+    },
+    cached: async (key, signal) => synthesisOf(await speech.cached(key), signal),
+    async lookup(request, signal) {
+      return synthesisOf(await speech.lookup(request), signal)
+    },
+    alignWords: (key, options, signal) => speech.alignWords(key, options, signal),
+    pruneLock: keep => speech.cache.pruneLock(keep),
+    transcribe: (request, signal) => speech.transcribe(request, signal),
+    async cloneVoice(request, signal) {
+      const bytes = async (blob: Blob) => new Uint8Array(await blob.arrayBuffer())
+      return speech.cloneVoice({
+        ...request.engine ? { engine: request.engine } : {},
+        voice: request.voice,
+        sample: await bytes(request.sample),
+        sampleMime: request.sample.type,
+        ...request.lang ? { lang: request.lang } : {},
+        ...request.text ? { text: request.text } : {},
+        consent: { speaker: request.consent.speaker, scope: request.consent.scope, statement: await bytes(request.consent.statement), statementMime: request.consent.statement.type },
+      }, signal)
+    },
+    cloneStatus: (engine, voice, signal) => speech.cloneStatus(engine, voice, signal),
+  }
+}

package/src/node/presmium.ts

@@ -0,0 +1,21 @@
+import { createRequire } from 'node:module'
+import { SPEECH } from '@lincyaw/kernel'
+import type { PresmiumNodePlugin } from '@lincyaw/kernel'
+import { SPEECH_ID } from '../domain/index.ts'
+import { speechConfigPass } from './config-pass.ts'
+import { nodeSpeech } from './node-service.ts'
+import { speechServer } from './server.ts'
+
+const { version } = createRequire(import.meta.url)('../../package.json') as { version: string }
+
+const plugin: PresmiumNodePlugin = {
+  id: SPEECH_ID,
+  version,
+  kernel: '^1.0.0',
+  operator: true,
+  passes: [speechConfigPass],
+  services: ctx => [[SPEECH, nodeSpeech(ctx)]],
+  server: speechServer,
+}
+
+export default plugin

package/src/node/protocol-routes.ts

@@ -0,0 +1,67 @@
+import { jsonResponse, problemResponse } from '@lincyaw/kernel'
+import type { SynthesisResponseBody, TranscriptionResponseBody } from '../domain/index.ts'
+import { toSynthesisRequest } from '../domain/index.ts'
+import type { SpeechBackend, SynthesisResult } from './backend.ts'
+import { blobOf } from './engines/index.ts'
+import { errorResponse } from './errors.ts'
+
+function synthesisResponseBody(result: SynthesisResult): SynthesisResponseBody {
+  return {
+    audio: Buffer.from(result.audio).toString('base64'),
+    format: result.ext,
+    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,
+    key: result.key,
+    synthetic: true,
+    AIGC: result.AIGC,
+  }
+}
+
+const text = (value: FormDataEntryValue | null | undefined) => (typeof value === 'string' && value.trim() ? value.trim() : undefined)
+
+export function protocolHandler(backend: SpeechBackend): (request: Request, path: string) => Promise<Response> {
+  return async (request, path) => {
+    const method = request.method.toUpperCase()
+    try {
+      if (path === 'engines' && method === 'GET') return jsonResponse(await backend.listEngines(request.headers.get('accept-language') ?? undefined))
+      if (path === 'audio/consent' && method === 'GET') {
+        const query = new URL(request.url).searchParams
+        await backend.consent(query.get('engine') ?? '', query.get('voice') ?? '', query.get('recorded') !== '0', request.signal)
+        return jsonResponse({ ok: true })
+      }
+      if (path === 'audio/voice-catalog' && method === 'GET') {
+        const query = new URL(request.url).searchParams
+        return jsonResponse(await backend.voiceCatalog?.(query.get('engine') || undefined, query.get('lang') || undefined, request.signal) ?? { status: 'unavailable', reason: 'unknown', voices: [] })
+      }
+      if (path === 'audio/voices' && method === 'GET') {
+        const query = new URL(request.url).searchParams
+        return jsonResponse({ voices: await backend.voices(query.get('engine') || undefined, query.get('lang') || undefined) })
+      }
+      if ((path === 'audio/speech' || path === 'audio/speech/timestamps') && method === 'POST') {
+        const parsed = toSynthesisRequest(await request.json().catch(() => undefined))
+        if (typeof parsed === 'string') return problemResponse(400, parsed)
+        const result = await backend.synthesize(parsed, request.signal)
+        if (path === 'audio/speech/timestamps') return jsonResponse(synthesisResponseBody(result))
+        return new Response(blobOf(result.audio, result.mime), { headers: { 'Content-Type': result.mime, 'Cache-Control': 'no-store', 'X-Presmium-Key': result.key } })
+      }
+      if (path === 'audio/transcriptions' && method === 'POST') {
+        const form = await request.formData().catch(() => undefined)
+        const file = form?.get('file')
+        if (!form || !(file instanceof Blob)) return problemResponse(400, 'multipart form data with the audio as `file`')
+        const hints = form.getAll('hints[]').flatMap(hint => text(hint) ?? [])
+        const transcript = await backend.transcribe({ audio: file, engine: text(form.get('engine')), lang: text(form.get('language')), ...hints.length ? { hints } : {} }, request.signal)
+        const body: TranscriptionResponseBody = { ...transcript, language: transcript.lang, words: transcript.segments.flatMap(segment => segment.words) }
+        return jsonResponse(body)
+      }
+      return problemResponse(404, `no speech route ${method} v1/${path}`)
+    } catch (error) {
+      return errorResponse(error)
+    }
+  }
+}

package/src/node/server.ts

@@ -0,0 +1,24 @@
+import type { ServerContext, ServerContribution } from '@lincyaw/kernel'
+import { CLONE_PATH, CONSENT_PATH, PROTOCOL_PATH } from '../domain/index.ts'
+import { createDeckSpeech } from './cached-speech.ts'
+import { cloneRoute, MAX_CLONE_AUDIO } from './clone-route.ts'
+import { consentRoute } from './consent.ts'
+import { reportEngines } from './core.ts'
+import { protocolHandler } from './protocol-routes.ts'
+
+const MAX_AUDIO = 32 * 1024 * 1024
+
+export function speechServer(ctx: ServerContext): ServerContribution {
+  const { core, speech } = createDeckSpeech(ctx)
+  void reportEngines(core, ctx.log)
+  const handle = protocolHandler(speech)
+  return {
+    routes: {
+      [`${PROTOCOL_PATH}/*`]: { role: 'editor', maxBody: MAX_AUDIO, handle: (request, route) => handle(request, route.rest) },
+      [`${CONSENT_PATH}/*`]: { role: 'owner', handle: (request, route) => consentRoute(request, route.rest, (engine, voice, record) => core.registerConsent(engine, voice, record)) },
+      // Training registers the speaker's consent and spends money: the owner's alone, like consent.
+      [CLONE_PATH]: { role: 'owner', maxBody: 2 * MAX_CLONE_AUDIO + 65536, handle: request => cloneRoute(request, '', speech) },
+      [`${CLONE_PATH}/*`]: { role: 'owner', handle: (request, route) => cloneRoute(request, route.rest, speech) },
+    },
+  }
+}