arcane-os 0.92.0 → 0.94.0

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;
+}