dsh-her 0.0.1 → 0.1.0

package/lib/voice/edge.js

@@ -0,0 +1,199 @@
+/**
+ * Microsoft Edge "Read aloud" voices (晓晓, 晓伊 …) through the open-source
+ * command-line tool edge-tts (https://github.com/rany2/edge-tts), the same
+ * way dsh-audiobook does it: we never talk to the service ourselves.
+ *
+ * Where the tool comes from, first found wins:
+ *   1. one already installed by dsh-her (`<home>/edge-tts`), dsh-audiobook or
+ *      dsh-tingdong (`~/.dsh/<plugin>/edge-tts`), or on the PATH via Homebrew;
+ *   2. otherwise it is installed in the background into `<home>/edge-tts`,
+ *      a Python virtual environment of its own, built with the computer's
+ *      Python 3.8+ if it has one;
+ *   3. without one (a new Mac has only a /usr/bin/python3 that asks to install
+ *      the developer tools), uv (https://github.com/astral-sh/uv, one pinned,
+ *      checksummed download) fetches a Python of its own into `<home>/uv`
+ *      and builds the environment with it. No dialogs, nothing system-wide.
+ * Deleting `<home>/edge-tts` (and `<home>/uv`) uninstalls it.
+ *
+ * One process per sentence, so each pays for a fresh connection (about 2.5 s
+ * measured on 2026-10-29); the speech queue synthesizes ahead to hide it.
+ * Needs the internet; not an official Microsoft API, so it may stop working.
+ */
+import { execFile } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { homedir, tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+/** audio-24khz-48kbitrate-mono-mp3: constant bitrate, so bytes give the duration. */
+const MP3_BYTES_PER_MS = 48_000 / 8 / 1000;
+const SPEAK_TIMEOUT_MS = 20_000;
+const win = process.platform === 'win32';
+function run(cmd, args, timeout, env) {
+    return new Promise((resolve, reject) => {
+        execFile(cmd, args, { timeout, maxBuffer: 8 << 20, ...(env === undefined ? {} : { env: { ...process.env, ...env } }) }, (error, stdout, stderr) => {
+            if (error !== null)
+                reject(new Error(String(stderr || error.message).trim().split('\n').slice(-2).join(' ')));
+            else
+                resolve(String(stdout));
+        });
+    });
+}
+const venvBin = (root, name) => join(root, win ? 'Scripts' : 'bin', win ? `${name}.exe` : name);
+/** `--rate` for a speed factor: 1.2 → "+20%". */
+export function edgeRate(speed) {
+    const percent = Math.round((speed - 1) * 100);
+    return `${percent >= 0 ? '+' : ''}${percent}%`;
+}
+export class EdgeVoice {
+    ownDir;
+    installing;
+    state = 'missing';
+    error;
+    viaUv;
+    /** `ownDir`: where dsh-her installs its own copy (`<home>/edge-tts`). `viaUv`: skip the computer's Python (tests). */
+    constructor(ownDir, options = {}) {
+        this.ownDir = ownDir;
+        this.viaUv = options.viaUv === true;
+        if (this.bin() !== undefined)
+            this.state = 'ready';
+    }
+    get status() {
+        return this.error === undefined ? { status: this.state } : { status: this.state, error: this.error };
+    }
+    /** The edge-tts command, or undefined when there is none yet. */
+    bin() {
+        const dsh = join(homedir(), '.dsh');
+        const roots = this.viaUv ? [this.ownDir] : [this.ownDir, join(dsh, 'dsh-audiobook', 'edge-tts'), join(dsh, 'dsh-tingdong', 'edge-tts')];
+        for (const root of roots) {
+            if (existsSync(venvBin(root, 'edge-tts')))
+                return venvBin(root, 'edge-tts');
+        }
+        return this.viaUv ? undefined : ['/opt/homebrew/bin/edge-tts', '/usr/local/bin/edge-tts', '/usr/bin/edge-tts'].find(p => existsSync(p));
+    }
+    /** Make sure the tool is there, installing it once if needed. */
+    ensure() {
+        if (this.bin() !== undefined) {
+            this.state = 'ready';
+            return Promise.resolve();
+        }
+        this.installing ??= this.install().finally(() => { this.installing = undefined; });
+        return this.installing;
+    }
+    /** One sentence as MP3. */
+    async synthesize(text, voice, speed) {
+        await this.ensure();
+        const bin = this.bin();
+        if (bin === undefined)
+            throw new Error('Edge 语音组件还没装好');
+        const started = Date.now();
+        const out = join(tmpdir(), `dsh-her-${randomUUID()}.mp3`);
+        try {
+            // --text=…: a sentence starting with "-" is not taken for an option.
+            const args = ['--voice', voice, `--rate=${edgeRate(speed)}`, `--text=${text}`, '--write-media', out];
+            try {
+                await run(bin, args, SPEAK_TIMEOUT_MS);
+            }
+            catch {
+                // The network hiccups now and then: once more.
+                await run(bin, args, SPEAK_TIMEOUT_MS);
+            }
+            const audio = new Uint8Array(await readFile(out));
+            if (audio.byteLength === 0)
+                throw new Error('Edge 没有返回声音');
+            return { audio, durationMs: Math.round(audio.byteLength / MP3_BYTES_PER_MS), ms: Date.now() - started };
+        }
+        finally {
+            await rm(out, { force: true });
+        }
+    }
+    async install() {
+        this.state = 'installing';
+        this.error = undefined;
+        try {
+            const python = this.viaUv ? undefined : await findPython();
+            const venvPython = venvBin(this.ownDir, win ? 'python' : 'python3');
+            if (python !== undefined) {
+                if (!existsSync(venvPython))
+                    await run(python, ['-m', 'venv', this.ownDir], 120_000);
+                await run(venvPython, ['-m', 'pip', 'install', '-q', '--disable-pip-version-check', '--upgrade', 'edge-tts'], 300_000);
+            }
+            else {
+                // No Python here: uv brings one of its own, kept next to edge-tts.
+                const uvHome = join(dirname(this.ownDir), 'uv');
+                const uv = await installUv(uvHome);
+                const env = { UV_PYTHON_INSTALL_DIR: join(uvHome, 'python'), UV_CACHE_DIR: join(uvHome, 'cache'), UV_NO_CONFIG: '1' };
+                if (!existsSync(venvPython))
+                    await run(uv, ['venv', '--quiet', '--python', '3.12', this.ownDir], 600_000, env);
+                await run(uv, ['pip', 'install', '--quiet', '--python', venvPython, '--upgrade', 'edge-tts'], 300_000, env);
+                // The downloads are installed now; only the Python itself must stay.
+                await rm(env.UV_CACHE_DIR, { recursive: true, force: true });
+            }
+            if (this.bin() === undefined)
+                throw new Error('装完了却找不到 edge-tts');
+            this.state = 'ready';
+        }
+        catch (error) {
+            this.state = 'failed';
+            this.error = `安装 Edge 语音组件失败：${error.message}`;
+            throw new Error(this.error);
+        }
+    }
+}
+/**
+ * A Python 3.8+ to build the virtual environment with. On a Mac,
+ * /usr/bin/python3 (and a bare `python3`, which is the same) only work once
+ * the developer tools are installed; before that, running them pops up the
+ * installer, so they are not even tried.
+ */
+async function findPython() {
+    const devTools = process.platform !== 'darwin' || await run('/usr/bin/xcode-select', ['-p'], 10_000).then(() => true, () => false);
+    const candidates = win ? ['py', 'python', 'python3'] : ['/opt/homebrew/bin/python3', '/usr/local/bin/python3', ...(devTools ? ['/usr/bin/python3', 'python3'] : [])];
+    for (const python of candidates) {
+        if (python.includes('/') && !existsSync(python))
+            continue;
+        try {
+            const [major, minor] = (await run(python, ['-c', 'import sys; print("%d.%d" % sys.version_info[:2])'], 15_000)).trim().split('.').map(Number);
+            if (major === 3 && minor >= 8)
+                return python;
+        }
+        catch {
+            // the next one
+        }
+    }
+    return undefined;
+}
+/** uv, pinned: version and the SHA-256 of each download (from the release's .sha256 files). */
+const UV_VERSION = '0.11.26';
+const UV_ASSETS = {
+    'darwin-arm64': { file: 'uv-aarch64-apple-darwin.tar.gz', sha256: '8f7fbf1708399b921857bce71e1d60f0d3ccf52a30caebc1c1a2f175dce13ab6' },
+    'darwin-x64': { file: 'uv-x86_64-apple-darwin.tar.gz', sha256: '922b460202707dd5f4ccacbadbe7f6a546cc46e82a99bf50ca99a7977a78eddd' },
+    'win32-x64': { file: 'uv-x86_64-pc-windows-msvc.zip', sha256: '4e1278ede866be6c0bf32d2f466cc6de7a9fb399ecf20c9ce2d186e52424be47' },
+};
+/** The uv binary in `uvHome`, downloaded and checked the first time. */
+async function installUv(uvHome) {
+    const key = `${process.platform}-${process.arch}`;
+    const asset = UV_ASSETS[key];
+    if (asset === undefined)
+        throw new Error(`这台电脑（${key}）没有 Python，也没有现成的办法自动装：请先装 Python 3`);
+    const dir = join(uvHome, UV_VERSION);
+    const found = [join(dir, 'uv'), join(dir, 'uv.exe'), join(dir, asset.file.replace(/\.(tar\.gz|zip)$/, ''), 'uv')].find(p => existsSync(p));
+    if (found !== undefined)
+        return found;
+    const res = await fetch(`https://github.com/astral-sh/uv/releases/download/${UV_VERSION}/${asset.file}`, { redirect: 'follow', signal: AbortSignal.timeout(300_000) });
+    if (!res.ok)
+        throw new Error(`下载 uv 失败（${res.status}）`);
+    const bytes = Buffer.from(await res.arrayBuffer());
+    if (createHash('sha256').update(bytes).digest('hex') !== asset.sha256)
+        throw new Error('下载的 uv 校验不对，没有使用');
+    await mkdir(dir, { recursive: true });
+    const archive = join(dir, asset.file);
+    await writeFile(archive, bytes);
+    // tar reads both the .tar.gz and (Windows 10+) the .zip.
+    await run('tar', ['-xf', archive, '-C', dir], 120_000);
+    await rm(archive, { force: true });
+    const uv = [join(dir, 'uv'), join(dir, 'uv.exe'), join(dir, asset.file.replace(/\.(tar\.gz|zip)$/, ''), 'uv')].find(p => existsSync(p));
+    if (uv === undefined)
+        throw new Error('uv 解压后找不到');
+    return uv;
+}

package/lib/voice/engine.js

@@ -0,0 +1,101 @@
+/**
+ * Parent side of the local speech recognition child process. Requests are answered in order of completion,
+ * matched by id. If the child dies, pending requests fail and the next call
+ * starts a fresh one.
+ *
+ * Inside the DSH desktop app `process.execPath` is Electron, so the child is
+ * started with ELECTRON_RUN_AS_NODE. The sherpa native library directory is
+ * put on the loader path, as sherpa-onnx documents.
+ */
+import { fork } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** Directory of the platform package holding sherpa's shared libraries, if installed. */
+function nativeLibDir() {
+    try {
+        const require = createRequire(import.meta.url);
+        return dirname(require.resolve(`sherpa-onnx-${process.platform === 'win32' ? 'win' : process.platform}-${process.arch}/package.json`));
+    }
+    catch {
+        return undefined;
+    }
+}
+function childEnv() {
+    const env = { ...process.env };
+    if (process.versions.electron !== undefined)
+        env.ELECTRON_RUN_AS_NODE = '1';
+    const lib = nativeLibDir();
+    if (lib !== undefined) {
+        const key = process.platform === 'darwin' ? 'DYLD_LIBRARY_PATH' : process.platform === 'win32' ? 'PATH' : 'LD_LIBRARY_PATH';
+        const sep = process.platform === 'win32' ? ';' : ':';
+        env[key] = env[key] ? `${lib}${sep}${env[key]}` : lib;
+    }
+    return env;
+}
+export class LocalVoice {
+    child;
+    nextId = 1;
+    pending = new Map();
+    ready;
+    init;
+    constructor(init) {
+        this.init = init;
+    }
+    /** Load the models (once); resolves with how long loading took. */
+    start() {
+        this.ready ??= this.request({ op: 'init', init: this.init }).then(reply => {
+            if (reply.op !== 'init')
+                throw new Error('unexpected reply');
+            return { loadMs: reply.loadMs };
+        });
+        return this.ready;
+    }
+    async recognize(samples, sampleRate) {
+        await this.start();
+        const reply = await this.request({ op: 'asr', samples, sampleRate });
+        if (reply.op !== 'asr')
+            throw new Error('unexpected reply');
+        return { text: reply.text, lang: reply.lang, ms: reply.ms };
+    }
+    stop() {
+        this.child?.kill();
+        this.child = undefined;
+        this.ready = undefined;
+    }
+    spawn() {
+        const here = fileURLToPath(import.meta.url);
+        const worker = here.replace(/engine\.(ts|js)$/, 'worker.$1');
+        const child = fork(worker, [], { env: childEnv(), serialization: 'advanced', stdio: ['ignore', 'inherit', 'inherit', 'ipc'] });
+        child.on('message', (reply) => {
+            const waiter = this.pending.get(reply.id);
+            if (waiter === undefined)
+                return;
+            this.pending.delete(reply.id);
+            if (reply.ok)
+                waiter.resolve(reply);
+            else
+                waiter.reject(new Error(reply.error));
+        });
+        child.on('exit', (code, signal) => {
+            if (this.child === child) {
+                this.child = undefined;
+                this.ready = undefined;
+            }
+            const error = new Error(`语音子进程退出了（${signal ?? code}）`);
+            for (const waiter of this.pending.values())
+                waiter.reject(error);
+            this.pending.clear();
+        });
+        return child;
+    }
+    request(body) {
+        this.child ??= this.spawn();
+        const id = this.nextId++;
+        const child = this.child;
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, { resolve, reject });
+            child.send({ ...body, id });
+        });
+    }
+}

package/lib/voice/models.js

@@ -0,0 +1,69 @@
+/**
+ * Local speech recognition models (sherpa-onnx). They are downloaded on first
+ * use into `<home>/models`, never shipped in the package. Her own voice is in
+ * the cloud (cosyvoice.ts). Design: docs/语音方案.md.
+ */
+import { execFile } from 'node:child_process';
+import { createWriteStream, existsSync, mkdirSync, renameSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { promisify } from 'node:util';
+const RELEASES = 'https://github.com/k2-fsa/sherpa-onnx/releases/download';
+export const MODELS = [
+    {
+        id: 'asr',
+        name: 'sherpa-onnx-sense-voice-zh-en-ja-ko-yue-int8-2025-09-09',
+        url: `${RELEASES}/asr-models/sherpa-onnx-sense-voice-zh-en-ja-ko-yue-int8-2025-09-09.tar.bz2`,
+        bytes: 165_783_878,
+        archive: true,
+    },
+    {
+        id: 'vad',
+        name: 'silero_vad.onnx',
+        url: `${RELEASES}/asr-models/silero_vad.onnx`,
+        bytes: 643_854,
+        archive: false,
+    },
+];
+export function modelPath(modelsDir, spec) {
+    return join(modelsDir, spec.name);
+}
+export function missingModels(modelsDir) {
+    return MODELS.filter(spec => !existsSync(modelPath(modelsDir, spec)));
+}
+/**
+ * Download and unpack one model. Writes to a temporary name first, so an
+ * interrupted download never looks installed.
+ */
+export async function fetchModel(modelsDir, spec, onProgress) {
+    mkdirSync(modelsDir, { recursive: true });
+    const response = await fetch(spec.url);
+    if (!response.ok || response.body === null)
+        throw new Error(`下载失败 ${spec.url}（HTTP ${response.status}）`);
+    const total = Number(response.headers.get('content-length') ?? spec.bytes);
+    const partial = join(modelsDir, `${spec.name}.download`);
+    let received = 0;
+    const body = Readable.fromWeb(response.body);
+    body.on('data', (chunk) => {
+        received += chunk.byteLength;
+        onProgress?.(received, total);
+    });
+    await pipeline(body, createWriteStream(partial));
+    if (!spec.archive) {
+        renameSync(partial, modelPath(modelsDir, spec));
+        return;
+    }
+    const staging = join(modelsDir, `${spec.name}.unpack`);
+    rmSync(staging, { recursive: true, force: true });
+    mkdirSync(staging, { recursive: true });
+    try {
+        // bsdtar ships with macOS and Windows 10+, and reads bzip2 itself.
+        await promisify(execFile)('tar', ['-xjf', partial, '-C', staging]);
+        renameSync(join(staging, spec.name), modelPath(modelsDir, spec));
+    }
+    finally {
+        rmSync(staging, { recursive: true, force: true });
+        rmSync(partial, { force: true });
+    }
+}

package/lib/voice/speech-queue.js

@@ -0,0 +1,118 @@
+/**
+ * Turns her replies into audio sentence by sentence, in order.
+ *
+ * The next few sentences are synthesized at once (AHEAD), so while one plays
+ * the following ones are already on their way; a slow voice service only
+ * makes the first sentence of a reply wait. Sentences are started and
+ * emitted strictly in order, across replies, so the first sentence of a reply
+ * is never queued behind a later one. Each result is emitted as soon as it
+ * and everything before it are ready (the body queues playback), and a reply's
+ * end is emitted after its last sentence. Cancelling a reply drops what has
+ * not been emitted yet; synthesis already running for it is thrown away.
+ *
+ * A sentence whose synthesis fails is still emitted, without audio, so the
+ * subtitle shows and the reply goes on.
+ */
+/** Sentences being synthesized at the same time, counted from the next to emit. */
+const AHEAD = 3;
+export class SpeechQueue {
+    jobs = [];
+    running = false;
+    cancelled = new Set();
+    sent = new Map();
+    synth;
+    out;
+    constructor(synth, out) {
+        this.synth = synth;
+        this.out = out;
+    }
+    say(uid, seq, text, cues = []) {
+        if (this.cancelled.has(uid))
+            return;
+        this.jobs.push({ uid, kind: 'sentence', seq, text, cues });
+        this.startAhead();
+        void this.pump();
+    }
+    end(uid) {
+        if (this.cancelled.has(uid))
+            return;
+        this.jobs.push({ uid, kind: 'end' });
+        void this.pump();
+    }
+    cancel(uid) {
+        this.cancelled.add(uid);
+        for (let i = this.jobs.length - 1; i >= 0; i--)
+            if (this.jobs[i].uid === uid)
+                this.jobs.splice(i, 1);
+        // Remember only recent cancellations.
+        if (this.cancelled.size > 32)
+            this.cancelled.delete(this.cancelled.values().next().value);
+    }
+    /** Sentences of a reply that went out, in order. */
+    sentOf(uid) {
+        return this.sent.get(uid) ?? [];
+    }
+    /** Resolves when nothing is queued or being synthesized. */
+    async idle() {
+        while (this.running || this.jobs.length > 0)
+            await new Promise(resolve => setTimeout(resolve, 5));
+    }
+    /** Start synthesizing the first AHEAD sentences still to emit. */
+    startAhead() {
+        let sentences = 0;
+        for (const job of this.jobs) {
+            if (job.kind !== 'sentence')
+                continue;
+            if (++sentences > AHEAD)
+                break;
+            job.audio ??= this.synth(job.text).catch(() => undefined);
+        }
+    }
+    async pump() {
+        if (this.running)
+            return;
+        this.running = true;
+        try {
+            for (let job = this.jobs[0]; job !== undefined; job = this.jobs[0]) {
+                if (job.kind === 'end') {
+                    this.jobs.shift();
+                    this.out.end(job.uid);
+                    continue;
+                }
+                this.startAhead();
+                const audio = await job.audio;
+                // Cancelled while it was synthesized: cancel() already took it out.
+                if (this.jobs[0] !== job)
+                    continue;
+                this.jobs.shift();
+                this.startAhead();
+                const record = this.sent.get(job.uid) ?? [];
+                record.push({ seq: job.seq, text: job.text, durationMs: audio?.durationMs ?? 0 });
+                this.sent.set(job.uid, record);
+                if (this.sent.size > 16)
+                    this.sent.delete(this.sent.keys().next().value);
+                this.out.sentence(job.uid, job.seq, job.text, audio, job.cues);
+            }
+        }
+        finally {
+            this.running = false;
+        }
+    }
+}
+/**
+ * How much of a reply was heard when it was cut off: every sentence before
+ * the one playing, plus the share of that one its played time covers.
+ */
+export function heardText(sent, seq, playedMs) {
+    let heard = '';
+    for (const sentence of sent) {
+        if (sentence.seq < seq)
+            heard += sentence.text;
+        else if (sentence.seq === seq) {
+            const chars = [...sentence.text];
+            const share = sentence.durationMs > 0 ? Math.min(1, Math.max(0, playedMs / sentence.durationMs)) : 0;
+            heard += chars.slice(0, Math.round(chars.length * share)).join('');
+        }
+    }
+    return heard;
+}

package/lib/voice/voice.js

@@ -0,0 +1,171 @@
+/**
+ * Her voice for the brain.
+ *
+ * - Listening: local speech recognition (sherpa-onnx SenseVoice in a child
+ *   process, engine.ts). Its model is downloaded in the background on first
+ *   use; until then she only reads what you type.
+ * - Speaking: the service of the voice she uses (core/voices.ts): Microsoft
+ *   Edge voices through the edge-tts tool (edge.ts, the default), or Alibaba
+ *   Cloud Model Studio CosyVoice (cosyvoice.ts). When the service cannot
+ *   speak (tool not installed yet, no key, no quota, offline), a sentence goes
+ *   out without audio and shows as text; a key added later is picked up
+ *   without restarting.
+ * - Cache: short sentences ("嗯。" "好呀。") are kept, so the most common
+ *   answers start at once.
+ */
+import { serviceOf, VOICE_MODEL } from "../core/index.js";
+import { LocalVoice } from "./engine.js";
+import { CloudAccountError, CosyVoice } from "./cosyvoice.js";
+import { EdgeVoice } from "./edge.js";
+import { readCloudKey } from "./cloud-key.js";
+import { fetchModel, missingModels, modelPath, MODELS } from "./models.js";
+const CACHE_MAX_CHARS = 8;
+const CACHE_ENTRIES = 64;
+/** After "no key" or "no quota", try the cloud again at most this often (a key added later is picked up). */
+const KEY_RECHECK_MS = 30_000;
+export class Voice {
+    asr;
+    listening = 'loading';
+    speakingState;
+    speakingError;
+    keyCheckedAt = 0;
+    cloud;
+    edge;
+    cache = new Map();
+    modelsDir;
+    config;
+    logger;
+    /** `edgeDir`: where dsh-her installs its own edge-tts if none is found. */
+    constructor(modelsDir, edgeDir, config, logger) {
+        this.modelsDir = modelsDir;
+        this.config = config;
+        this.logger = logger;
+        this.speakingState = config.enabled ? 'checking' : 'off';
+        this.cloud = new CosyVoice(VOICE_MODEL, readCloudKey);
+        this.edge = new EdgeVoice(edgeDir);
+    }
+    /** Listening. */
+    get status() {
+        return this.listening;
+    }
+    get speaking() {
+        const service = serviceOf(this.config.voice);
+        return this.speakingError === undefined ? { status: this.speakingState, service } : { status: this.speakingState, service, error: this.speakingError };
+    }
+    /** Check the cloud voice and get recognition ready. Never throws; the statuses say how it went. */
+    async start() {
+        if (this.config.enabled)
+            void this.speak('嗯。').catch(() => undefined);
+        try {
+            const missing = missingModels(this.modelsDir);
+            if (missing.length > 0) {
+                this.listening = 'downloading';
+                this.logger.info(`dsh-her: downloading speech recognition models (${missing.map(m => m.id).join(', ')}) into ${this.modelsDir}`);
+                for (const spec of missing)
+                    await fetchModel(this.modelsDir, spec);
+            }
+            this.listening = 'loading';
+            this.asr = new LocalVoice({ asrDir: modelPath(this.modelsDir, MODELS.find(m => m.id === 'asr')), threads: this.config.threads });
+            const { loadMs } = await this.asr.start();
+            this.listening = 'ready';
+            this.logger.info(`dsh-her: speech recognition ready (${loadMs} ms)`);
+        }
+        catch (error) {
+            this.listening = 'failed';
+            this.logger.warn(`dsh-her: speech recognition unavailable, typing only (${error.message})`);
+        }
+    }
+    /** You started talking: open the cloud connection now, while your words are recognized. */
+    warm() {
+        if (serviceOf(this.config.voice) === 'cosyvoice' && (this.speakingState === 'ready' || this.speakingState === 'failed'))
+            this.cloud.warm();
+    }
+    /** Change her voice and speed (from the "她" page); takes effect with the next sentence. */
+    setVoice(voice, speed) {
+        const switched = serviceOf(voice) !== serviceOf(this.config.voice);
+        this.config = { ...this.config, voice, speed };
+        if (switched && this.config.enabled) {
+            // A new service: what was true of the old one (no key …) says nothing about it.
+            this.mark('checking');
+            void this.speak('嗯。').catch(() => undefined);
+        }
+    }
+    /** One sentence in a given voice, for trying voices; not cached. Throws with a message for the page. */
+    async preview(text, voice, speed) {
+        if (!this.config.enabled)
+            throw new Error('她的声音已关闭（插件设置里 voice.enabled 是 false）');
+        return this.speak(text, voice, speed);
+    }
+    /** Her sentence as audio, or undefined when she cannot speak right now (it shows as text). */
+    async synthesize(text) {
+        if (!this.config.enabled || text === '')
+            return undefined;
+        if ((this.speakingState === 'no-key' || this.speakingState === 'no-quota') && Date.now() - this.keyCheckedAt < KEY_RECHECK_MS)
+            return undefined;
+        const key = `${this.config.voice}|${this.config.speed}|${text}`;
+        const cached = this.cache.get(key);
+        if (cached !== undefined)
+            return cached;
+        try {
+            const result = await this.speak(text);
+            if ([...text].length <= CACHE_MAX_CHARS) {
+                this.cache.set(key, result);
+                if (this.cache.size > CACHE_ENTRIES)
+                    this.cache.delete(this.cache.keys().next().value);
+            }
+            return result;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** What you said, from 16-bit mono PCM. Empty when nothing was understood. */
+    async recognize(pcm16, sampleRate) {
+        if (this.listening !== 'ready' || this.asr === undefined)
+            throw new Error('语音识别还没准备好');
+        const view = new DataView(pcm16.buffer, pcm16.byteOffset, pcm16.byteLength);
+        const samples = new Float32Array(Math.floor(pcm16.byteLength / 2));
+        for (let i = 0; i < samples.length; i++)
+            samples[i] = view.getInt16(i * 2, true) / 0x8000;
+        const heard = await this.asr.recognize(samples, sampleRate);
+        return { text: heard.text, ms: heard.ms };
+    }
+    stop() {
+        this.asr?.stop();
+        this.asr = undefined;
+        this.cloud.close();
+        if (this.listening !== 'off')
+            this.listening = 'failed';
+    }
+    async speak(text, voice = this.config.voice, speed = this.config.speed) {
+        try {
+            if (serviceOf(voice) === 'edge') {
+                if (this.edge.status.status !== 'ready')
+                    this.mark('installing');
+                const audio = await this.edge.synthesize(text, voice, speed);
+                this.mark('ready');
+                return { audio: audio.audio, durationMs: audio.durationMs, format: 'mp3' };
+            }
+            const audio = await this.cloud.synthesize(text, voice, speed);
+            this.mark('ready');
+            return { audio: audio.audio, durationMs: audio.durationMs, format: 'wav' };
+        }
+        catch (error) {
+            this.mark(error instanceof CloudAccountError ? (error.reason === 'quota' ? 'no-quota' : 'no-key') : 'failed', error.message);
+            throw error;
+        }
+    }
+    mark(status, error) {
+        if (status === 'no-key' || status === 'no-quota')
+            this.keyCheckedAt = Date.now();
+        if (status !== this.speakingState) {
+            const service = serviceOf(this.config.voice);
+            if (status === 'ready')
+                this.logger.info(`dsh-her: voice ready (${service})`);
+            else if (status !== 'checking' && status !== 'installing')
+                this.logger.warn(`dsh-her: voice ${status} (${service})${error === undefined ? '' : `: ${error}`}; replies show as text`);
+        }
+        this.speakingState = status;
+        this.speakingError = error;
+    }
+}