speechflow 2.2.0 → 2.3.0

package/speechflow-cli/src/speechflow-node-xio-websocket.ts

@@ -1,6 +1,6 @@
 /*
 **  SpeechFlow - Speech Processing Flow Graph
-**  Copyright (c) 2024-2025 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Copyright (c) 2024-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
 **  Licensed under GPL 3.0 <https://spdx.org/licenses/GPL-3.0-only>
 */
 
@@ -21,8 +21,9 @@ export default class SpeechFlowNodeXIOWebSocket extends SpeechFlowNode {
     public static name = "xio-websocket"
 
     /*  internal state  */
-    private server: ws.WebSocketServer | null = null
-    private client: ReconnWebSocket    | null = null
+    private server:     ws.WebSocketServer                    | null = null
+    private client:     ReconnWebSocket                       | null = null
+    private chunkQueue: util.AsyncQueue<SpeechFlowChunk>      | null = null
 
     /*  construct node  */
     constructor (id: string, cfg: { [ id: string ]: any }, opts: { [ id: string ]: any }, args: any[]) {
@@ -63,7 +64,7 @@ export default class SpeechFlowNodeXIOWebSocket extends SpeechFlowNode {
             /*  listen locally on a Websocket port  */
             const url = new URL(this.params.listen)
             const websockets = new Set<ws.WebSocket>()
-            const chunkQueue = new util.SingleQueue<SpeechFlowChunk>()
+            this.chunkQueue = new util.AsyncQueue<SpeechFlowChunk>()
             this.server = new ws.WebSocketServer({
                 host: url.hostname,
                 port: Number.parseInt(url.port, 10),
@@ -102,7 +103,7 @@ export default class SpeechFlowNodeXIOWebSocket extends SpeechFlowNode {
                     else
                         buffer = Buffer.concat(data)
                     const chunk = util.streamChunkDecode(buffer)
-                    chunkQueue.write(chunk)
+                    this.chunkQueue?.write(chunk)
                 })
             })
             this.server.on("error", (error) => {
@@ -124,9 +125,11 @@ export default class SpeechFlowNodeXIOWebSocket extends SpeechFlowNode {
                         callback(new Error("still no WebSocket connections available"))
                     else {
                         const data = util.streamChunkEncode(chunk)
-                        const results: Promise<void>[] = []
+                        const sends:   Promise<void>[] = []
+                        const clients: ws.WebSocket[]  = []
                         for (const websocket of websockets.values()) {
-                            results.push(new Promise<void>((resolve, reject) => {
+                            clients.push(websocket)
+                            sends.push(new Promise<void>((resolve, reject) => {
                                 websocket.send(data, (error) => {
                                     if (error)
                                         reject(error)
@@ -135,10 +138,27 @@ export default class SpeechFlowNodeXIOWebSocket extends SpeechFlowNode {
                                 })
                             }))
                         }
-                        Promise.all(results).then(() => {
-                            callback()
-                        }).catch((error: unknown) => {
-                            callback(util.ensureError(error))
+                        Promise.allSettled(sends).then((results) => {
+                            let lastError: Error | null = null
+                            for (let i = 0; i < results.length; i++) {
+                                if (results[i].status === "rejected") {
+                                    const error = util.ensureError((results[i] as PromiseRejectedResult).reason)
+                                    self.log("warning", `failed to send to WebSocket client: ${error.message}`)
+                                    websockets.delete(clients[i])
+                                    clients[i].terminate()
+                                    lastError = error
+                                }
+                            }
+                            const failures = results.filter((r) => r.status === "rejected").length
+                            if (failures > 0 && failures < results.length)
+                                self.log("warning", "partial broadcast failure: " +
+                                    `${failures} of ${results.length} WebSocket clients failed`)
+                            if (lastError !== null && failures === results.length)
+                                callback(lastError)
+                            else
+                                callback()
+                        }).catch((err: Error) => {
+                            callback(err)
                         })
                     }
                 },
@@ -147,12 +167,20 @@ export default class SpeechFlowNodeXIOWebSocket extends SpeechFlowNode {
                     callback()
                 },
                 read (size: number) {
-                    if (self.params.mode === "w")
-                        throw new Error("read operation on write-only node")
-                    reads.add(chunkQueue.read().then((chunk) => {
+                    if (self.params.mode === "w") {
+                        self.log("error", "read operation on write-only node")
+                        this.push(null)
+                        return
+                    }
+                    if (self.chunkQueue === null)
+                        return
+                    const queue = self.chunkQueue
+                    reads.add(queue.read().then((chunk) => {
                         this.push(chunk, "binary")
                     }).catch((err: Error) => {
                         self.log("warning", `read on chunk queue operation failed: ${err}`)
+                        if (queue.destroyed)
+                            this.push(null)
                     }))
                 }
             })
@@ -178,7 +206,7 @@ export default class SpeechFlowNodeXIOWebSocket extends SpeechFlowNode {
                 const error = util.ensureError(ev.error)
                 this.log("error", `error of connection on URL ${this.params.connect}: ${error.message}`)
             })
-            const chunkQueue = new util.SingleQueue<SpeechFlowChunk>()
+            this.chunkQueue = new util.AsyncQueue<SpeechFlowChunk>()
             this.client.addEventListener("message", (ev: MessageEvent) => {
                 if (this.params.mode === "w") {
                     this.log("warning", `connection to URL ${this.params.connect}: ` +
@@ -192,7 +220,7 @@ export default class SpeechFlowNodeXIOWebSocket extends SpeechFlowNode {
                 }
                 const buffer = Buffer.from(ev.data)
                 const chunk = util.streamChunkDecode(buffer)
-                chunkQueue.write(chunk)
+                this.chunkQueue?.write(chunk)
             })
             this.client.binaryType = "arraybuffer"
             const self = this
@@ -207,7 +235,7 @@ export default class SpeechFlowNodeXIOWebSocket extends SpeechFlowNode {
                         callback(new Error("write operation on read-only node"))
                     else if (chunk.type !== self.params.type)
                         callback(new Error(`written chunk is not of ${self.params.type} type`))
-                    else if (!self.client!.OPEN)
+                    else if (self.client!.readyState !== ReconnWebSocket.OPEN)
                         callback(new Error("still no WebSocket connection available"))
                     else {
                         const data = util.streamChunkEncode(chunk)
@@ -220,12 +248,20 @@ export default class SpeechFlowNodeXIOWebSocket extends SpeechFlowNode {
                     callback()
                 },
                 read (size: number) {
-                    if (self.params.mode === "w")
-                        throw new Error("read operation on write-only node")
-                    reads.add(chunkQueue.read().then((chunk) => {
+                    if (self.params.mode === "w") {
+                        self.log("error", "read operation on write-only node")
+                        this.push(null)
+                        return
+                    }
+                    if (self.chunkQueue === null)
+                        return
+                    const queue = self.chunkQueue
+                    reads.add(queue.read().then((chunk) => {
                         this.push(chunk, "binary")
                     }).catch((err: Error) => {
                         self.log("warning", `read on chunk queue operation failed: ${err}`)
+                        if (queue.destroyed)
+                            this.push(null)
                     }))
                 }
             })
@@ -234,8 +270,19 @@ export default class SpeechFlowNodeXIOWebSocket extends SpeechFlowNode {
 
     /*  close node  */
     async close () {
+        /*  drain and clear chunk queue reference  */
+        if (this.chunkQueue !== null) {
+            this.chunkQueue.destroy()
+            this.chunkQueue = null
+        }
+
         /*  close WebSocket server  */
         if (this.server !== null) {
+            /*  forcibly terminate all active client connections  */
+            for (const client of this.server.clients)
+                client.terminate()
+
+            /*  close connection  */
             await new Promise<void>((resolve, reject) => {
                 this.server!.close((error) => {
                     if (error) reject(error)

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

@@ -1,6 +1,6 @@
 /*
 **  SpeechFlow - Speech Processing Flow Graph
-**  Copyright (c) 2024-2025 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Copyright (c) 2024-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
 **  Licensed under GPL 3.0 <https://spdx.org/licenses/GPL-3.0-only>
 */
 
@@ -9,7 +9,10 @@ import Events, { EventEmitter } from "node:events"
 import Stream from "node:stream"
 
 /*  external dependencies  */
-import { DateTime, Duration } from "luxon"
+import { DateTime, Duration }   from "luxon"
+
+/*  internal dependencies  */
+import { deepClone }            from "./speechflow-util-misc"
 
 /*  the definition of a single payload chunk passed through the SpeechFlow nodes  */
 export class SpeechFlowChunk {
@@ -33,7 +36,7 @@ export class SpeechFlowChunk {
             this.kind,
             this.type,
             payload,
-            new Map(this.meta)
+            deepClone(this.meta)
         )
     }
 }
@@ -140,16 +143,12 @@ export default class SpeechFlowNode extends Events.EventEmitter {
                 if (typeof this.args[spec[name].pos] !== spec[name].type)
                     throw new Error(`invalid type of positional parameter "${name}" ` +
                         `(has to be ${spec[name].type})`)
-                if ("match" in spec[name]
-                    && this.args[spec[name].pos].match(spec[name].match) === null)
-                    throw new Error(`invalid value of positional parameter "${name}" ` +
-                        `(has to match ${spec[name].match})`)
                 if ("match" in spec[name]
                     && (   (   spec[name].match instanceof RegExp
                             && this.args[spec[name].pos].match(spec[name].match) === null)
                         || (   typeof spec[name].match === "function"
                             && !spec[name].match(this.args[spec[name].pos])    )          ))
-                    throw new Error(`invalid value "${this.opts[name]}" of positional parameter "${name}"`)
+                    throw new Error(`invalid value "${this.args[spec[name].pos!]}" of positional parameter "${name}"`)
                 this.params[name] = this.args[spec[name].pos]
             }
             else if ("val" in spec[name] && spec[name].val !== undefined)

package/speechflow-cli/src/speechflow-util-audio-wt.ts

@@ -1,6 +1,6 @@
 /*
 **  SpeechFlow - Speech Processing Flow Graph
-**  Copyright (c) 2024-2025 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Copyright (c) 2024-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
 **  Licensed under GPL 3.0 <https://spdx.org/licenses/GPL-3.0-only>
 */
 
@@ -15,7 +15,14 @@ interface StartCaptureMessage {
     chunkId: string
     expectedSamples: number
 }
-type WorkletMessage = InputChunkMessage | StartCaptureMessage
+interface CancelCaptureMessage {
+    type: "cancel-capture"
+    chunkId: string
+}
+interface CancelAllCapturesMessage {
+    type: "cancel-all-captures"
+}
+type WorkletMessage = InputChunkMessage | StartCaptureMessage | CancelCaptureMessage | CancelAllCapturesMessage
 interface ChunkData {
     data: Float32Array
     chunkId: string
@@ -24,6 +31,10 @@ interface ChunkStartedMessage {
     type: "chunk-started"
     chunkId: string
 }
+interface CaptureReadyMessage {
+    type: "capture-ready"
+    chunkId: string
+}
 interface CaptureCompleteMessage {
     type: "capture-complete"
     chunkId: string
@@ -43,9 +54,12 @@ class AudioSourceProcessor extends AudioWorkletProcessor {
 
         /*  receive input chunks  */
         this.port.addEventListener("message", (event: MessageEvent<WorkletMessage>) => {
-            const { type, chunkId } = event.data
+            const { type } = event.data
             if (type === "input-chunk")
-                this.pendingData.push({ data: event.data.data.pcmData, chunkId })
+                this.pendingData.push({
+                    data:    event.data.data.pcmData,
+                    chunkId: event.data.chunkId
+                })
         })
     }
 
@@ -114,7 +128,8 @@ class AudioSourceProcessor extends AudioWorkletProcessor {
 /*  audio capture node  */
 class AudioCaptureProcessor extends AudioWorkletProcessor {
     /*  internal state  */
-    private activeCaptures = new Map<string, { data: number[], expectedSamples: number }>()
+    private static readonly CAPTURE_TTL = 30 * 1000
+    private activeCaptures = new Map<string, { data: number[], expectedSamples: number, createdAt: number }>()
 
     /*  node construction  */
     constructor () {
@@ -122,13 +137,28 @@ class AudioCaptureProcessor extends AudioWorkletProcessor {
 
         /*  receive start of capturing command  */
         this.port.addEventListener("message", (event: MessageEvent<WorkletMessage>) => {
-            const { type, chunkId } = event.data
+            const { type } = event.data
             if (type === "start-capture") {
+                const chunkId = event.data.chunkId
                 this.activeCaptures.set(chunkId, {
                     data: [],
-                    expectedSamples: event.data.expectedSamples
+                    expectedSamples: event.data.expectedSamples,
+                    createdAt: Date.now()
                 })
+
+                /*  acknowledge capture registration  */
+                const ready: CaptureReadyMessage = {
+                    type: "capture-ready",
+                    chunkId
+                }
+                this.port.postMessage(ready)
             }
+            else if (type === "cancel-capture") {
+                const chunkId = event.data.chunkId
+                this.activeCaptures.delete(chunkId)
+            }
+            else if (type === "cancel-all-captures")
+                this.activeCaptures.clear()
         })
     }
 
@@ -145,6 +175,15 @@ class AudioCaptureProcessor extends AudioWorkletProcessor {
         const frameCount = input[0].length
         const channelCount = input.length
 
+        /*  evict stale captures (TTL safety net)  */
+        const currentTime = Date.now()
+        for (const [ chunkId, capture ] of this.activeCaptures) {
+            if ((currentTime - capture.createdAt) > AudioCaptureProcessor.CAPTURE_TTL)
+                this.activeCaptures.delete(chunkId)
+        }
+        if (this.activeCaptures.size === 0)
+            return true
+
         /*  iterate over all active captures  */
         for (const [ chunkId, capture ] of this.activeCaptures) {
             /*  convert planar to interleaved  */

package/speechflow-cli/src/speechflow-util-audio.ts

@@ -1,6 +1,6 @@
 /*
 **  SpeechFlow - Speech Processing Flow Graph
-**  Copyright (c) 2024-2025 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Copyright (c) 2024-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
 **  Licensed under GPL 3.0 <https://spdx.org/licenses/GPL-3.0-only>
 */
 
@@ -18,14 +18,11 @@ export function audioBufferDuration (
     buffer: Buffer,
     sampleRate   = 48000,
     bitDepth     = 16,
-    channels     = 1,
-    littleEndian = true
+    channels     = 1
 ) {
     /*  sanity check parameters  */
     if (!Buffer.isBuffer(buffer))
         throw new Error("invalid input (Buffer expected)")
-    if (littleEndian !== true)
-        throw new Error("only Little Endian supported")
     if (sampleRate <= 0)
         throw new Error("sample rate must be positive")
     if (bitDepth <= 0 || bitDepth % 8 !== 0)
@@ -234,7 +231,7 @@ export class WebAudio {
                     this.pendingPromises.delete(chunkId)
                     const int16Data = new Int16Array(data.length)
                     for (let i = 0; i < data.length; i++)
-                        int16Data[i] = Math.max(-32768, Math.min(32767, Math.round(data[i] * 32767)))
+                        int16Data[i] = Math.max(-32768, Math.min(32767, Math.round(data[i] * 32768)))
                     promise.resolve(int16Data)
                 }
             }
@@ -248,10 +245,14 @@ export class WebAudio {
 
     /*  process single audio chunk  */
     public async process (int16Array: Int16Array): Promise<Int16Array> {
+        if (this.sourceNode === null || this.captureNode === null)
+            throw new Error("WebAudio not ready (not yet setup or already destroyed)")
         const chunkId = `chunk_${Date.now()}_${Math.random().toString(36).substring(2, 11)}`
         return new Promise<Int16Array>((resolve, reject) => {
             const timeout = setTimeout(() => {
                 this.pendingPromises.delete(chunkId)
+                if (this.captureNode !== null)
+                    this.captureNode.port.postMessage({ type: "cancel-capture", chunkId })
                 reject(new Error("processing timeout"))
             }, (int16Array.length / this.channels / this.audioContext.sampleRate) * 1000 + 250)
             if (this.captureNode !== null)
@@ -270,15 +271,22 @@ export class WebAudio {
                     })
                 }
 
-                /*  small delay to ensure capture is ready before sending data  */
-                setTimeout(() => {
-                    /*  send input to source node  */
-                    this.sourceNode?.port.postMessage({
-                        type: "input-chunk",
-                        chunkId,
-                        data: { pcmData: float32Data, channels: this.channels }
-                    }, [ float32Data.buffer ])
-                }, 5)
+                /*  wait for capture-ready acknowledgment before sending data  */
+                const readyHandler = (event: MessageEvent) => {
+                    const { type: msgType, chunkId: msgChunkId } = event.data ?? {}
+                    if (msgType === "capture-ready" && msgChunkId === chunkId) {
+                        this.captureNode?.port.removeEventListener("message", readyHandler)
+
+                        /*  send input to source node  */
+                        this.sourceNode?.port.postMessage({
+                            type: "input-chunk",
+                            chunkId,
+                            data: { pcmData: float32Data, channels: this.channels }
+                        }, [ float32Data.buffer ])
+                    }
+                }
+                if (this.captureNode !== null)
+                    this.captureNode.port.addEventListener("message", readyHandler)
             }
             catch (error) {
                 clearTimeout(timeout)
@@ -291,6 +299,10 @@ export class WebAudio {
 
     /*  destroy object  */
     public async destroy (): Promise<void> {
+        /*  cancel all worklet captures  */
+        if (this.captureNode !== null)
+            this.captureNode.port.postMessage({ type: "cancel-all-captures" })
+
         /*  reject all pending promises  */
         shield(() => {
             this.pendingPromises.forEach(({ reject, timeout }) => {

package/speechflow-cli/src/speechflow-util-error.ts

@@ -1,6 +1,6 @@
 /*
 **  SpeechFlow - Speech Processing Flow Graph
-**  Copyright (c) 2024-2025 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Copyright (c) 2024-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
 **  Licensed under GPL 3.0 <https://spdx.org/licenses/GPL-3.0-only>
 */
 
@@ -193,7 +193,7 @@ export function runner<T> (
 export function shield<T extends (void | Promise<void>)> (op: () => T) {
     return run(
         "shielded operation",
-        () => { op() },
-        (_err) => { /* ignore error */ }
+        ()     => op(),
+        (_err) => undefined as T
     )
 }

package/speechflow-cli/src/speechflow-util-llm.ts

@@ -1,6 +1,6 @@
 /*
 **  SpeechFlow - Speech Processing Flow Graph
-**  Copyright (c) 2024-2025 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Copyright (c) 2024-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
 **  Licensed under GPL 3.0 <https://spdx.org/licenses/GPL-3.0-only>
 */
 

package/speechflow-cli/src/speechflow-util-misc.ts

@@ -1,23 +1,80 @@
 /*
 **  SpeechFlow - Speech Processing Flow Graph
-**  Copyright (c) 2024-2025 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Copyright (c) 2024-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
 **  Licensed under GPL 3.0 <https://spdx.org/licenses/GPL-3.0-only>
 */
 
+/*  external dependencies  */
+import { DateTime, Duration } from "luxon"
+
+/*  deep-clone a value while being aware of special class instances  */
+export const deepClone = (value: any): any => {
+    if (value === null || value === undefined || Number.isNaN(value))
+        return value
+    else if (typeof value !== "object")
+        return value
+    else if (Buffer.isBuffer(value))
+        return Buffer.from(value)
+    else if (value instanceof Uint8Array)
+        return new Uint8Array(value)
+    else if (value instanceof Duration)
+        return Duration.fromMillis(value.toMillis())
+    else if (value instanceof DateTime)
+        return DateTime.fromMillis(value.toMillis())
+    else if (Array.isArray(value))
+        return value.map((item) => deepClone(item))
+    else if (value instanceof Map) {
+        const result = new Map()
+        for (const [ k, v ] of value)
+            result.set(deepClone(k), deepClone(v))
+        return result
+    }
+    else if (value instanceof Set) {
+        const result = new Set()
+        for (const v of value)
+            result.add(deepClone(v))
+        return result
+    }
+    else if (Object.getPrototypeOf(value) === Object.prototype) {
+        const result: any = {}
+        for (const key of Object.keys(value))
+            result[key] = deepClone(value[key])
+        return result
+    }
+    else
+        return structuredClone(value)
+}
+
 /*  sleep: wait a duration of time and then resolve  */
-export function sleep (durationMs: number) {
+export function sleep (durationMs: number, signal?: AbortSignal) {
     return new Promise<void>((resolve) => {
-        setTimeout(() => {
+        const ac = new AbortController()
+        const timer = setTimeout(() => {
+            ac.abort()
             resolve()
         }, durationMs)
+        timer.unref()
+        if (signal !== undefined)
+            signal.addEventListener("abort", () => {
+                clearTimeout(timer)
+                resolve()
+            }, { once: true, signal: ac.signal })
     })
 }
 
 /*  timeout: wait a duration of time and then reject  */
-export function timeout (durationMs: number, info = "timeout") {
-    return new Promise<never>((_resolve, reject) => {
-        setTimeout(() => {
+export function timeout (durationMs: number, info = "timeout", signal?: AbortSignal) {
+    return new Promise<never>((resolve, reject) => {
+        const ac = new AbortController()
+        const timer = setTimeout(() => {
+            ac.abort()
             reject(new Error(info))
         }, durationMs)
+        timer.unref()
+        if (signal !== undefined)
+            signal.addEventListener("abort", () => {
+                clearTimeout(timer)
+                resolve(undefined as never)
+            }, { once: true, signal: ac.signal })
     })
 }