speechflow 0.9.5 → 0.9.7

package/src/speechflow-node-t2t-subtitle.ts

@@ -0,0 +1,101 @@
+/*
+**  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"
+
+/*  internal dependencies  */
+import SpeechFlowNode, { SpeechFlowChunk } from "./speechflow-node"
+
+/*  SpeechFlow node for subtitle (text-to-text) "translations"  */
+export default class SpeechFlowNodeSubtitle extends SpeechFlowNode {
+    /*  declare official node name  */
+    public static name = "subtitle"
+
+    /*  internal state  */
+    private sequenceNo = 1
+
+    /*  construct node  */
+    constructor (id: string, cfg: { [ id: string ]: any }, opts: { [ id: string ]: any }, args: any[]) {
+        super(id, cfg, opts, args)
+
+        /*  declare node configuration parameters  */
+        this.configure({
+            format:   { type: "string", pos: 0, val: "srt", match: /^(?:srt|vtt)$/ }
+        })
+
+        /*  declare node input/output format  */
+        this.input  = "text"
+        this.output = "text"
+    }
+
+    /*  open node  */
+    async open () {
+        this.sequenceNo = 1
+
+        /*  provide text-to-subtitle conversion  */
+        const convert = async (chunk: SpeechFlowChunk) => {
+            if (typeof chunk.payload !== "string")
+                throw new Error("chunk payload type must be string")
+            let text = chunk.payload
+            if (this.params.format === "srt") {
+                const start = chunk.timestampStart.toFormat("hh:mm:ss,SSS")
+                const end   = chunk.timestampEnd.toFormat("hh:mm:ss,SSS")
+                text = `${this.sequenceNo++}\n` +
+                    `${start} --> ${end}\n` +
+                    `${text}\n\n`
+            }
+            else if (this.params.format === "vtt") {
+                const start = chunk.timestampStart.toFormat("hh:mm:ss.SSS")
+                const end   = chunk.timestampEnd.toFormat("hh:mm:ss.SSS")
+                text = `${this.sequenceNo++}\n` +
+                    `${start} --> ${end}\n` +
+                    `${text}\n\n`
+            }
+            return text
+        }
+
+        /*  establish a duplex stream  */
+        this.stream = new Stream.Transform({
+            readableObjectMode: true,
+            writableObjectMode: true,
+            decodeStrings:      false,
+            transform (chunk: SpeechFlowChunk, encoding, callback) {
+                if (Buffer.isBuffer(chunk.payload))
+                    callback(new Error("invalid chunk payload type"))
+                else {
+                    if (chunk.payload === "") {
+                        this.push(chunk)
+                        callback()
+                    }
+                    else {
+                        convert(chunk).then((payload) => {
+                            const chunkNew = chunk.clone()
+                            chunkNew.payload = payload
+                            this.push(chunkNew)
+                            callback()
+                        }).catch((err) => {
+                            callback(err)
+                        })
+                    }
+                }
+            },
+            final (callback) {
+                this.push(null)
+                callback()
+            }
+        })
+    }
+
+    /*  open node  */
+    async close () {
+        /*  close stream  */
+        if (this.stream !== null) {
+            this.stream.destroy()
+            this.stream = null
+        }
+    }
+}

package/src/speechflow-node-x2x-trace.ts

@@ -0,0 +1,92 @@
+/*
+**  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 { Duration } from "luxon"
+
+/*  internal dependencies  */
+import SpeechFlowNode, { SpeechFlowChunk } from "./speechflow-node"
+
+/*  SpeechFlow node for data flow tracing  */
+export default class SpeechFlowNodeTrace extends SpeechFlowNode {
+    /*  declare official node name  */
+    public static name = "trace"
+
+    /*  construct node  */
+    constructor (id: string, cfg: { [ id: string ]: any }, opts: { [ id: string ]: any }, args: any[]) {
+        super(id, cfg, opts, args)
+
+        /*  declare node configuration parameters  */
+        this.configure({
+            type: { type: "string", pos: 0, val: "audio", match: /^(?:audio|text)$/ },
+            name: { type: "string", pos: 1 }
+        })
+
+        /*  declare node input/output format  */
+        this.input  = this.params.type
+        this.output = this.params.type
+    }
+
+    /*  open node  */
+    async open () {
+        /*  wrapper for local logging  */
+        const log = (level: string, msg: string) => {
+            if (this.params.name !== undefined)
+                this.log(level, `[${this.params.name}]: ${msg}`)
+            else
+                this.log(level, msg)
+        }
+
+        /*  provide Duplex stream and internally attach to Deepgram API  */
+        const type = this.params.type
+        this.stream = new Stream.Transform({
+            writableObjectMode: true,
+            readableObjectMode: true,
+            decodeStrings:      false,
+            transform (chunk: SpeechFlowChunk, encoding, callback) {
+                let error: Error | undefined
+                const fmt = (t: Duration) => t.toFormat("hh:mm:ss.SSS")
+                if (Buffer.isBuffer(chunk.payload)) {
+                    if (type === "audio")
+                        log("info", `writing ${type} chunk: start=${fmt(chunk.timestampStart)} ` +
+                            `end=${fmt(chunk.timestampEnd)} kind=${chunk.kind} type=${chunk.type} ` +
+                            `payload-type=Buffer payload-bytes=${chunk.payload.byteLength}`)
+                    else
+                        error = new Error(`writing ${type} chunk: seen Buffer instead of String chunk type`)
+                }
+                else {
+                    if (type === "text")
+                        log("info", `writing ${type} chunk: start=${fmt(chunk.timestampStart)} ` +
+                            `end=${fmt(chunk.timestampEnd)} kind=${chunk.kind} type=${chunk.type}` +
+                            `payload-type=String payload-length=${chunk.payload.length} ` +
+                            `payload-encoding=${encoding} payload-content="${chunk.payload.toString()}"`)
+                    else
+                        error = new Error(`writing ${type} chunk: seen String instead of Buffer chunk type`)
+                }
+                if (error !== undefined)
+                    callback(error)
+                else {
+                    this.push(chunk, encoding)
+                    callback()
+                }
+            },
+            final (callback) {
+                this.push(null)
+                callback()
+            }
+        })
+    }
+
+    /*  close node  */
+    async close () {
+        /*  close stream  */
+        if (this.stream !== null) {
+            this.stream.destroy()
+            this.stream = null
+        }
+    }
+}

package/src/{speechflow-node-device.ts → speechflow-node-xio-device.ts}

@@ -12,6 +12,7 @@ import PortAudio        from "@gpeng/naudiodon"
 
 /*  internal dependencies  */
 import SpeechFlowNode   from "./speechflow-node"
+import * as utils       from "./speechflow-utils"
 
 /*  SpeechFlow node for device access  */
 export default class SpeechFlowNodeDevice extends SpeechFlowNode {
@@ -19,11 +20,14 @@ export default class SpeechFlowNodeDevice extends SpeechFlowNode {
     public static name = "device"
 
     /*  internal state  */
-    private io: PortAudio.IoStreamRead | PortAudio.IoStreamWrite | PortAudio.IoStreamDuplex | null = null
+    private io: PortAudio.IoStreamRead
+        | PortAudio.IoStreamWrite
+        | PortAudio.IoStreamDuplex
+        | null = null
 
     /*  construct node  */
-    constructor (id: string, opts: { [ id: string ]: any }, args: any[]) {
-        super(id, opts, args)
+    constructor (id: string, cfg: { [ id: string ]: any }, opts: { [ id: string ]: any }, args: any[]) {
+        super(id, cfg, opts, args)
 
         /*  declare node configuration parameters  */
         this.configure({
@@ -62,6 +66,9 @@ export default class SpeechFlowNodeDevice extends SpeechFlowNode {
 
         /*  determine device of audio API  */
         const devices = PortAudio.getDevices()
+        for (const device of devices)
+            this.log("info", `found audio device "${device.name}" ` +
+                `(inputs: ${device.maxInputChannels}, outputs: ${device.maxOutputChannels}`)
         const device = devices.find((device) => {
             return (
                 (   (   mode === "r"   && device.maxInputChannels  > 0)
@@ -115,6 +122,11 @@ export default class SpeechFlowNodeDevice extends SpeechFlowNode {
                 }
             })
             this.stream = this.io as unknown as Stream.Duplex
+
+            /*  convert regular stream into object-mode stream  */
+            const wrapper1 = utils.createTransformStreamForWritableSide()
+            const wrapper2 = utils.createTransformStreamForReadableSide("audio", () => this.timeZero)
+            this.stream = Stream.compose(wrapper1, this.stream, wrapper2)
         }
         else if (this.params.mode === "r") {
             /*  input device  */
@@ -130,6 +142,11 @@ export default class SpeechFlowNodeDevice extends SpeechFlowNode {
                 }
             })
             this.stream = this.io as unknown as Stream.Readable
+
+            /*  convert regular stream into object-mode stream  */
+            const wrapper = utils.createTransformStreamForReadableSide("audio", () => this.timeZero)
+            this.stream.pipe(wrapper)
+            this.stream = wrapper
         }
         else if (this.params.mode === "w") {
             /*  output device  */
@@ -145,6 +162,11 @@ export default class SpeechFlowNodeDevice extends SpeechFlowNode {
                 }
             })
             this.stream = this.io as unknown as Stream.Writable
+
+            /*  convert regular stream into object-mode stream  */
+            const wrapper = utils.createTransformStreamForWritableSide()
+            wrapper.pipe(this.stream)
+            this.stream = wrapper
         }
         else
             throw new Error(`device "${device.id}" does not have any input or output channels`)

package/src/speechflow-node-xio-file.ts

@@ -0,0 +1,153 @@
+/*
+**  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 fs               from "node:fs"
+import Stream           from "node:stream"
+
+/*  internal dependencies  */
+import SpeechFlowNode   from "./speechflow-node"
+import * as utils       from "./speechflow-utils"
+
+/*  SpeechFlow node for file access  */
+export default class SpeechFlowNodeFile extends SpeechFlowNode {
+    /*  declare official node name  */
+    public static name = "file"
+
+    /*  construct node  */
+    constructor (id: string, cfg: { [ id: string ]: any }, opts: { [ id: string ]: any }, args: any[]) {
+        super(id, cfg, opts, args)
+
+        /*  declare node configuration parameters  */
+        this.configure({
+            path: { type: "string", pos: 0 },
+            mode: { type: "string", pos: 1, val: "r",     match: /^(?:r|w|rw)$/ },
+            type: { type: "string", pos: 2, val: "audio", match: /^(?:audio|text)$/ }
+        })
+
+        /*  declare node input/output format  */
+        if (this.params.mode === "rw") {
+            this.input  = this.params.type
+            this.output = this.params.type
+        }
+        else if (this.params.mode === "r") {
+            this.input  = "none"
+            this.output = this.params.type
+        }
+        else if (this.params.mode === "w") {
+            this.input  = this.params.type
+            this.output = "none"
+        }
+    }
+
+    /*  open node  */
+    async open () {
+        if (this.params.mode === "rw") {
+            if (this.params.path === "-") {
+                /*  standard I/O  */
+                if (this.params.type === "audio") {
+                    process.stdin.setEncoding()
+                    process.stdout.setEncoding()
+                }
+                else {
+                    process.stdin.setEncoding(this.config.textEncoding)
+                    process.stdout.setEncoding(this.config.textEncoding)
+                }
+                this.stream = Stream.Duplex.from({
+                    readable: process.stdin,
+                    writable: process.stdout
+                })
+            }
+            else {
+                /*  file I/O  */
+                if (this.params.type === "audio") {
+                    this.stream = Stream.Duplex.from({
+                        readable: fs.createReadStream(this.params.path),
+                        writable: fs.createWriteStream(this.params.path)
+                    })
+                }
+                else {
+                    this.stream = Stream.Duplex.from({
+                        readable: fs.createReadStream(this.params.path,
+                            { encoding: this.config.textEncoding }),
+                        writable: fs.createWriteStream(this.params.path,
+                            { encoding: this.config.textEncoding })
+                    })
+                }
+            }
+
+            /*  convert regular stream into object-mode stream  */
+            const wrapper1 = utils.createTransformStreamForWritableSide()
+            const wrapper2 = utils.createTransformStreamForReadableSide(this.params.type, () => this.timeZero)
+            this.stream = Stream.compose(wrapper1, this.stream, wrapper2)
+        }
+        else if (this.params.mode === "r") {
+            if (this.params.path === "-") {
+                /*  standard I/O  */
+                if (this.params.type === "audio")
+                    process.stdin.setEncoding()
+                else
+                    process.stdin.setEncoding(this.config.textEncoding)
+                this.stream = process.stdin
+            }
+            else {
+                /*  file I/O  */
+                if (this.params.type === "audio")
+                    this.stream = fs.createReadStream(this.params.path)
+                else
+                    this.stream = fs.createReadStream(this.params.path,
+                        { encoding: this.config.textEncoding })
+            }
+
+            /*  convert regular stream into object-mode stream  */
+            const wrapper = utils.createTransformStreamForReadableSide(this.params.type, () => this.timeZero)
+            this.stream.pipe(wrapper)
+            this.stream = wrapper
+        }
+        else if (this.params.mode === "w") {
+            if (this.params.path === "-") {
+                /*  standard I/O  */
+                if (this.params.type === "audio")
+                    process.stdout.setEncoding()
+                else
+                    process.stdout.setEncoding(this.config.textEncoding)
+                this.stream = process.stdout
+            }
+            else {
+                /*  file I/O  */
+                if (this.params.type === "audio")
+                    this.stream = fs.createWriteStream(this.params.path)
+                else
+                    this.stream = fs.createWriteStream(this.params.path,
+                        { encoding: this.config.textEncoding })
+            }
+
+            /*  convert regular stream into object-mode stream  */
+            const wrapper = utils.createTransformStreamForWritableSide()
+            wrapper.pipe(this.stream as Stream.Writable)
+            this.stream = wrapper
+        }
+        else
+            throw new Error(`invalid file mode "${this.params.mode}"`)
+    }
+
+    /*  close node  */
+    async close () {
+        /*  shutdown stream  */
+        if (this.stream !== null) {
+            await new Promise<void>((resolve) => {
+                if (this.stream instanceof Stream.Writable || this.stream instanceof Stream.Duplex)
+                    this.stream.end(() => { resolve() })
+                else
+                    resolve()
+            })
+            if (this.params.path !== "-")
+                this.stream.destroy()
+            this.stream = null
+        }
+    }
+}
+

package/src/speechflow-node-xio-mqtt.ts

@@ -0,0 +1,154 @@
+/*
+**  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"
+
+/*  external dependencies  */
+import MQTT                            from "mqtt"
+import UUID                            from "pure-uuid"
+
+/*  internal dependencies  */
+import SpeechFlowNode, { SpeechFlowChunk } from "./speechflow-node"
+import * as utils                          from "./speechflow-utils"
+
+/*  SpeechFlow node for MQTT networking  */
+export default class SpeechFlowNodeMQTT extends SpeechFlowNode {
+    /*  declare official node name  */
+    public static name = "mqtt"
+
+    /*  internal state  */
+    private broker: MQTT.MqttClient | null = null
+    private clientId: string = (new UUID(1)).format()
+
+    /*  construct node  */
+    constructor (id: string, cfg: { [ id: string ]: any }, opts: { [ id: string ]: any }, args: any[]) {
+        super(id, cfg, opts, args)
+
+        /*  declare node configuration parameters  */
+        this.configure({
+            url:        { type: "string", pos: 0, val: "",     match: /^(?:|(?:ws|mqtt):\/\/(.+?):(\d+)(?:\/.*)?)$/ },
+            username:   { type: "string", pos: 1, val: "",     match: /^.+$/ },
+            password:   { type: "string", pos: 2, val: "",     match: /^.+$/ },
+            topicRead:  { type: "string", pos: 3, val: "",     match: /^.+$/ },
+            topicWrite: { type: "string", pos: 4, val: "",     match: /^.+$/ },
+            mode:       { type: "string", pos: 5, val: "w",    match: /^(?:r|w|rw)$/ },
+            type:       { type: "string", pos: 6, val: "text", match: /^(?:audio|text)$/ }
+        })
+
+        /*  logical parameter sanity check  */
+        if ((this.params.mode === "w" || this.params.mode === "rw") && this.params.topicWrite === "")
+            throw new Error("writing to MQTT requires a topicWrite parameter")
+        if ((this.params.mode === "r" || this.params.mode === "rw") && this.params.topicRead === "")
+            throw new Error("reading from MQTT requires a topicRead parameter")
+
+        /*  declare node input/output format  */
+        if (this.params.mode === "rw") {
+            this.input  = this.params.type
+            this.output = this.params.type
+        }
+        else if (this.params.mode === "r") {
+            this.input  = "none"
+            this.output = this.params.type
+        }
+        else if (this.params.mode === "w") {
+            this.input  = this.params.type
+            this.output = "none"
+        }
+    }
+
+    /*  open node  */
+    async open () {
+        /*  connect remotely to a MQTT broker  */
+        this.broker = MQTT.connect(this.params.url, {
+            protocolId:      "MQTT",
+            protocolVersion: 5,
+            username:        this.params.username,
+            password:        this.params.password,
+            clientId:        this.clientId,
+            clean:           true,
+            resubscribe:     true,
+            keepalive:       60,        /* 60s */
+            reconnectPeriod: 2  * 1000, /*  2s */
+            connectTimeout:  30 * 1000  /* 30s */
+        })
+        this.broker.on("error", (error: Error) => {
+            this.log("error", `error on MQTT ${this.params.url}: ${error.message}`)
+        })
+        this.broker.on("connect", (packet: MQTT.IConnackPacket) => {
+            this.log("info", `connection opened to MQTT ${this.params.url}`)
+            if (this.params.mode !== "w" && !packet.sessionPresent)
+                this.broker!.subscribe([ this.params.topicRead ], () => {})
+        })
+        this.broker.on("reconnect", () => {
+            this.log("info", `connection re-opened to MQTT ${this.params.url}`)
+        })
+        this.broker.on("disconnect", (packet: MQTT.IDisconnectPacket) => {
+            this.log("info", `connection closed to MQTT ${this.params.url}`)
+        })
+        const chunkQueue = new utils.SingleQueue<SpeechFlowChunk>()
+        this.broker.on("message", (topic: string, payload: Buffer, packet: MQTT.IPublishPacket) => {
+            if (topic !== this.params.topicRead)
+                return
+            try {
+                const chunk = utils.streamChunkDecode(payload)
+                chunkQueue.write(chunk)
+            }
+            catch (_err: any) {
+                this.log("warning", `received invalid CBOR chunk from MQTT ${this.params.url}`)
+            }
+        })
+        const broker     = this.broker
+        const topicWrite = this.params.topicWrite
+        const type       = this.params.type
+        const mode       = this.params.mode
+        this.stream = new Stream.Duplex({
+            writableObjectMode: true,
+            readableObjectMode: true,
+            decodeStrings:      false,
+            write (chunk: SpeechFlowChunk, encoding, callback) {
+                if (mode === "r")
+                    callback(new Error("write operation on read-only node"))
+                else if (chunk.type !== type)
+                    callback(new Error(`written chunk is not of ${type} type`))
+                else if (!broker.connected)
+                    callback(new Error("still no MQTT connection available"))
+                else {
+                    const data = Buffer.from(utils.streamChunkEncode(chunk))
+                    broker.publish(topicWrite, data, { qos: 2, retain: false }, (err) => {
+                        if (err)
+                            callback(new Error(`failed to publish to MQTT topic "${topicWrite}": ${err}`))
+                        else
+                            callback()
+                    })
+                }
+            },
+            read (size: number) {
+                if (mode === "w")
+                    throw new Error("read operation on write-only node")
+                chunkQueue.read().then((chunk) => {
+                    this.push(chunk, "binary")
+                })
+            }
+        })
+    }
+
+    /*  close node  */
+    async close () {
+        /*  close Websocket server  */
+        if (this.broker !== null) {
+            if (this.broker.connected)
+                this.broker.end()
+            this.broker = null
+        }
+
+        /*  close stream  */
+        if (this.stream !== null) {
+            this.stream.destroy()
+            this.stream = null
+        }
+    }
+}