speechflow 1.6.0 → 1.6.1

package/speechflow-cli/src/speechflow-main-cli.ts

@@ -0,0 +1,259 @@
+/*
+**  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 path              from "node:path"
+
+/*  external dependencies  */
+import CLIio             from "cli-io"
+import yargs             from "yargs"
+import { hideBin }       from "yargs/helpers"
+import jsYAML            from "js-yaml"
+import dotenvx           from "@dotenvx/dotenvx"
+import syspath           from "syspath"
+import chalk             from "chalk"
+
+/*  internal dependencies  */
+import * as util         from "./speechflow-util"
+import pkg               from "../../package.json"
+
+/*  command-line options  */
+export interface CLIOptions {
+    V: boolean
+    S: boolean
+    v: string
+    a: string
+    p: number
+    C: string
+    d: string
+    o: string
+    e: string
+    f: string
+    c: string
+    _: (string | number)[]
+}
+
+export class CLIContext {
+    public cli:    CLIio      | null = null
+    public args:   CLIOptions | null = null
+    public config: string     | null = null
+    public debug                     = false
+
+    /*  type guard for initialization  */
+    isInitialized (): this is CLIContext & { cli: CLIio; args: CLIOptions; config: string } {
+        return this.cli !== null && this.args !== null && this.config !== null
+    }
+
+    /*  initialization of CLI  */
+    async init (): Promise<void> {
+        /*  determine system paths  */
+        const { dataDir } = syspath({
+            appName: "speechflow",
+            dataDirAutoCreate: true
+        })
+
+        /*  parse command-line arguments  */
+        const coerce = (arg: string) => Array.isArray(arg) ? arg[arg.length - 1] : arg
+        this.args = await yargs()
+            /* eslint @stylistic/indent: off */
+            .usage(
+                "Usage: $0 " +
+                "[-h|--help] " +
+                "[-V|--version] " +
+                "[-S|--status] " +
+                "[-v|--verbose <level>] " +
+                "[-a|--address <ip-address>] " +
+                "[-p|--port <tcp-port>] " +
+                "[-C|--cache <directory>] " +
+                "[-d|--dashboard <type>:<id>:<name>[,...]] " +
+                "[-o|--osc <ip-address>:<udp-port> " +
+                "[-e|--expression <expression>] " +
+                "[-f|--file <file>] " +
+                "[-c|--config <id>@<yaml-config-file>] " +
+                "[<argument> [...]]"
+            )
+            .version(false)
+            .option("V", {
+                alias:    "version",
+                type:     "boolean",
+                array:    false,
+                coerce,
+                default:  false,
+                describe: "show program version information"
+            })
+            .option("S", {
+                alias:    "status",
+                type:     "boolean",
+                array:    false,
+                coerce,
+                default:  false,
+                describe: "show one-time status of nodes"
+            })
+            .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("a", {
+                alias:    "address",
+                type:     "string",
+                array:    false,
+                coerce,
+                nargs:    1,
+                default:  "0.0.0.0",
+                describe: "IP address for REST/WebSocket API"
+            })
+            .option("p", {
+                alias:    "port",
+                type:     "number",
+                array:    false,
+                coerce,
+                nargs:    1,
+                default:  8484,
+                describe: "TCP port for REST/WebSocket API"
+            })
+            .option("C", {
+                alias:    "cache",
+                type:     "string",
+                array:    false,
+                coerce,
+                nargs:    1,
+                default:  path.join(dataDir, "cache"),
+                describe: "directory for cached files (primarily AI model files)"
+            })
+            .option("d", {
+                alias:    "dashboard",
+                type:     "string",
+                array:    false,
+                coerce,
+                nargs:    1,
+                default:  "",
+                describe: "list of dashboard block types and names"
+            })
+            .option("o", {
+                alias:    "osc",
+                type:     "string",
+                array:    false,
+                coerce,
+                nargs:    1,
+                default:  "",
+                describe: "OSC/UDP endpoint to send dashboard information"
+            })
+            .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)
+            .strict()
+            .demand(0)
+            .parse(hideBin(process.argv)) as CLIOptions
+
+        /*  short-circuit version request  */
+        if (this.args.V) {
+            process.stderr.write(`SpeechFlow ${pkg["x-stdver"]} (${pkg["x-release"]}) <${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  */
+        this.cli = new CLIio({
+            encoding:  "utf8",
+            logLevel:  this.args.v,
+            logTime:   true,
+            logPrefix: pkg.name
+        })
+        if (this.args.v.match(/^(?:info|debug)$/))
+            this.debug = true
+
+        /*  provide startup information  */
+        this.cli.log("info", `starting SpeechFlow ${pkg["x-stdver"]} (${pkg["x-release"]})`)
+
+        /*  load .env files  */
+        const result = dotenvx.config({
+            encoding: "utf8",
+            ignore:   [ "MISSING_ENV_FILE" ],
+            quiet:    true
+        })
+        if (result?.parsed !== undefined)
+            for (const key of Object.keys(result.parsed))
+                this.cli.log("info", `loaded environment variable "${key}" from ".env" files`)
+
+        /*  sanity check configuration situation  */
+        let n = 0
+        if (typeof this.args.e === "string" && this.args.e !== "") n++
+        if (typeof this.args.f === "string" && this.args.f !== "") n++
+        if (typeof this.args.c === "string" && this.args.c !== "") n++
+        if (n === 0)
+            throw new Error("need at least one FlowLink specification source (use one of the options -e, -f or -c)")
+        else if (n !== 1)
+            throw new Error("cannot use more than one FlowLink specification source (use only one of the options -e, -f or -c)")
+
+        /*  read configuration  */
+        if (typeof this.args.e === "string" && this.args.e !== "")
+            this.config = this.args.e
+        else if (typeof this.args.f === "string" && this.args.f !== "")
+            this.config = await this.cli.input(this.args.f, { encoding: "utf8" })
+        else if (typeof this.args.c === "string" && this.args.c !== "") {
+            const m = this.args.c.match(/^(.+?)@(.+)$/)
+            if (m === null)
+                throw new Error("invalid configuration file specification (expected \"<id>@<yaml-config-file>\")")
+            const [ , id, file ] = m
+            const yaml = await this.cli.input(file, { encoding: "utf8" })
+            const obj: any = util.run("parsing YAML configuration", () => jsYAML.load(yaml))
+            if (obj[id] === undefined)
+                throw new Error(`no such id "${id}" found in configuration file "${file}"`)
+            this.config = obj[id] as string
+        }
+    }
+
+    /*  utility function for handling a top-level error  */
+    handleTopLevelError (err: Error): never {
+        if (this.cli !== null) {
+            if (this.debug)
+                this.cli.log("error", `${err.message}\n${err.stack}`)
+            else
+                this.cli.log("error", `${err.message}`)
+        }
+        else {
+            if (this.debug)
+                process.stderr.write(`${pkg.name}: ${chalk.red("ERROR")}: ${err.message}\n${err.stack}\n`)
+            else
+                process.stderr.write(`${pkg.name}: ${chalk.red("ERROR")}: ${err.message}`)
+        }
+        process.exit(1)
+    }
+}

package/speechflow-cli/src/speechflow-main-config.ts

@@ -0,0 +1,17 @@
+/*
+**  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>
+*/
+
+/*  the node configuration  */
+export class NodeConfig {
+    constructor (
+        public readonly audioChannels      = 1,
+        public readonly audioBitDepth      = 16,
+        public readonly audioLittleEndian  = true,
+        public readonly audioSampleRate    = 48000,
+        public readonly textEncoding       = "utf8",
+        public cacheDir                    = ""
+    ) {}
+}

package/speechflow-cli/src/speechflow-main-graph.ts

@@ -0,0 +1,372 @@
+/*
+**  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 { DateTime }          from "luxon"
+import CLIio                 from "cli-io"
+import FlowLink              from "flowlink"
+import objectPath            from "object-path"
+
+/*  internal dependencies  */
+import SpeechFlowNode        from "./speechflow-node"
+import { NodeConfig }        from "./speechflow-main-config"
+import { CLIOptions }        from "./speechflow-main-cli"
+import { APIServer }         from "./speechflow-main-api"
+import * as util             from "./speechflow-util"
+
+/*  the SpeechFlow node graph management  */
+export class NodeGraph {
+    /*  internal state  */
+    private graphNodes    = new Set<SpeechFlowNode>()
+    private activeNodes   = new Set<SpeechFlowNode>()
+    private finishEvents  = new EventEmitter()
+    private timeZero:     DateTime | null = null
+    private shuttingDown  = false
+
+    /*  simple construction  */
+    constructor (
+        private cli:  CLIio,
+        private debug = false
+    ) {}
+
+    /*  get all graph nodes  */
+    getGraphNodes (): Set<SpeechFlowNode> {
+        return this.graphNodes
+    }
+
+    /*  find particular graph node  */
+    findGraphNode (name: string): SpeechFlowNode | undefined {
+        return Array.from(this.graphNodes).find((node) => node.id === name)
+    }
+
+    /*  graph establishment: PASS 1: parse DSL and create and connect nodes  */
+    async createAndConnectNodes (
+        config:    string,
+        nodes:     { [ id: string ]: typeof SpeechFlowNode },
+        cfg:       NodeConfig,
+        variables: { argv: any[], env: any },
+        accessBus: (name: string) => EventEmitter
+    ): Promise<void> {
+        const flowlink = new FlowLink<SpeechFlowNode>({
+            trace: (msg: string) => {
+                this.cli.log("debug", msg)
+            }
+        })
+        const nodeNums = new Map<typeof SpeechFlowNode, number>()
+        let ast: unknown
+        try {
+            ast = flowlink.compile(config)
+        }
+        catch (err) {
+            const errorMsg = err instanceof Error && err.name === "FlowLinkError"
+                ? err.toString() : (err instanceof Error ? err.message : "internal error")
+            this.cli.log("error", `failed to parse SpeechFlow configuration: ${errorMsg}`)
+            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)
+                    this.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 {
+                        const NodeClass = nodes[id]
+                        let num = nodeNums.get(NodeClass) ?? 0
+                        nodeNums.set(NodeClass, ++num)
+                        const name = num === 1 ? id : `${id}:${num}`
+                        node = new NodeClass(name, cfg, opts, args)
+                        node._accessBus = accessBus
+                    }
+                    catch (err) {
+                        /*  fatal error  */
+                        if (err instanceof Error)
+                            this.cli.log("error", `creation of node <${id}> failed: ${err.message}`)
+                        else
+                            this.cli.log("error", `creation of node <${id}> failed: ${err}`)
+                        process.exit(1)
+                    }
+                    const params = Object.keys(node.params).map((key) => {
+                        if (key.match(/key/))
+                            return `${key}: [...]`
+                        else
+                            return `${key}: ${JSON.stringify(node.params[key])}`
+                    }).join(", ")
+                    this.cli.log("info", `create node <${node.id}> (${params})`)
+                    this.graphNodes.add(node)
+                    return node
+                },
+                connectNodes: (node1: SpeechFlowNode, node2: SpeechFlowNode) => {
+                    this.cli.log("info", `connect node <${node1.id}> to node <${node2.id}>`)
+                    node1.connect(node2)
+                }
+            })
+        }
+        catch (err) {
+            const errorMsg = err instanceof Error && err.name === "FlowLinkError"
+                ? err.toString() : (err instanceof Error ? err.message : "internal error")
+            this.cli.log("error", `failed to materialize SpeechFlow configuration: ${errorMsg}`)
+            process.exit(1)
+        }
+    }
+
+    /*  graph establishment: PASS 2: prune connections of nodes  */
+    async pruneConnections () {
+        for (const node of this.graphNodes) {
+            /*  determine connections  */
+            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`)
+
+            /*  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) })
+
+            /*  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 ` +
+                        `connected to ${other.input} input node <${other.id}> (payload is incompatible)`)
+        }
+    }
+
+    /*  graph establishment: PASS 3: open nodes  */
+    async openNodes(): Promise<void> {
+        this.timeZero = DateTime.now()
+        for (const node of this.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)})`
+                this.cli.log(level, str)
+            })
+
+            /*  open node  */
+            this.cli.log("info", `open node <${node.id}>`)
+            node.setTimeZero(this.timeZero)
+            await Promise.race<void>([
+                node.open(),
+                new Promise<never>((resolve, reject) => setTimeout(() =>
+                    reject(new Error("timeout")), 10 * 1000))
+            ]).catch((err: Error) => {
+                this.cli.log("error", `<${node.id}>: failed to open node <${node.id}>: ${err.message}`)
+                throw new Error(`failed to open node <${node.id}>: ${err.message}`)
+            })
+        }
+    }
+
+    /*  graph establishment: PASS 4: connect node streams  */
+    async connectStreams() {
+        for (const node of this.graphNodes) {
+            if (node.stream === null)
+                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`)
+                this.cli.log("info", `connect stream of node <${node.id}> to stream of node <${other.id}>`)
+                if (!( node.stream instanceof Stream.Readable
+                    || node.stream instanceof Stream.Duplex  ))
+                    throw new Error(`stream of output node <${node.id}> is neither of Readable nor Duplex type`)
+                if (!( other.stream instanceof Stream.Writable
+                    || other.stream instanceof Stream.Duplex  ))
+                    throw new Error(`stream of input node <${other.id}> is neither of Writable nor Duplex type`)
+                node.stream.pipe(other.stream)
+            }
+        }
+    }
+
+    /*  graph establishment: PASS 5: track stream finishing  */
+    trackFinishing(args: CLIOptions, api: APIServer): void {
+        this.finishEvents.removeAllListeners()
+        this.finishEvents.setMaxListeners(this.graphNodes.size + 10)
+        for (const node of this.graphNodes) {
+            if (node.stream === null)
+                throw new Error(`stream of node <${node.id}> still not initialized`)
+            this.cli.log("info", `observe stream of node <${node.id}> for finish event`)
+            this.activeNodes.add(node)
+            const deactivateNode = (node: SpeechFlowNode, msg: string) => {
+                if (this.activeNodes.has(node))
+                    this.activeNodes.delete(node)
+                this.cli.log("info", `${msg} (${this.activeNodes.size} active nodes remaining)`)
+                if (this.activeNodes.size === 0) {
+                    const timeFinished = DateTime.now()
+                    const duration = timeFinished.diff(this.timeZero!)
+                    this.cli.log("info", "**** everything finished -- stream processing in SpeechFlow graph stops " +
+                        `(total duration: ${duration.toFormat("hh:mm:ss.SSS")}) ****`)
+                    this.finishEvents.emit("finished")
+                    this.shutdown("finished", args, api)
+                }
+            }
+            node.stream.on("end", () => {
+                deactivateNode(node, `readable stream side of node <${node.id}> raised "end" event`)
+            })
+            node.stream.on("finish", () => {
+                deactivateNode(node, `writable stream side of node <${node.id}> raised "finish" event`)
+            })
+        }
+
+        /*  start of internal stream processing  */
+        this.cli.log("info", "**** everything established -- stream processing in SpeechFlow graph starts ****")
+    }
+
+    /*  graph destruction: PASS 1: disconnect node streams  */
+    async disconnectStreams(): Promise<void> {
+        for (const node of this.graphNodes) {
+            if (node.stream === null) {
+                this.cli.log("warning", `stream of node <${node.id}> no longer initialized`)
+                continue
+            }
+            for (const other of Array.from(node.connectionsOut)) {
+                if (other.stream === null) {
+                    this.cli.log("warning", `stream of incoming node <${other.id}> no longer initialized`)
+                    continue
+                }
+                if (!( node.stream instanceof Stream.Readable
+                    || node.stream instanceof Stream.Duplex  )) {
+                    this.cli.log("warning", `stream of output node <${node.id}> is neither of Readable nor Duplex type`)
+                    continue
+                }
+                if (!( other.stream instanceof Stream.Writable
+                    || other.stream instanceof Stream.Duplex  )) {
+                    this.cli.log("warning", `stream of input node <${other.id}> is neither of Writable nor Duplex type`)
+                    continue
+                }
+                this.cli.log("info", `disconnect stream of node <${node.id}> from stream of node <${other.id}>`)
+                node.stream.unpipe(other.stream)
+            }
+        }
+    }
+
+    /*  graph destruction: PASS 2: close nodes  */
+    async closeNodes(): Promise<void> {
+        for (const node of this.graphNodes) {
+            this.cli.log("info", `close node <${node.id}>`)
+            await Promise.race<void>([
+                node.close(),
+                new Promise<never>((resolve, reject) => setTimeout(() =>
+                    reject(new Error("timeout")), 10 * 1000))
+            ]).catch((err: Error) => {
+                this.cli.log("warning", `node <${node.id}> failed to close: ${err.message}`)
+            })
+        }
+    }
+
+    /*  graph destruction: PASS 3: disconnect nodes  */
+    disconnectNodes(): void {
+        for (const node of this.graphNodes) {
+            this.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) })
+        }
+    }
+
+    /*  graph destruction: PASS 4: destroy nodes  */
+    destroyNodes(): void {
+        for (const node of this.graphNodes) {
+            this.cli.log("info", `destroy node <${node.id}>`)
+            this.graphNodes.delete(node)
+        }
+    }
+
+    /*  setup signal handling for shutdown  */
+    setupSignalHandlers(args: CLIOptions, api: APIServer): void {
+        /*  internal helper functions  */
+        const shutdownHandler = (signal: string) =>
+            this.shutdown(signal, args, api)
+        const logError = (error: Error) => {
+            if (this.debug)
+                this.cli.log("error", `uncaught exception: ${error.message}\n${error.stack}`)
+            else
+                this.cli.log("error", `uncaught exception: ${error.message}`)
+        }
+
+        /*  hook into process signals  */
+        process.on("SIGINT",  () => { shutdownHandler("SIGINT")   })
+        process.on("SIGUSR1", () => { shutdownHandler("SIGUSR1")  })
+        process.on("SIGUSR2", () => { shutdownHandler("SIGUSR2")  })
+        process.on("SIGTERM", () => { shutdownHandler("SIGTERM")  })
+
+        /*  re-hook into uncaught exception handler  */
+        process.removeAllListeners("uncaughtException")
+        process.on("uncaughtException", (err) => {
+            const error = util.ensureError(err, "uncaught exception")
+            logError(error)
+            shutdownHandler("exception")
+        })
+
+        /*  re-hook into unhandled promise rejection handler  */
+        process.removeAllListeners("unhandledRejection")
+        process.on("unhandledRejection", (reason) => {
+            const error = util.ensureError(reason, "unhandled promise rejection")
+            logError(error)
+            shutdownHandler("exception")
+        })
+    }
+
+    /*  shutdown procedure  */
+    async shutdown(signal: string, args: CLIOptions, api: APIServer): Promise<void> {
+        if (this.shuttingDown)
+            return
+        this.shuttingDown = true
+        if (signal === "finished")
+            this.cli.log("info", "**** streams of all nodes finished -- shutting down service ****")
+        else if (signal === "exception")
+            this.cli.log("warning", "**** exception occurred -- shutting down service ****")
+        else
+            this.cli.log("warning", `**** received signal ${signal} -- shutting down service ****`)
+
+        /*  shutdown API service  */
+        await api.stop(args)
+
+        /*  disconnect, close and destroy nodes  */
+        await this.disconnectStreams()
+        await this.closeNodes()
+        this.disconnectNodes()
+        this.destroyNodes()
+
+        /*  clear event emitters  */
+        this.finishEvents.removeAllListeners()
+
+        /*  clear active nodes  */
+        this.activeNodes.clear()
+
+        /*  terminate process  */
+        if (signal === "finished") {
+            this.cli.log("info", "terminate process (exit code 0)")
+            process.exit(0)
+        }
+        else {
+            this.cli.log("info", "terminate process (exit code 1)")
+            process.exit(1)
+        }
+    }
+}