speechflow 0.9.4 → 0.9.7

package/dst/speechflow-utils.js

@@ -0,0 +1,194 @@
+"use strict";
+/*
+**  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>
+*/
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DoubleQueue = exports.SingleQueue = void 0;
+exports.audioBufferDuration = audioBufferDuration;
+exports.createTransformStreamForWritableSide = createTransformStreamForWritableSide;
+exports.createTransformStreamForReadableSide = createTransformStreamForReadableSide;
+exports.ensureStreamChunk = ensureStreamChunk;
+exports.streamChunkEncode = streamChunkEncode;
+exports.streamChunkDecode = streamChunkDecode;
+/*  external dependencies  */
+const node_stream_1 = __importDefault(require("node:stream"));
+const node_events_1 = require("node:events");
+const luxon_1 = require("luxon");
+const cbor2_1 = __importDefault(require("cbor2"));
+/*  internal dependencies  */
+const speechflow_node_1 = require("./speechflow-node");
+/*  calculate duration of an audio buffer  */
+function audioBufferDuration(buffer, sampleRate = 48000, bitDepth = 16, channels = 1, littleEndian = true) {
+    if (!Buffer.isBuffer(buffer))
+        throw new Error("invalid input (Buffer expected)");
+    if (littleEndian !== true)
+        throw new Error("only Little Endian supported");
+    const bytesPerSample = bitDepth / 8;
+    const totalSamples = buffer.length / (bytesPerSample * channels);
+    return totalSamples / sampleRate;
+}
+/*  create a Duplex/Transform stream which has
+    object-mode on Writable side and buffer/string-mode on Readable side  */
+function createTransformStreamForWritableSide() {
+    return new node_stream_1.default.Transform({
+        readableObjectMode: true,
+        writableObjectMode: true,
+        decodeStrings: false,
+        transform(chunk, encoding, callback) {
+            this.push(chunk.payload);
+            callback();
+        }
+    });
+}
+/*  create a Duplex/Transform stream which has
+    object-mode on Readable side and buffer/string-mode on Writable side  */
+function createTransformStreamForReadableSide(type, getTimeZero) {
+    return new node_stream_1.default.Transform({
+        readableObjectMode: true,
+        writableObjectMode: true,
+        decodeStrings: false,
+        transform(chunk, encoding, callback) {
+            const timeZero = getTimeZero();
+            const start = luxon_1.DateTime.now().diff(timeZero);
+            let end = start;
+            if (type === "audio") {
+                const duration = audioBufferDuration(chunk);
+                end = start.plus(duration * 1000);
+            }
+            const obj = new speechflow_node_1.SpeechFlowChunk(start, end, "final", type, chunk);
+            this.push(obj);
+            callback();
+        }
+    });
+}
+/*  ensure a chunk is of a certain type and format  */
+function ensureStreamChunk(type, chunk) {
+    if (chunk instanceof speechflow_node_1.SpeechFlowChunk) {
+        if (chunk.type !== type)
+            throw new Error(`invalid payload chunk (expected ${type} type, received ${chunk.type} type)`);
+    }
+    else {
+        if (type === "text" && Buffer.isBuffer(chunk))
+            chunk = chunk.toString("utf8");
+        else if (type === "audio" && !Buffer.isBuffer(chunk))
+            chunk = Buffer.from(chunk);
+    }
+    return chunk;
+}
+/*  encode/serialize chunk of data  */
+function streamChunkEncode(chunk) {
+    let payload;
+    if (Buffer.isBuffer(chunk.payload))
+        payload = new Uint8Array(chunk.payload);
+    else {
+        const encoder = new TextEncoder();
+        payload = encoder.encode(chunk.payload);
+    }
+    const data = {
+        timestampStart: chunk.timestampStart.toMillis(),
+        timestampEnd: chunk.timestampEnd.toMillis(),
+        kind: chunk.kind,
+        type: chunk.type,
+        payload
+    };
+    const _data = cbor2_1.default.encode(data);
+    return _data;
+}
+/*  decode/unserialize chunk of data  */
+function streamChunkDecode(_data) {
+    let data;
+    try {
+        data = cbor2_1.default.decode(_data);
+    }
+    catch (err) {
+        throw new Error(`CBOR decoding failed: ${err}`);
+    }
+    let payload;
+    if (data.type === "audio")
+        payload = Buffer.from(data.payload);
+    else
+        payload = (new TextDecoder()).decode(data.payload);
+    const chunk = new speechflow_node_1.SpeechFlowChunk(luxon_1.Duration.fromMillis(data.timestampStart), luxon_1.Duration.fromMillis(data.timestampEnd), data.kind, data.type, payload);
+    return chunk;
+}
+/*  helper class for single item queue  */
+class SingleQueue extends node_events_1.EventEmitter {
+    queue = new Array();
+    write(item) {
+        this.queue.unshift(item);
+        this.emit("dequeue");
+    }
+    read() {
+        return new Promise((resolve, reject) => {
+            const consume = () => {
+                if (this.queue.length > 0)
+                    return this.queue.pop();
+                else
+                    return null;
+            };
+            let item = consume();
+            if (item !== null)
+                resolve(item);
+            else {
+                const tryToConsume = () => {
+                    item = consume();
+                    if (item !== null)
+                        resolve(item);
+                    else
+                        this.once("dequeue", tryToConsume);
+                };
+                this.once("dequeue", tryToConsume);
+            }
+        });
+    }
+}
+exports.SingleQueue = SingleQueue;
+/*  helper class for double-item queue  */
+class DoubleQueue extends node_events_1.EventEmitter {
+    queue0 = new Array();
+    queue1 = new Array();
+    notify() {
+        if (this.queue0.length > 0 && this.queue1.length > 0)
+            this.emit("dequeue");
+    }
+    write0(item) {
+        this.queue0.unshift(item);
+        this.notify();
+    }
+    write1(item) {
+        this.queue1.unshift(item);
+        this.notify();
+    }
+    read() {
+        return new Promise((resolve, reject) => {
+            const consume = () => {
+                if (this.queue0.length > 0 && this.queue1.length > 0) {
+                    const item0 = this.queue0.pop();
+                    const item1 = this.queue1.pop();
+                    return [item0, item1];
+                }
+                else
+                    return null;
+            };
+            let items = consume();
+            if (items !== null)
+                resolve(items);
+            else {
+                const tryToConsume = () => {
+                    items = consume();
+                    if (items !== null)
+                        resolve(items);
+                    else
+                        this.once("dequeue", tryToConsume);
+                };
+                this.once("dequeue", tryToConsume);
+            }
+        });
+    }
+}
+exports.DoubleQueue = DoubleQueue;

package/dst/speechflow.js

@@ -10,8 +10,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 /*  standard dependencies  */
+const node_path_1 = __importDefault(require("node:path"));
 const node_stream_1 = __importDefault(require("node:stream"));
+const node_events_1 = require("node:events");
 /*  external dependencies  */
+const luxon_1 = require("luxon");
 const cli_io_1 = __importDefault(require("cli-io"));
 const yargs_1 = __importDefault(require("yargs"));
 const js_yaml_1 = __importDefault(require("js-yaml"));
@@ -19,10 +22,16 @@ const flowlink_1 = __importDefault(require("flowlink"));
 const object_path_1 = __importDefault(require("object-path"));
 const installed_packages_1 = __importDefault(require("installed-packages"));
 const dotenvx_1 = __importDefault(require("@dotenvx/dotenvx"));
+const syspath_1 = __importDefault(require("syspath"));
 const package_json_1 = __importDefault(require("../package.json"));
 /*  central CLI context  */
 let cli = null;
 (async () => {
+    /*  determine system paths  */
+    const { dataDir } = (0, syspath_1.default)({
+        appName: "speechflow",
+        dataDirAutoCreate: true
+    });
     /*  parse command-line arguments  */
     const args = await (0, yargs_1.default)()
         /* eslint @stylistic/indent: off */
@@ -30,9 +39,10 @@ let cli = null;
         "[-h|--help] " +
         "[-V|--version] " +
         "[-v|--verbose <level>] " +
+        "[-C|--cache <directory>] " +
         "[-e|--expression <expression>] " +
-        "[-f|--expression-file <expression-file>] " +
-        "[-c|--config <key>@<yaml-config-file>] " +
+        "[-f|--file <file>] " +
+        "[-c|--config <id>@<yaml-config-file>] " +
         "[<argument> [...]]")
         .help("h").alias("h", "help").default("h", false)
         .describe("h", "show usage help")
@@ -40,12 +50,14 @@ let cli = null;
         .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("f").nargs("f", 1).alias("f", "expression-file").default("f", "")
+        .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", "configuration in format <id>@<file>")
+        .describe("c", "FlowLink expression reference into YAML file (in format <id>@<file>)")
         .version(false)
         .strict()
         .showHelpOnFail(true)
@@ -117,14 +129,20 @@ let cli = null;
     const nodes = {};
     /*  load internal SpeechFlow nodes  */
     const pkgsI = [
-        "./speechflow-node-file.js",
-        "./speechflow-node-device.js",
-        "./speechflow-node-websocket.js",
-        "./speechflow-node-ffmpeg.js",
-        "./speechflow-node-deepgram.js",
-        "./speechflow-node-deepl.js",
-        "./speechflow-node-elevenlabs.js",
-        "./speechflow-node-gemma.js",
+        "./speechflow-node-a2a-ffmpeg.js",
+        "./speechflow-node-a2a-wav.js",
+        "./speechflow-node-a2t-deepgram.js",
+        "./speechflow-node-t2a-elevenlabs.js",
+        "./speechflow-node-t2t-deepl.js",
+        "./speechflow-node-t2t-format.js",
+        "./speechflow-node-t2t-gemma.js",
+        "./speechflow-node-t2t-opus.js",
+        "./speechflow-node-t2t-subtitle.js",
+        "./speechflow-node-x2x-trace.js",
+        "./speechflow-node-xio-device.js",
+        "./speechflow-node-xio-file.js",
+        "./speechflow-node-xio-mqtt.js",
+        "./speechflow-node-xio-websocket.js"
     ];
     for (const pkg of pkgsI) {
         let node = await import(pkg);
@@ -162,34 +180,78 @@ let cli = null;
     let nodenum = 1;
     const variables = { argv: args._, env: process.env };
     const graphNodes = new Set();
-    flowlink.evaluate(config, {
-        resolveVariable(id) {
-            if (!object_path_1.default.has(variables, id))
-                throw new Error(`failed to resolve variable "${id}"`);
-            const value = object_path_1.default.get(variables, id);
-            cli.log("info", `resolve variable: "${id}" -> "${value}"`);
-            return value;
-        },
-        createNode(id, opts, args) {
-            if (nodes[id] === undefined)
-                throw new Error(`unknown node "${id}"`);
-            const node = new nodes[id](`${id}[${nodenum++}]`, opts, args);
-            const params = Object.keys(node.params)
-                .map((key) => `${key}: ${JSON.stringify(node.params[key])}`).join(", ");
-            cli.log("info", `create node "${node.id}" (${params})`);
-            graphNodes.add(node);
-            return node;
-        },
-        connectNode(node1, node2) {
-            cli.log("info", `connect node "${node1.id}" to node "${node2.id}"`);
-            node1.connect(node2);
-        }
-    });
+    const cfg = {
+        audioChannels: 1,
+        audioBitDepth: 16,
+        audioLittleEndian: true,
+        audioSampleRate: 48000,
+        textEncoding: "utf8",
+        cacheDir: args.cache
+    };
+    let ast;
+    try {
+        ast = flowlink.compile(config);
+    }
+    catch (err) {
+        if (err instanceof Error && err.name === "FlowLinkError")
+            cli.log("error", `failed to parse SpeechFlow configuration: ${err.toString()}"`);
+        else if (err instanceof Error)
+            cli.log("error", `failed to parse SpeechFlow configuration: ${err.message}"`);
+        else
+            cli.log("error", "failed to parse SpeechFlow configuration: internal error");
+        process.exit(1);
+    }
+    try {
+        flowlink.execute(ast, {
+            resolveVariable(id) {
+                if (!object_path_1.default.has(variables, id))
+                    throw new Error(`failed to resolve variable "${id}"`);
+                const value = object_path_1.default.get(variables, id);
+                cli.log("info", `resolve variable: "${id}" -> "${value}"`);
+                return value;
+            },
+            createNode(id, opts, args) {
+                if (nodes[id] === undefined)
+                    throw new Error(`unknown node "${id}"`);
+                let node;
+                try {
+                    node = new nodes[id](`${id}[${nodenum}]`, cfg, opts, args);
+                }
+                catch (err) {
+                    /*  fatal error  */
+                    if (err instanceof Error)
+                        cli.log("error", `creation of "${id}[${nodenum}]" node failed: ${err.message}`);
+                    else
+                        cli.log("error", `creation of "${id}"[${nodenum}] node failed: ${err}`);
+                    process.exit(1);
+                }
+                nodenum++;
+                const params = Object.keys(node.params)
+                    .map((key) => `${key}: ${JSON.stringify(node.params[key])}`).join(", ");
+                cli.log("info", `create node "${node.id}" (${params})`);
+                graphNodes.add(node);
+                return node;
+            },
+            connectNode(node1, node2) {
+                cli.log("info", `connect node "${node1.id}" to node "${node2.id}"`);
+                node1.connect(node2);
+            }
+        });
+    }
+    catch (err) {
+        if (err instanceof Error && err.name === "FlowLinkError")
+            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}"`);
+        else
+            cli.log("error", "failed to materialize SpeechFlow configuration: internal error");
+        process.exit(1);
+    }
     /*  graph processing: PASS 2: prune connections of nodes  */
     for (const node of graphNodes) {
         /*  determine connections  */
-        const connectionsIn = Array.from(node.connectionsIn);
-        const connectionsOut = Array.from(node.connectionsOut);
+        let connectionsIn = Array.from(node.connectionsIn);
+        let connectionsOut = Array.from(node.connectionsOut);
         /*  ensure necessary incoming links  */
         if (node.input !== "none" && connectionsIn.length === 0)
             throw new Error(`node "${node.id}" requires input but has no input nodes connected`);
@@ -203,6 +265,8 @@ let cli = null;
         if (node.output === "none" && connectionsOut.length > 0)
             connectionsOut.forEach((other) => { node.disconnect(other); });
         /*  check for payload compatibility  */
+        connectionsIn = Array.from(node.connectionsIn);
+        connectionsOut = Array.from(node.connectionsOut);
         for (const other of connectionsOut)
             if (other.input !== node.output)
                 throw new Error(`${node.output} output node "${node.id}" cannot be ` +
@@ -212,7 +276,7 @@ let cli = null;
     for (const node of graphNodes) {
         /*  connect node events  */
         node.on("log", (level, msg, data) => {
-            let str = `[${node.id}]: ${msg}`;
+            let str = `<${node.id}>: ${msg}`;
             if (data !== undefined)
                 str += ` (${JSON.stringify(data)})`;
             cli.log(level, str);
@@ -224,7 +288,13 @@ let cli = null;
             throw new Error(`failed to open node "${node.id}"`);
         });
     }
-    /*  graph processing: PASS 4: connect node streams  */
+    /*  graph processing: PASS 4: set time zero in all nodes  */
+    const timeZero = luxon_1.DateTime.now();
+    for (const node of graphNodes) {
+        cli.log("info", `set time zero in node "${node.id}"`);
+        node.setTimeZero(timeZero);
+    }
+    /*  graph processing: PASS 5: connect node streams  */
     for (const node of graphNodes) {
         if (node.stream === null)
             throw new Error(`stream of node "${node.id}" still not initialized`);
@@ -241,13 +311,38 @@ let cli = null;
             node.stream.pipe(other.stream);
         }
     }
+    /*  graph processing: PASS 6: track stream finishing  */
+    const activeNodes = new Set();
+    const finishEvents = new node_events_1.EventEmitter();
+    for (const node of graphNodes) {
+        if (node.stream === null)
+            throw new Error(`stream of node "${node.id}" still not initialized`);
+        cli.log("info", `observe stream of node "${node.id}" for finish event`);
+        activeNodes.add(node);
+        node.stream.on("finish", () => {
+            activeNodes.delete(node);
+            cli.log("info", `stream of node "${node.id}" finished (${activeNodes.size} nodes remaining active)`);
+            if (activeNodes.size === 0) {
+                const timeFinished = luxon_1.DateTime.now();
+                const duration = timeFinished.diff(timeZero);
+                cli.log("info", "everything finished -- stream processing in SpeechFlow graph stops " +
+                    `(total duration: ${duration.toFormat("hh:mm:ss.SSS")})`);
+                finishEvents.emit("finished");
+            }
+        });
+    }
+    /*  start of internal stream processing  */
+    cli.log("info", "everything established -- stream processing in SpeechFlow graph starts");
     /*  gracefully shutdown process  */
     let shuttingDown = false;
     const shutdown = async (signal) => {
         if (shuttingDown)
             return;
         shuttingDown = true;
-        cli.log("warning", `received signal ${signal} -- shutting down service`);
+        if (signal === "finished")
+            cli.log("info", "streams of all nodes finished -- shutting down service");
+        else
+            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) {
@@ -276,7 +371,9 @@ let cli = null;
         /*  graph processing: PASS 2: close nodes  */
         for (const node of graphNodes) {
             cli.log("info", `close node "${node.id}"`);
-            await node.close();
+            await node.close().catch((err) => {
+                cli.log("warning", `node "${node.id}" failed to close: ${err}`);
+            });
         }
         /*  graph processing: PASS 3: disconnect nodes  */
         for (const node of graphNodes) {
@@ -292,8 +389,14 @@ let cli = null;
             graphNodes.delete(node);
         }
         /*  terminate process  */
-        process.exit(1);
+        if (signal === "finished")
+            process.exit(0);
+        else
+            process.exit(1);
     };
+    finishEvents.on("finished", () => {
+        shutdown("finished");
+    });
     process.on("SIGINT", () => {
         shutdown("SIGINT");
     });

package/etc/biome.jsonc

@@ -5,11 +5,16 @@
 */
 
 {
+    "root": false,
     "formatter": {
         "enabled": false
     },
-    "organizeImports": {
-        "enabled": false
+    "assist": {
+        "actions": {
+            "source": {
+                "organizeImports": "off"
+            }
+        }
     },
     "linter": {
         "enabled": true,
@@ -28,8 +33,11 @@
             },
             "suspicious": {
                 "noExplicitAny": "off",
-                "noAssignInExpressions": "off",
-                "useValidTypeof": "off"
+                "noAssignInExpressions": "off"
+            },
+            "correctness": {
+                "useValidTypeof": "off",
+                "noUnusedFunctionParameters": "off"
             }
         }
     }

package/etc/stx.conf

@@ -0,0 +1,65 @@
+##
+##  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>
+##
+
+#   make patches
+patch-make
+    npm shrinkwrap && \
+    patch-package --patch-dir package.d "@ericedouard/vad-node-realtime" && \
+    shx rm -f npm-shrinkwrap.json
+
+#   [INTERNAL] apply patches
+patch-apply
+    patch-package --patch-dir package.d
+
+#   multiview-style development dashboard
+dev
+    stmux -w always -m beep -e "built.in.+ms" -- \
+    [ -s 35% "stx lint-watch" : \
+    -s 15% "stx build-watch" : \
+    -s 30% "stx server-delay server-watch" ]
+
+#   static code analysis (linting)
+lint:
+    tsc --project etc/tsconfig.json --noEmit && \
+    oxlint --config etc/oxlint.jsonc src/**/*.ts && \
+    biome lint --diagnostic-level=warn --config-path=etc/biome.jsonc src/*.ts && \
+    eslint --config etc/eslint.mjs src/**/*.ts
+
+#   static code analysis (linting) with file watching
+lint-watch
+    nodemon --exec "stx lint" --watch src --ext ts
+
+#   code compilation/transpiling (building)
+build
+    tsc --project etc/tsconfig.json && \
+    (echo "#!/usr/bin/env node"; cat dst/speechflow.js) >dst/speechflow.js.new && \
+    mv dst/speechflow.js.new dst/speechflow.js
+
+#   code compilation/transpiling (building) with file watching
+build-watch
+    nodemon --exec "stx build" --watch src --ext ts
+
+#   [INTERNAL] wait for server
+server-delay
+    delay 2.0
+
+#   run program
+server
+    node dst/speechflow.js -v info -c studio@sample.yaml
+
+#   run program with file watching
+server-watch
+    cross-env NODE_OPTIONS="--enable-source-maps" \
+         nodemon --exec "stx server" --watch dst --ext ts --delay 1.0
+
+#   remove all files regularly generated
+clean
+    shx rm -rf dst
+
+#   remove all files generated
+clean-dist : clean
+    shx rm -rf node_modules
+

package/package.d/@ericedouard+vad-node-realtime+0.2.0.patch

@@ -0,0 +1,18 @@
+diff --git a/node_modules/@ericedouard/vad-node-realtime/dist/common/models/v5.js b/node_modules/@ericedouard/vad-node-realtime/dist/common/models/v5.js
+index 4a75457..e3a4e9a 100644
+--- a/node_modules/@ericedouard/vad-node-realtime/dist/common/models/v5.js
++++ b/node_modules/@ericedouard/vad-node-realtime/dist/common/models/v5.js
+@@ -39,13 +39,11 @@ class SileroV5 {
+ exports.SileroV5 = SileroV5;
+ _a = SileroV5;
+ SileroV5.new = async (ortInstance, modelFetcher) => {
+-    logging_1.log.debug("Loading VAD...");
+     const modelArrayBuffer = await modelFetcher();
+     const _session = await ortInstance.InferenceSession.create(modelArrayBuffer);
+     // @ts-ignore
+     const _sr = new ortInstance.Tensor("int64", [16000n]);
+     const _state = getNewState(ortInstance);
+-    logging_1.log.debug("...finished loading VAD");
+     return new _a(_session, _state, _sr, ortInstance);
+ };
+ //# sourceMappingURL=v5.js.map