speechflow 0.9.0

package/src/speechflow-node.ts

@@ -0,0 +1,76 @@
+/*
+**  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>
+*/
+
+import Events  from "node:events"
+import Stream  from "node:stream"
+
+export default class SpeechFlowNode extends Events.EventEmitter {
+    public config = {
+        audioChannels:     1,      /* audio mono channel       */
+        audioBitDepth:     16,     /* audio PCM 16-bit integer */
+        audioLittleEndian: true,   /* audio PCM little-endian  */
+        audioSampleRate:   48000,  /* audio 48kHz sample rate  */
+        textEncoding:      "utf8"  /* UTF-8 text encoding      */
+    } as const
+    public input  = "none"
+    public output = "none"
+    public params = {} as { [ id: string ]: any }
+    public stream: Stream.Writable | Stream.Readable | Stream.Duplex | null = null
+
+    public connectionsIn  = new Set<SpeechFlowNode>()
+    public connectionsOut = new Set<SpeechFlowNode>()
+
+    constructor (
+        public id: string,
+        private opts: { [ id: string ]: any },
+        private args: any[]
+    ) {
+        super()
+    }
+
+    configure (spec: { [ id: string ]: { type: string, pos?: number, val?: any, match?: RegExp } }) {
+        for (const name of Object.keys(spec)) {
+            if (this.opts[name] !== undefined) {
+                if (typeof this.opts[name] !== spec[name].type)
+                    throw new Error(`invalid type of option "${name}"`)
+                if ("match" in spec[name] && this.opts[name].match(spec[name].match) === null)
+                    throw new Error(`invalid value of option "${name}" (has to match ${spec[name].match})`)
+                this.params[name] = this.opts[name]
+            }
+            else if (this.opts[name] === undefined
+                && "pos" in spec[name]
+                && spec[name].pos! < this.args.length) {
+                if (typeof this.args[spec[name].pos!] !== spec[name].type)
+                    throw new Error(`invalid type of argument "${name}"`)
+                if ("match" in spec[name] && this.args[spec[name].pos!].match(spec[name].match) === null)
+                    throw new Error(`invalid value of option "${name}" (has to match ${spec[name].match})`)
+                this.params[name] = this.args[spec[name].pos!]
+            }
+            else if ("val" in spec[name] && spec[name].val !== undefined)
+                this.params[name] = spec[name].val
+            else
+                throw new Error(`required parameter "${name}" not given`)
+        }
+    }
+    connect (other: SpeechFlowNode) {
+        this.connectionsOut.add(other)
+        other.connectionsIn.add(this)
+    }
+    disconnect (other: SpeechFlowNode) {
+        if (!this.connectionsOut.has(other))
+            throw new Error("invalid node: not connected to this node")
+        this.connectionsOut.delete(other)
+        other.connectionsIn.delete(this)
+    }
+    log (level: string, msg: string, data?: any) {
+        this.emit("log", level, msg, data)
+    }
+    async open () {
+    }
+    async close () {
+    }
+}
+

package/src/speechflow-util.ts

@@ -0,0 +1,36 @@
+/*
+**  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>
+*/
+
+import PortAudio from "@gpeng/naudiodon"
+
+export default class SpeechFlowUtil {
+    static audioDeviceFromURL (mode: "any" | "r" | "w" | "rw", url: string) {
+        const m = url.match(/^(.+?):(.+)$/)
+        if (m === null)
+            throw new Error(`invalid audio device URL "${url}"`)
+        const [ , type, name ] = m
+        const apis = PortAudio.getHostAPIs()
+        const api = apis.HostAPIs.find((api) => api.type.toLowerCase() === type.toLowerCase())
+        if (!api)
+            throw new Error(`invalid audio device type "${type}"`)
+        const devices = PortAudio.getDevices()
+        console.log(devices)
+        const device = devices.find((device) => {
+            return (
+                (   (   mode === "r"   && device.maxInputChannels  > 0)
+                    || (mode === "w"   && device.maxOutputChannels > 0)
+                    || (mode === "rw"  && device.maxInputChannels  > 0 && device.maxOutputChannels > 0)
+                    || (mode === "any" && (device.maxInputChannels  > 0 || device.maxOutputChannels > 0)))
+                && device.name.match(name)
+                && device.hostAPIName === api.name
+            )
+        })
+        if (!device)
+            throw new Error(`invalid audio device name "${name}" (of audio type "${type}")`)
+        return device
+    }
+}
+

package/src/speechflow.ts

@@ -0,0 +1,242 @@
+/*
+**  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>
+*/
+
+import Stream                   from "node:stream"
+
+import CLIio                    from "cli-io"
+import yargs                    from "yargs"
+import jsYAML                   from "js-yaml"
+import FlowLink                 from "flowlink"
+import objectPath               from "object-path"
+
+import SpeechFlowNode           from "./speechflow-node"
+import SpeechFlowNodeFile       from "./speechflow-node-file"
+import SpeechFlowNodeDevice     from "./speechflow-node-device"
+import SpeechFlowNodeWebsocket  from "./speechflow-node-websocket"
+import SpeechFlowNodeDeepgram   from "./speechflow-node-deepgram"
+import SpeechFlowNodeDeepL      from "./speechflow-node-deepl"
+import SpeechFlowNodeElevenLabs from "./speechflow-node-elevenlabs"
+
+import pkg                      from "../package.json"
+
+let cli: CLIio | null = null
+;(async () => {
+    /*  parse command-line arguments  */
+    const args = await yargs()
+        /* eslint @stylistic/indent: off */
+        .usage(
+            "Usage: $0 " +
+            "[-h|--help] " +
+            "[-V|--version] " +
+            "[-v|--verbose <level>] " +
+            "[-e|--expression <expression>] " +
+            "[-f|--expression-file <expression-file>] " +
+            "[-c|--config <key>@<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("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("f", "FlowLink expression file")
+        .string("c").nargs("c", 1).alias("c", "config-file").default("c", "")
+            .describe("c", "configuration in format <id>@<file>")
+        .version(false)
+        .strict()
+        .showHelpOnFail(true)
+        .demand(0)
+        .parse(process.argv.slice(2))
+
+    /*  short-circuit version request  */
+    if (args.version) {
+        process.stderr.write(`${pkg.name} ${pkg.version} <${pkg.homepage}>\n`)
+        process.stderr.write(`${pkg.description}\n`)
+        process.stderr.write(`Copyright (c) 2024-2025 ${pkg.author.name} <${pkg.author.url}>\n`)
+        process.stderr.write(`Licensed under ${pkg.license} <http://spdx.org/licenses/${pkg.license}.html>\n`)
+        process.exit(0)
+    }
+
+    /*  establish CLI environment  */
+    cli = new CLIio({
+        encoding:  "utf8",
+        logLevel:  args.logLevel,
+        logTime:   true,
+        logPrefix: pkg.name
+    })
+
+    /*  handle uncaught exceptions  */
+    process.on("uncaughtException", async (err: Error) => {
+        cli!.log("warning", `process crashed with a fatal error: ${err} ${err.stack}`)
+        process.exit(1)
+    })
+
+    /*  handle unhandled promise rejections  */
+    process.on("unhandledRejection", async (reason, promise) => {
+        if (reason instanceof Error)
+            cli!.log("error", `promise rejection not handled: ${reason.message}: ${reason.stack}`)
+        else
+            cli!.log("error", `promise rejection not handled: ${reason}`)
+        process.exit(1)
+    })
+
+    /*  sanity check usage  */
+    let n = 0
+    if (typeof args.expression     === "string" && args.expression     !== "") n++
+    if (typeof args.expressionFile === "string" && args.expressionFile !== "") n++
+    if (typeof args.configFile     === "string" && args.configFile     !== "") 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 (m === null)
+            throw new Error("invalid configuration file specification (expected \"<key>@<yaml-config-file>\")")
+        const [ , key, file ] = m
+        const yaml = await cli.input(file, { encoding: "utf8" })
+        const obj: any = jsYAML.load(yaml)
+        if (obj[key] === undefined)
+            throw new Error(`no such key "${key}" found in configuration file`)
+        config = obj[key] as string
+    }
+
+    /*  configuration of nodes  */
+    const nodes: { [ id: string ]: typeof SpeechFlowNode } = {
+        "file":       SpeechFlowNodeFile,
+        "device":     SpeechFlowNodeDevice,
+        "websocket":  SpeechFlowNodeWebsocket,
+        "deepgram":   SpeechFlowNodeDeepgram,
+        "deepl":      SpeechFlowNodeDeepL,
+        "elevenlabs": SpeechFlowNodeElevenLabs
+    }
+
+    /*  parse configuration into node graph  */
+    const flowlink = new FlowLink<SpeechFlowNode>({
+        trace: (msg: string) => {
+            cli!.log("debug", msg)
+        }
+    })
+    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 SpeechFlow 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})`)
+            return node
+        },
+        connectNode (node1: SpeechFlowNode, node2: SpeechFlowNode) {
+            cli!.log("info", `connect SpeechFlow node "${node1.id}" to node "${node2.id}"`)
+            node1.connect(node2)
+        }
+    })
+
+    /*  graph processing: PASS 1: activate and sanity check nodes  */
+    for (const node of graphNodes) {
+        /*  connect node events  */
+        node.on("log", (level: string, msg: string, data?: any) => {
+            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: Error) => {
+            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)
+
+        /*  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`)
+
+        /*  prune unnecessary incoming links  */
+        if (node.input === "none" && connectionsIn.length > 0)
+            connectionsIn.forEach((other) => { other.disconnect(node) })
+
+        /*  ensure necessary outgoing links  */
+        if (node.output !== "none" && connectionsOut.length === 0)
+            throw new Error(`node "${node.id}" requires output but has no output nodes connected`)
+
+        /*  prune unnecessary outgoing links  */
+        if (node.output === "none" && connectionsOut.length > 0)
+            connectionsOut.forEach((other) => { node.disconnect(other) })
+    }
+
+    /*  graph processing: PASS 2: activate streams  */
+    for (const node of graphNodes) {
+        if (node.stream === null)
+            throw new Error(`stream of outgoing 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}"`)
+            node.stream.pipe(other.stream as Stream.Writable)
+        }
+    }
+
+    /*  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`)
+        for (const node of graphNodes) {
+            cli!.log("info", `closing 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()
+        }
+        process.exit(1)
+    }
+    process.on("SIGINT", () => {
+        shutdown("SIGINT")
+    })
+    process.on("SIGTERM", () => {
+        shutdown("SIGTERM")
+    })
+})().catch((err: Error) => {
+    if (cli !== null)
+        cli.log("error", err.message)
+    else
+        process.stderr.write(`${pkg.name}: ERROR: ${err.message}\n`)
+    process.exit(1)
+})
+

package/tsconfig.json

@@ -0,0 +1,3 @@
+{
+    "extends": "./etc/tsconfig.json"
+}