speechflow 0.9.7 → 0.9.9

package/dst/speechflow.js

@@ -17,6 +17,7 @@ const node_events_1 = require("node:events");
 const luxon_1 = require("luxon");
 const cli_io_1 = __importDefault(require("cli-io"));
 const yargs_1 = __importDefault(require("yargs"));
+const helpers_1 = require("yargs/helpers");
 const js_yaml_1 = __importDefault(require("js-yaml"));
 const flowlink_1 = __importDefault(require("flowlink"));
 const object_path_1 = __importDefault(require("object-path"));
@@ -33,6 +34,7 @@ let cli = null;
         dataDirAutoCreate: true
     });
     /*  parse command-line arguments  */
+    const coerce = (arg) => Array.isArray(arg) ? arg[arg.length - 1] : arg;
     const args = await (0, yargs_1.default)()
         /* eslint @stylistic/indent: off */
         .usage("Usage: $0 " +
@@ -44,27 +46,68 @@ let cli = null;
         "[-f|--file <file>] " +
         "[-c|--config <id>@<yaml-config-file>] " +
         "[<argument> [...]]")
-        .help("h").alias("h", "help").default("h", false)
-        .describe("h", "show usage help")
-        .boolean("V").alias("V", "version").default("V", false)
-        .describe("V", "show program version information")
-        .string("v").nargs("v", 1).alias("v", "log-level").default("v", "warning")
-        .describe("v", "level for verbose logging ('none', 'error', 'warning', 'info', 'debug')")
-        .string("C").nargs("C", 1).alias("C", "cache").default("C", node_path_1.default.join(dataDir, "cache"))
-        .describe("C", "directory for cached files (primarily AI model files)")
-        .string("e").nargs("e", 1).alias("e", "expression").default("e", "")
-        .describe("e", "FlowLink expression string")
-        .string("f").nargs("f", 1).alias("f", "file").default("f", "")
-        .describe("f", "FlowLink expression file")
-        .string("c").nargs("c", 1).alias("c", "config-file").default("c", "")
-        .describe("c", "FlowLink expression reference into YAML file (in format <id>@<file>)")
+        .option("V", {
+        alias: "version",
+        type: "boolean",
+        array: false,
+        coerce,
+        default: false,
+        describe: "show program version information"
+    })
+        .option("v", {
+        alias: "log-level",
+        type: "string",
+        array: false,
+        coerce,
+        nargs: 1,
+        default: "warning",
+        describe: "level for verbose logging ('none', 'error', 'warning', 'info', 'debug')"
+    })
+        .option("C", {
+        alias: "cache",
+        type: "string",
+        array: false,
+        coerce,
+        nargs: 1,
+        default: node_path_1.default.join(dataDir, "cache"),
+        describe: "directory for cached files (primarily AI model files)"
+    })
+        .option("e", {
+        alias: "expression",
+        type: "string",
+        array: false,
+        coerce,
+        nargs: 1,
+        default: "",
+        describe: "FlowLink expression string"
+    })
+        .option("f", {
+        alias: "file",
+        type: "string",
+        array: false,
+        coerce,
+        nargs: 1,
+        default: "",
+        describe: "FlowLink expression file"
+    })
+        .option("c", {
+        alias: "config",
+        type: "string",
+        array: false,
+        coerce,
+        nargs: 1,
+        default: "",
+        describe: "FlowLink expression reference into YAML file (in format <id>@<file>)"
+    })
+        .help("h", "show usage help")
+        .alias("h", "help")
+        .showHelpOnFail(true)
         .version(false)
         .strict()
-        .showHelpOnFail(true)
         .demand(0)
-        .parse(process.argv.slice(2));
+        .parse((0, helpers_1.hideBin)(process.argv));
     /*  short-circuit version request  */
-    if (args.version) {
+    if (args.V) {
         process.stderr.write(`SpeechFlow ${package_json_1.default["x-stdver"]} (${package_json_1.default["x-release"]}) <${package_json_1.default.homepage}>\n`);
         process.stderr.write(`${package_json_1.default.description}\n`);
         process.stderr.write(`Copyright (c) 2024-2025 ${package_json_1.default.author.name} <${package_json_1.default.author.url}>\n`);
@@ -74,7 +117,7 @@ let cli = null;
     /*  establish CLI environment  */
     cli = new cli_io_1.default({
         encoding: "utf8",
-        logLevel: args.logLevel,
+        logLevel: args.v,
         logTime: true,
         logPrefix: package_json_1.default.name
     });
@@ -100,30 +143,30 @@ let cli = null;
     });
     /*  sanity check usage  */
     let n = 0;
-    if (typeof args.expression === "string" && args.expression !== "")
+    if (typeof args.e === "string" && args.e !== "")
         n++;
-    if (typeof args.expressionFile === "string" && args.expressionFile !== "")
+    if (typeof args.f === "string" && args.f !== "")
         n++;
-    if (typeof args.configFile === "string" && args.configFile !== "")
+    if (typeof args.c === "string" && args.c !== "")
         n++;
     if (n !== 1)
         throw new Error("cannot use more than one FlowLink specification source (either option -e, -f or -c)");
     /*  read configuration  */
     let config = "";
-    if (typeof args.expression === "string" && args.expression !== "")
-        config = args.expression;
-    else if (typeof args.expressionFile === "string" && args.expressionFile !== "")
-        config = await cli.input(args.expressionFile, { encoding: "utf8" });
-    else if (typeof args.configFile === "string" && args.configFile !== "") {
-        const m = args.configFile.match(/^(.+?)@(.+)$/);
+    if (typeof args.e === "string" && args.e !== "")
+        config = args.e;
+    else if (typeof args.f === "string" && args.f !== "")
+        config = await cli.input(args.f, { encoding: "utf8" });
+    else if (typeof args.c === "string" && args.c !== "") {
+        const m = args.c.match(/^(.+?)@(.+)$/);
         if (m === null)
-            throw new Error("invalid configuration file specification (expected \"<key>@<yaml-config-file>\")");
-        const [, key, file] = m;
+            throw new Error("invalid configuration file specification (expected \"<id>@<yaml-config-file>\")");
+        const [, id, file] = m;
         const yaml = await cli.input(file, { encoding: "utf8" });
         const obj = js_yaml_1.default.load(yaml);
-        if (obj[key] === undefined)
-            throw new Error(`no such key "${key}" found in configuration file`);
-        config = obj[key];
+        if (obj[id] === undefined)
+            throw new Error(`no such id "${id}" found in configuration file`);
+        config = obj[id];
     }
     /*  track the available SpeechFlow nodes  */
     const nodes = {};
@@ -133,11 +176,14 @@ let cli = null;
         "./speechflow-node-a2a-wav.js",
         "./speechflow-node-a2t-deepgram.js",
         "./speechflow-node-t2a-elevenlabs.js",
+        "./speechflow-node-t2a-kokoro.js",
         "./speechflow-node-t2t-deepl.js",
-        "./speechflow-node-t2t-format.js",
-        "./speechflow-node-t2t-gemma.js",
+        "./speechflow-node-t2t-openai.js",
+        "./speechflow-node-t2t-ollama.js",
+        "./speechflow-node-t2t-transformers.js",
         "./speechflow-node-t2t-opus.js",
         "./speechflow-node-t2t-subtitle.js",
+        "./speechflow-node-t2t-format.js",
         "./speechflow-node-x2x-trace.js",
         "./speechflow-node-xio-device.js",
         "./speechflow-node-xio-file.js",
@@ -186,7 +232,7 @@ let cli = null;
         audioLittleEndian: true,
         audioSampleRate: 48000,
         textEncoding: "utf8",
-        cacheDir: args.cache
+        cacheDir: args.C
     };
     let ast;
     try {
@@ -240,9 +286,9 @@ let cli = null;
     }
     catch (err) {
         if (err instanceof Error && err.name === "FlowLinkError")
-            cli.log("error", `failed to materialize SpeechFlow configuration: ${err.toString()}"`);
+            cli.log("error", `failed to materialize SpeechFlow configuration: ${err.toString()}`);
         else if (err instanceof Error)
-            cli.log("error", `failed to materialize SpeechFlow configuration: ${err.message}"`);
+            cli.log("error", `failed to materialize SpeechFlow configuration: ${err.message}`);
         else
             cli.log("error", "failed to materialize SpeechFlow configuration: internal error");
         process.exit(1);
@@ -332,7 +378,7 @@ let cli = null;
         });
     }
     /*  start of internal stream processing  */
-    cli.log("info", "everything established -- stream processing in SpeechFlow graph starts");
+    cli.log("info", "**** everything established -- stream processing in SpeechFlow graph starts ****");
     /*  gracefully shutdown process  */
     let shuttingDown = false;
     const shutdown = async (signal) => {
@@ -340,9 +386,9 @@ let cli = null;
             return;
         shuttingDown = true;
         if (signal === "finished")
-            cli.log("info", "streams of all nodes finished -- shutting down service");
+            cli.log("info", "**** streams of all nodes finished -- shutting down service ****");
         else
-            cli.log("warning", `received signal ${signal} -- shutting down service`);
+            cli.log("warning", `**** received signal ${signal} -- shutting down service ****`);
         /*  graph processing: PASS 1: disconnect node streams  */
         for (const node of graphNodes) {
             if (node.stream === null) {

package/etc/speechflow.bat

@@ -0,0 +1,6 @@
+@echo off
+title Speechflow
+"c:\Program Files\nodejs\node.exe" ^
+    .\dst\speechflow.js ^
+    -v info ^
+    -c studio@.\etc\speechflow.yaml

package/etc/speechflow.sh

@@ -0,0 +1,5 @@
+#!/bin/sh
+node \
+   ./dst/speechflow.js \
+   -v info \
+   -c studio@./etc/speechflow.yaml

package/{sample.yaml → etc/speechflow.yaml}

@@ -17,8 +17,8 @@ pass-through: |
         device(device: "wasapi:VoiceMeeter VAIO3 Input", mode: "w")
     }
 
-#   Generate text file with German narration of MP3 audio file
-narration: |
+#   Generate text file with German transcription of MP3 audio file
+transcription: |
     file(path: argv.0, mode: "r", type: "audio") |
         ffmpeg(src: "mp3", dst: "pcm") |
             deepgram(language: "de", key: env.SPEECHFLOW_KEY_DEEPGRAM) |
@@ -39,6 +39,13 @@ translation: |
         deepl(src: "de", dst: "en") |
             file(path: "-", mode: "w", type: "text")
 
+#   Generate audio file with English voice for a text file
+speaking: |
+    file(path: argv.0, mode: "r", type: "text") |
+        kokoro(language: "en") |
+            wav(mode: "encode") |
+                file(path: argv.1, mode: "w", type: "audio")
+
 #  Real-time studio translation from German to English,
 #  including the capturing of all involved inputs and outputs:
 studio: |

package/etc/stx.conf

@@ -48,7 +48,7 @@ server-delay
 
 #   run program
 server
-    node dst/speechflow.js -v info -c studio@sample.yaml
+    node dst/speechflow.js -v info -c studio@etc/speechflow.yaml "$@"
 
 #   run program with file watching
 server-watch

package/package.json

@@ -1,8 +1,8 @@
 {
     "name":                                 "speechflow",
-    "version":                              "0.9.7",
-    "x-stdver":                             "0.9.7-EA",
-    "x-release":                            "2025-07-12",
+    "version":                              "0.9.9",
+    "x-stdver":                             "0.9.9-EA",
+    "x-release":                            "2025-07-13",
     "homepage":                             "https://github.com/rse/speechflow",
     "description":                          "Speech Processing Flow Graph",
     "license":                              "GPL-3.0-only",
@@ -35,6 +35,7 @@
         "utf-8-validate":                   "6.0.5",
         "@opensumi/reconnecting-websocket": "4.4.0",
         "ollama":                           "0.5.16",
+        "openai":                           "5.9.0",
         "@rse/ffmpeg":                      "1.4.2",
         "ffmpeg-stream":                    "1.0.1",
         "installed-packages":               "1.0.13",
@@ -45,10 +46,10 @@
         "pure-uuid":                        "1.8.1",
         "wavefile":                         "11.0.0",
         "@huggingface/transformers":        "3.6.3",
+        "kokoro-js":                        "1.2.1",
         "@ericedouard/vad-node-realtime":   "0.2.0",
         "luxon":                            "3.7.1",
-        "wrap-text":                        "1.0.10",
-        "smart-whisper":                    "0.8.1"
+        "wrap-text":                        "1.0.10"
     },
     "devDependencies": {
         "eslint":                           "9.31.0",
@@ -84,7 +85,7 @@
         "cross-env":                        "7.0.3"
     },
     "overrides": {
-        "onnxruntime-node":                 "1.22.0-dev.20250418-c19a49615b"
+        "@huggingface/transformers":        { "onnxruntime-node": "1.23.0-dev.20250703-7fc6235861" }
     },
     "upd":                                  [ "!@biomejs/biome" ],
     "engines": {

package/src/speechflow-node-t2a-kokoro.ts

@@ -0,0 +1,160 @@
+/*
+**  SpeechFlow - Speech Processing Flow Graph
+**  Copyright (c) 2024-2025 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under GPL 3.0 <https://spdx.org/licenses/GPL-3.0-only>
+*/
+
+/*  standard dependencies  */
+import Stream                from "node:stream"
+
+/*  external dependencies  */
+import { KokoroTTS }         from "kokoro-js"
+import SpeexResampler        from "speex-resampler"
+
+/*  internal dependencies  */
+import SpeechFlowNode, { SpeechFlowChunk } from "./speechflow-node"
+
+/*  SpeechFlow node for Kokoro text-to-speech conversion  */
+export default class SpeechFlowNodeKokoro extends SpeechFlowNode {
+    /*  declare official node name  */
+    public static name = "kokoro"
+
+    /*  internal state  */
+    private kokoro: KokoroTTS | null = null
+    private static speexInitialized = false
+
+    /*  construct node  */
+    constructor (id: string, cfg: { [ id: string ]: any }, opts: { [ id: string ]: any }, args: any[]) {
+        super(id, cfg, opts, args)
+
+        /*  declare node configuration parameters  */
+        this.configure({
+            voice:    { type: "string", val: "Aoede", pos: 0, match: /^(?:Aoede|Heart|Puck|Fenrir)$/ },
+            language: { type: "string", val: "en",    pos: 1, match: /^(?:en)$/ },
+            speed:    { type: "number", val: 1.25,    pos: 2, match: (n: number) => n >= 1.0 && n <= 1.30 },
+        })
+
+        /*  declare node input/output format  */
+        this.input  = "text"
+        this.output = "audio"
+    }
+
+    /*  open node  */
+    async open () {
+        /*  establish Kokoro  */
+        const model = "onnx-community/Kokoro-82M-v1.0-ONNX"
+        const progressState = new Map<string, number>()
+        const progressCallback = (progress: any) => {
+            let artifact = model
+            if (typeof progress.file === "string")
+                artifact += `:${progress.file}`
+            let percent = 0
+            if (typeof progress.loaded === "number" && typeof progress.total === "number")
+                percent = (progress.loaded as number / progress.total as number) * 100
+            else if (typeof progress.progress === "number")
+                percent = progress.progress
+            if (percent > 0)
+                progressState.set(artifact, percent)
+        }
+        const interval = setInterval(() => {
+            for (const [ artifact, percent ] of progressState) {
+                this.log("info", `downloaded ${percent.toFixed(2)}% of artifact "${artifact}"`)
+                if (percent >= 1.0)
+                    progressState.delete(artifact)
+            }
+        }, 1000)
+        this.kokoro = await KokoroTTS.from_pretrained(model, {
+            dtype: "q4f16",
+            progress_callback: progressCallback
+        })
+        clearInterval(interval)
+        if (this.kokoro === null)
+            throw new Error("failed to instantiate Kokoro")
+
+        /*  establish resampler from Kokoro's maximum 24Khz
+            output to our standard audio sample rate (48KHz)  */
+        if (!SpeechFlowNodeKokoro.speexInitialized) {
+            /*  at least once initialize resampler  */
+            await SpeexResampler.initPromise
+            SpeechFlowNodeKokoro.speexInitialized = true
+        }
+        const resampler = new SpeexResampler(1, 24000, this.config.audioSampleRate, 7)
+
+        /*  determine voice for text-to-speech operation  */
+        const voices = {
+            "Aoede":  "af_aoede",
+            "Heart":  "af_heart",
+            "Puck":   "am_puck",
+            "Fenrir": "am_fenrir"
+        }
+        const voice = ((voices as any)[this.params.voice]) as string | undefined
+        if (voice === undefined)
+            throw new Error(`invalid Kokoro voice "${this.params.voice}"`)
+
+        /*  perform text-to-speech operation with Elevenlabs API  */
+        const text2speech = async (text: string) => {
+            this.log("info", `Kokoro: input: "${text}"`)
+            const audio = await this.kokoro!.generate(text, {
+                speed: this.params.speed,
+                voice: voice as any
+            })
+            if (audio.sampling_rate !== 24000)
+                throw new Error("expected 24KHz sampling rate in Kokoro output")
+
+            /*  convert audio samples from PCM/F32/24Khz to PCM/I16/24KHz  */
+            const samples = audio.audio
+            const buffer1 = Buffer.alloc(samples.length * 2)
+            for (let i = 0; i < samples.length; i++) {
+                const sample = Math.max(-1, Math.min(1, samples[i]))
+                buffer1.writeInt16LE(sample * 0x7FFF, i * 2)
+            }
+
+            /*  resample audio samples from PCM/I16/24Khz to PCM/I16/48KHz  */
+            const buffer2 = resampler.processChunk(buffer1)
+
+            return buffer2
+        }
+
+        /*  create transform stream and connect it to the Kokoro API  */
+        const log = (level: string, msg: string) => { this.log(level, msg) }
+        this.stream = new Stream.Transform({
+            writableObjectMode: true,
+            readableObjectMode: true,
+            decodeStrings:      false,
+            transform (chunk: SpeechFlowChunk, encoding, callback) {
+                if (Buffer.isBuffer(chunk.payload))
+                    callback(new Error("invalid chunk payload type"))
+                else {
+                    text2speech(chunk.payload).then((buffer) => {
+                        log("info", `Kokoro: received audio (buffer length: ${buffer.byteLength})`)
+                        chunk = chunk.clone()
+                        chunk.type = "audio"
+                        chunk.payload = buffer
+                        this.push(chunk)
+                        callback()
+                    }).catch((err) => {
+                        callback(err)
+                    })
+                }
+            },
+            final (callback) {
+                this.push(null)
+                callback()
+            }
+        })
+    }
+
+    /*  close node  */
+    async close () {
+        /*  destroy stream  */
+        if (this.stream !== null) {
+            this.stream.destroy()
+            this.stream = null
+        }
+
+        /*  destroy Kokoro API  */
+        if (this.kokoro !== null)
+            this.kokoro = null
+    }
+}
+

package/src/{speechflow-node-t2t-gemma.ts → speechflow-node-t2t-ollama.ts}

@@ -17,10 +17,10 @@ import SpeechFlowNode, { SpeechFlowChunk } from "./speechflow-node"
 type ConfigEntry = { systemPrompt: string, chat: Array<{ role: string, content: string }> }
 type Config      = { [ key: string ]: ConfigEntry }
 
-/*  SpeechFlow node for Gemma/Ollama text-to-text translation  */
-export default class SpeechFlowNodeGemma extends SpeechFlowNode {
+/*  SpeechFlow node for Ollama text-to-text translation  */
+export default class SpeechFlowNodeOllama extends SpeechFlowNode {
     /*  declare official node name  */
-    public static name = "gemma"
+    public static name = "ollama"
 
     /*  internal state  */
     private ollama: Ollama | null = null
@@ -103,7 +103,8 @@ export default class SpeechFlowNodeGemma extends SpeechFlowNode {
                 "Do not show any prolog.\n" +
                 "Do not show any epilog.\n" +
                 "Get to the point.\n" +
-                "Directly translate text from Enlish (EN) to German (DE) language.\n",
+                "Preserve the original meaning, tone, and nuance.\n" +
+                "Directly translate text from English (EN) to fluent and natural German (DE) language.\n",
             chat: [
                 { role: "user",   content: "I love my wife." },
                 { role: "system", content: "Ich liebe meine Frau." },
@@ -121,13 +122,14 @@ export default class SpeechFlowNodeGemma extends SpeechFlowNode {
                 "Output only the requested text.\n" +
                 "Do not use markdown.\n" +
                 "Do not chat.\n" +
-                "Do not show any explanations. \n" +
+                "Do not show any explanations.\n" +
                 "Do not show any introduction.\n" +
                 "Do not show any preamble. \n" +
                 "Do not show any prolog. \n" +
                 "Do not show any epilog. \n" +
                 "Get to the point.\n" +
-                "Directly translate text from German (DE) to English (EN) language.\n",
+                "Preserve the original meaning, tone, and nuance.\n" +
+                "Directly translate text from German (DE) to fluent and natural English (EN) language.\n",
             chat: [
                 { role: "user",   content: "Ich liebe meine Frau." },
                 { role: "system", content: "I love my wife." },
@@ -145,11 +147,19 @@ export default class SpeechFlowNodeGemma extends SpeechFlowNode {
 
         /*  declare node configuration parameters  */
         this.configure({
-            api: { type: "string", val: "http://127.0.0.1:11434", match: /^https?:\/\/.+?:\d+$/ },
-            src: { type: "string", pos: 0, val: "de", match: /^(?:de|en)$/ },
-            dst: { type: "string", pos: 1, val: "en", match: /^(?:de|en)$/ }
+            api:   { type: "string", val: "http://127.0.0.1:11434", match: /^https?:\/\/.+?:\d+$/ },
+            model: { type: "string", val: "gemma3:4b-it-q4_K_M", match: /^.+$/ },
+            src:   { type: "string", pos: 0, val: "de", match: /^(?:de|en)$/ },
+            dst:   { type: "string", pos: 1, val: "en", match: /^(?:de|en)$/ }
         })
 
+        /*  tell effective mode  */
+        if (this.params.src === this.params.dst)
+            this.log("info", `Ollama: operation mode: spellchecking for language "${this.params.src}"`)
+        else
+            this.log("info", `Ollama: operation mode: translation from language "${this.params.src}"` +
+                ` to language "${this.params.dst}"`)
+
         /*  declare node input/output format  */
         this.input  = "text"
         this.output = "text"
@@ -160,12 +170,36 @@ export default class SpeechFlowNodeGemma extends SpeechFlowNode {
         /*  instantiate Ollama API  */
         this.ollama = new Ollama({ host: this.params.api })
 
+        /*  ensure the model is available  */
+        const model  = this.params.model
+        const models = await this.ollama.list()
+        const exists = models.models.some((m) => m.name === model)
+        if (!exists) {
+            this.log("info", `Ollama: model "${model}" still not present in Ollama -- ` +
+                "automatically downloading model")
+            let artifact = ""
+            let percent  = 0
+            const interval = setInterval(() => {
+                this.log("info", `downloaded ${percent.toFixed(2)}% of artifact "${artifact}"`)
+            }, 1000)
+            const progress = await this.ollama.pull({ model, stream: true })
+            for await (const event of progress) {
+                if (event.digest)
+                    artifact = event.digest
+                if (event.completed && event.total)
+                    percent = (event.completed / event.total) * 100
+            }
+            clearInterval(interval)
+        }
+        else
+            this.log("info", `Ollama: model "${model}" already present in Ollama`)
+
         /*  provide text-to-text translation  */
         const translate = async (text: string) => {
             const key = `${this.params.src}-${this.params.dst}`
             const cfg = this.setup[key]
             const response = await this.ollama!.chat({
-                model: "gemma3:4b-it-q4_K_M",
+                model,
                 messages: [
                     { role: "system", content: cfg.systemPrompt },
                     ...cfg.chat,