speechflow 0.9.4 → 0.9.7

package/src/speechflow.ts

@@ -5,9 +5,12 @@
 */
 
 /*  standard dependencies  */
+import path                     from "node:path"
 import Stream                   from "node:stream"
+import { EventEmitter }         from "node:events"
 
 /*  external dependencies  */
+import { DateTime }             from "luxon"
 import CLIio                    from "cli-io"
 import yargs                    from "yargs"
 import jsYAML                   from "js-yaml"
@@ -15,6 +18,7 @@ import FlowLink                 from "flowlink"
 import objectPath               from "object-path"
 import installedPackages        from "installed-packages"
 import dotenvx                  from "@dotenvx/dotenvx"
+import syspath                  from "syspath"
 
 /*  internal dependencies  */
 import SpeechFlowNode           from "./speechflow-node"
@@ -25,6 +29,12 @@ let cli: CLIio | null = null
 
 /*  establish asynchronous environment  */
 ;(async () => {
+    /*  determine system paths  */
+    const { dataDir } = syspath({
+        appName: "speechflow",
+        dataDirAutoCreate: true
+    })
+
     /*  parse command-line arguments  */
     const args = await yargs()
         /* eslint @stylistic/indent: off */
@@ -33,9 +43,10 @@ let cli: CLIio | null = 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)
@@ -44,12 +55,14 @@ let cli: CLIio | null = 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", path.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)
@@ -128,14 +141,20 @@ let cli: CLIio | null = null
 
     /*  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: any = await import(pkg)
@@ -175,35 +194,79 @@ let cli: CLIio | null = null
     let nodenum = 1
     const variables = { argv: args._, env: process.env }
     const graphNodes = new Set<SpeechFlowNode>()
-    flowlink.evaluate(config, {
-        resolveVariable (id: string) {
-            if (!objectPath.has(variables, id))
-                throw new Error(`failed to resolve variable "${id}"`)
-            const value = objectPath.get(variables, id)
-            cli!.log("info", `resolve variable: "${id}" -> "${value}"`)
-            return value
-        },
-        createNode (id: string, opts: { [ id: string ]: any }, args: any[]) {
-            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: SpeechFlowNode, node2: SpeechFlowNode) {
-            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: unknown
+    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: string) {
+                if (!objectPath.has(variables, id))
+                    throw new Error(`failed to resolve variable "${id}"`)
+                const value = objectPath.get(variables, id)
+                cli!.log("info", `resolve variable: "${id}" -> "${value}"`)
+                return value
+            },
+            createNode (id: string, opts: { [ id: string ]: any }, args: any[]) {
+                if (nodes[id] === undefined)
+                    throw new Error(`unknown node "${id}"`)
+                let node: SpeechFlowNode
+                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: SpeechFlowNode, node2: SpeechFlowNode) {
+                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)
@@ -222,6 +285,8 @@ let cli: CLIio | null = null
             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 ` +
@@ -232,7 +297,7 @@ let cli: CLIio | null = null
     for (const node of graphNodes) {
         /*  connect node events  */
         node.on("log", (level: string, msg: string, data?: any) => {
-            let str = `[${node.id}]: ${msg}`
+            let str = `<${node.id}>: ${msg}`
             if (data !== undefined)
                 str += ` (${JSON.stringify(data)})`
             cli!.log(level, str)
@@ -246,7 +311,14 @@ let cli: CLIio | null = null
         })
     }
 
-    /*  graph processing: PASS 4: connect node streams  */
+    /*  graph processing: PASS 4: set time zero in all nodes  */
+    const timeZero = 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`)
@@ -264,13 +336,40 @@ let cli: CLIio | null = null
         }
     }
 
+    /*  graph processing: PASS 6: track stream finishing  */
+    const activeNodes  = new Set<SpeechFlowNode>()
+    const finishEvents = new 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 = 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: string) => {
         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) {
@@ -301,7 +400,9 @@ let cli: CLIio | null = 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  */
@@ -320,8 +421,14 @@ let cli: CLIio | null = null
         }
 
         /*  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/nps.yaml

@@ -1,40 +0,0 @@
-##
-##  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>
-##
-
-scripts:
-    #   multiview-style development dashboard
-    dev: >
-                            stmux -w always -m beep -e "built.in.+ms" --
-                            [ -s 35% "npm start lint-watch" :
-                            -s 15% "npm start build-watch" :
-                            -s 30% "npm start server-delay server-watch" ]
-
-    #   static code analysis (linting)
-    lint-watch:             nodemon --exec "npm start lint" --watch src --ext ts
-    lint:                   npm start lint-tsc lint-oxlint lint-biome lint-eslint
-    lint-tsc:               tsc --project etc/tsconfig.json --noEmit
-    lint-oxlint:            oxlint --config etc/oxlint.jsonc src/**/*.ts
-    lint-biome:             biome lint --diagnostic-level=warn --config-path=etc/biome.jsonc src/*.ts
-    lint-eslint:            eslint --config etc/eslint.mjs src/**/*.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
-    build-watch:            nodemon --exec "npm start build" --watch src --ext ts
-
-    #   start server run-time
-    server-delay:           delay 2.0
-    server:                 node dst/speechflow.js -v info -c sample@sample.yaml
-    server-watch: >
-                            cross-env NODE_OPTIONS="--enable-source-maps"
-                            nodemon --exec "npm start server" --watch dst --ext ts --delay 1.0
-
-    #   cleanup filesystem
-    clean:                  rimraf dst
-    clean-dist:             rimraf dst node_modules
-

package/src/speechflow-node-deepgram.ts

@@ -1,133 +0,0 @@
-/*
-**  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 { EventEmitter } from "node:events"
-
-/*  external dependencies  */
-import Stream           from "node:stream"
-import * as Deepgram    from "@deepgram/sdk"
-
-/*  internal dependencies  */
-import SpeechFlowNode   from "./speechflow-node"
-
-/*  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-3", pos: 0 },
-            version:  { type: "string", val: "latest", pos: 1 },
-            language: { type: "string", val: "multi",  pos: 2 }
-        })
-
-        /*  declare node input/output format  */
-        this.input  = "audio"
-        this.output = "text"
-    }
-
-    /*  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")
-
-        /*  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,
-            version:          this.params.version,
-            language:         this.params.language,
-            channels:         this.config.audioChannels,
-            sample_rate:      this.config.audioSampleRate,
-            encoding:         "linear16",
-            multichannel:     false,
-            endpointing:      10,
-            interim_results:  false,
-            smart_format:     true,
-            punctuate:        true,
-            filler_words:     true,
-            diarize:          true,
-            numerals:         true,
-            paragraphs:       true,
-            profanity_filter: true,
-            utterances:       false
-        })
-
-        /*  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.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, callback) {
-                const data = chunk.buffer.slice(chunk.byteOffset, chunk.byteOffset + chunk.byteLength)
-                if (data.byteLength === 0)
-                    queue.emit("text", "")
-                else
-                    dg.send(data)
-                callback()
-            },
-            read (size) {
-                queue.once("text", (text: string) => {
-                    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-elevenlabs.ts

@@ -1,116 +0,0 @@
-/*
-**  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"
-import { EventEmitter }      from "node:events"
-
-/*  external dependencies  */
-import * as ElevenLabs       from "elevenlabs"
-import { getStreamAsBuffer } from "get-stream"
-
-/*  internal dependencies  */
-import SpeechFlowNode        from "./speechflow-node"
-
-/*
-const elevenlabsVoices = {
-    "drew":    { name: "Drew",    model: "eleven_multilingual_v2", lang: [ "en", "de" ] },
-    "george":  { name: "George",  model: "eleven_multilingual_v2", lang: [ "en", "de" ] },
-    "bill":    { name: "Bill",    model: "eleven_multilingual_v2", lang: [ "en", "de" ] },
-    "daniel":  { name: "Daniel",  model: "eleven_multilingual_v1", lang: [ "en", "de" ] },
-    "brian":   { name: "Brian",   model: "eleven_turbo_v2",        lang: [ "en"       ] },
-    "sarah":   { name: "Sarah",   model: "eleven_multilingual_v2", lang: [ "en", "de" ] },
-    "racel":   { name: "Racel",   model: "eleven_multilingual_v2", lang: [ "en", "de" ] },
-    "grace":   { name: "Grace",   model: "eleven_multilingual_v1", lang: [ "en", "de" ] },
-    "matilda": { name: "Matilda", model: "eleven_multilingual_v1", lang: [ "en", "de" ] },
-    "alice":   { name: "Alice",   model: "eleven_turbo_v2",        lang: [ "en"       ] }
-}
-*/
-
-export default class SpeechFlowNodeElevenlabs extends SpeechFlowNode {
-    /*  declare official node name  */
-    public static name = "elevenlabs"
-
-    /*  internal state  */
-    private elevenlabs: ElevenLabs.ElevenLabsClient | 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_ELEVENLABS },
-            voice:    { type: "string", val: "Brian",  pos: 0 },
-            language: { type: "string", val: "de",     pos: 1 }
-        })
-
-        /*  declare node input/output format  */
-        this.input  = "text"
-        this.output = "audio"
-    }
-
-    /*  open node  */
-    async open () {
-        this.elevenlabs = new ElevenLabs.ElevenLabsClient({
-            apiKey: this.params.key
-        })
-        const voices = await this.elevenlabs.voices.getAll()
-        const voice = voices.voices.find((voice) => voice.name === this.params.voice)
-        if (voice === undefined)
-            throw new Error(`invalid ElevenLabs voice "${this.params.voice}"`)
-        const speechStream = (text: string) => {
-            return this.elevenlabs!.textToSpeech.convert(voice.voice_id, {
-                text,
-                optimize_streaming_latency: 2,
-                output_format: "pcm_16000", // S16LE
-                model_id: "eleven_flash_v2_5",
-                /*
-                voice_settings: {
-                    stability: 0,
-                    similarity_boost: 0
-                }
-                */
-            }, {
-                timeoutInSeconds: 30,
-                maxRetries: 10
-            })
-        }
-        const queue = new EventEmitter()
-        this.stream = new Stream.Duplex({
-            write (chunk: Buffer, encoding: BufferEncoding, callback: (error?: Error | null | undefined) => void) {
-                if (encoding !== "utf8" && encoding !== "utf-8")
-                    callback(new Error("only text input supported by Elevenlabs node"))
-                const data = chunk.toString()
-                speechStream(data).then((stream) => {
-                    getStreamAsBuffer(stream).then((buffer) => {
-                        queue.emit("audio", buffer)
-                        callback()
-                    }).catch((error) => {
-                        callback(error)
-                    })
-                }).catch((error) => {
-                    callback(error)
-                })
-            },
-            read (size: number) {
-                queue.once("audio", (buffer: Buffer) => {
-                    this.push(buffer, "binary")
-                })
-            }
-        })
-    }
-
-    /*  close node  */
-    async close () {
-        /*  destroy stream  */
-        if (this.stream !== null) {
-            this.stream.destroy()
-            this.stream = null
-        }
-    }
-}
-