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

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,43 @@
-# Temporary Holding Version
+# @lincyaw/addon-speech
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Speech services: speech synthesis and transcription through the operator's engines, the synthesis cache, and `presmium-speech`.
+
+Part of [Presmium](https://github.com/Lincyaw/presmium), which compiles canonical lecture.json teaching documents into web pages, slides, Jupyter notebooks and narrated playback.
+
+## Install
+
+```sh
+pnpm add -D @lincyaw/addon-speech
+```
+
+Add this package to `metadata.plugins` in the document's `lecture.json`.
+
+It is a Presmium plugin: its components work on the web page and in the slides. It needs `@lincyaw/cli` and the renderers in the same project, and declares the Presmium packages it shares with them as peer dependencies (Presmium 1.x).
+
+## What it provides
+
+- The `SPEECH` service in Node and in the browser, with the cache `.presmium/speech/` (commit it, and others build without credentials).
+- Speech is marked as AI generated in the player and in the audio's metadata; cloned voices need a recorded consent (`presmium-speech consent`).
+
+## Configuration
+
+In Studio, open **Settings → Voice Service**, enter the API key from the Volcengine speech console and save. Volcengine speech synthesis 2.0 is the default. The same page is linked from Video Production → Voiceover. Saved credentials apply to the next operation without restarting Studio; choose a voice and explicitly preview or generate it afterwards. **Check Configuration** checks saved local settings, not provider authentication or billing permissions.
+
+The key is stored with mode 0600 in `<operatorDir>/speech/credentials.json`, outside the workspace and document. The owner-only route uses the existing workspace authorization. Reads return configuration status without the key; clearing the saved key restores the environment fallback. Concurrent changes use a revision check under a filesystem lock. Explicit compiler secret resolvers keep precedence.
+
+The operator defines engines in environment variables: `PRESMIUM_SPEECH_<ID>_URL`, `_PROVIDER` and, optionally, `_KEY`. Documents name the engine's id only, for example `presmium: { presmium.speech: { engine: volcengine } }`.
+
+Volcengine (engine id `volcengine`) needs only `PRESMIUM_SPEECH_VOLCENGINE_KEY`, the API key from its speech console; it synthesizes with speech synthesis 2.0 (`seed-tts-2.0`). Its voice list is bundled with the package. With the account's IAM access key pair, `PRESMIUM_SPEECH_VOLCENGINE_ACCESS_KEY_ID` and `PRESMIUM_SPEECH_VOLCENGINE_SECRET_ACCESS_KEY` (and `PRESMIUM_SPEECH_VOLCENGINE_PROJECT`, by default `default`), the list comes from the account through Volcengine's SDK, together with the account's cloned voices.
+
+Cloned voices stay off until the operator sets `settings.presmium.speech.cloned: true` in `presmium.workspace.yaml`. Then the workbench trains one from its voice dialog (Clone a voice…), and so does `presmium-speech clone <engine> <voice> <sample> --speaker … --scope … --statement <recording>`: both register the speaker's consent before the sample leaves the machine. The provider charges for training and for every synthesis; a pay-as-you-go Volcengine voice is charged at its first synthesis, previews included.
+
+Engine URLs must be HTTP(S) addresses without user information, a query or a fragment; credentials belong in `_KEY`. New cache keys include the normalized address, provider, adapter kind and model identity, excluding credentials. Changing a model or provider under the same engine ID requires explicit generation; reads never generate missing audio. Commit the matching cache and `speech.lock.json` for offline builds. An incomplete definition, including a model-only setting, is unavailable rather than an offline fallback. With no definition at all, request lookup accepts one locked result; multiple profiles for that request are ambiguous. Legacy locked audio remains readable offline, but cannot establish the identity of a configured provider. Every cache read verifies the audio SHA; alignment also verifies its audio and transcription profile.
+
+## Documentation
+
+- [Author guide](https://github.com/Lincyaw/presmium/blob/main/site/guide/locales/en/lecture.json) (Chinese: `site/guide/lecture.json`)
+- [Document contract](https://github.com/Lincyaw/presmium/blob/main/.agents/skills/presmium-author/references/document.md): normalized entities, parameters, states and shared validation
+
+## License
+
+Apache-2.0

package/bin/presmium-speech.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { createJiti } from 'jiti'
+
+const emitWarning = process.emitWarning
+process.emitWarning = (warning, ...args) => {
+  const code = typeof args[0] === 'object' ? args[0]?.code : args[1]
+  if (code !== 'DEP0040') emitWarning.call(process, warning, ...args)
+}
+
+const jiti = createJiti(import.meta.url)
+const { main } = await jiti.import('../src/node/cli.ts')
+const code = await main(process.argv.slice(2))
+if (code !== undefined) process.exitCode = code

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@lincyaw/addon-speech",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0-rc.2",
+  "description": "Presmium plugin: speech services: the speech routes, engine adapters, the synthesis cache, and presmium-speech",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Lincyaw/presmium.git",
+    "directory": "packages/addon-speech"
+  },
+  "homepage": "https://github.com/Lincyaw/presmium/tree/main/packages/addon-speech#readme",
+  "bugs": "https://github.com/Lincyaw/presmium/issues",
+  "keywords": [
+    "presmium"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22.19"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "presmium-speech": "./bin/presmium-speech.mjs"
+  },
+  "exports": {
+    "./domain": "./src/domain/index.ts",
+    "./client": "./src/client/index.ts",
+    "./presmium": "./src/node/presmium.ts",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "dependencies": {
+    "@volcengine/speechsaasprod": "1.0.5",
+    "@volcengine/speechsaasprod20250521": "1.0.5",
+    "jiti": "^2.7.0"
+  },
+  "peerDependencies": {
+    "@lincyaw/host": "^1.0.0-rc.2",
+    "@lincyaw/compiler": "^1.0.0-rc.2",
+    "@lincyaw/kernel": "^1.0.0-rc.2"
+  },
+  "devDependencies": {
+    "@lincyaw/cli": "1.0.0-rc.2",
+    "@lincyaw/compiler": "1.0.0-rc.2",
+    "@lincyaw/host": "1.0.0-rc.2",
+    "@lincyaw/kernel": "1.0.0-rc.2"
+  },
+  "presmium": {
+    "preview": {
+      "restartable": true
+    }
+  }
 }

package/src/client/index.ts

@@ -0,0 +1,2 @@
+export { default as speechPlugin } from './plugin.ts'
+export { browserSpeech } from './speech.ts'

package/src/client/plugin.ts

@@ -0,0 +1,23 @@
+import { SPEECH } from '@lincyaw/kernel'
+import type { PluginDefinition } from '@lincyaw/kernel'
+import { version } from '../../package.json'
+import { SPEECH_ID } from '../domain/index.ts'
+import { browserSpeech } from './speech.ts'
+
+const plugin: PluginDefinition = {
+  // dispose releases everything setup made; a paused preview starts the same definition again.
+  restartable: true,
+  manifest: {
+    id: SPEECH_ID,
+    name: { 'zh-CN': '语音服务', en: 'Voice Service' },
+    version,
+    kernel: '^1.0.0',
+    provides: [SPEECH],
+    capabilities: ['network'],
+  },
+  setup(ctx) {
+    ctx.provide(SPEECH, browserSpeech(ctx.config))
+  },
+}
+
+export default plugin

package/src/client/speech.ts

@@ -0,0 +1,63 @@
+import { serverClient } from '@lincyaw/host'
+import type { SpeechService, Synthesis, VoiceCatalog } from '@lincyaw/kernel'
+import type { EnginesResponseBody, SynthesisResponseBody, TranscriptionResponseBody, VoicesResponseBody } from '../domain/index.ts'
+import { deckSpeechConfig, PROTOCOL_PATH, SPEECH_ID, synthesisRequestBody, transcriptOf } from '../domain/index.ts'
+
+function bytesOf(base64: string): Uint8Array<ArrayBuffer> {
+  const binary = atob(base64)
+  const bytes = new Uint8Array(binary.length)
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i)
+  return bytes
+}
+
+export function browserSpeech(config: Record<string, unknown>): SpeechService {
+  const defaults = deckSpeechConfig(config).config
+  const server = serverClient()
+  const call = async <T>(path: string, init?: RequestInit): Promise<T> => {
+    if (!server.available) throw new Error('speech needs presmium dev or presmium serve: a static page has no speech service')
+    const response = await server.fetch(SPEECH_ID, `${PROTOCOL_PATH}/${path}`, init)
+    const body = await response.json().catch(() => undefined) as (T & { error?: string }) | undefined
+    if (!response.ok) throw new Error(body?.error ?? `the speech service answered ${response.status}`)
+    return body as T
+  }
+
+  return {
+    async engines() {
+      return (await call<EnginesResponseBody>('engines')).engines.map(({ model: _model, transcribeModel: _transcribe, ...info }) => info)
+    },
+    async voices(engine, lang) {
+      const query = new URLSearchParams({ engine, ...lang ? { lang } : {} })
+      return (await call<VoicesResponseBody>(`audio/voices?${query}`)).voices
+    },
+    async voiceCatalog(engine, lang, signal) {
+      const selected = engine ?? defaults.engine
+      const query = new URLSearchParams({ ...selected ? { engine: selected } : {}, ...lang ? { lang } : {} })
+      return call<VoiceCatalog>(`audio/voice-catalog?${query}`, { signal })
+    },
+    async synthesize(request, signal): Promise<Synthesis> {
+      const body = synthesisRequestBody({ ...request, ...request.engine || defaults.engine ? { engine: request.engine ?? defaults.engine } : {} })
+      const synthesized = await call<SynthesisResponseBody>('audio/speech/timestamps', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body), signal })
+      return {
+        audio: new Blob([bytesOf(synthesized.audio)], { type: synthesized.mime }),
+        mime: synthesized.mime,
+        duration: synthesized.duration,
+        ...synthesized.words ? { words: synthesized.words } : {},
+        key: synthesized.key,
+        engine: synthesized.engine,
+        model: synthesized.model,
+        voice: synthesized.voice,
+        provider: synthesized.provider,
+        synthetic: true,
+      }
+    },
+    async transcribe(request, signal) {
+      const form = new FormData()
+      form.set('file', request.audio, 'audio')
+      const engine = request.engine ?? defaults.transcribe ?? defaults.engine
+      if (engine) form.set('engine', engine)
+      if (request.lang) form.set('language', request.lang)
+      for (const hint of request.hints ?? []) form.append('hints[]', hint)
+      return transcriptOf(await call<TranscriptionResponseBody>('audio/transcriptions', { method: 'POST', body: form, signal }))
+    },
+  }
+}

package/src/domain/config.ts

@@ -0,0 +1,50 @@
+import { isRecord } from '@lincyaw/kernel'
+import { howToDefine } from './engines.ts'
+
+export const SPEECH_ID = 'presmium.speech'
+
+export const PROTOCOL_PATH = 'v1'
+
+export const CONSENT_PATH = 'consent'
+
+/** Training a cloned voice (`clone`) and its status (`clone/status`); for the owner only. */
+export const CLONE_PATH = 'clone'
+
+export const DEFAULT_CONSENT_DIR = 'consent'
+
+export interface DeckSpeechConfig {
+  engine?: string
+  transcribe?: string
+}
+
+export interface ConfigProblem {
+  severity: 'error' | 'warning'
+  message: string
+}
+
+const DEFINITION = new Set(['url', 'baseUrl', 'base_url', 'endpoint', 'key', 'keyEnv', 'apiKey', 'api_key', 'token', 'tokenEnv', 'secret', 'provider', 'appid', 'appId', 'model'])
+const OPERATOR = new Set(['cloned', 'consentDir'])
+
+export function deckSpeechConfig(value: unknown): { config: DeckSpeechConfig, problems: ConfigProblem[] } {
+  const config: DeckSpeechConfig = {}
+  const problems: ConfigProblem[] = []
+  if (!isRecord(value)) return { config, problems }
+  for (const [key, item] of Object.entries(value)) {
+    if (key === 'engine' || key === 'transcribe') {
+      if (typeof item === 'string' && item.trim()) config[key] = item.trim()
+      else problems.push({ severity: 'error', message: `presmium.speech.${key} names an engine by its id, e.g. ${key}: volcengine` })
+    } else if (key === 'engines') {
+      for (const [id, definition] of Object.entries(isRecord(item) ? item : {})) {
+        const fields = isRecord(definition) ? Object.keys(definition) : []
+        problems.push({ severity: 'error', message: `presmium.speech.engines.${id}${fields.length ? ` (${fields.join(', ')})` : ''} is not used, as a deck only names engines: engine "${id}" is not defined; ${howToDefine(id)}` })
+      }
+    } else if (DEFINITION.has(key)) {
+      problems.push({ severity: 'error', message: `presmium.speech.${key} is not used, as a deck only names engines; ${howToDefine(config.engine ?? (typeof value.engine === 'string' ? value.engine : '<id>'))}` })
+    } else if (OPERATOR.has(key)) {
+      problems.push({ severity: 'warning', message: `presmium.speech.${key} is an operator setting (settings.presmium.speech in presmium.workspace.yaml); the deck's is ignored` })
+    } else {
+      problems.push({ severity: 'warning', message: `presmium.speech.${key} is not a setting of speech (engine, transcribe); it is ignored` })
+    }
+  }
+  return { config, problems }
+}

package/src/domain/consent.ts

@@ -0,0 +1,25 @@
+import { isRecord, speechEngineId } from '@lincyaw/kernel'
+
+export interface ConsentRecord {
+  speaker: string
+  scope: string
+  date: string
+  statementSha256: string
+}
+
+export function safeName(name: string): boolean {
+  return /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(name)
+}
+
+export function consentProblem(value: unknown): string | undefined {
+  if (!isRecord(value)) return 'a consent record is a JSON object { speaker, scope, date, statementSha256 }'
+  const missing = (['speaker', 'scope', 'date', 'statementSha256'] as const).filter(key => typeof value[key] !== 'string' || !(value[key] as string).trim())
+  if (missing.length) return `the consent record lacks ${missing.join(', ')}`
+  if (Number.isNaN(Date.parse(value.date as string))) return `the consent record's date "${value.date as string}" is not an ISO 8601 date`
+  if (!/^[0-9a-f]{64}$/i.test(value.statementSha256 as string)) return 'the consent record\'s statementSha256 is not a sha256 in hex'
+  return undefined
+}
+
+export function consentPath(engine: string, voice: string): string {
+  return `${speechEngineId(engine)}/${voice}.json`
+}

package/src/domain/engines.ts

@@ -0,0 +1,152 @@
+import { speechEngineId } from '@lincyaw/kernel'
+import type { SpeechEngineInfo } from '@lincyaw/kernel'
+
+export const VOLCENGINE = 'volcengine'
+export const FAKE = 'fake'
+
+export type EngineKind = 'volcengine' | 'openai' | 'fake'
+
+export interface EngineDefinition {
+  id: string
+  kind: EngineKind
+  url: string
+  provider: string
+  key?: string
+  appid?: string
+  model: string
+  transcribeModel: string
+  /** False when the operator says the engine does not synthesize (`PRESMIUM_SPEECH_<ID>_MODEL=none`). */
+  synthesizes: boolean
+  /** False when the operator says the engine does not transcribe (`PRESMIUM_SPEECH_<ID>_TRANSCRIBE_MODEL=none`). */
+  transcribes: boolean
+  /**
+   * Volcengine's console (OpenAPI) credentials, an IAM access key pair separate from the speech API key: with them
+   * the voice list and the account's cloned voices come from the account; without, from the bundled catalogue.
+   */
+  console?: { accessKeyId: string, secretAccessKey: string, project: string }
+}
+
+/** The model an operator writes for a use an engine does not have, e.g. an engine that only says text. */
+export const NO_MODEL = 'none'
+
+export type EngineUse = 'synthesize' | 'transcribe'
+
+export function engineDoes(engine: EngineDefinition, use: EngineUse): boolean {
+  return use === 'synthesize' ? engine.synthesizes : engine.transcribes
+}
+
+/** Why an engine named for a use cannot do it. */
+export function whyEngineCannot(engine: EngineDefinition, use: EngineUse): string {
+  return `speech engine "${engine.id}" does not ${use}: ${engineVariable(engine.id, use === 'synthesize' ? 'MODEL' : 'TRANSCRIBE_MODEL')} is ${NO_MODEL}`
+}
+
+export interface UnavailableEngine {
+  id: string
+  reason: string
+}
+
+export const VOLCENGINE_URL = 'https://openspeech.bytedance.com'
+
+const SUFFIXES = ['URL', 'PROVIDER', 'KEY', 'APPID', 'MODEL', 'TRANSCRIBE_MODEL', 'ACCESS_KEY_ID', 'SECRET_ACCESS_KEY', 'PROJECT'] as const
+type Suffix = typeof SUFFIXES[number]
+const VARIABLE = new RegExp(`^PRESMIUM_SPEECH_([A-Z0-9_]+?)_(${SUFFIXES.join('|')})$`)
+
+export function engineVariable(id: string, suffix: Suffix): string {
+  return `PRESMIUM_SPEECH_${speechEngineId(id).toUpperCase()}_${suffix}`
+}
+
+export function howToDefine(id: string): string {
+  return `the operator defines engine "${id}" in the environment of the process that holds the credentials (${engineVariable(id, 'URL')}, ${engineVariable(id, 'PROVIDER')} and optionally ${engineVariable(id, 'KEY')}; ${VOLCENGINE} needs only ${engineVariable(VOLCENGINE, 'KEY')})`
+}
+
+export function engineIds(names: Iterable<string>): string[] {
+  const ids = new Set<string>()
+  for (const name of names) {
+    const match = VARIABLE.exec(name)
+    if (match) ids.add(speechEngineId(match[1]!))
+  }
+  return [...ids].sort()
+}
+
+function isLoopback(url: string): boolean {
+  try {
+    return ['localhost', '127.0.0.1', '[::1]'].includes(new URL(url).hostname)
+  } catch {
+    return false
+  }
+}
+
+/** The engines the operator defined; `warnings` are settings that were ignored, for the operator's log. */
+export function operatorEngines(names: Iterable<string>, secret: (name: string) => string | undefined): { engines: EngineDefinition[], unavailable: UnavailableEngine[], warnings: string[] } {
+  const engines: EngineDefinition[] = []
+  const unavailable: UnavailableEngine[] = []
+  const warnings: string[] = []
+  for (const id of engineIds(names)) {
+    const value = (suffix: Suffix) => secret(engineVariable(id, suffix))?.trim() || undefined
+    if (id === VOLCENGINE) {
+      const key = value('KEY')
+      const accessKeyId = value('ACCESS_KEY_ID'), secretAccessKey = value('SECRET_ACCESS_KEY')
+      if (!key) unavailable.push({ id, reason: `${engineVariable(id, 'KEY')} is not set` })
+      else {
+        if (Boolean(accessKeyId) !== Boolean(secretAccessKey)) warnings.push(`speech engine ${id}: ${engineVariable(id, 'ACCESS_KEY_ID')} and ${engineVariable(id, 'SECRET_ACCESS_KEY')} come as a pair, and only one is set, so the voice list is the bundled one`)
+        engines.push({
+          id, kind: 'volcengine', url: VOLCENGINE_URL, provider: VOLCENGINE_NAME['zh-CN'], key, appid: value('APPID'), model: 'seed-tts-2.0', transcribeModel: 'volc.bigasr.auc_turbo', synthesizes: true, transcribes: true,
+          ...accessKeyId && secretAccessKey ? { console: { accessKeyId, secretAccessKey, project: value('PROJECT') ?? 'default' } } : {},
+        })
+      }
+      continue
+    }
+    const missing = (['URL', 'PROVIDER'] as const).filter(suffix => !value(suffix)).map(suffix => engineVariable(id, suffix))
+    if (missing.length) {
+      unavailable.push({ id, reason: `${missing.join(' and ')} ${missing.length > 1 ? 'are' : 'is'} not set; an engine needs its address and the name of its provider` })
+      continue
+    }
+    let url: string
+    try {
+      const parsed = new URL(value('URL')!)
+      if (!['http:', 'https:'].includes(parsed.protocol) || parsed.username || parsed.password || parsed.search || parsed.hash) throw new Error('address')
+      url = parsed.href.replace(/\/+$/, '')
+    } catch {
+      unavailable.push({ id, reason: `${engineVariable(id, 'URL')} must be an http(s) address without credentials, query or fragment` })
+      continue
+    }
+    const fake = id === FAKE
+    const none = (suffix: Suffix) => value(suffix)?.toLowerCase() === NO_MODEL
+    engines.push({
+      id,
+      kind: fake ? 'fake' : 'openai',
+      url,
+      provider: value('PROVIDER')!,
+      key: value('KEY'),
+      model: value('MODEL') ?? (fake ? 'fake-tts' : 'tts-1'),
+      transcribeModel: value('TRANSCRIBE_MODEL') ?? (fake ? 'fake-stt' : 'whisper-1'),
+      synthesizes: !none('MODEL'),
+      transcribes: !none('TRANSCRIBE_MODEL'),
+    })
+  }
+  engines.sort((a, b) => Number(b.id === VOLCENGINE) - Number(a.id === VOLCENGINE) || a.id.localeCompare(b.id))
+  return { engines, unavailable, warnings }
+}
+
+const VOLCENGINE_NAME = { 'zh-CN': '火山引擎', 'en': 'Volcengine' }
+
+function isChinese(lang: string | undefined): boolean {
+  return /^zh\b/i.test((lang ?? '').trim())
+}
+
+export function providerName(engine: EngineDefinition, lang?: string): string {
+  if (engine.kind !== 'volcengine') return engine.provider
+  return VOLCENGINE_NAME[isChinese(lang ?? 'zh') ? 'zh-CN' : 'en']
+}
+
+export function engineInfo(engine: EngineDefinition, lang?: string): SpeechEngineInfo {
+  return {
+    id: engine.id,
+    provider: providerName(engine, lang),
+    stt: engine.transcribes,
+    tts: engine.synthesizes,
+    wordTimes: engine.kind !== 'openai',
+    local: engine.kind === 'fake' || (engine.kind === 'openai' && isLoopback(engine.url)),
+    clone: engine.kind !== 'openai' && engine.synthesizes,
+  }
+}

package/src/domain/index.ts

@@ -0,0 +1,11 @@
+export { CLONE_PATH, CONSENT_PATH, DEFAULT_CONSENT_DIR, deckSpeechConfig, PROTOCOL_PATH, SPEECH_ID } from './config.ts'
+export type { ConfigProblem, DeckSpeechConfig } from './config.ts'
+export { consentPath, consentProblem, safeName } from './consent.ts'
+export type { ConsentRecord } from './consent.ts'
+export { whyEngineCannot, engineDoes, engineIds, engineInfo, engineVariable, FAKE, howToDefine, NO_MODEL, operatorEngines, providerName, VOLCENGINE, VOLCENGINE_URL } from './engines.ts'
+export type { EngineDefinition, EngineKind, EngineUse, UnavailableEngine } from './engines.ts'
+export { applyLexicon, applyLexiconWithSpans } from './lexicon.ts'
+export type { LexiconText } from './lexicon.ts'
+export { synthesisRequestBody, toSynthesisRequest, transcriptOf } from './protocol.ts'
+export type { EnginesResponseBody, ListedEngine, SynthesisRequestBody, SynthesisResponseBody, TranscriptionResponseBody, VoicesResponseBody } from './protocol.ts'
+export { oneSegment, wordsIntoSegments } from './transcript.ts'