speechflow 2.2.1 → 2.3.1

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)
@@ -261,7 +262,26 @@ export class WebAudio {
                 for (let i = 0; i < int16Array.length; i++)
                     float32Data[i] = int16Array[i] / 32768.0
 
-                /*  start capture first  */
+                /*  register capture-ready handler first (before posting start-capture,
+                    to avoid a race where capture-ready arrives before the listener
+                    is in place)  */
+                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)
+
+                /*  start capture after handler is registered  */
                 if (this.captureNode !== null) {
                     this.captureNode.port.postMessage({
                         type: "start-capture",
@@ -269,16 +289,6 @@ export class WebAudio {
                         expectedSamples: int16Array.length
                     })
                 }
-
-                /*  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)
             }
             catch (error) {
                 clearTimeout(timeout)
@@ -291,6 +301,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,12 +1,15 @@
 /*
 **  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>
 */
 
 /*  standard dependencies  */
 import EventEmitter                  from "node:events"
 
+/*  internal dependencies  */
+import * as util                     from "./speechflow-util-misc"
+
 /*  external dependencies  */
 import OpenAI                        from "openai"
 import Anthropic                     from "@anthropic-ai/sdk"
@@ -353,8 +356,16 @@ export class LLM extends EventEmitter {
             this.ollama?.abort()
             this.ollama = null
         }
-        else if (this.config.provider === "transformers") {
-            this.transformer?.dispose()
+        else if (this.config.provider === "transformers" && this.transformer !== null) {
+            const ac = new AbortController()
+            await Promise.race([
+                this.transformer.dispose(),
+                util.timeout(5000, "transformer dispose timeout", ac.signal)
+            ]).finally(() => {
+                ac.abort()
+            }).catch((error) => {
+                this.log("warning", `error during transformer cleanup: ${error}`)
+            })
             this.transformer = null
         }
         this.initialized = false

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 })
     })
 }

package/speechflow-cli/src/speechflow-util-queue.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>
 */
 
@@ -26,70 +26,6 @@ export function importObject<T> (name: string, arg: object | string, validator:
     return result as T
 }
 
-/*  helper class for single item queue  */
-export class SingleQueue<T> extends EventEmitter {
-    private queue = new Array<T>()
-    write (item: T) {
-        this.queue.unshift(item)
-        this.emit("dequeue")
-    }
-    read () {
-        return new Promise<T>((resolve) => {
-            const tryToConsume = () => {
-                const item = this.queue.pop()
-                if (item !== undefined)
-                    resolve(item)
-                else
-                    this.once("dequeue", tryToConsume)
-            }
-            tryToConsume()
-        })
-    }
-    drain () {
-        const items = this.queue
-        this.queue = new Array<T>()
-        return items
-    }
-}
-
-/*  helper class for double-item queue  */
-export class DoubleQueue<T0, T1> extends EventEmitter {
-    private queue0 = new Array<T0>()
-    private queue1 = new Array<T1>()
-    private notify () {
-        if (this.queue0.length > 0 && this.queue1.length > 0)
-            this.emit("dequeue")
-    }
-    write0 (item: T0) {
-        this.queue0.unshift(item)
-        this.notify()
-    }
-    write1 (item: T1) {
-        this.queue1.unshift(item)
-        this.notify()
-    }
-    read () {
-        return new Promise<[ T0, T1 ]>((resolve) => {
-            const consume = (): [ T0, T1 ] | undefined => {
-                if (this.queue0.length > 0 && this.queue1.length > 0) {
-                    const item0 = this.queue0.pop() as T0
-                    const item1 = this.queue1.pop() as T1
-                    return [ item0, item1 ]
-                }
-                return undefined
-            }
-            const tryToConsume = () => {
-                const items = consume()
-                if (items !== undefined)
-                    resolve(items)
-                else
-                    this.once("dequeue", tryToConsume)
-            }
-            tryToConsume()
-        })
-    }
-}
-
 /*  queue element  */
 export type QueueElement = { type: string }
 
@@ -112,6 +48,15 @@ export class QueuePointer<T extends QueueElement> extends EventEmitter {
     silent (silence: boolean) {
         this.silence = silence
     }
+    silently<R> (fn: () => R): R {
+        this.silence = true
+        try {
+            return fn()
+        }
+        finally {
+            this.silence = false
+        }
+    }
 
     /*  notify about operation  */
     notify (event: string, info: any) {
@@ -126,7 +71,7 @@ export class QueuePointer<T extends QueueElement> extends EventEmitter {
     position (index?: number): number {
         if (index !== undefined) {
             this.index = Math.max(0, Math.min(index, this.queue.elements.length))
-            this.notify("position", this.index)
+            this.notify("position", { start: this.index })
         }
         return this.index
     }
@@ -139,35 +84,53 @@ export class QueuePointer<T extends QueueElement> extends EventEmitter {
         if (this.index !== indexOld)
             this.notify("position", { start: this.index })
     }
-    walkForwardUntil (type: T["type"]) {
+    walkForwardUntil (type: T["type"]): boolean {
         while (this.index < this.queue.elements.length
             && this.queue.elements[this.index].type !== type)
             this.index++
         this.notify("position", { start: this.index })
+        return this.index < this.queue.elements.length
+            && this.queue.elements[this.index].type === type
     }
-    walkBackwardUntil (type: T["type"]) {
-        while (this.index > 0
-            && this.queue.elements[this.index].type !== type)
+    walkBackwardUntil (type: T["type"]): boolean {
+        if (this.index === this.queue.elements.length && this.index > 0)
+            this.index--
+        while (this.index < this.queue.elements.length
+            && this.queue.elements[this.index].type !== type) {
+            if (this.index === 0)
+                break
             this.index--
+        }
         this.notify("position", { start: this.index })
+        return this.index < this.queue.elements.length
+            && this.queue.elements[this.index].type === type
     }
 
     /*  search operations  */
-    searchForward (type: T["type"]) {
+    searchForward (type: T["type"]): number {
         let position = this.index
         while (position < this.queue.elements.length
             && this.queue.elements[position].type !== type)
             position++
-        this.notify("search", { start: this.index, end: position })
-        return position
+        const found = position < this.queue.elements.length
+            && this.queue.elements[position].type === type
+        this.notify("search", { start: this.index, end: found ? position : this.index })
+        return found ? position : -1
     }
-    searchBackward (type: T["type"]) {
+    searchBackward (type: T["type"]): number {
         let position = this.index
-        while (position > 0
-            && this.queue.elements[position].type !== type)
+        if (position === this.queue.elements.length && position > 0)
             position--
-        this.notify("search", { start: position, end: this.index })
-        return position
+        while (position < this.queue.elements.length
+            && this.queue.elements[position].type !== type) {
+            if (position === 0)
+                break
+            position--
+        }
+        const found = position < this.queue.elements.length
+            && this.queue.elements[position].type === type
+        this.notify("search", { start: found ? position : this.index, end: this.index })
+        return found ? position : -1
     }
 
     /*  reading operations  */
@@ -217,12 +180,14 @@ export class QueuePointer<T extends QueueElement> extends EventEmitter {
     }
     insert (element: T) {
         this.queue.elements.splice(this.index, 0, element)
+        this.queue.adjustPointers(this, this.index, "insert")
         this.queue.notify("write", { start: this.index, end: this.index, op: "insert" })
     }
     delete () {
         if (this.index >= this.queue.elements.length)
             throw new Error("cannot delete after last element")
         this.queue.elements.splice(this.index, 1)
+        this.queue.adjustPointers(this, this.index, "delete")
         this.queue.notify("write", { start: this.index, end: this.index, op: "delete" })
     }
 }
@@ -239,6 +204,15 @@ export class Queue<T extends QueueElement> extends EventEmitter {
     silent (silence: boolean) {
         this.silence = silence
     }
+    silently<R> (fn: () => R): R {
+        this.silence = true
+        try {
+            return fn()
+        }
+        finally {
+            this.silence = false
+        }
+    }
     notify (event: string, info: any) {
         if (!this.silence)
             this.emit(event, info)
@@ -253,6 +227,24 @@ export class Queue<T extends QueueElement> extends EventEmitter {
             throw new Error("pointer does not exist")
         this.pointers.delete(name)
     }
+
+    /*  adjust all sibling pointer positions (after insert/delete splice)
+        NOTICE: for insert, pointers AT the index are shifted forward to preserve
+        their pointer-to-element binding; for delete, pointers AT the index are
+        intentionally NOT adjusted, causing them to silently advance to the next
+        element (which shifted into the deleted position).  */
+    adjustPointers (exclude: QueuePointer<T>, index: number, op: "insert" | "delete"): void {
+        for (const pointer of this.pointers.values()) {
+            if (pointer === exclude)
+                continue
+            const pos = pointer.position()
+            if (op === "insert" && pos >= index)
+                pointer.position(pos + 1)
+            else if (op === "delete" && pos > index)
+                pointer.position(pos - 1)
+        }
+    }
+
     trim (): void {
         /*  determine minimum pointer position  */
         let min = this.elements.length
@@ -269,9 +261,15 @@ export class Queue<T extends QueueElement> extends EventEmitter {
             for (const pointer of this.pointers.values())
                 pointer.position(pointer.position() - min)
 
+            /*  notify (start/end refer to pre-splice indices)  */
             this.notify("write", { start: 0, end: min, op: "trim" })
         }
     }
+    clear (): void {
+        this.elements.length = 0
+        for (const pointer of this.pointers.values())
+            pointer.position(0)
+    }
 }
 
 /*  meta store  */
@@ -301,9 +299,12 @@ export class TimeStore<T> extends EventEmitter {
 
 /*  asynchronous queue  */
 export class AsyncQueue<T> {
-    private queue: Array<T> = []
+    private queue = new Array<T>()
     private resolvers: { resolve: (v: T) => void, reject: (err: Error) => void }[] = []
+    public destroyed = false
     write (v: T) {
+        if (this.destroyed)
+            return
         const resolver = this.resolvers.shift()
         if (resolver)
             resolver.resolve(v)
@@ -319,7 +320,13 @@ export class AsyncQueue<T> {
     empty () {
         return this.queue.length === 0
     }
+    drain () {
+        const items = this.queue
+        this.queue = new Array<T>()
+        return items
+    }
     destroy () {
+        this.destroyed = true
         for (const resolver of this.resolvers)
             resolver.reject(new Error("AsyncQueue destroyed"))
         this.resolvers = []
@@ -359,7 +366,22 @@ export class PromiseSet<T> {
             this.promises.delete(promise)
         }).catch(() => {})
     }
-    async awaitAll () {
-        await Promise.all(this.promises)
+    async awaitAll (timeout = 0) {
+        const deadline = timeout > 0 ? Date.now() + timeout : 0
+        while (this.promises.size > 0) {
+            const snapshot = [ ...this.promises ]
+            const remaining = deadline > 0 ? deadline - Date.now() : 0
+            if (deadline > 0 && remaining <= 0)
+                break
+            if (deadline > 0)
+                await Promise.race([
+                    Promise.all(snapshot),
+                    new Promise((resolve) => { setTimeout(resolve, remaining) })
+                ])
+            else
+                await Promise.all(snapshot)
+            if (deadline > 0 && Date.now() >= deadline)
+                break
+        }
     }
 }

package/speechflow-cli/src/speechflow-util-stream.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>
 */
 
@@ -59,7 +59,10 @@ export function ensureStreamChunk (type: "audio" | "text", chunk: SpeechFlowChun
 export function createTransformStreamForReadableSide (
     type: "text" | "audio",
     getTimeZero: () => DateTime,
-    writableHighWaterMark?: number
+    writableHighWaterMark?: number,
+    sampleRate?: number,
+    bitDepth?: number,
+    channels?: number
 ) {
     return new Stream.Transform({
         writableObjectMode:    false,
@@ -72,7 +75,8 @@ export function createTransformStreamForReadableSide (
             const start = DateTime.now().diff(timeZero)
             let end = start
             if (type === "audio") {
-                const duration = util.audioBufferDuration(chunk as Buffer)
+                const duration = util.audioBufferDuration(chunk as Buffer,
+                    sampleRate, bitDepth, channels)
                 end = start.plus(duration * 1000)
             }
             const payload = ensureStreamChunk(type, chunk) as Buffer | string
@@ -185,9 +189,33 @@ export class StreamWrapper extends Stream.Transform {
             return
         }
         try {
-            if (typeof this.foreignStream.end === "function")
+            if (typeof this.foreignStream.end === "function") {
                 this.foreignStream.end()
-            callback()
+
+                /*  wait for the foreign stream to finish flushing
+                    before signaling completion of this Transform stream  */
+                const ac = new AbortController()
+                Promise.race([
+                    new Promise<void>((resolve, reject) => {
+                        if (typeof this.foreignStream.once === "function") {
+                            this.foreignStream.once("finish", () => { resolve() })
+                            this.foreignStream.once("error",  (err: Error) => { reject(err) })
+                        }
+                        else
+                            resolve()
+                    }),
+                    util.timeout(5000, "foreign stream flush timeout", ac.signal)
+                ]).finally(() => {
+                    ac.abort()
+                }).then(() => {
+                    callback()
+                }).catch(() => {
+                    /*  ignore timeout -- stream will be destroyed anyway  */
+                    callback()
+                })
+            }
+            else
+                callback()
         }
         catch (err: unknown) {
             callback(util.ensureError(err))
@@ -211,15 +239,19 @@ export async function destroyStream (
     if ((  stream instanceof Stream.Duplex
         || stream instanceof Stream.Transform
         || stream instanceof Stream.Writable )
-        && (!stream.writableEnded && !stream.destroyed))
+        && (!stream.writableEnded && !stream.destroyed)) {
+        const ac = new AbortController()
         await Promise.race([
             new Promise<void>((resolve) => {
                 stream.end(() => { resolve() })
             }),
-            util.timeout(5000, "stream end timeout")
-        ]).catch(() => {
+            util.timeout(5000, "stream end timeout", ac.signal)
+        ]).finally(() => {
+            ac.abort()
+        }).catch(() => {
             /*  ignore timeout -- stream will be destroyed anyway  */
         })
+    }
 
     /*  destroy the stream  */
     stream.destroy()

package/speechflow-cli/src/speechflow-util.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.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 /*!
 **  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-ui-db/dst/index.html

@@ -2,7 +2,7 @@
 <!--
 **
 **  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>
 **
 -->