arcane-os 0.93.0 → 0.94.0

package/src/local-ai/install.mjs

@@ -10,7 +10,7 @@ import {ArcaneError,ERROR_CODES,normalizeError,throwIfAborted} from '../errors.m
 import {createEventQueue} from '../event-queue.mjs';
 import {runProcess} from '../process.mjs';
 import {extractLocalAIArchive} from './archive.mjs';
-import {normalizeImageRuntimeRequirement,normalizeLlamaRuntimeRequirement} from './config.mjs';
+import {normalizeImageRuntimeRequirement,normalizeKokoroRuntimeRequirement,normalizeLlamaRuntimeRequirement} from './config.mjs';
 import {normalizeWhisperRuntimeRequirement} from './whisper/config.mjs';
 import {bundledWhisperRuntime, installedWhisperRuntime, installWhisperDistribution, whisperRuntimeSelection} from './whisper/install.mjs';
 
@@ -28,6 +28,21 @@ function selectedONNXNativeDistribution(runtime,platform,architecture){
         ?onnxWindowsDistribution:null;
 }
 
+function kokoroRuntimeSelection(runtime) {
+    return JSON.stringify(
+        {
+            source: runtime.helperRoot ? 'directory' : runtime.url ? 'archive' : 'sdk-release',
+            version: runtime.version ?? null,
+            url: runtime.url ?? null,
+            helperRoot: runtime.helperRoot ? path.resolve(runtime.helperRoot) : null,
+            helperExecutable: runtime.helperExecutable ?? null,
+            espeakDataDirectory: runtime.espeakDataDirectory ?? null,
+            libraryDirectory: runtime.libraryDirectory ?? null,
+            sdkVersion: !runtime.helperRoot && !runtime.url ? packageMetadata.version : null
+        }
+    );
+}
+
 function selectRuntimes(runtimes){
     if(!is.array(runtimes)){
         throw new ArcaneError(ERROR_CODES.usage,'Local AI runtimes must be an array.');
@@ -37,14 +52,23 @@ function selectRuntimes(runtimes){
         const requirement=is.string(item)?{id:item}:item;
         const runtime=requirement?.id==='stable-diffusion.cpp'?normalizeImageRuntimeRequirement(requirement)
             :requirement?.id==='whisper.cpp'?normalizeWhisperRuntimeRequirement(requirement)
+            :requirement?.id==='kokoro-native'?normalizeKokoroRuntimeRequirement(requirement)
             :requirement?.id==='llama.cpp'?normalizeLlamaRuntimeRequirement(requirement):requirement;
-        if(!runtime||!['llama.cpp','ollama','nemo-speech','onnx','stable-diffusion.cpp','whisper.cpp'].includes(runtime.id)){
+        if(!runtime||!['llama.cpp','ollama','nemo-speech','onnx','stable-diffusion.cpp','whisper.cpp','kokoro-native'].includes(runtime.id)){
             throw new ArcaneError(ERROR_CODES.targetUnavailable,`Local AI runtime installation is unavailable for ${String(runtime?.id)}.`);
         }
         const prior=selected.get(runtime.id);
         if(prior&&runtime.id==='whisper.cpp'&&whisperRuntimeSelection(prior)!==whisperRuntimeSelection(runtime)){
             throw new ArcaneError(ERROR_CODES.usage,'Select one complete whisper.cpp runtime and model requirement for this operation.');
         }
+        if (runtime.id === 'kokoro-native') {
+            if (runtime.helperRoot && runtime.url) {
+                throw new ArcaneError(ERROR_CODES.usage, 'Select either a kokoro-native helperRoot or an archive URL for this operation.');
+            }
+            if (prior && kokoroRuntimeSelection(prior) !== kokoroRuntimeSelection(runtime)) {
+                throw new ArcaneError(ERROR_CODES.usage, 'Select one complete kokoro-native helper requirement for this operation.');
+            }
+        }
         if(prior&&(prior.version!==runtime.version||prior.url!==runtime.url
             ||(['stable-diffusion.cpp','llama.cpp'].includes(runtime.id)&&prior.backend!==runtime.backend)
             ||(runtime.id==='llama.cpp'&&prior.companionUrl!==runtime.companionUrl))){
@@ -111,6 +135,20 @@ async function selectRelease(runtime,platform,architecture,signal){
     if (runtime.id === 'stable-diffusion.cpp') {
         return selectImageRelease(runtime, platform, architecture, signal);
     }
+    if (runtime.id === 'kokoro-native') {
+        if (runtime.helperRoot) return null;
+        if (!runtime.url) {
+            if (platform !== 'win32' || architecture !== 'x64') {
+                throw new ArcaneError(ERROR_CODES.targetUnavailable, `Supply a complete kokoro-native archive URL or helperRoot for ${platform}/${architecture}.`);
+            }
+            const name = 'arcane-kokoro-windows-x64.tar.gz';
+            return {
+                version: packageMetadata.version,
+                url: `https://github.com/TheWizardNexus/arcane-os-sdk/releases/download/${packageMetadata.version}/${name}`,
+                name
+            };
+        }
+    }
     const backend=runtime.id==='llama.cpp'?llamaBackendCandidate(runtime,platform,architecture):undefined;
     if(runtime.url){
         const name=path.posix.basename(new URL(runtime.url).pathname);
@@ -432,6 +470,7 @@ async function installedRuntime(base,runtime,platform,architecture,signal,reuseW
             throw error;
         }
         if(installation.requestVersion!==(runtime.version??null)||installation.requestUrl!==(runtime.url??null))continue;
+        if (runtime.id === 'kokoro-native' && installation.requestKokoro !== kokoroRuntimeSelection(runtime)) continue;
         if (runtime.id === 'stable-diffusion.cpp' && installation.requestBackend !== runtime.backend) continue;
         if(runtime.id==='llama.cpp'&&((installation.requestBackend??'auto')!==runtime.backend
             ||(installation.requestCompanionUrl??null)!==(runtime.companionUrl??null)))continue;
@@ -445,6 +484,10 @@ async function installedRuntime(base,runtime,platform,architecture,signal,reuseW
         if(record?.id!==runtime.id||record.platform!==platform||record.architecture!==architecture)continue;
         if(runtime.id==='llama.cpp'&&record.backend!==undefined&&record.backend!==llamaBackend)continue;
         try{
+            if (runtime.id === 'kokoro-native') {
+                if (await installedKokoroRuntime(record, signal)) return record;
+                continue;
+            }
             if(runtime.id==='whisper.cpp'){
                 if(await installedWhisperRuntime(record,signal,!reuseWhisper))return reuseWhisper?{runtime:record,requirement:whisperRequirement}:record;
                 continue;
@@ -507,6 +550,51 @@ async function installedRuntime(base,runtime,platform,architecture,signal,reuseW
     return null;
 }
 
+function kokoroRuntimeLocations(runtime, root, platform) {
+    const sourceRoot = runtime.helperRoot ? path.resolve(runtime.helperRoot) : root;
+    const defaults = {
+        helperExecutable: path.join('bin', `arcane-kokoro${platform === 'win32' ? '.exe' : ''}`),
+        espeakDataDirectory: 'share',
+        libraryDirectory: 'bin'
+    };
+    const locations = {};
+    for (const [field, fallback] of Object.entries(defaults)) {
+        const selected = path.resolve(sourceRoot, runtime[field] ?? fallback);
+        const relative = path.relative(sourceRoot, selected);
+        if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+            throw new ArcaneError(ERROR_CODES.usage, `kokoro-native ${field} must belong to the selected complete helper tree so it can be relocated.`);
+        }
+        locations[field] = path.join(root, relative);
+    }
+    return locations;
+}
+
+async function installedKokoroRuntime(record, signal) {
+    throwIfAborted(signal);
+    const locations = [record.helperExecutable, record.espeakDataDirectory, record.libraryDirectory];
+    const missingLocation = locations.some(
+        function missingKokoroLocation(location) {
+            return !is.string(location);
+        }
+    );
+    if (missingLocation) return false;
+    // eSpeak's data argument is the parent of its espeak-ng-data directory.
+    locations.push(path.join(record.espeakDataDirectory, 'espeak-ng-data'));
+    const entries = await Promise.all(
+        locations.map(
+            function inspectKokoroLocation(location) {
+                return stat(location);
+            }
+        )
+    );
+    throwIfAborted(signal);
+    return entries.every(
+        function kokoroLocationPresent(info, index) {
+            return index === 0 ? info.isFile() : info.isDirectory();
+        }
+    );
+}
+
 async function runtimeExecutable(root,id,platform,signal){
     const filename=`${id==='llama.cpp'?'llama-server':'ollama'}${platform==='win32'?'.exe':''}`;
     const directories=[root];
@@ -645,6 +733,22 @@ async function installRuntime(runtime,{directory,platform,architecture,signal,on
                 release,
                 {root, directory, platform, architecture, signal, onEvent}
             );
+        } else if (runtime.id === 'kokoro-native' && runtime.helperRoot) {
+            const sourceRoot = path.resolve(runtime.helperRoot);
+            const destination = path.relative(sourceRoot, root);
+            if (destination !== '..' && !destination.startsWith(`..${path.sep}`) && !path.isAbsolute(destination)) {
+                throw new ArcaneError(ERROR_CODES.usage, 'The kokoro-native installation directory must be outside helperRoot so copying does not include its own output.');
+            }
+            locations = {version: runtime.version ?? 'custom', ...kokoroRuntimeLocations(runtime, root, platform)};
+            await onEvent(
+                {
+                    type: 'local-ai.install.copying',
+                    message: 'Copying the selected complete Kokoro helper tree.',
+                    data: {id: runtime.id, platform, architecture}
+                }
+            );
+            const files = [];
+            await copyRuntimeTree(sourceRoot, root, root, files, signal);
         }else{
             const assets=[{url:release.url,name:release.name,archive}];
             if(companionArchive){
@@ -679,13 +783,17 @@ async function installRuntime(runtime,{directory,platform,architecture,signal,on
                 ...(runtime.id==='llama.cpp'?{backend:release.backend,requestedBackend:release.requestedBackend}:{}),
                 ...(runtime.id==='nemo-speech'
                 ?await nemoRuntimeDirectories(root,signal)
+                :runtime.id==='kokoro-native'?kokoroRuntimeLocations(runtime,root,platform)
                 :{executable:await runtimeExecutable(root,runtime.id,platform,signal)})};
         }
         const record={id:runtime.id,platform,architecture,root,...locations,...(runtime.version?{requestedVersion:runtime.version}:{})};
+        if (runtime.id === 'kokoro-native' && !await installedKokoroRuntime(record, signal)) {
+            throw new ArcaneError(ERROR_CODES.operationFailed, 'Kokoro preparation did not produce the selected helper executable, eSpeak data, and library directory.');
+        }
         throwIfAborted(signal);
         if(archive)await unlink(archive);
         if(companionArchive)await unlink(companionArchive);
-        await writeFile(path.join(attempt,'installation.json'),`${JSON.stringify({requestVersion:runtime.version??null,requestUrl:runtime.url??null,...(['stable-diffusion.cpp','llama.cpp'].includes(runtime.id)?{requestBackend:runtime.backend}:{}),...(runtime.id==='llama.cpp'?{requestCompanionUrl:runtime.companionUrl??null}:{}),...(runtime.id==='whisper.cpp'?{requestWhisper:whisperRuntimeSelection(runtime)}:{}),runtime:record},null,2)}\n`,{flag:'wx',signal});
+        await writeFile(path.join(attempt,'installation.json'),`${JSON.stringify({requestVersion:runtime.version??null,requestUrl:runtime.url??null,...(['stable-diffusion.cpp','llama.cpp'].includes(runtime.id)?{requestBackend:runtime.backend}:{}),...(runtime.id==='llama.cpp'?{requestCompanionUrl:runtime.companionUrl??null}:{}),...(runtime.id==='whisper.cpp'?{requestWhisper:whisperRuntimeSelection(runtime)}:{}),...(runtime.id==='kokoro-native'?{requestKokoro:kokoroRuntimeSelection(runtime)}:{}),runtime:record},null,2)}\n`,{flag:'wx',signal});
         completed=true;
         await onEvent({type:'local-ai.install.completed',message:`${runtime.id} ${record.version} is available.`,data:record});
         return record;
@@ -705,7 +813,7 @@ async function installRuntime(runtime,{directory,platform,architecture,signal,on
 
 function shareInstallation(runtime,options){
     throwIfAborted(options.signal);
-    const key=JSON.stringify([options.directory,options.platform,options.architecture,runtime.id,runtime.version??null,runtime.url??null,['stable-diffusion.cpp','llama.cpp'].includes(runtime.id)?runtime.backend:null,runtime.id==='whisper.cpp'?whisperRuntimeSelection(runtime):null,runtime.id==='llama.cpp'?runtime.companionUrl??null:null]);
+    const key=JSON.stringify([options.directory,options.platform,options.architecture,runtime.id,runtime.version??null,runtime.url??null,['stable-diffusion.cpp','llama.cpp'].includes(runtime.id)?runtime.backend:null,runtime.id==='whisper.cpp'?whisperRuntimeSelection(runtime):null,runtime.id==='llama.cpp'?runtime.companionUrl??null:null,runtime.id==='kokoro-native'?kokoroRuntimeSelection(runtime):null]);
     let entry=installations.get(key);
     if(entry?.controller.signal.aborted){
         // The prior cancelled attempt owns its cleanup. A later request waits
@@ -855,7 +963,7 @@ export async function bundleLocalAIRuntimes({runtimes=[],directory,outputRoot,pl
         const relative=`runtime/local-ai/${runtime.id}`;
         const destination=path.join(root,relative);
         const bundled=runtime.id==='whisper.cpp'?bundledWhisperRuntime(runtime,relative):{...runtime,root:relative};
-        for(const field of ['executable','modulePath','includeDirectory','libraryDirectory','binaryDirectory','cmakeDirectory','libraryPath','bindingModulePath']){
+        for(const field of ['executable','modulePath','includeDirectory','libraryDirectory','binaryDirectory','cmakeDirectory','libraryPath','bindingModulePath','helperExecutable','espeakDataDirectory']){
             if(runtime[field]===undefined)continue;
             bundled[field]=path.posix.join(relative,path.relative(runtime.root,runtime[field]).split(path.sep).join('/'));
         }

package/src/local-ai/kokoro/frontend.mjs

@@ -0,0 +1,219 @@
+import {readFile} from 'node:fs/promises';
+import {endianness} from 'node:os';
+import Is from 'strong-type';
+
+const is = new Is(false);
+
+export const KOKORO_MODEL = 'onnx-community/Kokoro-82M-v1.0-ONNX';
+export const KOKORO_REVISION = '1939ad2a8e416c0acfeecc08a694d14ef25f2231';
+export const KOKORO_SAMPLE_RATE = 24000;
+export const KOKORO_VOICES = [
+    'af_heart', 'af_alloy', 'af_aoede', 'af_bella', 'af_jessica', 'af_kore',
+    'af_nicole', 'af_nova', 'af_river', 'af_sarah', 'af_sky',
+    'am_adam', 'am_echo', 'am_eric', 'am_fenrir', 'am_liam', 'am_michael',
+    'am_onyx', 'am_puck', 'am_santa', 'bf_emma', 'bf_isabella', 'bm_george',
+    'bm_lewis', 'bf_alice', 'bf_lily', 'bm_daniel', 'bm_fable'
+];
+
+/** Read the selected model's public tokenizer and voice tensors, without a second model store. */
+export async function loadKokoroFrontend(paths, {signal} = {}) {
+    const resources = await Promise.allSettled([
+        readFile(paths.tokenizer, {encoding: 'utf8', signal}),
+        readFile(paths.tokenizerConfig, {encoding: 'utf8', signal}),
+        ...KOKORO_VOICES.map(function readVoice(voice) { return readFile(paths.voices[voice], {signal}); })
+    ]);
+    const failures = resources.filter(function failed(result) { return result.status === 'rejected'; })
+        .map(function cause(result) { return result.reason; });
+    if (signal?.aborted) {
+        const independent = failures.filter(function independentFailure(cause) {
+            return cause !== signal.reason && !(cause?.code === 'ABORT_ERR' && cause.cause === signal.reason);
+        });
+        if (independent.length) throw new AggregateError([signal.reason, ...independent], 'Kokoro resource loading was cancelled with errors.', {cause: signal.reason});
+        signal.throwIfAborted();
+    }
+    if (failures.length) throw new AggregateError(failures, 'Reading the complete Kokoro frontend resources failed.');
+    const tokenizer = JSON.parse(resources[0].value);
+    const configuration = JSON.parse(resources[1].value);
+    const vocabulary = tokenizer.model.vocab;
+    const context = configuration.model_max_length;
+    const boundary = vocabulary[configuration.pad_token];
+    if (!is.integer(context) || context < 3 || !is.integer(boundary)) {
+        throw new Error('The selected Kokoro tokenizer does not describe its context and boundary token.');
+    }
+    const voices = new Map();
+    // Independent files load concurrently; the activation owns every read until it settles.
+    for (let voiceIndex = 0; voiceIndex < KOKORO_VOICES.length; voiceIndex += 1) {
+        const voice = KOKORO_VOICES[voiceIndex];
+        signal?.throwIfAborted();
+        const encoded = resources[voiceIndex + 2].value;
+        const values = new Float32Array(Math.ceil(encoded.length / 4));
+        for (let index = 0; index < values.length; index += 1) {
+            values[index] = encoded.readFloatLE(index * 4);
+        }
+        voices.set(voice, values);
+    }
+
+    function tokens(clauses, voice) {
+        const language = voiceLanguage(voice);
+        const result = [];
+        for (let index = 0; index < clauses.length; index += 1) {
+            const clause = clauses[index];
+            const phonemes = kokoroPhonemes(clause.phonemes, language);
+            const beginning = clause.source.match(/^[\s;:,.!?—…"()“”]+/u)?.[0] ?? '';
+            let ending = clause.source.match(/[\s;:,.!?—…"()“”]+$/u);
+            // The public cursor can include one next-clause character saved by
+            // eSpeak's UngetC. Its phonemes belong to the next returned clause;
+            // recover only the preceding punctuation, leaving both records intact.
+            if (!ending && index + 1 < clauses.length) {
+                ending = clause.source.match(/[;:,.!?—…"()“”][\s;:,.!?—…"()“”]*(?=[^\s;:,.!?—…"()“”]$)/u);
+            }
+            const punctuation = ending && ending.index >= beginning.length ? ending[0] : '';
+            const complete = beginning.replace(/\s/gu, ' ') + phonemes + punctuation.replace(/\s/gu, ' ');
+            for (const symbol of complete) {
+                const id = vocabulary[symbol];
+                if (!is.integer(id)) {
+                    const failure = new Error(`Kokoro has no token for the emitted phoneme ${JSON.stringify(symbol)}.`);
+                    failure.code = 'KOKORO_PHONEME_UNSUPPORTED';
+                    failure.data = {symbol, language, source: clause.source, phonemes: clause.phonemes, mappedPhonemes: complete};
+                    throw failure;
+                }
+                result.push({id, symbol});
+            }
+        }
+        return result;
+    }
+
+    function* segments(clauses, voice) {
+        const content = tokens(clauses, voice);
+        const style = voices.get(voice);
+        const capacity = context - 2;
+        let offset = 0;
+        while (offset < content.length) {
+            let end = Math.min(offset + capacity, content.length);
+            if (end < content.length) {
+                for (let candidate = end; candidate > offset; candidate -= 1) {
+                    if (/[ ;:,.!?—…]/u.test(content[candidate - 1].symbol)) {
+                        end = candidate;
+                        break;
+                    }
+                }
+            }
+            const count = end - offset;
+            const input = new BigInt64Array(count + 2);
+            input[0] = BigInt(boundary);
+            for (let index = 0; index < count; index += 1) input[index + 1] = BigInt(content[offset + index].id);
+            input[count + 1] = BigInt(boundary);
+            // The public model contract selects the style row by content-token count, excluding BOS/EOS.
+            const row = style.subarray(count * 256, (count + 1) * 256);
+            if (row.length !== 256) throw new Error(`The selected ${voice} tensor has no style row for ${count} phoneme tokens.`);
+            yield {input, style: row, tokenCount: count};
+            offset = end;
+        }
+    }
+
+    return {segments};
+}
+
+export function voiceLanguage(voice) {
+    if (!KOKORO_VOICES.includes(voice)) {
+        const failure = new Error(`The selected Kokoro voice ${String(voice)} is unavailable.`);
+        failure.code = 'KOKORO_VOICE_UNAVAILABLE';
+        throw failure;
+    }
+    return voice.startsWith('b') ? 'en-gb' : 'en-us';
+}
+
+/** Model-specific IPA spelling for Kokoro v1.0 English, including the versioned recipe:
+ * https://github.com/hexgrad/misaki/blob/main/misaki/espeak.py
+ * This is phoneme conversion; the caller's source text is never rewritten.
+ */
+export function kokoroPhonemes(ipa, language) {
+    const british = language === 'en-gb';
+    const phones = Array.from(ipa);
+    const output = [];
+    const diphthongs = new Map([
+        ['aɪ', 'I'], ['aʊ', 'W'], ['eɪ', 'A'], ['ɔɪ', 'Y'],
+        ['oʊ', 'O'], ['əʊ', 'Q'], ['tʃ', 'ʧ'], ['dʒ', 'ʤ']
+    ]);
+    for (let index = 0; index < phones.length; index += 1) {
+        const phone = phones[index];
+        const tied = phones[index + 1] === '^';
+        const next = phones[index + (tied ? 2 : 1)];
+        const pair = phone + (next ?? '');
+        if (diphthongs.has(pair)) {
+            output.push(diphthongs.get(pair));
+            index += tied ? 2 : 1;
+        } else if (british && pair === 'eə') {
+            output.push('ɛː');
+            index += tied ? 2 : 1;
+        } else if (british && pair === 'iə') {
+            output.push('ɪə');
+            index += tied ? 2 : 1;
+        } else if (!british && pair === 'ɪə') {
+            output.push('iə');
+            index += tied ? 2 : 1;
+        } else if (tied && pair === 'əl') {
+            output.push('ᵊl');
+            index += 2;
+        } else if (phone === 'ʔ' && (next === 'n' || (next === 'ˌ' && phones[index + 2] === 'n'))
+            && phones[index + (next === 'n' ? 2 : 3)] === '\u0329') {
+            output.push('tn');
+            index += next === 'n' ? 2 : 3;
+        } else if (phone === '\u0329') {
+            const consonant = output.pop();
+            if (consonant === undefined) throw new Error('eSpeak emitted a syllabic mark without its consonant.');
+            output.push('ᵊ', consonant);
+        } else if (phone === 'ɚ') output.push('əɹ');
+        else if (phone === 'ɝ') output.push('ɜɹ');
+        else if (phone === 'r') output.push('ɹ');
+        else if (phone === 'g') output.push('ɡ');
+        else if (phone === 'ɐ') output.push('ə');
+        else if (phone === 'ɬ') output.push('l');
+        else if (phone === 'x' || phone === 'ç') output.push('k');
+        else if (phone === 'ʔ') output.push('t');
+        else if (phone === 'ɾ') output.push('T');
+        else if (phone === 'ʲ') {
+            if (next === 'o' || next === 'ə') output.push('j');
+        } else if (phone === '\u0303') continue;
+        else if (phone === 'o') output.push('ɔ');
+        else if (phone === 'e') output.push('A');
+        else if (phone === '^') continue;
+        else if (phone === 'ː' && !british) {
+            if (phones[index - 1] === 'ɜ' && next !== 'ɹ' && next !== 'r') output.push('ɹ');
+        } else if (/\s/u.test(phone)) output.push(' ');
+        else output.push(phone);
+    }
+    return output.join('');
+}
+
+/** IEEE float WAV preserves the complete native waveform without amplitude clamps. */
+export function encodeKokoroWav(chunks) {
+    const samples = chunks.reduce(function countSamples(total, chunk) { return total + chunk.length; }, 0);
+    const dataLength = samples * 4;
+    // RIFF's unsigned 32-bit chunk fields are an external format constraint, not a content policy.
+    if (dataLength + 48 > 0xffffffff) throw new RangeError('This complete waveform exceeds the WAV RIFF format; select Ogg Opus.');
+    const header = Buffer.alloc(56);
+    header.write('RIFF', 0);
+    header.writeUInt32LE(dataLength + 48, 4);
+    header.write('WAVEfmt ', 8);
+    header.writeUInt32LE(16, 16);
+    header.writeUInt16LE(3, 20);
+    header.writeUInt16LE(1, 22);
+    header.writeUInt32LE(KOKORO_SAMPLE_RATE, 24);
+    header.writeUInt32LE(KOKORO_SAMPLE_RATE * 4, 28);
+    header.writeUInt16LE(4, 32);
+    header.writeUInt16LE(32, 34);
+    header.write('fact', 36);
+    header.writeUInt32LE(4, 40);
+    header.writeUInt32LE(samples, 44);
+    header.write('data', 48);
+    header.writeUInt32LE(dataLength, 52);
+    return Buffer.concat([header, ...chunks.map(floatPCM)]);
+}
+
+export function floatPCM(samples) {
+    if (endianness() === 'LE') return Buffer.from(samples.buffer, samples.byteOffset, samples.byteLength);
+    const encoded = Buffer.allocUnsafe(samples.length * 4);
+    for (let index = 0; index < samples.length; index += 1) encoded.writeFloatLE(samples[index], index * 4);
+    return encoded;
+}

package/src/local-ai/kokoro/helper.mjs

@@ -0,0 +1,168 @@
+import path from 'node:path';
+import {PassThrough} from 'node:stream';
+import Is from 'strong-type';
+import {runProcess} from '../../process.mjs';
+import {floatPCM} from './frontend.mjs';
+
+const is = new Is(false);
+
+/** One retained helper owns eSpeak's process-global state and the public Opus encoder. */
+export function createKokoroHelper(runtime, {onEvent} = {}) {
+    const controller = new AbortController();
+    const input = new PassThrough();
+    const readiness = deferred();
+    let pending = null;
+    let fragment = Buffer.alloc(0);
+    let frame = null;
+    let sequence = 0;
+    let stopping = false;
+    let exited = false;
+    let terminalError = null;
+    const env = {...process.env};
+    const directory = runtime.libraryDirectory ?? path.dirname(runtime.helperExecutable);
+    const variable = process.platform === 'win32'
+        ? Object.keys(env).find(function pathName(name) { return name.toLowerCase() === 'path'; }) ?? 'PATH'
+        : process.platform === 'darwin' ? 'DYLD_LIBRARY_PATH' : 'LD_LIBRARY_PATH';
+    env[variable] = [directory, env[variable]].filter(Boolean).join(path.delimiter);
+    const source = input[Symbol.asyncIterator]();
+    const incoming = {
+        [Symbol.asyncIterator]() { return this; },
+        next() { return source.next(); },
+        return() { input.end(); return source.return(); }
+    };
+    const completion = runProcess(runtime.helperExecutable, ['--data', runtime.espeakDataDirectory], {
+        env, signal: controller.signal, onEvent, input: incoming,
+        outputEncoding: {stdout: null, stderr: 'utf8'},
+        captureOutput: {stdout: false, stderr: true},
+        emitOutputEvents: {stdout: false, stderr: true},
+        onOutput: receive
+    }).then(function helperExited(result) {
+        if (!stopping) throw new Error('The Kokoro helper exited before being released.');
+        return result;
+    }).catch(function helperFailed(error) {
+        terminalError = error;
+        throw error;
+    }).finally(function helperSettled() {
+        exited = true;
+        input.end();
+        const failure = terminalError ?? new Error('The Kokoro helper has stopped.');
+        readiness.reject(failure);
+        pending?.response.reject(failure);
+    });
+    completion.catch(function observeHelperFailure() {});
+
+    function receive({stream, chunk}) {
+        if (stream !== 'stdout') return;
+        fragment = fragment.length ? Buffer.concat([fragment, chunk]) : chunk;
+        for (;;) {
+            if (!frame) {
+                const boundary = fragment.indexOf(10);
+                if (boundary < 0) return;
+                const [kind, id, length] = fragment.subarray(0, boundary).toString('utf8').split('\t');
+                frame = {kind, id, length: Number(length)};
+                if (!is.safeInteger(frame.length) || frame.length < 0) throw new Error('The Kokoro helper returned unreadable protocol framing.');
+                fragment = fragment.subarray(boundary + 1);
+            }
+            if (fragment.length < frame.length) return;
+            const payload = fragment.subarray(0, frame.length);
+            fragment = fragment.subarray(frame.length);
+            const record = frame;
+            frame = null;
+            if (record.kind === 'ready') {
+                readiness.resolve();
+                continue;
+            }
+            if (!pending || record.id !== pending.id) throw new Error('The Kokoro helper returned a response without its active request.');
+            if (record.kind === 'error') pending.response.reject(new Error(payload.toString('utf8')));
+            else if (record.kind === 'clause') pending.clauses.push(JSON.parse(payload.toString('utf8')));
+            else if (record.kind === 'page') pending.pages.push(Buffer.from(payload));
+            else if (record.kind === 'done') pending.response.resolve(pending);
+            else throw new Error(`The Kokoro helper returned an unknown record ${record.kind}.`);
+        }
+    }
+
+    async function command(kind, body, language, signal) {
+        signal?.throwIfAborted();
+        await readiness.promise;
+        signal?.throwIfAborted();
+        if (pending || stopping || exited) throw terminalError ?? new Error('The Kokoro helper is unavailable for a new operation.');
+        const operation = {id: String(++sequence), response: deferred(), clauses: [], pages: []};
+        pending = operation;
+        function cancel() { stopping = true; controller.abort(signal.reason); }
+        signal?.addEventListener('abort', cancel, {once: true});
+        try {
+            if (signal?.aborted) cancel();
+            const length = body.reduce(function frameLength(total, part) { return total + part.length; }, 0);
+            await write(Buffer.from(`${kind}\t${operation.id}\t${length}\t${language ?? ''}\n`));
+            for (const part of body) {
+                signal?.throwIfAborted();
+                await write(part);
+            }
+            const result = await operation.response.promise;
+            signal?.throwIfAborted();
+            return result;
+        } catch (failure) {
+            // A partial command cannot share this pipe with another request.
+            stopping = true;
+            controller.abort(failure);
+            let primary = failure;
+            if (signal?.aborted && expectedCancellation(failure)) primary = signal.reason;
+            try {
+                await completion;
+            } catch (completionFailure) {
+                if (completionFailure !== failure && !expectedCancellation(completionFailure)) {
+                    throw new AggregateError([primary, completionFailure], 'The Kokoro command and helper shutdown failed.', {cause: primary});
+                }
+            }
+            throw primary;
+        } finally {
+            signal?.removeEventListener('abort', cancel);
+            if (pending === operation) pending = null;
+        }
+    }
+
+    function write(value) {
+        if (exited || controller.signal.aborted) return Promise.reject(terminalError ?? controller.signal.reason ?? new Error('The Kokoro helper stopped.'));
+        return new Promise(function writeInput(resolve, reject) {
+            input.write(value, function inputWritten(error) { if (error) reject(error); else resolve(); });
+        });
+    }
+
+    async function phonemize(text, language, {signal} = {}) {
+        if (text.includes('\0')) throw new TypeError('The public eSpeak text interface cannot consume an embedded NUL character.');
+        if (!text.isWellFormed()) throw new TypeError('The public eSpeak UTF-8 interface cannot represent an unpaired Unicode surrogate.');
+        const result = await command('phonemize', [Buffer.from(text, 'utf8')], language, signal);
+        return result.clauses;
+    }
+
+    async function encodeOpus(chunks, {signal} = {}) {
+        const result = await command('opus', chunks.map(floatPCM), null, signal);
+        return Buffer.concat(result.pages);
+    }
+
+    async function close(reason) {
+        stopping = true;
+        if (reason !== undefined) controller.abort(reason);
+        input.end();
+        try { await completion; }
+        catch (failure) {
+            if (!expectedCancellation(failure)) throw failure;
+        }
+    }
+
+    function expectedCancellation(failure) {
+        if (!controller.signal.aborted || failure?.code !== 'ARCANE_CANCELLED') return false;
+        if (is.array(failure.errors) && !failure.errors.every(expectedCancellation)) return false;
+        return failure.cause === controller.signal.reason || expectedCancellation(failure.cause);
+    }
+
+    return {ready: readiness.promise, completion, phonemize, encodeOpus, close,
+        get exited() { return exited; }};
+}
+
+function deferred() {
+    const value = {};
+    value.promise = new Promise(function pending(resolve, reject) { value.resolve = resolve; value.reject = reject; });
+    value.promise.catch(function observePendingFailure() {});
+    return value;
+}