speechflow 1.3.0 → 1.3.2

package/package.json

@@ -1,8 +1,8 @@
 {
     "name":                                 "speechflow",
-    "version":                              "1.3.0",
-    "x-stdver":                             "1.3.0-GA",
-    "x-release":                            "2025-07-26",
+    "version":                              "1.3.2",
+    "x-stdver":                             "1.3.2-GA",
+    "x-release":                            "2025-08-04",
     "homepage":                             "https://github.com/rse/speechflow",
     "description":                          "Speech Processing Flow Graph",
     "license":                              "GPL-3.0-only",
@@ -18,7 +18,7 @@
     "dependencies": {
         "cli-io":                           "0.9.13",
         "yargs":                            "18.0.0",
-        "flowlink":                         "0.9.11",
+        "flowlink":                         "1.0.0",
         "js-yaml":                          "4.1.0",
         "@gpeng/naudiodon":                 "2.4.1",
         "@deepgram/sdk":                    "4.11.1",
@@ -26,7 +26,7 @@
         "@elevenlabs/elevenlabs-js":        "2.7.0",
         "stream-transform":                 "3.4.0",
         "get-stream":                       "9.0.1",
-        "@dotenvx/dotenvx":                 "1.48.3",
+        "@dotenvx/dotenvx":                 "1.48.4",
         "speex-resampler":                  "3.0.1",
         "object-path":                      "0.11.8",
         "ws":                               "8.18.3",
@@ -34,23 +34,24 @@
         "utf-8-validate":                   "6.0.5",
         "@hapi/hapi":                       "21.4.0",
         "@hapi/boom":                       "10.0.1",
+        "@hapi/inert":                      "7.1.0",
         "hapi-plugin-header":               "1.1.8",
         "hapi-plugin-websocket":            "2.4.11",
         "@opensumi/reconnecting-websocket": "4.4.0",
         "ollama":                           "0.5.16",
-        "openai":                           "5.10.2",
+        "openai":                           "5.11.0",
         "@rse/ffmpeg":                      "1.4.2",
         "ffmpeg-stream":                    "1.0.1",
         "installed-packages":               "1.0.13",
         "syspath":                          "1.0.8",
         "wav":                              "1.0.2",
-        "mqtt":                             "5.13.3",
+        "mqtt":                             "5.14.0",
         "cbor2":                            "2.0.1",
         "arktype":                          "2.1.20",
         "pure-uuid":                        "1.8.1",
         "wavefile":                         "11.0.0",
         "audio-inspect":                    "0.0.3",
-        "@huggingface/transformers":        "3.7.0",
+        "@huggingface/transformers":        "3.7.1",
         "kokoro-js":                        "1.2.1",
         "@ericedouard/vad-node-realtime":   "0.2.0",
         "luxon":                            "3.7.1",
@@ -67,10 +68,10 @@
         "eslint-plugin-node":               "11.1.0",
         "@typescript-eslint/eslint-plugin": "8.38.0",
         "@typescript-eslint/parser":        "8.38.0",
-        "oxlint":                           "1.8.0",
-        "eslint-plugin-oxlint":             "1.8.0",
+        "oxlint":                           "1.9.0",
+        "eslint-plugin-oxlint":             "1.9.0",
         "@biomejs/biome":                   "2.0.6",
-        "eslint-config-biome":              "1.9.4",
+        "eslint-config-biome":              "2.1.3",
 
         "@types/node":                      "24.1.0",
         "@types/yargs":                     "17.0.33",
@@ -79,7 +80,7 @@
         "@types/ws":                        "8.18.1",
         "@types/resolve":                   "1.20.6",
         "@types/wav":                       "1.0.4",
-        "@types/luxon":                     "3.6.2",
+        "@types/luxon":                     "3.7.1",
         "@types/wrap-text":                 "1.0.2",
 
         "patch-package":                    "8.0.0",
@@ -95,7 +96,7 @@
     "overrides": {
         "@huggingface/transformers":        { "onnxruntime-node": "1.23.0-dev.20250703-7fc6235861" }
     },
-    "upd":                                  [ "!@biomejs/biome" ],
+    "upd":                                  [ "!@biomejs/biome", "!typescript" ],
     "engines": {
         "node":                             ">=22.0.0"
     },

package/src/speechflow-node-a2a-gender.ts

@@ -39,6 +39,8 @@ export default class SpeechFlowNodeGender extends SpeechFlowNode {
     private queueAC   = this.queue.pointerUse("ac")
     private queueSend = this.queue.pointerUse("send")
     private shutdown  = false
+    private workingOffTimer:  ReturnType<typeof setTimeout>  | null = null
+    private progressInterval: ReturnType<typeof setInterval> | null = null
 
     /*  construct node  */
     constructor (id: string, cfg: { [ id: string ]: any }, opts: { [ id: string ]: any }, args: any[]) {
@@ -60,6 +62,9 @@ export default class SpeechFlowNodeGender extends SpeechFlowNode {
         if (this.config.audioBitDepth !== 16 || !this.config.audioLittleEndian)
             throw new Error("Gender node currently supports PCM-S16LE audio only")
 
+        /*  clear shutdown flag  */
+        this.shutdown = false
+
         /*  pass-through logging  */
         const log = (level: string, msg: string) => { this.log(level, msg) }
 
@@ -69,6 +74,8 @@ export default class SpeechFlowNodeGender extends SpeechFlowNode {
         /*  track download progress when instantiating Transformers engine and model  */
         const progressState = new Map<string, number>()
         const progressCallback: Transformers.ProgressCallback = (progress: any) => {
+            if (this.shutdown)
+                return
             let artifact = model
             if (typeof progress.file === "string")
                 artifact += `:${progress.file}`
@@ -80,31 +87,54 @@ export default class SpeechFlowNodeGender extends SpeechFlowNode {
             if (percent > 0)
                 progressState.set(artifact, percent)
         }
-        const interval = setInterval(() => {
+        this.progressInterval = setInterval(() => {
+            if (this.shutdown)
+                return
             for (const [ artifact, percent ] of progressState) {
                 this.log("info", `downloaded ${percent.toFixed(2)}% of artifact "${artifact}"`)
                 if (percent >= 1.0)
                     progressState.delete(artifact)
             }
         }, 1000)
-
-        /*  instantiate Transformers engine and model  */
-        const pipeline = Transformers.pipeline("audio-classification", model, {
-            cache_dir: path.join(this.config.cacheDir, "gender"),
-            dtype:     "q4",
-            device:    "auto",
-            progress_callback: progressCallback
-        })
-        this.classifier = await pipeline
-        clearInterval(interval)
+        try {
+            const pipelinePromise = Transformers.pipeline("audio-classification", model, {
+                cache_dir: path.join(this.config.cacheDir, "gender"),
+                dtype:     "q4",
+                device:    "auto",
+                progress_callback: progressCallback
+            })
+            const timeoutPromise = new Promise((resolve, reject) => setTimeout(() =>
+                reject(new Error("model initialization timeout")), 30 * 1000))
+            this.classifier = await Promise.race([
+                pipelinePromise, timeoutPromise
+            ]) as Transformers.AudioClassificationPipeline
+        }
+        catch (error) {
+            if (this.progressInterval) {
+                clearInterval(this.progressInterval)
+                this.progressInterval = null
+            }
+            throw new Error(`failed to initialize classifier pipeline: ${error}`)
+        }
+        if (this.progressInterval) {
+            clearInterval(this.progressInterval)
+            this.progressInterval = null
+        }
         if (this.classifier === null)
             throw new Error("failed to instantiate classifier pipeline")
 
         /*  classify a single large-enough concatenated audio frame  */
         const classify = async (data: Float32Array) => {
-            const result = await this.classifier!(data)
-            const classified: Transformers.AudioClassificationOutput =
-                Array.isArray(result) ? result as Transformers.AudioClassificationOutput : [ result ]
+            if (this.shutdown || this.classifier === null)
+                throw new Error("classifier shutdown during operation")
+            const classifyPromise = this.classifier(data)
+            const timeoutPromise = new Promise((resolve, reject) => setTimeout(() =>
+                reject(new Error("classification timeout")), 30 * 1000))
+            const result = await Promise.race([ classifyPromise, timeoutPromise ]) as
+                Transformers.AudioClassificationOutput | Transformers.AudioClassificationOutput[]
+            const classified = Array.isArray(result) ?
+                result as Transformers.AudioClassificationOutput :
+                [ result ]
             const c1 = classified.find((c: any) => c.label === "male")
             const c2 = classified.find((c: any) => c.label === "female")
             const male   = c1 ? c1.score : 0.0
@@ -119,57 +149,65 @@ export default class SpeechFlowNodeGender extends SpeechFlowNode {
         const frameWindowDuration = 0.5
         const frameWindowSamples  = frameWindowDuration * sampleRateTarget
         let lastGender = ""
-        let workingOffTimer: ReturnType<typeof setTimeout> | null = null
         let workingOff = false
         const workOffQueue = async () => {
             /*  control working off round  */
             if (workingOff || this.shutdown)
                 return
             workingOff = true
-            if (workingOffTimer !== null) {
-                clearTimeout(workingOffTimer)
-                workingOffTimer = null
+            if (this.workingOffTimer !== null) {
+                clearTimeout(this.workingOffTimer)
+                this.workingOffTimer = null
             }
             this.queue.off("write", workOffQueue)
 
-            let pos0 = this.queueAC.position()
-            const posL = this.queueAC.maxPosition()
-            const data = new Float32Array(frameWindowSamples)
-            data.fill(0)
-            let samples = 0
-            let pos = pos0
-            while (pos < posL && samples < frameWindowSamples) {
-                const element = this.queueAC.peek(pos)
-                if (element === undefined || element.type !== "audio-frame")
-                    break
-                if ((samples + element.data.length) < frameWindowSamples) {
-                    data.set(element.data, samples)
-                    samples += element.data.length
-                }
-                pos++
-            }
-            if (pos0 < pos && samples > frameWindowSamples * 0.75) {
-                const gender = await classify(data)
-                const posM = pos0 + Math.trunc((pos - pos0) * 0.25)
-                while (pos0 < posM && pos0 < posL) {
-                    const element = this.queueAC.peek(pos0)
+            try {
+                let pos0 = this.queueAC.position()
+                const posL = this.queueAC.maxPosition()
+                const data = new Float32Array(frameWindowSamples)
+                data.fill(0)
+                let samples = 0
+                let pos = pos0
+                while (pos < posL && samples < frameWindowSamples && !this.shutdown) {
+                    const element = this.queueAC.peek(pos)
                     if (element === undefined || element.type !== "audio-frame")
                         break
-                    element.gender = gender
-                    this.queueAC.touch()
-                    this.queueAC.walk(+1)
-                    pos0++
+                    if ((samples + element.data.length) < frameWindowSamples) {
+                        data.set(element.data, samples)
+                        samples += element.data.length
+                    }
+                    pos++
                 }
-                if (lastGender !== gender) {
-                    log("info", `gender now recognized as <${gender}>`)
-                    lastGender = gender
+                if (pos0 < pos && samples > frameWindowSamples * 0.75 && !this.shutdown) {
+                    const gender = await classify(data)
+                    if (this.shutdown)
+                        return
+                    const posM = pos0 + Math.trunc((pos - pos0) * 0.25)
+                    while (pos0 < posM && pos0 < posL && !this.shutdown) {
+                        const element = this.queueAC.peek(pos0)
+                        if (element === undefined || element.type !== "audio-frame")
+                            break
+                        element.gender = gender
+                        this.queueAC.touch()
+                        this.queueAC.walk(+1)
+                        pos0++
+                    }
+                    if (lastGender !== gender && !this.shutdown) {
+                        log("info", `gender now recognized as <${gender}>`)
+                        lastGender = gender
+                    }
                 }
             }
+            catch (error) {
+                log("error", `gender classification error: ${error}`)
+            }
 
             /*  re-initiate working off round  */
             workingOff = false
-            workingOffTimer = setTimeout(workOffQueue, 100)
-            this.queue.once("write", workOffQueue)
+            if (!this.shutdown) {
+                this.workingOffTimer = setTimeout(workOffQueue, 100)
+                this.queue.once("write", workOffQueue)
+            }
         }
         this.queue.once("write", workOffQueue)
 
@@ -183,28 +221,41 @@ export default class SpeechFlowNodeGender extends SpeechFlowNode {
 
             /*  receive audio chunk (writable side of stream)  */
             write (chunk: SpeechFlowChunk, encoding, callback) {
+                if (self.shutdown) {
+                    callback(new Error("stream already destroyed"))
+                    return
+                }
                 if (!Buffer.isBuffer(chunk.payload))
                     callback(new Error("expected audio input as Buffer chunks"))
                 else if (chunk.payload.byteLength === 0)
                     callback()
                 else {
-                    /*  convert audio samples from PCM/I16/48KHz to PCM/F32/16KHz  */
-                    let data = utils.convertBufToF32(chunk.payload, self.config.audioLittleEndian)
-                    const wav = new WaveFile()
-                    wav.fromScratch(self.config.audioChannels, self.config.audioSampleRate, "32f", data)
-                    wav.toSampleRate(sampleRateTarget, { method: "cubic" })
-                    data = wav.getSamples(false, Float32Array<ArrayBuffer>) as
-                        any as Float32Array<ArrayBuffer>
-
-                    /*  queue chunk and converted data  */
-                    self.queueRecv.append({ type: "audio-frame", chunk, data })
+                    try {
+                        /*  convert audio samples from PCM/I16/48KHz to PCM/F32/16KHz  */
+                        let data = utils.convertBufToF32(chunk.payload, self.config.audioLittleEndian)
+                        const wav = new WaveFile()
+                        wav.fromScratch(self.config.audioChannels, self.config.audioSampleRate, "32f", data)
+                        wav.toSampleRate(sampleRateTarget, { method: "cubic" })
+                        data = wav.getSamples(false, Float32Array<ArrayBuffer>) as
+                            any as Float32Array<ArrayBuffer>
 
-                    callback()
+                        /*  queue chunk and converted data  */
+                        self.queueRecv.append({ type: "audio-frame", chunk, data })
+                        callback()
+                    }
+                    catch (error) {
+                        callback(error instanceof Error ? error : new Error("audio processing failed"))
+                    }
                 }
             },
 
             /*  receive no more audio chunks (writable side of stream)  */
             final (callback) {
+                if (self.shutdown) {
+                    callback()
+                    return
+                }
+
                 /*  signal end of file  */
                 self.queueRecv.append({ type: "audio-eof" })
                 callback()
@@ -214,8 +265,10 @@ export default class SpeechFlowNodeGender extends SpeechFlowNode {
             read (_size) {
                 /*  flush pending audio chunks  */
                 const flushPendingChunks = () => {
-                    if (self.shutdown)
+                    if (self.shutdown) {
+                        this.push(null)
                         return
+                    }
                     const element = self.queueSend.peek()
                     if (element !== undefined
                         && element.type === "audio-eof")
@@ -224,6 +277,10 @@ export default class SpeechFlowNodeGender extends SpeechFlowNode {
                         && element.type === "audio-frame"
                         && element.gender !== undefined) {
                         while (true) {
+                            if (self.shutdown) {
+                                this.push(null)
+                                return
+                            }
                             const element = self.queueSend.peek()
                             if (element === undefined)
                                 break
@@ -242,7 +299,7 @@ export default class SpeechFlowNodeGender extends SpeechFlowNode {
                             self.queue.trim()
                         }
                     }
-                    else
+                    else if (!self.shutdown)
                         self.queue.once("write", flushPendingChunks)
                 }
                 flushPendingChunks()
@@ -255,16 +312,43 @@ export default class SpeechFlowNodeGender extends SpeechFlowNode {
         /*  indicate shutdown  */
         this.shutdown = true
 
+        /*  cleanup working-off timer  */
+        if (this.workingOffTimer !== null) {
+            clearTimeout(this.workingOffTimer)
+            this.workingOffTimer = null
+        }
+
+        /*  cleanup progress interval  */
+        if (this.progressInterval !== null) {
+            clearInterval(this.progressInterval)
+            this.progressInterval = null
+        }
+
+        /*  remove all event listeners  */
+        this.queue.removeAllListeners("write")
+
         /*  close stream  */
         if (this.stream !== null) {
             this.stream.destroy()
             this.stream = null
         }
 
-        /*  close classifier  */
+        /*  cleanup classifier  */
         if (this.classifier !== null) {
-            this.classifier.dispose()
+            try {
+                const disposePromise = this.classifier.dispose()
+                const timeoutPromise = new Promise((resolve) => setTimeout(resolve, 5000))
+                await Promise.race([ disposePromise, timeoutPromise ])
+            }
+            catch (error) {
+                this.log("warning", `error during classifier cleanup: ${error}`)
+            }
             this.classifier = null
         }
+
+        /*  cleanup queue pointers  */
+        this.queue.pointerDelete("recv")
+        this.queue.pointerDelete("ac")
+        this.queue.pointerDelete("send")
     }
-}
+}

package/src/speechflow-node-a2a-meter.ts

@@ -20,7 +20,9 @@ export default class SpeechFlowNodeMeter extends SpeechFlowNode {
     public static name = "meter"
 
     /*  internal state  */
-    interval: ReturnType<typeof setInterval> | null = null
+    private interval: ReturnType<typeof setInterval> | null = null
+    private destroyed = false
+    private pendingCalculations = new Set<ReturnType<typeof setTimeout>>()
 
     /*  construct node  */
     constructor (id: string, cfg: { [ id: string ]: any }, opts: { [ id: string ]: any }, args: any[]) {
@@ -42,6 +44,9 @@ export default class SpeechFlowNodeMeter extends SpeechFlowNode {
         if (this.config.audioBitDepth !== 16 || !this.config.audioLittleEndian)
             throw new Error("meter node currently supports PCM-S16LE audio only")
 
+        /*  clear destruction flag  */
+        this.destroyed = false
+
         /*  internal state  */
         const sampleWindowDuration = 3 /* LUFS-S requires 3s */
         const sampleWindowSize = this.config.audioSampleRate * sampleWindowDuration
@@ -52,12 +57,14 @@ export default class SpeechFlowNodeMeter extends SpeechFlowNode {
 
         /*  setup loudness emitting interval  */
         this.interval = setInterval(() => {
+            if (this.destroyed)
+                return
             this.log("debug", `LUFS-S: ${lufss.toFixed(1)} dB, RMS: ${rms.toFixed(1)} dB`)
             this.sendResponse([ "meter", "LUFS-S", lufss ])
             this.sendResponse([ "meter", "RMS", rms ])
         }, this.params.interval)
 
-        /*  provide Duplex stream and internally attach to VAD  */
+        /*  provide Duplex stream and internally attach to meter  */
         const self = this
         this.stream = new Stream.Transform({
             writableObjectMode: true,
@@ -67,46 +74,78 @@ export default class SpeechFlowNodeMeter extends SpeechFlowNode {
 
             /*  transform audio chunk  */
             transform (chunk: SpeechFlowChunk, encoding, callback) {
+                if (self.destroyed) {
+                    callback(new Error("stream already destroyed"))
+                    return
+                }
                 if (!Buffer.isBuffer(chunk.payload))
                     callback(new Error("expected audio input as Buffer chunks"))
                 else if (chunk.payload.byteLength === 0)
                     callback()
                 else {
-                    /*  convert audio samples from PCM/I16 to PCM/F32  */
-                    const data = utils.convertBufToF32(chunk.payload, self.config.audioLittleEndian)
-
-                    /*  update internal audio sample sliding window  */
-                    const fusion = new Float32Array(sampleWindow.length + data.length)
-                    fusion.set(sampleWindow, 0)
-                    fusion.set(data, sampleWindow.length)
-                    sampleWindow = fusion.slice(fusion.length - sampleWindowSize)
-
-                    /*  asynchronously calculate the LUFS-S metric  */
-                    setTimeout(() => {
-                        const audioData = {
-                            sampleRate:       self.config.audioSampleRate,
-                            numberOfChannels: self.config.audioChannels,
-                            channelData:      [ sampleWindow ],
-                            duration:         sampleWindowDuration,
-                            length:           sampleWindow.length
-                        } satisfies AudioData
-                        const lufs = getLUFS(audioData, {
-                            channelMode: self.config.audioChannels === 1 ? "mono" : "stereo",
-                            calculateShortTerm:     true,
-                            calculateMomentary:     false,
-                            calculateLoudnessRange: false,
-                            calculateTruePeak:      false
-                        })
-                        lufss = lufs.shortTerm ? lufs.shortTerm[0] : 0
-                        rms = getRMS(audioData, { asDB: true })
-                    }, 0)
-
-                    /*  pass-through original audio chunk  */
-                    this.push(chunk)
-                    callback()
+                    try {
+                        /*  convert audio samples from PCM/I16 to PCM/F32  */
+                        const data = utils.convertBufToF32(chunk.payload, self.config.audioLittleEndian)
+
+                        /*  update internal audio sample sliding window  */
+                        if (data.length >= sampleWindowSize)
+                            /*  new data is larger than window, so just use the tail  */
+                            sampleWindow = data.slice(data.length - sampleWindowSize)
+                        else {
+                            /*  shift existing data and append new data  */
+                            const newWindow = new Float32Array(sampleWindowSize)
+                            const keepSize = sampleWindowSize - data.length
+                            newWindow.set(sampleWindow.slice(sampleWindow.length - keepSize), 0)
+                            newWindow.set(data, keepSize)
+                            sampleWindow = newWindow
+                        }
+
+                        /*  asynchronously calculate the LUFS-S metric  */
+                        const calculator = setTimeout(() => {
+                            if (self.destroyed)
+                                return
+                            try {
+                                self.pendingCalculations.delete(calculator)
+                                const audioData = {
+                                    sampleRate:       self.config.audioSampleRate,
+                                    numberOfChannels: self.config.audioChannels,
+                                    channelData:      [ sampleWindow ],
+                                    duration:         sampleWindowDuration,
+                                    length:           sampleWindow.length
+                                } satisfies AudioData
+                                const lufs = getLUFS(audioData, {
+                                    channelMode: self.config.audioChannels === 1 ? "mono" : "stereo",
+                                    calculateShortTerm:     true,
+                                    calculateMomentary:     false,
+                                    calculateLoudnessRange: false,
+                                    calculateTruePeak:      false
+                                })
+                                if (!self.destroyed) {
+                                    lufss = lufs.shortTerm ? lufs.shortTerm[0] : 0
+                                    rms = getRMS(audioData, { asDB: true })
+                                }
+                            }
+                            catch (error) {
+                                if (!self.destroyed)
+                                    self.log("warning", `meter calculation error: ${error}`)
+                            }
+                        }, 0)
+                        self.pendingCalculations.add(calculator)
+
+                        /*  pass-through original audio chunk  */
+                        this.push(chunk)
+                        callback()
+                    }
+                    catch (error) {
+                        callback(error instanceof Error ? error : new Error("Meter processing failed"))
+                    }
                 }
             },
             final (callback) {
+                if (self.destroyed) {
+                    callback()
+                    return
+                }
                 this.push(null)
                 callback()
             }
@@ -115,16 +154,24 @@ export default class SpeechFlowNodeMeter extends SpeechFlowNode {
 
     /*  close node  */
     async close () {
-        /*  close stream  */
-        if (this.stream !== null) {
-            this.stream.destroy()
-            this.stream = null
-        }
+        /*  indicate destruction  */
+        this.destroyed = true
+
+        /*  clear all pending calculations  */
+        for (const timeout of this.pendingCalculations)
+            clearTimeout(timeout)
+        this.pendingCalculations.clear()
 
         /*  stop interval  */
         if (this.interval !== null) {
             clearInterval(this.interval)
             this.interval = null
         }
+
+        /*  close stream  */
+        if (this.stream !== null) {
+            this.stream.destroy()
+            this.stream = null
+        }
     }
-}
+}