@kongyo2/kongyoroid 1.0.0 → 2.1.0

package/dist/kongyoroid.js

@@ -1,29 +1,107 @@
 import { createHash } from "node:crypto";
 import { performance } from "node:perf_hooks";
+import process from "node:process";
 import { DiskCache, LayeredCache, MemoryCache, cacheKey } from "./cache.js";
 import { Semaphore } from "./concurrency.js";
-import { KongyoroidError, asKongyoroidError, checkAbort } from "./errors.js";
-import { formatKanaNotation, parseKanaNotation } from "./notation.js";
-import { renderFormant } from "./formant.js";
+import { KongyoroidError, asKongyoroidError, checkAbort, invalid } from "./errors.js";
 import { DEFAULT_SAMPLE_RATE, LIMITS } from "./limits.js";
-import { parseRequest, parseStyleRef } from "./request.js";
-import { integer, isObject } from "./validate.js";
-import { VERSION } from "./version.js";
+import { parseEngine, parseRequest, parseStyleRef, requestHash } from "./request.js";
+import { compileRequest, readForRequest, summarizePlan } from "./synth/engine.js";
+import { encodePlanAsync, renderPcmStream } from "./synth/stream.js";
+import { synthesizeTextStream } from "./synth/textstream.js";
+import { BUILTIN_VOICES, describeVoice, resolveVoice, voiceProfileHash } from "./synth/voice.js";
+import { estimatePitch, signalStats } from "./synth/analysis.js";
+import { LocalDictionary, dictionaryFromJson } from "./text/dictionary.js";
+import { frontendState, loadFrontend } from "./text/frontend.js";
+import { formatKanaNotation, parseKanaNotation } from "./text/notation.js";
+import { integer, isObject, literal } from "./validate.js";
+import { ENGINE_VERSION, FRONTEND_VERSION, PACKAGE_NAME, PLAN_VERSION, VERSION } from "./version.js";
 import { VoicevoxClient } from "./voicevox/client.js";
 import { Dictionary } from "./voicevox/dictionary.js";
 import { accentPhrasesToKana, synthesizeSpeech } from "./voicevox/speech.js";
 import { synthesizeSong } from "./voicevox/song.js";
 import { StyleCatalog } from "./voicevox/styles.js";
-import { audioInfo, inspectWav } from "./wav.js";
+import { audioInfo, decodeWav, inspectWav } from "./wav.js";
 const PROBE_RETRY_MS = 30_000;
+const PACK_VERSION = 2;
 function packRender(entry) {
-    const meta = new TextEncoder().encode(JSON.stringify({ kana: entry.kana ?? null, chunks: entry.chunks }));
+    const meta = new TextEncoder().encode(JSON.stringify({
+        v: PACK_VERSION,
+        kana: entry.kana ?? null,
+        chunks: entry.chunks,
+        warnings: entry.warnings,
+        adjustments: entry.adjustments,
+        stats: entry.stats ?? null,
+        voice: entry.voice ?? null,
+    }));
     const out = new Uint8Array(4 + meta.length + entry.audio.length);
     new DataView(out.buffer).setUint32(0, meta.length, true);
     out.set(meta, 4);
     out.set(entry.audio, 4 + meta.length);
     return out;
 }
+function statsFrom(value) {
+    if (!isObject(value))
+        return undefined;
+    const peak = value["peak"];
+    const rms = value["rms"];
+    const limitedSamples = value["limitedSamples"];
+    const frames = value["frames"];
+    if (typeof peak !== "number" ||
+        typeof rms !== "number" ||
+        typeof limitedSamples !== "number" ||
+        typeof frames !== "number") {
+        return undefined;
+    }
+    return { peak, rms, limitedSamples, frames };
+}
+function diagnosticsFrom(value) {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const item of value) {
+        if (!isObject(item))
+            continue;
+        const severity = item["severity"];
+        const code = item["code"];
+        const message = item["message"];
+        if (severity !== "error" && severity !== "warning" && severity !== "advice")
+            continue;
+        if (typeof code !== "string" || typeof message !== "string")
+            continue;
+        const sourceSpan = item["sourceSpan"];
+        out.push({
+            severity,
+            code,
+            message,
+            ...(typeof item["path"] === "string" ? { path: item["path"] } : {}),
+            ...(typeof item["help"] === "string" ? { help: item["help"] } : {}),
+            ...(typeof item["surface"] === "string" ? { surface: item["surface"] } : {}),
+            ...(isObject(sourceSpan) &&
+                typeof sourceSpan["start"] === "number" &&
+                typeof sourceSpan["end"] === "number" &&
+                sourceSpan["unit"] === "unicode-code-point"
+                ? { sourceSpan: { start: sourceSpan["start"], end: sourceSpan["end"], unit: "unicode-code-point" } }
+                : {}),
+            ...(item["detail"] === undefined ? {} : { detail: item["detail"] }),
+        });
+    }
+    return out;
+}
+function adjustmentsFrom(value) {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const item of value) {
+        if (!isObject(item))
+            continue;
+        const code = item["code"];
+        const message = item["message"];
+        if (typeof code === "string" && typeof message === "string")
+            out.push({ ...item, code, message });
+    }
+    return out;
+}
 function unpackRender(bytes) {
     if (bytes.length < 4)
         return undefined;
@@ -32,7 +110,7 @@ function unpackRender(bytes) {
         return undefined;
     try {
         const meta = JSON.parse(new TextDecoder().decode(bytes.subarray(4, 4 + length)));
-        if (!isObject(meta))
+        if (!isObject(meta) || meta["v"] !== PACK_VERSION)
             return undefined;
         const audio = bytes.slice(4 + length);
         inspectWav(audio);
@@ -40,58 +118,156 @@ function unpackRender(bytes) {
             audio,
             kana: typeof meta["kana"] === "string" ? meta["kana"] : undefined,
             chunks: typeof meta["chunks"] === "number" ? meta["chunks"] : 1,
+            warnings: diagnosticsFrom(meta["warnings"]),
+            adjustments: adjustmentsFrom(meta["adjustments"]),
+            stats: statsFrom(meta["stats"]),
+            voice: typeof meta["voice"] === "string" ? meta["voice"] : undefined,
         };
     }
     catch {
         return undefined;
     }
 }
+function round(value, digits = 2) {
+    const factor = 10 ** digits;
+    return Math.round(value * factor) / factor;
+}
 export class Kongyoroid {
-    client;
-    styles;
     dictionary;
+    clientInstance;
+    stylesInstance;
+    voicevoxDictionaryInstance;
+    voicevoxOptions;
     defaults;
     semaphore;
     cache;
+    cacheStrict;
+    diskCache;
     concurrency;
     probeTimeoutMs;
+    inFlight = new Map();
     probe;
     constructor(options = {}) {
-        this.client = new VoicevoxClient(options);
-        this.styles = new StyleCatalog(this.client);
-        this.dictionary = new Dictionary(this.client);
+        const voicevox = {
+            ...(options.endpoint === undefined ? {} : { endpoint: options.endpoint }),
+            ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+            ...(options.retries === undefined ? {} : { retries: options.retries }),
+            ...(options.maxResponseBytes === undefined ? {} : { maxResponseBytes: options.maxResponseBytes }),
+            ...(options.fetch === undefined ? {} : { fetch: options.fetch }),
+            ...(options.headers === undefined ? {} : { headers: options.headers }),
+            ...(options.speaker === undefined ? {} : { speaker: options.speaker }),
+            ...(options.singer === undefined ? {} : { singer: options.singer }),
+            ...(options.teacher === undefined ? {} : { teacher: options.teacher }),
+            ...(options.probeTimeoutMs === undefined ? {} : { probeTimeoutMs: options.probeTimeoutMs }),
+            ...(options.voicevox ?? {}),
+        };
+        this.voicevoxOptions = voicevox;
         this.defaults = {
-            engine: options.engine,
-            speaker: options.speaker === undefined ? undefined : parseStyleRef(options.speaker, "$.speaker"),
-            singer: options.singer === undefined ? undefined : parseStyleRef(options.singer, "$.singer"),
-            teacher: options.teacher === undefined ? undefined : parseStyleRef(options.teacher, "$.teacher"),
+            engine: options.engine ?? "formant",
+            voice: options.voice === undefined ? undefined : resolveVoice(options.voice, "$.voice").id,
+            speaker: voicevox.speaker === undefined ? undefined : parseStyleRef(voicevox.speaker, "$.speaker"),
+            singer: voicevox.singer === undefined ? undefined : parseStyleRef(voicevox.singer, "$.singer"),
+            teacher: voicevox.teacher === undefined ? undefined : parseStyleRef(voicevox.teacher, "$.teacher"),
+            strictReading: options.strictReading,
         };
+        if (options.engine !== undefined)
+            parseEngine(options.engine, "$.engine");
+        this.dictionary =
+            options.dictionary === undefined
+                ? new LocalDictionary()
+                : options.dictionary instanceof LocalDictionary
+                    ? options.dictionary
+                    : dictionaryFromJson(options.dictionary, "$.dictionary");
         this.concurrency = integer(options.concurrency ?? 2, "$.concurrency", 1, LIMITS.concurrency);
         this.semaphore = new Semaphore(this.concurrency);
-        const memory = new MemoryCache(options.cacheBytes ?? 64 * 1024 * 1024);
-        this.cache = options.cacheDir === undefined ? memory : new LayeredCache([memory, new DiskCache(options.cacheDir)]);
-        this.probeTimeoutMs = integer(options.probeTimeoutMs ?? 3000, "$.probeTimeoutMs", 100, 600_000);
+        const cacheOptions = {
+            ...(options.cacheDir === undefined ? {} : { directory: options.cacheDir }),
+            ...(options.cacheBytes === undefined ? {} : { memoryBytes: options.cacheBytes }),
+            ...(options.cache ?? {}),
+        };
+        this.cacheStrict = cacheOptions.strict ?? false;
+        if (cacheOptions.enabled === false) {
+            this.cache = undefined;
+            this.diskCache = undefined;
+        }
+        else {
+            const memory = new MemoryCache(cacheOptions.memoryBytes ?? 64 * 1024 * 1024);
+            if (cacheOptions.directory === undefined) {
+                this.cache = memory;
+                this.diskCache = undefined;
+            }
+            else {
+                this.diskCache = new DiskCache(cacheOptions.directory, {
+                    ...(cacheOptions.maxBytes === undefined ? {} : { maxBytes: cacheOptions.maxBytes }),
+                    ...(cacheOptions.maxEntries === undefined ? {} : { maxEntries: cacheOptions.maxEntries }),
+                });
+                this.cache = new LayeredCache([memory, this.diskCache]);
+            }
+        }
+        this.probeTimeoutMs = integer(voicevox.probeTimeoutMs ?? 3000, "$.probeTimeoutMs", 100, 600_000);
+    }
+    get client() {
+        this.clientInstance ??= new VoicevoxClient(this.voicevoxOptions);
+        return this.clientInstance;
+    }
+    get styles() {
+        this.stylesInstance ??= new StyleCatalog(this.client);
+        return this.stylesInstance;
+    }
+    get voicevoxDictionary() {
+        this.voicevoxDictionaryInstance ??= new Dictionary(this.client);
+        return this.voicevoxDictionaryInstance;
+    }
+    get defaultEngine() {
+        return this.defaults.engine;
+    }
+    get voices$() {
+        return BUILTIN_VOICES;
     }
-    clearCache() {
-        return this.cache.clear();
+    async clearCache() {
+        return this.cache === undefined ? 0 : this.cache.clear();
+    }
+    async cacheStats() {
+        return this.cache === undefined ? null : this.cache.stats();
+    }
+    async pruneCache(maxBytes, maxEntries) {
+        return this.diskCache === undefined ? 0 : this.diskCache.prune(maxBytes, maxEntries);
     }
     withDefaults(request) {
         if (!isObject(request))
             return request;
         const merged = { ...request };
-        if (merged["engine"] === undefined && this.defaults.engine !== undefined)
+        const hasStyle = merged["speaker"] !== undefined || merged["singer"] !== undefined || merged["teacher"] !== undefined;
+        if (merged["engine"] === undefined && (this.defaults.engine !== "formant" || !hasStyle))
             merged["engine"] = this.defaults.engine;
-        if (merged["kind"] === "speech" && merged["speaker"] === undefined && this.defaults.speaker !== undefined) {
+        if (merged["voice"] === undefined && this.defaults.voice !== undefined)
+            merged["voice"] = this.defaults.voice;
+        if (merged["strictReading"] === undefined && this.defaults.strictReading !== undefined)
+            merged["strictReading"] = this.defaults.strictReading;
+        const engine = merged["engine"];
+        const wantsVoicevox = engine === "voicevox" || engine === "auto" || hasStyle;
+        if (wantsVoicevox &&
+            merged["kind"] === "speech" &&
+            merged["speaker"] === undefined &&
+            this.defaults.speaker !== undefined) {
             merged["speaker"] = this.defaults.speaker;
         }
-        if (merged["kind"] === "song") {
+        if (wantsVoicevox && merged["kind"] === "song") {
             if (merged["singer"] === undefined && this.defaults.singer !== undefined)
                 merged["singer"] = this.defaults.singer;
             if (merged["teacher"] === undefined && this.defaults.teacher !== undefined)
                 merged["teacher"] = this.defaults.teacher;
         }
+        if (merged["engine"] === "formant" && hasStyle) {
+            if (this.defaults.engine === "formant" && isObject(request) && request["engine"] === undefined)
+                delete merged["engine"];
+        }
         return merged;
     }
+    parse(request) {
+        const resolved = parseRequest(this.withDefaults(request));
+        return { request: resolved, requestHash: requestHash({ ...resolved, dictionaryDigest: this.dictionary.digest() }) };
+    }
     resolveEngine(selector, options = {}) {
         if (selector !== "auto")
             return Promise.resolve(selector);
@@ -121,7 +297,7 @@ export class Kongyoroid {
         try {
             const words = await this.client.dictionary(options);
             const rows = words
-                .map((word) => [word.uuid, word.surface, word.pronunciation, word.accentType, word.priority].join("\u0000"))
+                .map((word) => [word.uuid, word.surface, word.pronunciation, word.accentType, word.priority].join(""))
                 .sort();
             return createHash("sha256").update(rows.join("\n")).digest("hex");
         }
@@ -143,56 +319,301 @@ export class Kongyoroid {
                 : await this.styles.resolve(undefined, "teacher", options);
         return { singer, teacher };
     }
+    compileOptions(options) {
+        return {
+            ...(options.signal === undefined ? {} : { signal: options.signal }),
+            dictionary: this.dictionary,
+        };
+    }
+    async compile(request, options = {}) {
+        const parsed = this.parse(request);
+        const engine = await this.resolveEngine(parsed.request.engine, options);
+        if (engine !== "formant") {
+            invalid("$.engine", "Plans can only be compiled for the formant engine.", {
+                hint: 'Set engine to "formant" (or omit the VOICEVOX style) to inspect the plan.',
+                repairOptions: [{ action: "use-formant-engine", description: "Use the built-in engine for plan inspection." }],
+            });
+        }
+        const sampleRate = parsed.request.sampleRate ?? DEFAULT_SAMPLE_RATE;
+        const compiled = await compileRequest(parsed.request, sampleRate, this.compileOptions(options));
+        return { ...compiled, request: parsed.request, requestHash: parsed.requestHash, engine: "formant" };
+    }
+    async validate(request, options = {}) {
+        const parsed = this.parse(request);
+        const resolved = parsed.request;
+        const engine = resolved.engine === "auto" ? "auto" : resolved.engine;
+        if (engine !== "formant") {
+            return {
+                ok: true,
+                operation: "validate",
+                engine,
+                kind: resolved.kind,
+                renderable: "unknown",
+                estimate: null,
+                voice: undefined,
+                reading: null,
+                notes: resolved.kind === "song" ? resolved.notes.length : null,
+                warnings: [
+                    {
+                        severity: "advice",
+                        code: "EXTERNAL_ENGINE_NOT_PROBED",
+                        message: "The request targets VOICEVOX; structure was validated but the engine was not contacted.",
+                        help: "Run doctor --engine voicevox to check the endpoint.",
+                    },
+                ],
+                adjustments: [],
+                requestHash: parsed.requestHash,
+                planHash: null,
+                request: resolved,
+            };
+        }
+        const sampleRate = resolved.sampleRate ?? DEFAULT_SAMPLE_RATE;
+        const compiled = await compileRequest(resolved, sampleRate, this.compileOptions(options));
+        const plan = compiled.plan;
+        return {
+            ok: true,
+            operation: "validate",
+            engine: "formant",
+            kind: resolved.kind,
+            renderable: true,
+            estimate: {
+                durationSeconds: round(plan.frames / sampleRate, 3),
+                frames: plan.frames,
+                wavBytes: 44 + plan.frames * 2,
+                sampleRate,
+            },
+            voice: plan.voice.id,
+            reading: plan.reading === null
+                ? null
+                : { kana: plan.reading.kana, frontend: plan.reading.frontend, moraCount: plan.reading.moraCount },
+            notes: resolved.kind === "song" ? resolved.notes.length : null,
+            warnings: plan.warnings,
+            adjustments: plan.adjustments,
+            requestHash: parsed.requestHash,
+            planHash: compiled.planHash,
+            request: resolved,
+        };
+    }
+    async plan(request, options = {}) {
+        const resolved = typeof options === "string" ? { detail: options } : options;
+        const detail = literal(resolved.detail ?? "summary", "$.detail", ["summary", "phonemes", "acoustics"]);
+        const compiled = await this.compile(request, resolved);
+        return {
+            ok: true,
+            operation: "plan",
+            engine: "formant",
+            requestHash: compiled.requestHash,
+            plan: summarizePlan(compiled.plan, compiled.planHash, detail),
+            request: compiled.request,
+        };
+    }
+    async renderPlan(plan, options = {}) {
+        const start = performance.now();
+        checkAbort(options.signal);
+        const encoded = await encodePlanAsync(plan, options);
+        const renderMs = performance.now() - start;
+        return this.formantResult({
+            audio: encoded.audio,
+            kana: plan.reading?.kana,
+            chunks: 1,
+            warnings: plan.warnings,
+            adjustments: plan.adjustments,
+            stats: encoded.stats,
+            voice: plan.voice.id,
+        }, plan.kind, false, options.requestHash ?? "", {
+            readMs: options.readMs ?? 0,
+            planMs: options.planMs ?? 0,
+            renderMs,
+            encodeMs: 0,
+            totalMs: (options.readMs ?? 0) + (options.planMs ?? 0) + renderMs,
+        });
+    }
+    formantResult(entry, kind, cached, hash, timings) {
+        return {
+            audio: entry.audio,
+            info: audioInfo(inspectWav(entry.audio)),
+            engine: "formant",
+            kind,
+            voice: entry.voice,
+            styles: {},
+            kana: entry.kana,
+            chunks: entry.chunks,
+            cached,
+            sha256: createHash("sha256").update(entry.audio).digest("hex"),
+            requestHash: hash,
+            elapsedMs: round(timings.totalMs),
+            timings: {
+                readMs: round(timings.readMs),
+                planMs: round(timings.planMs),
+                renderMs: round(timings.renderMs),
+                encodeMs: round(timings.encodeMs),
+                totalMs: round(timings.totalMs),
+            },
+            warnings: entry.warnings,
+            adjustments: entry.adjustments,
+            peak: entry.stats === undefined ? undefined : round(entry.stats.peak, 4),
+            rms: entry.stats === undefined ? undefined : round(entry.stats.rms, 4),
+            limitedSamples: entry.stats?.limitedSamples,
+            engineVersion: ENGINE_VERSION,
+        };
+    }
+    async cacheGet(key, warnings) {
+        if (this.cache === undefined)
+            return undefined;
+        try {
+            const bytes = await this.cache.get(key);
+            return bytes === undefined ? undefined : unpackRender(bytes);
+        }
+        catch (error) {
+            if (this.cacheStrict)
+                throw asKongyoroidError(error);
+            warnings.push({
+                severity: "warning",
+                code: "CACHE_READ_FAILED",
+                message: `The render cache could not be read: ${error instanceof Error ? error.message : String(error)}`,
+            });
+            return undefined;
+        }
+    }
+    async cacheSet(key, entry, warnings) {
+        if (this.cache === undefined)
+            return;
+        try {
+            await this.cache.set(key, packRender(entry));
+        }
+        catch (error) {
+            if (this.cacheStrict)
+                throw asKongyoroidError(error);
+            warnings.push({
+                severity: "warning",
+                code: "CACHE_WRITE_FAILED",
+                message: `The render was produced but could not be cached: ${error instanceof Error ? error.message : String(error)}`,
+            });
+        }
+    }
     async render(request, options = {}) {
         const start = performance.now();
         checkAbort(options.signal);
-        const resolved = parseRequest(this.withDefaults(request));
+        const parsed = this.parse(request);
+        const resolved = parsed.request;
         const engine = await this.resolveEngine(resolved.engine, options);
+        const cacheWarnings = [];
         const styles = engine === "voicevox" ? await this.resolveStyles(resolved, options) : {};
         const manifest = engine === "voicevox" ? await this.client.manifest(options) : undefined;
-        const dictionary = engine === "voicevox" && resolved.kind === "speech" ? await this.dictionaryDigest(options) : "";
+        const dictionary = engine === "voicevox" && resolved.kind === "speech"
+            ? await this.dictionaryDigest(options)
+            : this.dictionary.digest();
         const key = dictionary === undefined
             ? undefined
-            : cacheKey(engine, VERSION, engine === "voicevox" ? [this.client.endpoint.origin, manifest?.version ?? "", styles, dictionary] : [], resolved);
-        const cached = key === undefined ? undefined : unpackRender((await this.cache.get(key)) ?? new Uint8Array(0));
-        const entry = cached ??
-            (await this.semaphore.run(async () => {
-                checkAbort(options.signal);
-                if (engine === "formant") {
-                    const audio = await renderFormant(resolved, resolved.sampleRate ?? DEFAULT_SAMPLE_RATE, options);
-                    return { audio, kana: resolved.kind === "speech" ? resolved.kana : undefined, chunks: 1 };
-                }
-                if (resolved.kind === "speech") {
-                    const speaker = styles.speaker;
-                    if (speaker === undefined)
-                        throw asKongyoroidError(new Error("speaker was not resolved"));
-                    const result = await synthesizeSpeech(this.client, resolved, speaker, {
-                        ...options,
-                        concurrency: this.concurrency,
-                    });
-                    return { audio: result.audio, kana: result.kana, chunks: result.chunks };
-                }
-                const singer = styles.singer;
-                const teacher = styles.teacher;
-                if (singer === undefined || teacher === undefined) {
-                    throw asKongyoroidError(new Error("singer was not resolved"));
+            : cacheKey(engine, VERSION, engine === "voicevox"
+                ? [this.client.endpoint.href, manifest?.version ?? "", styles, dictionary]
+                : [ENGINE_VERSION, FRONTEND_VERSION, PLAN_VERSION, dictionary], resolved);
+        const cached = key === undefined ? undefined : await this.cacheGet(key, cacheWarnings);
+        checkAbort(options.signal);
+        let timings = { readMs: 0, planMs: 0, renderMs: 0, encodeMs: 0, totalMs: 0 };
+        let entry;
+        if (cached !== undefined) {
+            entry = cached;
+        }
+        else {
+            const shared = key === undefined ? undefined : this.inFlight.get(key);
+            if (shared !== undefined) {
+                entry = await shared;
+            }
+            else {
+                const job = this.semaphore.run(async () => {
+                    checkAbort(options.signal);
+                    if (engine === "formant") {
+                        const sampleRate = resolved.sampleRate ?? DEFAULT_SAMPLE_RATE;
+                        const compiled = await compileRequest(resolved, sampleRate, this.compileOptions(options));
+                        const renderStart = performance.now();
+                        const encoded = await encodePlanAsync(compiled.plan, options.signal === undefined ? {} : { signal: options.signal });
+                        const renderMs = performance.now() - renderStart;
+                        timings = { readMs: compiled.readMs, planMs: compiled.planMs, renderMs, encodeMs: 0, totalMs: 0 };
+                        return {
+                            audio: encoded.audio,
+                            kana: compiled.plan.reading?.kana,
+                            chunks: compiled.plan.reading?.sentences.length ?? 1,
+                            warnings: compiled.plan.warnings,
+                            adjustments: compiled.plan.adjustments,
+                            stats: encoded.stats,
+                            voice: compiled.plan.voice.id,
+                        };
+                    }
+                    if (resolved.kind === "speech") {
+                        const speaker = styles.speaker;
+                        if (speaker === undefined)
+                            throw asKongyoroidError(new Error("speaker was not resolved"));
+                        const result = await synthesizeSpeech(this.client, resolved, speaker, {
+                            ...options,
+                            concurrency: this.concurrency,
+                        });
+                        return {
+                            audio: result.audio,
+                            kana: result.kana,
+                            chunks: result.chunks,
+                            warnings: [],
+                            adjustments: [],
+                            stats: undefined,
+                            voice: undefined,
+                        };
+                    }
+                    const singer = styles.singer;
+                    const teacher = styles.teacher;
+                    if (singer === undefined || teacher === undefined)
+                        throw asKongyoroidError(new Error("singer was not resolved"));
+                    const result = await synthesizeSong(this.client, resolved, singer, teacher, options);
+                    return {
+                        audio: result.audio,
+                        kana: undefined,
+                        chunks: 1,
+                        warnings: [],
+                        adjustments: [],
+                        stats: undefined,
+                        voice: undefined,
+                    };
+                }, options.signal);
+                if (key !== undefined) {
+                    this.inFlight.set(key, job);
+                    job
+                        .finally(() => {
+                        if (this.inFlight.get(key) === job)
+                            this.inFlight.delete(key);
+                    })
+                        .catch(() => undefined);
                 }
-                const result = await synthesizeSong(this.client, resolved, singer, teacher, options);
-                return { audio: result.audio, kana: undefined, chunks: 1 };
-            }, options.signal));
-        if (key !== undefined && cached === undefined)
-            await this.cache.set(key, packRender(entry));
+                entry = await job;
+                if (key !== undefined)
+                    await this.cacheSet(key, entry, cacheWarnings);
+            }
+        }
+        checkAbort(options.signal);
+        const total = performance.now() - start;
+        const finalTimings = { ...timings, totalMs: total };
+        const warnings = cacheWarnings.length === 0 ? entry.warnings : [...entry.warnings, ...cacheWarnings];
+        if (engine === "formant") {
+            return this.formantResult({ ...entry, warnings }, resolved.kind, cached !== undefined, parsed.requestHash, finalTimings);
+        }
         return {
             audio: entry.audio,
             info: audioInfo(inspectWav(entry.audio)),
             engine,
             kind: resolved.kind,
+            voice: undefined,
             styles,
             kana: entry.kana,
             chunks: entry.chunks,
             cached: cached !== undefined,
             sha256: createHash("sha256").update(entry.audio).digest("hex"),
-            elapsedMs: Math.round((performance.now() - start) * 100) / 100,
+            requestHash: parsed.requestHash,
+            elapsedMs: round(total),
+            timings: { readMs: 0, planMs: 0, renderMs: round(total), encodeMs: 0, totalMs: round(total) },
+            warnings,
+            adjustments: [],
+            peak: undefined,
+            rms: undefined,
+            limitedSamples: undefined,
+            engineVersion: manifest?.version ?? "voicevox",
         };
     }
     speak(input, options = {}) {
@@ -201,41 +622,214 @@ export class Kongyoroid {
     sing(input, options = {}) {
         return this.render({ kind: "song", ...input }, options);
     }
+    async *renderStream(request, options = {}) {
+        const compiled = await this.compile(request, options.signal === undefined ? {} : { signal: options.signal });
+        const iterator = renderPcmStream(compiled.plan, options);
+        while (true) {
+            const next = await iterator.next();
+            if (next.done)
+                return { plan: compiled.plan, stats: next.value };
+            yield next.value;
+        }
+    }
+    speakStream(chunks, input = {}, options = {}) {
+        const parsed = this.parse({ ...input, kind: "speech", text: "placeholder" });
+        const request = parsed.request;
+        if (request.kind !== "speech")
+            invalid("$.kind", "Streaming synthesis needs a speech request.");
+        if (request.kana !== undefined) {
+            invalid("$.kana", "Streaming synthesis reads every sentence from the streamed text; kana cannot be given.", {
+                hint: "Drop kana and use a dictionary for readings, or synthesize the whole text at once with kana.",
+            });
+        }
+        if (request.engine === "voicevox") {
+            invalid("$.engine", "Streaming synthesis is only available with the formant engine.", {
+                hint: 'Set engine to "formant" (or "auto", which streams with the built-in engine) and drop the speaker.',
+                repairOptions: [{ action: "use-formant-engine", description: "Use engine formant for streaming." }],
+            });
+        }
+        const resolved = request.engine === "formant" ? request : { ...request, engine: "formant" };
+        return synthesizeTextStream(chunks, resolved, {
+            ...options,
+            dictionary: this.dictionary,
+            sampleRate: options.sampleRate ?? resolved.sampleRate ?? DEFAULT_SAMPLE_RATE,
+        });
+    }
     async reading(text, options = {}) {
-        const speaker = await this.styles.resolve(options.speaker ?? this.defaults.speaker, "speaker", options);
-        const phrases = options.kana === undefined
-            ? (await this.client.audioQuery(text, speaker.id, options)).accent_phrases
-            : await this.client.accentPhrases(formatKanaNotation(parseKanaNotation(options.kana, "$.kana")), speaker.id, true, options);
-        return {
-            kana: accentPhrasesToKana(phrases),
-            speaker,
-            phrases: phrases.map((phrase) => ({
-                text: phrase.moras.map((mora) => mora.text).join(""),
-                accent: phrase.accent,
-                pause: phrase.pause_mora !== null,
-                interrogative: phrase.is_interrogative,
-                moras: phrase.moras.map((mora) => ({
-                    text: mora.text,
-                    consonant: mora.consonant,
-                    vowel: mora.vowel,
-                    consonantLength: mora.consonant_length,
-                    vowelLength: mora.vowel_length,
-                    pitch: mora.pitch,
+        const engine = await this.resolveEngine(options.engine ?? (options.speaker !== undefined ? "voicevox" : this.defaults.engine), options);
+        if (engine === "voicevox") {
+            const speaker = await this.styles.resolve(options.speaker ?? this.defaults.speaker, "speaker", options);
+            const phrases = options.kana === undefined
+                ? (await this.client.audioQuery(text, speaker.id, options)).accent_phrases
+                : await this.client.accentPhrases(formatKanaNotation(parseKanaNotation(options.kana, "$.kana")), speaker.id, true, options);
+            return {
+                engine: "voicevox",
+                frontend: "voicevox",
+                kana: accentPhrasesToKana(phrases),
+                speaker,
+                warnings: [],
+                dictionaryHits: [],
+                sentences: [],
+                phrases: phrases.map((phrase) => ({
+                    text: phrase.moras.map((mora) => mora.text).join(""),
+                    accent: phrase.accent,
+                    accentSource: "frontend",
+                    boundary: phrase.pause_mora !== null ? "pause" : "phrase",
+                    pause: phrase.pause_mora !== null,
+                    interrogative: phrase.is_interrogative,
+                    moras: phrase.moras.map((mora) => ({
+                        text: mora.text,
+                        consonant: mora.consonant,
+                        vowel: mora.vowel,
+                        consonantLength: mora.consonant_length,
+                        vowelLength: mora.vowel_length,
+                        pitch: mora.pitch,
+                    })),
                 })),
-            })),
-        };
+            };
+        }
+        const request = this.parse({
+            kind: "speech",
+            text,
+            ...(options.kana === undefined ? {} : { kana: options.kana }),
+            ...(options.strict === undefined ? {} : { strictReading: options.strict }),
+        }).request;
+        if (request.kind !== "speech")
+            invalid("$.kind", "Reading analysis needs a speech request.");
+        const read = await readForRequest(request, {
+            ...(options.signal === undefined ? {} : { signal: options.signal }),
+            dictionary: options.dictionary === undefined ? this.dictionary : this.dictionary.merge(options.dictionary),
+        });
+        return readingFromPlan(read.reading);
     }
-    async voices(kind = "all", options = {}) {
-        const all = await this.styles.all(options);
-        if (kind === "all")
-            return all;
-        return all.filter((style) => kind === "speech"
-            ? style.type === "talk" || style.type === "streaming_talk"
-            : style.type === "frame_decode" || style.type === "sing" || style.type === "singing_teacher");
+    async voices(options = {}) {
+        const engine = options.engine ?? "all";
+        const kind = options.kind ?? "all";
+        const voices = [];
+        if (engine === "formant" || engine === "all" || engine === "auto") {
+            for (const profile of BUILTIN_VOICES) {
+                const described = describeVoice(profile);
+                voices.push({
+                    id: described.id,
+                    engine: "formant",
+                    name: described.name,
+                    character: null,
+                    description: described.description,
+                    kinds: ["speech", "song"],
+                    styleId: null,
+                    type: null,
+                    baseF0: described.baseF0,
+                    f0Range: described.f0Range,
+                    hash: described.hash,
+                });
+            }
+        }
+        let voicevox = { queried: false, available: false, error: null };
+        if (engine === "voicevox" || engine === "all" || engine === "auto") {
+            try {
+                const all = await this.styles.all(options);
+                const filtered = all.filter((style) => kind === "all"
+                    ? true
+                    : kind === "speech"
+                        ? style.type === "talk" || style.type === "streaming_talk"
+                        : style.type === "frame_decode" || style.type === "sing" || style.type === "singing_teacher");
+                for (const style of filtered)
+                    voices.push(voicevoxDescriptor(style));
+                voicevox = { queried: true, available: true, error: null };
+            }
+            catch (error) {
+                const failure = asKongyoroidError(error);
+                if (failure.code === "ABORTED" || engine === "voicevox")
+                    throw failure;
+                voicevox = { queried: true, available: false, error: failure.toJSON() };
+            }
+        }
+        return { voices, voicevox };
     }
     async doctor(options = {}) {
-        const endpoint = this.client.endpoint.origin;
+        const engine = options.engine ?? this.defaults.engine;
+        const checkVoicevox = engine === "voicevox" || engine === "auto" || engine === "all";
+        const checkFormant = engine === "formant" || engine === "auto" || engine === "all" || options.frontend === true;
+        let frontend = { available: false, version: FRONTEND_VERSION, loadMs: null, error: null };
+        let synthesis = { ok: false, ms: 0, frames: 0, error: null };
+        if (checkFormant) {
+            const started = performance.now();
+            try {
+                await loadFrontend();
+                frontend = {
+                    available: true,
+                    version: FRONTEND_VERSION,
+                    loadMs: round(performance.now() - started),
+                    error: null,
+                };
+            }
+            catch (error) {
+                frontend = {
+                    available: false,
+                    version: FRONTEND_VERSION,
+                    loadMs: round(performance.now() - started),
+                    error: asKongyoroidError(error).toJSON(),
+                };
+            }
+            const synthStart = performance.now();
+            try {
+                const compiled = await this.compile({ kind: "speech", engine: "formant", text: "てすと", kana: "テ'_スト", prePause: 0, postPause: 0 }, options);
+                const encoded = await encodePlanAsync(compiled.plan, options.signal === undefined ? {} : { signal: options.signal });
+                synthesis = {
+                    ok: encoded.audio.length > 44 && encoded.stats.peak > 0.01,
+                    ms: round(performance.now() - synthStart),
+                    frames: compiled.plan.frames,
+                    error: null,
+                };
+            }
+            catch (error) {
+                synthesis = {
+                    ok: false,
+                    ms: round(performance.now() - synthStart),
+                    frames: 0,
+                    error: asKongyoroidError(error).toJSON(),
+                };
+            }
+        }
+        let cache = { directory: this.diskCache?.directory ?? null, stats: null, error: null };
+        if (this.cache !== undefined) {
+            try {
+                cache = { directory: this.diskCache?.directory ?? null, stats: await this.cache.stats(), error: null };
+            }
+            catch (error) {
+                cache = { directory: this.diskCache?.directory ?? null, stats: null, error: asKongyoroidError(error).toJSON() };
+            }
+        }
+        let voicevox = null;
+        if (checkVoicevox)
+            voicevox = await this.voicevoxDoctor(options);
+        const formantOk = !checkFormant || (frontend.available && synthesis.ok);
+        const voicevoxOk = voicevox === null || voicevox.ok;
+        const ok = engine === "auto"
+            ? formantOk
+            : engine === "all"
+                ? formantOk && voicevoxOk
+                : engine === "voicevox"
+                    ? voicevoxOk
+                    : formantOk;
+        return {
+            ok,
+            name: PACKAGE_NAME,
+            version: VERSION,
+            engineVersion: ENGINE_VERSION,
+            node: process.version,
+            defaultEngine: this.defaults.engine,
+            formant: { ok: formantOk, voices: BUILTIN_VOICES.map((voice) => voice.id), frontend, synthesis },
+            cache,
+            dictionary: this.dictionary.size === 0 ? null : { entries: this.dictionary.size, digest: this.dictionary.digest() },
+            voicevox,
+            error: ok ? null : (voicevox?.error ?? frontend.error ?? synthesis.error ?? null),
+        };
+    }
+    async voicevoxDoctor(options = {}) {
+        let endpoint = "";
         try {
+            endpoint = this.client.endpoint.origin;
             const version = await this.client.version(options);
             const manifest = await this.client.manifest(options);
             const devices = await this.client.supportedDevices(options).catch(() => null);
@@ -271,5 +865,111 @@ export class Kongyoroid {
             };
         }
     }
+    inspect(audio, options = {}) {
+        const layout = inspectWav(audio);
+        const decoded = decodeWav(audio);
+        const stats = signalStats(decoded.samples);
+        const window = Math.max(256, Math.round(((options.windowMs ?? 40) / 1000) * layout.sampleRate));
+        const hop = Math.round(window / 2);
+        const track = [];
+        const voiced = [];
+        let windows = 0;
+        for (let start = 0; start + window <= decoded.samples.length; start += hop) {
+            windows += 1;
+            const estimate = estimatePitch(decoded.samples, layout.sampleRate, start, start + window, 50, 1500);
+            const frameStats = signalStats(decoded.samples, start, start + window);
+            const isVoiced = estimate.clarity > 0.7 && frameStats.rms > 0.01;
+            if (isVoiced)
+                voiced.push(estimate.hz);
+            if (options.pitchTrack === true)
+                track.push({
+                    seconds: round(start / layout.sampleRate, 4),
+                    hz: isVoiced ? round(estimate.hz, 1) : 0,
+                    clarity: round(estimate.clarity, 3),
+                });
+        }
+        const sorted = [...voiced].sort((a, b) => a - b);
+        const median = sorted.length === 0 ? null : (sorted[Math.floor(sorted.length / 2)] ?? null);
+        return {
+            info: audioInfo(layout),
+            bytes: audio.byteLength,
+            sha256: createHash("sha256").update(audio).digest("hex"),
+            peak: round(stats.peak, 4),
+            rms: round(stats.rms, 4),
+            dc: round(stats.dc, 5),
+            clipped: stats.clipped,
+            finite: stats.finite,
+            pitch: {
+                medianHz: median === null ? null : round(median, 1),
+                minHz: sorted.length === 0 ? null : round(sorted[0] ?? 0, 1),
+                maxHz: sorted.length === 0 ? null : round(sorted[sorted.length - 1] ?? 0, 1),
+                voicedRatio: windows === 0 ? 0 : round(voiced.length / windows, 3),
+                ...(options.pitchTrack === true ? { track } : {}),
+            },
+        };
+    }
+    frontendStatus() {
+        return frontendState();
+    }
+    voiceProfile(id) {
+        return resolveVoice(id ?? this.defaults.voice, "$.voice");
+    }
+    voiceHash(id) {
+        return voiceProfileHash(this.voiceProfile(id));
+    }
+}
+function voicevoxDescriptor(style) {
+    const speech = style.type === "talk" || style.type === "streaming_talk";
+    return {
+        id: `voicevox:${style.id}`,
+        engine: "voicevox",
+        name: style.name,
+        character: style.character,
+        description: null,
+        kinds: speech ? ["speech"] : ["song"],
+        styleId: style.id,
+        type: style.type,
+        baseF0: null,
+        f0Range: null,
+        hash: null,
+    };
+}
+export function readingFromPlan(plan) {
+    return {
+        engine: "formant",
+        frontend: plan.frontend,
+        kana: plan.kana,
+        speaker: null,
+        warnings: plan.warnings,
+        dictionaryHits: plan.dictionaryHits.map((hit) => ({
+            surface: hit.surface,
+            reading: hit.reading,
+            accent: hit.accent,
+            source: hit.source,
+            applied: hit.applied,
+        })),
+        sentences: plan.sentences.map((sentence) => ({
+            text: sentence.text,
+            kana: sentence.kana,
+            start: sentence.sourceSpan.start,
+            end: sentence.sourceSpan.end,
+        })),
+        phrases: plan.phrases.map((phrase) => ({
+            text: phrase.moras.map((mora) => mora.text).join(""),
+            accent: phrase.accent,
+            accentSource: phrase.accentSource,
+            boundary: phrase.boundary,
+            pause: phrase.boundary !== "phrase" && phrase.boundary !== "end",
+            interrogative: phrase.interrogative,
+            moras: phrase.moras.map((mora) => ({
+                text: mora.text,
+                consonant: mora.consonant,
+                vowel: mora.vowel,
+                consonantLength: null,
+                vowelLength: 0,
+                pitch: 0,
+            })),
+        })),
+    };
 }
 //# sourceMappingURL=kongyoroid.js.map