speechflow 1.4.5 → 1.5.0

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

@@ -0,0 +1,172 @@
+/*
+**  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>
+*/
+
+/*  internal types  */
+interface InputChunkMessage {
+    type: "input-chunk"
+    chunkId: string
+    data: { pcmData: Float32Array, channels: number }
+}
+interface StartCaptureMessage {
+    type: "start-capture"
+    chunkId: string
+    expectedSamples: number
+}
+type WorkletMessage = InputChunkMessage | StartCaptureMessage
+interface ChunkData {
+    data: Float32Array
+    chunkId: string
+}
+interface ChunkStartedMessage {
+    type: "chunk-started"
+    chunkId: string
+}
+interface CaptureCompleteMessage {
+    type: "capture-complete"
+    chunkId: string
+    data: number[]
+}
+
+/*  audio source node  */
+class AudioSourceProcessor extends AudioWorkletProcessor {
+    /*  internal state  */
+    private pendingData:  ChunkData[] = []
+    private currentChunk: ChunkData | null = null
+    private currentOffset = 0
+
+    /*  node construction  */
+    constructor() {
+        super()
+
+        /*  receive input chunks  */
+        this.port.addEventListener("message", (event: MessageEvent<WorkletMessage>) => {
+            const { type, chunkId } = event.data
+            if (type === "input-chunk")
+                this.pendingData.push({ data: event.data.data.pcmData, chunkId })
+        })
+    }
+
+    /*  process audio frame  */
+    process(
+        inputs:     Float32Array[][],            /* unused */
+        outputs:    Float32Array[][],
+        parameters: Record<string, Float32Array> /* unused */
+    ): boolean {
+        /*  determine output  */
+        const output = outputs[0]
+        if (!output || output.length === 0)
+            return true
+        const frameCount = output[0].length
+        const channelCount = output.length
+
+        /*  get current chunk if we don't have one  */
+        if (this.currentChunk === null && this.pendingData.length > 0) {
+            this.currentChunk = this.pendingData.shift()!
+            this.currentOffset = 0
+
+            /*  signal chunk start  */
+            const message: ChunkStartedMessage = {
+                type: "chunk-started",
+                chunkId: this.currentChunk.chunkId
+            }
+            this.port.postMessage(message)
+        }
+
+        /*  process input  */
+        if (this.currentChunk) {
+            /*  output current chunk  */
+            const samplesPerChannel = this.currentChunk.data.length / channelCount
+            const remainingFrames   = samplesPerChannel - this.currentOffset
+            const framesToProcess   = Math.min(frameCount, remainingFrames)
+
+            /*  copy data from current chunk (interleaved to planar)  */
+            for (let frame = 0; frame < framesToProcess; frame++) {
+                for (let ch = 0; ch < channelCount; ch++) {
+                    const interleavedIndex = (this.currentOffset + frame) * channelCount + ch
+                    output[ch][frame] = this.currentChunk.data[interleavedIndex] ?? 0
+                }
+            }
+
+            /*  zero-pad remaining output if needed  */
+            for (let frame = framesToProcess; frame < frameCount; frame++)
+                for (let ch = 0; ch < channelCount; ch++)
+                    output[ch][frame] = 0
+
+            /*  check if current chunk is finished  */
+            this.currentOffset += framesToProcess
+            if (this.currentOffset >= samplesPerChannel) {
+                this.currentChunk  = null
+                this.currentOffset = 0
+            }
+        }
+        else {
+            /*  output silence when no input  */
+            for (let ch = 0; ch < channelCount; ch++)
+                output[ch].fill(0)
+        }
+        return true
+    }
+}
+
+/*  audio capture node  */
+class AudioCaptureProcessor extends AudioWorkletProcessor {
+    /*  internal state  */
+    private activeCaptures = new Map<string, { data: number[], expectedSamples: number }>()
+
+    /*  node construction  */
+    constructor() {
+        super()
+
+        /*  receive start of capturing command  */
+        this.port.addEventListener("message", (event: MessageEvent<WorkletMessage>) => {
+            const { type, chunkId } = event.data
+            if (type === "start-capture") {
+                this.activeCaptures.set(chunkId, {
+                    data: [],
+                    expectedSamples: event.data.expectedSamples
+                })
+            }
+        })
+    }
+
+    /*  process audio frame  */
+    process(
+        inputs:     Float32Array[][],
+        outputs:    Float32Array[][],             /* unused */
+        parameters: Record<string, Float32Array>  /* unused */
+    ): boolean {
+        /*  determine input  */
+        const input = inputs[0]
+        if (!input || input.length === 0 || this.activeCaptures.size === 0)
+            return true
+        const frameCount = input[0].length
+        const channelCount = input.length
+
+        /*  iterate over all active captures  */
+        for (const [ chunkId, capture ] of this.activeCaptures) {
+            /*  convert planar to interleaved  */
+            for (let frame = 0; frame < frameCount; frame++)
+                for (let ch = 0; ch < channelCount; ch++)
+                    capture.data.push(input[ch][frame])
+
+            /*  send back captured data  */
+            if (capture.data.length >= capture.expectedSamples) {
+                const message: CaptureCompleteMessage = {
+                    type: "capture-complete",
+                    chunkId,
+                    data: capture.data.slice(0, capture.expectedSamples)
+                }
+                this.port.postMessage(message)
+                this.activeCaptures.delete(chunkId)
+            }
+        }
+        return true
+    }
+}
+
+/*  register the new audio nodes  */
+registerProcessor("source",  AudioSourceProcessor)
+registerProcessor("capture", AudioCaptureProcessor)

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

@@ -0,0 +1,147 @@
+/*
+**  SpeechFlow - Speech Processing Flow Graph
+**  Copyright (c) 2024-2025 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under GPL 3.0 <https://spdx.org/licenses/GPL-3.0-only>
+*/
+
+/*  standard dependencies  */
+import path from "node:path"
+
+/*  external dependencies  */
+import { AudioContext, AudioWorkletNode } from "node-web-audio-api"
+
+export class WebAudio {
+    /*  internal state  */
+    public audioContext: AudioContext
+    public sourceNode:   AudioWorkletNode | null = null
+    public captureNode:  AudioWorkletNode | null = null
+    private pendingPromises = new Map<string, {
+        resolve: (value: Int16Array) => void
+        reject: (error: Error) => void
+        timeout: ReturnType<typeof setTimeout>
+    }>()
+
+    /*  construct object  */
+    constructor(
+        public sampleRate: number,
+        public channels: number
+    ) {
+        /*  create new audio context  */
+        this.audioContext = new AudioContext({
+            sampleRate,
+            latencyHint: "interactive"
+        })
+    }
+
+    /*  setup object  */
+    public async setup (): Promise<void> {
+        /*  ensure audio context is not suspended  */
+        if (this.audioContext.state === "suspended")
+            await this.audioContext.resume()
+
+        /*  add audio worklet module  */
+        const url = path.resolve(__dirname, "speechflow-utils-audio-wt.js")
+        await this.audioContext.audioWorklet.addModule(url)
+
+        /*  create source node  */
+        this.sourceNode = new AudioWorkletNode(this.audioContext, "source", {
+            numberOfInputs:  0,
+            numberOfOutputs: 1,
+            outputChannelCount: [ this.channels ]
+        })
+
+        /*  create capture node  */
+        this.captureNode = new AudioWorkletNode(this.audioContext, "capture", {
+            numberOfInputs:  1,
+            numberOfOutputs: 0
+        })
+        this.captureNode!.port.addEventListener("message", (event) => {
+            const { type, chunkId, data } = event.data ?? {}
+            if (type === "capture-complete") {
+                const promise = this.pendingPromises.get(chunkId)
+                if (promise) {
+                    clearTimeout(promise.timeout)
+                    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)))
+                    promise.resolve(int16Data)
+                }
+            }
+        })
+
+        /*  start ports  */
+        this.sourceNode.port.start()
+        this.captureNode!.port.start()
+    }
+
+    /*  process single audio chunk  */
+    public async process (int16Array: Int16Array): Promise<Int16Array> {
+        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)
+                reject(new Error("processing timeout"))
+            }, (int16Array.length / this.audioContext.sampleRate) * 1000 + 250)
+            if (this.captureNode !== null)
+                this.pendingPromises.set(chunkId, { resolve, reject, timeout })
+            try {
+                const float32Data = new Float32Array(int16Array.length)
+                for (let i = 0; i < int16Array.length; i++)
+                    float32Data[i] = int16Array[i] / 32768.0
+
+                /*  start capture first  */
+                if (this.captureNode !== null) {
+                    this.captureNode?.port.postMessage({
+                        type: "start-capture",
+                        chunkId,
+                        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)
+                if (this.captureNode !== null)
+                    this.pendingPromises.delete(chunkId)
+                reject(new Error(`failed to process chunk: ${error}`))
+            }
+        })
+    }
+
+    public async destroy (): Promise<void> {
+        /*  reject all pending promises  */
+        try {
+            this.pendingPromises.forEach(({ reject, timeout }) => {
+                clearTimeout(timeout)
+                reject(new Error("WebAudio destroyed"))
+            })
+            this.pendingPromises.clear()
+        }
+        catch (_err) {
+            /* ignored - cleanup during shutdown */
+        }
+
+        /*  disconnect nodes  */
+        if (this.sourceNode !== null) {
+            this.sourceNode.disconnect()
+            this.sourceNode = null
+        }
+        if (this.captureNode !== null) {
+            this.captureNode.disconnect()
+            this.captureNode = null
+        }
+
+        /*  stop context  */
+        await this.audioContext.close()
+    }
+}

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

@@ -10,7 +10,7 @@ import { EventEmitter }       from "node:events"
 
 /*  external dependencies  */
 import { DateTime, Duration } from "luxon"
-import CBOR                   from "cbor2"
+import * as CBOR              from "cbor2"
 import * as IntervalTree      from "node-interval-tree"
 
 /*  internal dependencies  */
@@ -86,6 +86,31 @@ export function convertF32ToBuf (arr: Float32Array) {
     return Buffer.from(int16Array.buffer)
 }
 
+/*  helper function: convert Buffer in PCM/I16 to Int16Array  */
+export function convertBufToI16 (buf: Buffer, littleEndian = true) {
+    if (buf.length % 2 !== 0)
+        throw new Error("buffer length must be even for 16-bit samples")
+    const dataView = new DataView(buf.buffer, buf.byteOffset, buf.byteLength)
+    const arr = new Int16Array(buf.length / 2)
+    for (let i = 0; i < buf.length / 2; i++)
+        arr[i] = dataView.getInt16(i * 2, littleEndian)
+    return arr
+}
+
+/*  helper function: convert In16Array in PCM/I16 to Buffer  */
+export function convertI16ToBuf (arr: Int16Array, littleEndian = true) {
+    if (arr.length === 0)
+        return Buffer.alloc(0)
+    const buf = Buffer.allocUnsafe(arr.length * 2)
+    for (let i = 0; i < arr.length; i++) {
+        if (littleEndian)
+            buf.writeInt16LE(arr[i], i * 2)
+        else
+            buf.writeInt16BE(arr[i], i * 2)
+    }
+    return buf
+}
+
 /*  create a Duplex/Transform stream which has
     object-mode on Writable side and buffer/string-mode on Readable side  */
 export function createTransformStreamForWritableSide () {
@@ -209,25 +234,16 @@ export class SingleQueue<T> extends EventEmitter {
     }
     read () {
         return new Promise<T>((resolve, reject) => {
-            const consume = () => {
-                if (this.queue.length > 0)
-                    return this.queue.pop()!
+            const consume = () =>
+                this.queue.length > 0 ? this.queue.pop()! : null
+            const tryToConsume = () => {
+                const item = consume()
+                if (item !== null)
+                    resolve(item)
                 else
-                    return null
-            }
-            let item = consume()
-            if (item !== null)
-                resolve(item)
-            else {
-                const tryToConsume = () => {
-                    item = consume()
-                    if (item !== null)
-                        resolve(item)
-                    else
-                        this.once("dequeue", tryToConsume)
-                }
-                this.once("dequeue", tryToConsume)
+                    this.once("dequeue", tryToConsume)
             }
+            tryToConsume()
         })
     }
 }
@@ -256,22 +272,16 @@ export class DoubleQueue<T0, T1> extends EventEmitter {
                     const item1 = this.queue1.pop() as T1
                     return [ item0, item1 ]
                 }
-                else
-                    return null
+                return null
             }
-            let items = consume()
-            if (items !== null)
-                resolve(items)
-            else {
-                const tryToConsume = () => {
-                    items = consume()
-                    if (items !== null)
-                        resolve(items)
-                    else
-                        this.once("dequeue", tryToConsume)
-                }
-                this.once("dequeue", tryToConsume)
+            const tryToConsume = () => {
+                const items = consume()
+                if (items !== null)
+                    resolve(items)
+                else
+                    this.once("dequeue", tryToConsume)
             }
+            tryToConsume()
         })
     }
 }
@@ -520,3 +530,86 @@ export class TimeStore<T> extends EventEmitter {
         this.tree = new IntervalTree.IntervalTree<TimeStoreInterval<T>>()
     }
 }
+
+/*  asynchronous queue  */
+export class AsyncQueue<T> {
+    private queue: Array<T | null> = []
+    private resolvers: ((v: T | null) => void)[] = []
+    write (v: T | null) {
+        const resolve = this.resolvers.shift()
+        if (resolve)
+            resolve(v)
+        else
+            this.queue.push(v)
+    }
+    async read () {
+        if (this.queue.length > 0)
+            return this.queue.shift()!
+        else
+            return new Promise<T | null>((resolve) => this.resolvers.push(resolve))
+    }
+    destroy () {
+        for (const resolve of this.resolvers)
+            resolve(null)
+        this.resolvers = []
+        this.queue = []
+    }
+}
+
+/*  process Int16Array in fixed-size segments  */
+export async function processInt16ArrayInSegments (
+    data: Int16Array<ArrayBuffer>,
+    segmentSize: number,
+    processor: (segment: Int16Array<ArrayBuffer>) => Promise<Int16Array<ArrayBuffer>>
+): Promise<Int16Array<ArrayBuffer>> {
+    /*  process full segments  */
+    let i = 0
+    while ((i + segmentSize) <= data.length) {
+        const segment = data.slice(i, i + segmentSize)
+        const result = await processor(segment)
+        data.set(result, i)
+        i += segmentSize
+    }
+
+    /*  process final partial segment if it exists  */
+    if (i < data.length) {
+        const len = data.length - i
+        const segment = new Int16Array(segmentSize)
+        segment.set(data.slice(i), 0)
+        segment.fill(0, len, segmentSize)
+        const result = await processor(segment)
+        data.set(result.slice(0, len), i)
+    }
+    return data
+}
+
+/*  cached regular expression class  */
+export class CachedRegExp {
+    private cache = new Map<string, RegExp>()
+    compile (pattern: string): RegExp | null {
+        if (this.cache.has(pattern))
+            return this.cache.get(pattern)!
+        try {
+            const regex = new RegExp(pattern)
+            this.cache.set(pattern, regex)
+            return regex
+        }
+        catch (_error) {
+            return null
+        }
+    }
+    clear (): void {
+        this.cache.clear()
+    }
+    size (): number {
+        return this.cache.size
+    }
+}
+
+/*  helper functions for linear/decibel conversions  */
+export function lin2dB (x: number): number {
+    return 20 * Math.log10(Math.max(x, 1e-12))
+}
+export function dB2lin (db: number): number {
+    return Math.pow(10, db / 20)
+}