speechflow 0.9.0 → 0.9.2

package/dst/speechflow.js

@@ -8,18 +8,18 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+/*  standard dependencies  */
+const node_stream_1 = __importDefault(require("node:stream"));
+/*  external dependencies  */
 const cli_io_1 = __importDefault(require("cli-io"));
 const yargs_1 = __importDefault(require("yargs"));
 const js_yaml_1 = __importDefault(require("js-yaml"));
 const flowlink_1 = __importDefault(require("flowlink"));
 const object_path_1 = __importDefault(require("object-path"));
-const speechflow_node_file_1 = __importDefault(require("./speechflow-node-file"));
-const speechflow_node_device_1 = __importDefault(require("./speechflow-node-device"));
-const speechflow_node_websocket_1 = __importDefault(require("./speechflow-node-websocket"));
-const speechflow_node_deepgram_1 = __importDefault(require("./speechflow-node-deepgram"));
-const speechflow_node_deepl_1 = __importDefault(require("./speechflow-node-deepl"));
-const speechflow_node_elevenlabs_1 = __importDefault(require("./speechflow-node-elevenlabs"));
+const installed_packages_1 = __importDefault(require("installed-packages"));
+const dotenvx_1 = __importDefault(require("@dotenvx/dotenvx"));
 const package_json_1 = __importDefault(require("../package.json"));
+/*  central CLI context  */
 let cli = null;
 (async () => {
     /*  parse command-line arguments  */
@@ -52,7 +52,7 @@ let cli = null;
         .parse(process.argv.slice(2));
     /*  short-circuit version request  */
     if (args.version) {
-        process.stderr.write(`${package_json_1.default.name} ${package_json_1.default.version} <${package_json_1.default.homepage}>\n`);
+        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`);
         process.stderr.write(`Licensed under ${package_json_1.default.license} <http://spdx.org/licenses/${package_json_1.default.license}.html>\n`);
@@ -65,6 +65,13 @@ let cli = null;
         logTime: true,
         logPrefix: package_json_1.default.name
     });
+    /*  provide startup information  */
+    cli.log("info", `starting SpeechFlow ${package_json_1.default["x-stdver"]} (${package_json_1.default["x-release"]})`);
+    /*  load .env files  */
+    const result = dotenvx_1.default.config({ encoding: "utf8", quiet: true });
+    if (result?.parsed !== undefined)
+        for (const key of Object.keys(result.parsed))
+            cli.log("info", `loaded environment variable "${key}" from ".env" files`);
     /*  handle uncaught exceptions  */
     process.on("uncaughtException", async (err) => {
         cli.log("warning", `process crashed with a fatal error: ${err} ${err.stack}`);
@@ -105,16 +112,47 @@ let cli = null;
             throw new Error(`no such key "${key}" found in configuration file`);
         config = obj[key];
     }
-    /*  configuration of nodes  */
-    const nodes = {
-        "file": speechflow_node_file_1.default,
-        "device": speechflow_node_device_1.default,
-        "websocket": speechflow_node_websocket_1.default,
-        "deepgram": speechflow_node_deepgram_1.default,
-        "deepl": speechflow_node_deepl_1.default,
-        "elevenlabs": speechflow_node_elevenlabs_1.default
-    };
-    /*  parse configuration into node graph  */
+    /*  track the available SpeechFlow nodes  */
+    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",
+    ];
+    for (const pkg of pkgsI) {
+        let node = await import(pkg);
+        while (node.default !== undefined)
+            node = node.default;
+        if (typeof node === "function" && typeof node.name === "string") {
+            cli.log("info", `loading SpeechFlow node "${node.name}" from internal module`);
+            nodes[node.name] = node;
+        }
+    }
+    /*  load external SpeechFlow nodes  */
+    const pkgsE = await (0, installed_packages_1.default)();
+    for (const pkg of pkgsE) {
+        if (pkg.match(/^(?:@[^/]+\/)?speechflow-node-.+$/)) {
+            let node = await import(pkg);
+            while (node.default !== undefined)
+                node = node.default;
+            if (typeof node === "function" && typeof node.name === "string") {
+                if (nodes[node.name] !== undefined) {
+                    cli.log("warning", `failed loading SpeechFlow node "${node.name}" ` +
+                        `from external module "${pkg}" -- node already exists`);
+                    continue;
+                }
+                cli.log("info", `loading SpeechFlow node "${node.name}" from external module "${pkg}"`);
+                nodes[node.name] = node;
+            }
+        }
+    }
+    /*  graph processing: PASS 1: parse DSL and create and connect nodes  */
     const flowlink = new flowlink_1.default({
         trace: (msg) => {
             cli.log("debug", msg);
@@ -133,34 +171,21 @@ let cli = null;
         },
         createNode(id, opts, args) {
             if (nodes[id] === undefined)
-                throw new Error(`unknown SpeechFlow node "${id}"`);
+                throw new Error(`unknown node "${id}"`);
             const node = new nodes[id](`${id}[${nodenum++}]`, opts, args);
-            graphNodes.add(node);
             const params = Object.keys(node.params)
                 .map((key) => `${key}: ${JSON.stringify(node.params[key])}`).join(", ");
-            cli.log("info", `created SpeechFlow node "${node.id}" (${params})`);
+            cli.log("info", `create node "${node.id}" (${params})`);
+            graphNodes.add(node);
             return node;
         },
         connectNode(node1, node2) {
-            cli.log("info", `connect SpeechFlow node "${node1.id}" to node "${node2.id}"`);
+            cli.log("info", `connect node "${node1.id}" to node "${node2.id}"`);
             node1.connect(node2);
         }
     });
-    /*  graph processing: PASS 1: activate and sanity check nodes  */
+    /*  graph processing: PASS 2: prune connections of nodes  */
     for (const node of graphNodes) {
-        /*  connect node events  */
-        node.on("log", (level, msg, data) => {
-            let str = `[${node.id}]: ${msg}`;
-            if (data !== undefined)
-                str += ` (${JSON.stringify(data)})`;
-            cli.log(level, str);
-        });
-        /*  open node  */
-        cli.log("info", `opening node "${node.id}"`);
-        await node.open().catch((err) => {
-            cli.log("error", `[${node.id}]: ${err.message}`);
-            throw new Error(`failed to open node "${node.id}"`);
-        });
         /*  determine connections  */
         const connectionsIn = Array.from(node.connectionsIn);
         const connectionsOut = Array.from(node.connectionsOut);
@@ -176,18 +201,42 @@ let cli = null;
         /*  prune unnecessary outgoing links  */
         if (node.output === "none" && connectionsOut.length > 0)
             connectionsOut.forEach((other) => { node.disconnect(other); });
+        /*  check for payload compatibility  */
+        for (const other of connectionsOut)
+            if (other.input !== node.output)
+                throw new Error(`${node.output} output node "${node.id}" cannot be ` +
+                    `connected to ${other.input} input node "${other.id}" (payload is incompatible)`);
     }
-    /*  graph processing: PASS 2: activate streams  */
+    /*  graph processing: PASS 3: open nodes  */
+    for (const node of graphNodes) {
+        /*  connect node events  */
+        node.on("log", (level, msg, data) => {
+            let str = `[${node.id}]: ${msg}`;
+            if (data !== undefined)
+                str += ` (${JSON.stringify(data)})`;
+            cli.log(level, str);
+        });
+        /*  open node  */
+        cli.log("info", `open node "${node.id}"`);
+        await node.open().catch((err) => {
+            cli.log("error", `[${node.id}]: ${err.message}`);
+            throw new Error(`failed to open node "${node.id}"`);
+        });
+    }
+    /*  graph processing: PASS 4: connect node streams  */
     for (const node of graphNodes) {
         if (node.stream === null)
-            throw new Error(`stream of outgoing node "${node.id}" still not initialized`);
+            throw new Error(`stream of node "${node.id}" still not initialized`);
         for (const other of Array.from(node.connectionsOut)) {
             if (other.stream === null)
                 throw new Error(`stream of incoming node "${other.id}" still not initialized`);
-            if (node.output !== other.input)
-                throw new Error(`${node.output} output node "${node.id}" cannot be " +
-                    "connected to ${other.input} input node "${other.id}" (payload is incompatible)`);
-            cli.log("info", `connecting stream of node "${node.id}" to stream of node "${other.id}"`);
+            cli.log("info", `connect stream of node "${node.id}" to stream of node "${other.id}"`);
+            if (!(node.stream instanceof node_stream_1.default.Readable
+                || node.stream instanceof node_stream_1.default.Duplex))
+                throw new Error(`stream of output node "${node.id}" is neither of Readable nor Duplex type`);
+            if (!(other.stream instanceof node_stream_1.default.Writable
+                || other.stream instanceof node_stream_1.default.Duplex))
+                throw new Error(`stream of input node "${other.id}" is neither of Writable nor Duplex type`);
             node.stream.pipe(other.stream);
         }
     }
@@ -198,14 +247,50 @@ let cli = null;
             return;
         shuttingDown = true;
         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) {
+                cli.log("warning", `stream of node "${node.id}" no longer initialized`);
+                continue;
+            }
+            for (const other of Array.from(node.connectionsOut)) {
+                if (other.stream === null) {
+                    cli.log("warning", `stream of incoming node "${other.id}" no longer initialized`);
+                    continue;
+                }
+                if (!(node.stream instanceof node_stream_1.default.Readable
+                    || node.stream instanceof node_stream_1.default.Duplex)) {
+                    cli.log("warning", `stream of output node "${node.id}" is neither of Readable nor Duplex type`);
+                    continue;
+                }
+                if (!(other.stream instanceof node_stream_1.default.Writable
+                    || other.stream instanceof node_stream_1.default.Duplex)) {
+                    cli.log("warning", `stream of input node "${other.id}" is neither of Writable nor Duplex type`);
+                    continue;
+                }
+                cli.log("info", `disconnect stream of node "${node.id}" from stream of node "${other.id}"`);
+                node.stream.unpipe(other.stream);
+            }
+        }
+        /*  graph processing: PASS 2: close nodes  */
+        for (const node of graphNodes) {
+            cli.log("info", `close node "${node.id}"`);
+            await node.close();
+        }
+        /*  graph processing: PASS 3: disconnect nodes  */
         for (const node of graphNodes) {
-            cli.log("info", `closing node "${node.id}"`);
+            cli.log("info", `disconnect node "${node.id}"`);
             const connectionsIn = Array.from(node.connectionsIn);
             const connectionsOut = Array.from(node.connectionsOut);
             connectionsIn.forEach((other) => { other.disconnect(node); });
             connectionsOut.forEach((other) => { node.disconnect(other); });
-            await node.close();
         }
+        /*  graph processing: PASS 4: shutdown nodes  */
+        for (const node of graphNodes) {
+            cli.log("info", `destroy node "${node.id}"`);
+            graphNodes.delete(node);
+        }
+        /*  terminate process  */
         process.exit(1);
     };
     process.on("SIGINT", () => {

package/etc/tsconfig.json

@@ -14,6 +14,8 @@
         "lib":                     [ "es2022" ],
         "skipLibCheck":            true,
         "noEmit":                  false,
+        "declaration":             true,
+        "emitDeclarationOnly":     false,
         "types":                   [ "node" ],
         "rootDir":                 "../src"
     },

package/package.json

@@ -1,8 +1,8 @@
 {
     "name":                                 "speechflow",
-    "version":                              "0.9.0",
-    "x-stdver":                             "0.9.0-EA",
-    "x-release":                            "2025-04-26",
+    "version":                              "0.9.2",
+    "x-stdver":                             "0.9.1-EA",
+    "x-release":                            "2025-04-27",
     "homepage":                             "https://github.com/rse/speechflow",
     "description":                          "Speech Processing Flow Graph",
     "license":                              "GPL-3.0-only",
@@ -13,7 +13,7 @@
     },
     "repository": {
         "type":                             "git",
-        "url":                              "git+https://github.com/rse/speechflow"
+        "url":                              "git+https://github.com/rse/speechflow.git"
     },
     "dependencies": {
         "cli-io":                           "0.9.13",
@@ -25,7 +25,8 @@
         "deepl-node":                       "1.17.3",
         "elevenlabs":                       "1.57.0",
         "stream-transform":                 "3.3.3",
-        "get-stream":                       "6.0.1",
+        "get-stream":                       "9.0.1",
+        "@dotenvx/dotenvx":                 "1.41.0",
         "speex-resampler":                  "3.0.1",
         "pcm-convert":                      "1.6.5",
         "object-path":                      "0.11.8",
@@ -33,7 +34,10 @@
         "bufferutil":                       "4.0.9",
         "utf-8-validate":                   "6.0.5",
         "@opensumi/reconnecting-websocket": "4.4.0",
-        "get-stream":                       "9.0.1"
+        "ollama":                           "0.5.15",
+        "@rse/ffmpeg":                      "1.4.2",
+        "ffmpeg-stream":                    "1.0.0",
+        "installed-packages":               "1.0.13"
     },
     "devDependencies": {
         "eslint":                           "9.25.1",
@@ -44,8 +48,8 @@
         "eslint-plugin-node":               "11.1.0",
         "@typescript-eslint/eslint-plugin": "8.31.0",
         "@typescript-eslint/parser":        "8.31.0",
-        "oxlint":                           "0.16.7",
-        "eslint-plugin-oxlint":             "0.16.7",
+        "oxlint":                           "0.16.8",
+        "eslint-plugin-oxlint":             "0.16.8",
         "@biomejs/biome":                   "1.9.4",
         "eslint-config-biome":              "1.9.4",
 
@@ -54,6 +58,7 @@
         "@types/js-yaml":                   "4.0.9",
         "@types/object-path":               "0.11.4",
         "@types/ws":                        "8.18.1",
+        "@types/resolve":                   "1.20.6",
 
         "ts-node":                          "10.9.2",
         "stmux":                            "1.8.10",
@@ -65,11 +70,20 @@
         "nps":                              "5.10.0",
         "cross-env":                        "7.0.3"
     },
-    "upd":                                  [ "!get-stream" ],
+    "upd":                                  [],
     "engines": {
-        "node":                             ">=20.6.0"
+        "node":                             ">=22.0.0"
+    },
+    "bin":                                  { "speechflow": "dst/speechflow.js" },
+    "types":                                "./dst/speechflow-node.d.ts",
+    "module":                               "./dst/speechflow-node.js",
+    "main":                                 "./dst/speechflow-node.js",
+    "exports": {
+        ".": {
+            "import":                       { "types": "./dst/speechflow-node.d.ts", "default": "./dst/speechflow-node.js" },
+            "require":                      { "types": "./dst/speechflow-node.d.ts", "default": "./dst/speechflow-node.js" }
+        }
     },
-    "main":                                 "dst/speechflow.js",
     "scripts": {
         "start":                            "nps -c etc/nps.yaml"
     }

package/src/speechflow-node-deepgram.ts

@@ -4,33 +4,51 @@
 **  Licensed under GPL 3.0 <https://spdx.org/licenses/GPL-3.0-only>
 */
 
+/*  standard dependencies  */
 import { EventEmitter } from "node:events"
+
+/*  external dependencies  */
 import Stream           from "node:stream"
 import * as Deepgram    from "@deepgram/sdk"
+
+/*  internal dependencies  */
 import SpeechFlowNode   from "./speechflow-node"
 
-export default class SpeechFlowNodeDevice extends SpeechFlowNode {
+/*  SpeechFlow node for Deepgram speech-to-text conversion  */
+export default class SpeechFlowNodeDeepgram extends SpeechFlowNode {
+    /*  declare official node name  */
+    public static name = "deepgram"
+
+    /*  internal state  */
     private dg: Deepgram.LiveClient | null = null
+
+    /*  construct node  */
     constructor (id: string, opts: { [ id: string ]: any }, args: any[]) {
         super(id, opts, args)
+
+        /*  declare node configuration parameters  */
         this.configure({
             key:      { type: "string", val: process.env.SPEECHFLOW_KEY_DEEPGRAM },
-            model:    { type: "string", val: "nova-2", pos: 0 }, /* FIXME: nova-3 multiligual */
+            model:    { type: "string", val: "nova-3", pos: 0 },
             version:  { type: "string", val: "latest", pos: 1 },
-            language: { type: "string", val: "de",     pos: 2 }
+            language: { type: "string", val: "multi",  pos: 2 }
         })
-    }
-    async open () {
+
+        /*  declare node input/output format  */
         this.input  = "audio"
         this.output = "text"
-        this.stream = null
+    }
 
+    /*  open node  */
+    async open () {
         /*  sanity check situation  */
         if (this.config.audioBitDepth !== 16 || !this.config.audioLittleEndian)
             throw new Error("Deepgram node currently supports PCM-S16LE audio only")
 
-        /*  connect to Deepgram API  */
+        /*  create queue for results  */
         const queue = new EventEmitter()
+
+        /*  connect to Deepgram API  */
         const deepgram = Deepgram.createClient(this.params.key)
         this.dg = deepgram.listen.live({
             model:            this.params.model,
@@ -40,7 +58,7 @@ export default class SpeechFlowNodeDevice extends SpeechFlowNode {
             sample_rate:      this.config.audioSampleRate,
             encoding:         "linear16",
             multichannel:     false,
-            // endpointing:      false,  /* FIXME: ? */
+            endpointing:      10,
             interim_results:  false,
             smart_format:     true,
             punctuate:        true,
@@ -49,33 +67,39 @@ export default class SpeechFlowNodeDevice extends SpeechFlowNode {
             numerals:         true,
             paragraphs:       true,
             profanity_filter: true,
-            utterances:       false,
-        })
-        await new Promise((resolve) => {
-            this.dg!.on(Deepgram.LiveTranscriptionEvents.Open, () => {
-                this.log("info", "Deepgram: connection open")
-                resolve(true)
-            })
+            utterances:       false
         })
 
-        /*  hooks onto Deepgram API events  */
-        this.dg.on(Deepgram.LiveTranscriptionEvents.Close, () => {
-            this.log("info", "Deepgram: connection close")
-        })
+        /*  hook onto Deepgram API events  */
         this.dg.on(Deepgram.LiveTranscriptionEvents.Transcript, async (data) => {
             const text = data.channel?.alternatives[0].transcript ?? ""
             if (text === "")
                 return
             queue.emit("text", text)
         })
+        this.dg.on(Deepgram.LiveTranscriptionEvents.Metadata, (data) => {
+            this.log("info", "Deepgram: metadata received")
+        })
+        this.dg.on(Deepgram.LiveTranscriptionEvents.Close, () => {
+            this.log("info", "Deepgram: connection close")
+        })
         this.dg.on(Deepgram.LiveTranscriptionEvents.Error, (error: Error) => {
-            this.log("error", `Deepgram: ${error}`)
+            this.log("error", `Deepgram: ${error.message}`)
+            this.emit("error")
+        })
+
+        /*  wait for Deepgram API to be available  */
+        await new Promise((resolve) => {
+            this.dg!.once(Deepgram.LiveTranscriptionEvents.Open, () => {
+                this.log("info", "Deepgram: connection open")
+                resolve(true)
+            })
         })
 
         /*  provide Duplex stream and internally attach to Deepgram API  */
         const dg = this.dg
         this.stream = new Stream.Duplex({
-            write (chunk: Buffer, encoding: BufferEncoding, callback: (error?: Error | null | undefined) => void) {
+            write (chunk: Buffer, encoding, callback) {
                 const data = chunk.buffer.slice(chunk.byteOffset, chunk.byteOffset + chunk.byteLength)
                 if (data.byteLength === 0)
                     queue.emit("text", "")
@@ -83,19 +107,26 @@ export default class SpeechFlowNodeDevice extends SpeechFlowNode {
                     dg.send(data)
                 callback()
             },
-            read (size: number) {
+            read (size) {
                 queue.once("text", (text: string) => {
-                    if (text !== "")
-                        this.push(text)
+                    this.push(text)
                 })
+            },
+            final (callback) {
+                dg.requestClose()
             }
         })
     }
+
+    /*  close node  */
     async close () {
+        /*  close stream  */
         if (this.stream !== null) {
             this.stream.destroy()
             this.stream = null
         }
+
+        /*  shutdown Deepgram API  */
         if (this.dg !== null)
             this.dg.requestClose()
     }

package/src/speechflow-node-deepl.ts

@@ -4,44 +4,62 @@
 **  Licensed under GPL 3.0 <https://spdx.org/licenses/GPL-3.0-only>
 */
 
+/*  standard dependencies  */
 import Stream           from "node:stream"
 import { EventEmitter } from "node:events"
-import SpeechFlowNode   from "./speechflow-node"
+
+/*  external dependencies  */
 import * as DeepL       from "deepl-node"
 
+/*  internal dependencies  */
+import SpeechFlowNode   from "./speechflow-node"
+
+/*  SpeechFlow node for DeepL text-to-text translations  */
 export default class SpeechFlowNodeDeepL extends SpeechFlowNode {
-    private translator: DeepL.Translator | null = null
+    /*  declare official node name  */
+    public static name = "deepl"
+
+    /*  internal state  */
+    private deepl: DeepL.Translator | null = null
 
+    /*  construct node  */
     constructor (id: string, opts: { [ id: string ]: any }, args: any[]) {
         super(id, opts, args)
 
-        this.input  = "text"
-        this.output = "text"
-        this.stream = null
-
+        /*  declare node configuration parameters  */
         this.configure({
-            key: { type: "string", val: process.env.SPEECHFLOW_KEY_DEEPL },
-            src: { type: "string", pos: 0, val: "de",    match: /^(?:de|en-US)$/ },
-            dst: { type: "string", pos: 1, val: "en-US", match: /^(?:de|en-US)$/ }
+            key:      { type: "string", val: process.env.SPEECHFLOW_KEY_DEEPL },
+            src:      { type: "string", pos: 0, val: "de",      match: /^(?:de|en-US)$/ },
+            dst:      { type: "string", pos: 1, val: "en-US",   match: /^(?:de|en-US)$/ },
+            optimize: { type: "string", pos: 2, val: "latency", match: /^(?:latency|quality)$/ }
         })
+
+        /*  declare node input/output format  */
+        this.input  = "text"
+        this.output = "text"
     }
 
+    /*  open node  */
     async open () {
         /*  instantiate DeepL API SDK  */
-        this.translator = new DeepL.Translator(this.params.key)
+        this.deepl = new DeepL.Translator(this.params.key)
 
         /*  provide text-to-text translation  */
         const translate = async (text: string) => {
-            const result = await this.translator!.translateText(text, this.params.src, this.params.dst, {
-                splitSentences: "off"
+            const result = await this.deepl!.translateText(text, this.params.src, this.params.dst, {
+                splitSentences: "off",
+                modelType: this.params.optimize === "latency" ?
+                    "latency_optimized" : "prefer_quality_optimized",
+                preserveFormatting: true,
+                formality: "prefer_more"
             })
             return (result?.text ?? text)
         }
 
-        /*  establish a duplex stream and connect it to the translation  */
+        /*  establish a duplex stream and connect it to DeepL translation  */
         const queue = new EventEmitter()
         this.stream = new Stream.Duplex({
-            write (chunk: Buffer, encoding: BufferEncoding, callback: (error?: Error | null | undefined) => void) {
+            write (chunk: Buffer, encoding, callback) {
                 const data = chunk.toString()
                 if (data === "") {
                     queue.emit("result", "")
@@ -64,13 +82,17 @@ export default class SpeechFlowNodeDeepL extends SpeechFlowNode {
         })
     }
 
+    /*  open node  */
     async close () {
+        /*  close stream  */
         if (this.stream !== null) {
             this.stream.destroy()
             this.stream = null
         }
-        if (this.translator !== null)
-            this.translator = null
+
+        /*  shutdown DeepL API  */
+        if (this.deepl !== null)
+            this.deepl = null
     }
 }