@kongyo2/kongyoroid 2.0.0 → 2.1.0

package/dist/cli.js

@@ -5,21 +5,21 @@ import { commandHelp, rootHelp } from "./cli/help.js";
 import { ALLOWED, assign, checkAllowed, env, numberFlag, parseCommandLine, parseDictEntries, styleFlag, } from "./cli/flags.js";
 import { DiskCache } from "./cache.js";
 import { EXIT_CODES, KongyoroidError, asKongyoroidError, exitCodeOf, formatDiagnostic, invalid } from "./errors.js";
-import { existingFileSha256, readBytes, readChunks, readLines, readText, writeAudioIdempotent, writeStream, writeTextFile, writeWithBackpressure, } from "./io.js";
-import { LIMITS } from "./limits.js";
+import { ensureReadableFile, existingFileSha256, readBytes, readChunks, readLines, readText, writeAudioIdempotent, writeStream, writeTextFile, writeWithBackpressure, } from "./io.js";
+import { DEFAULT_SAMPLE_RATE, LIMITS } from "./limits.js";
 import { Kongyoroid } from "./kongyoroid.js";
 import { playWav } from "./player.js";
 import { parseEngine, parseJson } from "./request.js";
 import { BATCH_JOB_SCHEMA, CAPABILITIES, DICTIONARY_SCHEMA, REQUEST_SCHEMA } from "./schema.js";
 import { pcm16Bytes, streamingWavHeader } from "./synth/stream.js";
 import { LocalDictionary } from "./text/dictionary.js";
-import { isObject, keys, literal, object, string } from "./validate.js";
+import { integer, isObject, keys, literal, object, string } from "./validate.js";
 import { PACKAGE_NAME, VERSION } from "./version.js";
 import { wavHeader } from "./wav.js";
 async function emit(value, error = false) {
     await writeStream(error ? process.stderr : process.stdout, `${JSON.stringify(value)}\n`);
 }
-function metadata(result) {
+function metadata(result, extraWarnings = []) {
     return {
         engine: result.engine,
         engineVersion: result.engineVersion,
@@ -39,21 +39,30 @@ function metadata(result) {
         ...(result.peak === undefined ? {} : { peak: result.peak, rms: result.rms, limitedSamples: result.limitedSamples }),
         elapsedMs: result.elapsedMs,
         timings: result.timings,
-        warnings: result.warnings,
+        warnings: extraWarnings.length === 0 ? result.warnings : [...result.warnings, ...extraWarnings],
         adjustments: result.adjustments,
     };
 }
+const PLAN_UNAVAILABLE = {
+    severity: "warning",
+    code: "PLAN_UNAVAILABLE",
+    message: "--plan-out was ignored: only the formant engine produces a synthesis plan.",
+    help: "Render with --engine formant (and no VOICEVOX style) to write the plan.",
+    path: "$flags.plan-out",
+};
 async function reportDiagnostics(values, warnings, location) {
     if (values.diagnostics !== "compact")
         return;
     for (const warning of warnings)
         await writeStream(process.stderr, `${formatDiagnostic(warning, location)}\n`);
 }
-async function deliver(agent, result, values, signal, plan) {
-    if (values["plan-out"] !== undefined && values["plan-out"] !== "-") {
-        await writeTextFile(values["plan-out"], `${JSON.stringify(plan ?? (await agent.plan(result.requestHash)), null, 2)}\n`, values.force ?? false);
+async function deliver(result, values, signal, plan) {
+    const planOut = values["plan-out"];
+    const extraWarnings = planOut !== undefined && plan === undefined ? [PLAN_UNAVAILABLE] : [];
+    if (planOut !== undefined && planOut !== "-" && plan !== undefined) {
+        await writeTextFile(planOut, `${JSON.stringify(plan, null, 2)}\n`, values.force ?? false);
     }
-    await reportDiagnostics(values, result.warnings, values.input ?? "<request>");
+    await reportDiagnostics(values, [...result.warnings, ...extraWarnings], values.input ?? "<request>");
     if (values.output === "-") {
         if (values.play)
             invalid("$flags.play", "--play cannot be combined with --output -.", {
@@ -63,8 +72,8 @@ async function deliver(agent, result, values, signal, plan) {
         return {
             ok: true,
             output: "stdout",
-            ...metadata(result),
-            ...(plan === undefined || values["plan-out"] !== "-" ? {} : { plan }),
+            ...metadata(result, extraWarnings),
+            ...(plan === undefined || planOut !== "-" ? {} : { plan }),
         };
     }
     const path = values.output ?? `kongyoroid-${result.kind}-${result.sha256.slice(0, 12)}.wav`;
@@ -75,28 +84,45 @@ async function deliver(agent, result, values, signal, plan) {
         path: written.path,
         written: written.written,
         unchanged: written.unchanged,
-        ...metadata(result),
+        ...metadata(result, extraWarnings),
         ...(played === undefined ? {} : { player: played.player }),
-        ...(plan === undefined || values["plan-out"] !== "-" ? {} : { plan }),
+        ...(plan === undefined || planOut !== "-" ? {} : { plan }),
     };
 }
 function speechRequestFromFlags(values, text) {
-    const request = { kind: "speech", text };
+    return withSpeechFlags(values, { kind: "speech", text });
+}
+function assignExclusive(request, values, first, second) {
+    const a = numberFlag(values, first.flag);
+    const b = numberFlag(values, second.flag);
+    if (a !== undefined && b !== undefined)
+        invalid(`$flags.${second.flag}`, `Use either --${first.flag} or --${second.flag}, not both.`);
+    if (a !== undefined) {
+        request[first.key] = a;
+        delete request[second.key];
+    }
+    if (b !== undefined) {
+        request[second.key] = b;
+        delete request[first.key];
+    }
+}
+function withSpeechFlags(values, base) {
+    const request = { ...base, kind: "speech" };
     assign(request, "engine", values.engine);
     assign(request, "voice", values.voice);
     assign(request, "kana", values.kana);
     const entries = parseDictEntries(values);
-    if (entries.length > 0)
-        request["dictionary"] = entries;
+    if (entries.length > 0) {
+        const existing = Array.isArray(base["dictionary"]) ? base["dictionary"] : [];
+        request["dictionary"] = [...existing, ...entries];
+    }
     if (values["strict-reading"] === false)
         request["strictReading"] = false;
     assign(request, "speaker", styleFlag(values, "speaker"));
     assign(request, "speed", numberFlag(values, "speed"));
-    assign(request, "pitch", numberFlag(values, "pitch"));
-    assign(request, "pitchSemitones", numberFlag(values, "pitch-semitones"));
+    assignExclusive(request, values, { flag: "pitch", key: "pitch" }, { flag: "pitch-semitones", key: "pitchSemitones" });
     assign(request, "intonation", numberFlag(values, "intonation"));
-    assign(request, "volume", numberFlag(values, "volume"));
-    assign(request, "gainDb", numberFlag(values, "gain-db"));
+    assignExclusive(request, values, { flag: "volume", key: "volume" }, { flag: "gain-db", key: "gainDb" });
     assign(request, "breathiness", numberFlag(values, "breathiness"));
     assign(request, "prePause", numberFlag(values, "pre-pause"));
     assign(request, "postPause", numberFlag(values, "post-pause"));
@@ -109,6 +135,30 @@ function speechRequestFromFlags(values, text) {
     assign(request, "seed", numberFlag(values, "seed"));
     return request;
 }
+function applyVibratoFlags(request, values, base) {
+    const depth = numberFlag(values, "vibrato-depth");
+    const rate = numberFlag(values, "vibrato-rate");
+    const delay = numberFlag(values, "vibrato-delay-ms");
+    const fade = numberFlag(values, "vibrato-fade-ms");
+    const existing = isObject(base["vibrato"]) ? base["vibrato"] : undefined;
+    if (existing === undefined && delay === undefined && fade === undefined) {
+        assign(request, "vibratoDepth", depth);
+        assign(request, "vibratoRate", rate);
+        return;
+    }
+    const vibrato = { ...existing };
+    if (existing === undefined) {
+        assign(vibrato, "depthCents", base["vibratoDepth"]);
+        assign(vibrato, "rateHz", base["vibratoRate"]);
+        delete request["vibratoDepth"];
+        delete request["vibratoRate"];
+    }
+    assign(vibrato, "depthCents", depth);
+    assign(vibrato, "rateHz", rate);
+    assign(vibrato, "delayMs", delay);
+    assign(vibrato, "fadeMs", fade);
+    request["vibrato"] = vibrato;
+}
 function songRequestFromFlags(values, base) {
     const request = { ...base, kind: "song" };
     if (values.mml !== undefined) {
@@ -130,29 +180,20 @@ function songRequestFromFlags(values, base) {
             hint: 'Example: --lyrics "ドレミ" --melody "C4 D4 E4" --beats "1 1 2"',
         });
     }
+    if (request["notes"] === undefined) {
+        invalid(values.input === undefined ? "$flags.melody" : "$.notes", "A song needs notes: give --lyrics with --melody, --mml, or --input FILE containing a notes list.", {
+            hint: 'Examples: kongyoroid sing --lyrics "ドレミ" --melody "C4 D4 E4" | kongyoroid sing --mml "t120 o4 c d e" | kongyoroid sing --input song.json',
+        });
+    }
     assign(request, "engine", values.engine);
     assign(request, "voice", values.voice);
     assign(request, "tempo", numberFlag(values, "tempo"));
     assign(request, "singer", styleFlag(values, "singer"));
     assign(request, "teacher", styleFlag(values, "teacher"));
     assign(request, "transpose", numberFlag(values, "transpose"));
-    assign(request, "volume", numberFlag(values, "volume"));
-    assign(request, "gainDb", numberFlag(values, "gain-db"));
+    assignExclusive(request, values, { flag: "volume", key: "volume" }, { flag: "gain-db", key: "gainDb" });
     assign(request, "breathiness", numberFlag(values, "breathiness"));
-    assign(request, "vibratoDepth", numberFlag(values, "vibrato-depth"));
-    assign(request, "vibratoRate", numberFlag(values, "vibrato-rate"));
-    const delay = numberFlag(values, "vibrato-delay-ms");
-    const fade = numberFlag(values, "vibrato-fade-ms");
-    if (delay !== undefined || fade !== undefined) {
-        const vibrato = {};
-        assign(vibrato, "delayMs", delay);
-        assign(vibrato, "fadeMs", fade);
-        assign(vibrato, "depthCents", numberFlag(values, "vibrato-depth"));
-        assign(vibrato, "rateHz", numberFlag(values, "vibrato-rate"));
-        delete request["vibratoDepth"];
-        delete request["vibratoRate"];
-        request["vibrato"] = vibrato;
-    }
+    applyVibratoFlags(request, values, base);
     assign(request, "portamentoMs", numberFlag(values, "portamento-ms"));
     assign(request, "scoopCents", numberFlag(values, "scoop-cents"));
     assign(request, "scoopMs", numberFlag(values, "scoop-ms"));
@@ -164,38 +205,53 @@ function songRequestFromFlags(values, base) {
     assign(request, "seed", numberFlag(values, "seed"));
     return request;
 }
-async function textInput(values, signal) {
+function rejectTextAndInput(values) {
     if (values.text !== undefined && values.input !== undefined)
         invalid("$flags", "Use either --text or --input, not both.");
+}
+async function textInput(values, signal) {
+    rejectTextAndInput(values);
     if (values.text !== undefined)
         return values.text;
     if (values.input !== undefined)
         return (await readText(values.input, signal)).replace(/\r?\n$/u, "");
+    if (values.kana !== undefined)
+        return values.kana;
     return invalid("$flags.text", "Provide --text or --input FILE (use - for standard input).", {
         hint: 'Example: kongyoroid speak --text "こんにちは" -o hello.wav',
     });
 }
+function overlayRequest(values, json) {
+    if (isObject(json) && json["kind"] === "song")
+        return songRequestFromFlags(values, json);
+    if (isObject(json) && json["kind"] === "speech" && typeof json["text"] === "string")
+        return withSpeechFlags(values, json);
+    if (isObject(json)) {
+        const overlay = { ...json };
+        assign(overlay, "engine", values.engine);
+        assign(overlay, "voice", values.voice);
+        return overlay;
+    }
+    return json;
+}
 async function requestFromInputs(values, signal, command) {
+    rejectTextAndInput(values);
     const hasSpeech = values.text !== undefined || values.kana !== undefined;
     const hasSong = values.lyrics !== undefined || values.melody !== undefined || values.mml !== undefined;
     if (values.input !== undefined) {
         const raw = await readText(values.input, signal);
-        const trimmed = raw.trim();
-        if (hasSpeech && !hasSong && !trimmed.startsWith("{"))
+        const looksLikeJson = raw.trim().startsWith("{");
+        if (!looksLikeJson && !hasSong)
             return speechRequestFromFlags(values, raw.replace(/\r?\n$/u, ""));
-        const json = parseJson(raw);
-        if (isObject(json) && json["kind"] === "song")
-            return songRequestFromFlags(values, json);
-        if (isObject(json) && values.engine !== undefined)
-            return { ...json, engine: values.engine };
-        return json;
+        return overlayRequest(values, parseJson(raw));
     }
     if (hasSong)
         return songRequestFromFlags(values, {});
-    if (hasSpeech || values.text !== undefined)
+    if (hasSpeech)
         return speechRequestFromFlags(values, await textInput(values, signal));
-    return invalid("$flags.input", `Provide --input FILE|- (a request JSON), --text, or --lyrics/--melody/--mml for ${command}.`, {
-        hint: `Examples: kongyoroid ${command} --input request.json | kongyoroid ${command} --text "こんにちは"`,
+    const scoreHint = command === "speak" ? "" : ", or --lyrics/--melody/--mml";
+    return invalid("$flags.input", `Provide --input FILE|- (text or a request JSON) or --text${scoreHint} for ${command}.`, {
+        hint: `Examples: kongyoroid ${command} --text "こんにちは" | kongyoroid ${command} --input request.json`,
     });
 }
 async function loadDictionaryFile(path, tolerateMissing) {
@@ -264,33 +320,84 @@ async function runPlan(agent, values, signal) {
     const result = await agent.plan(request, { signal, detail: planDetail(values) });
     await emit(result);
 }
+async function* single(text) {
+    yield text;
+}
+async function* prepend(head, iterator) {
+    for (const chunk of head)
+        yield chunk;
+    try {
+        while (true) {
+            const next = await iterator.next();
+            if (next.done === true)
+                return;
+            yield next.value;
+        }
+    }
+    finally {
+        await iterator.return?.();
+    }
+}
+async function streamInput(values, signal) {
+    const fromFlags = () => {
+        const request = speechRequestFromFlags(values, "placeholder");
+        delete request["text"];
+        return request;
+    };
+    if (values.text !== undefined)
+        return { request: fromFlags(), source: single(values.text) };
+    const iterator = readChunks(values.input ?? "-", signal)[Symbol.asyncIterator]();
+    const head = [];
+    let leading = "";
+    while (leading.trim().length === 0) {
+        const next = await iterator.next();
+        if (next.done === true)
+            break;
+        head.push(next.value);
+        leading += next.value;
+    }
+    if (!leading.trimStart().startsWith("{"))
+        return { request: fromFlags(), source: prepend(head, iterator) };
+    for (let next = await iterator.next(); next.done !== true; next = await iterator.next())
+        head.push(next.value);
+    const json = object(parseJson(head.join("")), "$");
+    if (json["kind"] !== undefined && json["kind"] !== "speech")
+        invalid("$.kind", "speak accepts only speech requests; use sing or render for songs.");
+    const text = json["text"];
+    if (typeof text !== "string")
+        invalid("$.text", "A request JSON given to --stream needs a text string to stream.", {
+            hint: 'Example: {"kind":"speech","text":"一文目。二文目。","voice":"soft"}',
+        });
+    const request = withSpeechFlags(values, json);
+    delete request["text"];
+    return { request, source: single(text) };
+}
 async function runSpeakStream(agent, values, signal) {
     if (values.play)
         invalid("$flags.play", "--play cannot be combined with --stream.");
+    if (values.kana !== undefined)
+        invalid("$flags.kana", "--kana cannot be combined with --stream; streaming reads each sentence from the text.", {
+            hint: "Give readings with --dict-entry SURFACE=READING[:ACCENT], or drop --stream to speak the kana at once.",
+        });
+    rejectTextAndInput(values);
     const format = literal(values.format ?? "wav", "$flags.format", ["wav", "pcm", "ndjson"]);
     const output = values.output ?? "-";
     if (output !== "-" && format !== "wav")
         invalid("$flags.format", "Streaming to a file writes WAV; use --output - for pcm or ndjson.");
-    const input = speechRequestFromFlags(values, "placeholder");
-    delete input["text"];
-    const source = values.text !== undefined
-        ? (async function* () {
-            yield values.text ?? "";
-        })()
-        : readChunks(values.input ?? "-", signal);
-    const events = agent.speakStream(source, input, { signal });
+    const flushRaw = numberFlag(values, "flush-ms");
+    const flushMs = flushRaw === undefined ? undefined : integer(flushRaw, "$flags.flush-ms", 1, 600_000);
+    const { request: input, source } = await streamInput(values, signal);
+    const events = agent.speakStream(source, input, { signal, ...(flushMs === undefined ? {} : { flushMs }) });
     const stdout = process.stdout;
     let sampleRate = 0;
     let file;
     let fileFrames = 0;
-    let fileBytes = 0;
-    let filePath = "";
+    const filePath = output === "-" ? "" : resolve(output);
     const sentences = [];
     const openFile = async () => {
-        if (output === "-")
+        if (output === "-" || file !== undefined)
             return;
         const { open } = await import("node:fs/promises");
-        filePath = resolve(output);
         if (!values.force) {
             const existing = await existingFileSha256(filePath);
             if (existing !== undefined)
@@ -299,11 +406,13 @@ async function runSpeakStream(agent, values, signal) {
                     repairOptions: [{ action: "use-force", description: "Overwrite with --force." }],
                 });
         }
+        if (sampleRate === 0)
+            sampleRate = numberFlag(values, "sample-rate") ?? DEFAULT_SAMPLE_RATE;
         file = await open(filePath, "w", 0o644);
         await file.write(wavHeader(0, sampleRate));
-        fileBytes = 44;
     };
     let headerWritten = false;
+    let completed = false;
     try {
         for await (const event of events) {
             if (event.type === "sentence") {
@@ -333,7 +442,6 @@ async function runSpeakStream(agent, values, signal) {
                 if (file !== undefined) {
                     await file.write(bytes);
                     fileFrames += block.samples.length;
-                    fileBytes += bytes.length;
                     continue;
                 }
                 if (format === "ndjson") {
@@ -347,12 +455,16 @@ async function runSpeakStream(agent, values, signal) {
                 await writeWithBackpressure(stdout, bytes, signal);
                 continue;
             }
+            completed = true;
+            if (output !== "-")
+                await openFile();
             const summary = {
                 ok: true,
                 operation: "speak",
                 stream: true,
                 format,
                 output: output === "-" ? "stdout" : filePath,
+                ...(output === "-" ? {} : { written: true }),
                 sentences: event.sentences,
                 frames: event.frames,
                 durationSeconds: Math.round(event.durationSeconds * 1000) / 1000,
@@ -370,8 +482,8 @@ async function runSpeakStream(agent, values, signal) {
             const header = wavHeader(fileFrames, sampleRate);
             await file.write(header, 0, 44, 0);
             await file.close();
-            void fileBytes;
         }
+        void completed;
     }
 }
 async function runBatch(agent, values, signal, onFailure) {
@@ -598,6 +710,13 @@ async function runCache(values, positionals) {
         await emit({ ok: true, operation: "cache.stats", ...(await cache.stats()) });
         return;
     }
+    const maxBytes = numberFlag(values, "max-bytes");
+    const maxEntries = numberFlag(values, "max-entries");
+    if (action === "prune" && maxBytes === undefined && maxEntries === undefined) {
+        invalid("$flags.max-bytes", "cache prune needs --max-bytes N and/or --max-entries N.", {
+            hint: "Example: kongyoroid cache prune --cache-dir ./cache --max-bytes 200000000",
+        });
+    }
     const before = await cache.stats();
     if (values["dry-run"]) {
         await emit({
@@ -605,14 +724,12 @@ async function runCache(values, positionals) {
             operation: `cache.${action}`,
             dryRun: true,
             directory: cache.directory,
-            wouldRemove: action === "clear" ? before.entries : null,
+            wouldRemove: action === "clear" ? before.entries : await cache.prune(maxBytes, maxEntries, true),
             ...before,
         });
         return;
     }
-    const removed = action === "clear"
-        ? await cache.clear()
-        : await cache.prune(numberFlag(values, "max-bytes"), numberFlag(values, "max-entries"));
+    const removed = action === "clear" ? await cache.clear() : await cache.prune(maxBytes, maxEntries);
     await emit({ ok: true, operation: `cache.${action}`, directory: cache.directory, removed, ...(await cache.stats()) });
 }
 async function main(argv) {
@@ -665,8 +782,9 @@ async function main(argv) {
     const signal = controller.signal;
     try {
         if (command === "play") {
-            const path = string(positionals[1], "$.play.file", 1, 4096);
-            await emit({ ok: true, operation: "play", path: resolve(path), ...(await playWav(resolve(path), signal)) });
+            const path = resolve(string(positionals[1], "$.play.file", 1, 4096));
+            await ensureReadableFile(path);
+            await emit({ ok: true, operation: "play", path, ...(await playWav(path, signal)) });
             return;
         }
         if (command === "inspect") {
@@ -689,11 +807,13 @@ async function main(argv) {
         const agent = await createAgent(values, command === "dict");
         switch (command) {
             case "speak": {
-                if (values.stream) {
+                if (values.stream && !values["dry-run"]) {
                     await runSpeakStream(agent, values, signal);
                     return;
                 }
-                const request = speechRequestFromFlags(values, await textInput(values, signal));
+                const request = await requestFromInputs(values, signal, "speak");
+                if (isObject(request) && request["kind"] !== "speech")
+                    invalid("$.kind", "speak accepts only speech requests; use sing or render for songs.");
                 if (values["dry-run"]) {
                     await runValidateRequest(agent, request, values, signal);
                     return;
@@ -702,7 +822,7 @@ async function main(argv) {
                 const plan = values["plan-out"] === undefined || result.engine !== "formant"
                     ? undefined
                     : (await agent.plan(request, { signal, detail: "phonemes" })).plan;
-                await emit(await deliver(agent, result, values, signal, plan), values.output === "-");
+                await emit(await deliver(result, values, signal, plan), values.output === "-");
                 return;
             }
             case "sing": {
@@ -718,7 +838,7 @@ async function main(argv) {
                 const plan = values["plan-out"] === undefined || result.engine !== "formant"
                     ? undefined
                     : (await agent.plan(request, { signal, detail: "phonemes" })).plan;
-                await emit(await deliver(agent, result, values, signal, plan), values.output === "-");
+                await emit(await deliver(result, values, signal, plan), values.output === "-");
                 return;
             }
             case "render": {
@@ -739,7 +859,7 @@ async function main(argv) {
                 const plan = values["plan-out"] === undefined || result.engine !== "formant"
                     ? undefined
                     : (await agent.plan(withFlags, { signal, detail: "phonemes" })).plan;
-                await emit(await deliver(agent, result, values, signal, plan), values.output === "-");
+                await emit(await deliver(result, values, signal, plan), values.output === "-");
                 return;
             }
             case "validate":