speechflow 1.4.5 → 1.5.1

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

@@ -7,15 +7,204 @@
 /*  standard dependencies  */
 import Stream                 from "node:stream"
 import { EventEmitter }       from "node:events"
+import { type, type Type }    from "arktype"
 
 /*  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  */
 import { SpeechFlowChunk }    from "./speechflow-node"
 
+/*  helper function for retrieving an Error object  */
+export function ensureError (error: unknown, prefix?: string): Error {
+    if (error instanceof Error && prefix === undefined)
+        return error
+    let msg = error instanceof Error ?
+        error.message : String(error)
+    if (prefix)
+        msg = `${prefix}: ${msg}`
+    return new Error(msg, { cause: error })
+}
+
+/*  helper function for retrieving a Promise object  */
+export function ensurePromise<T> (arg: T | Promise<T>): Promise<T> {
+    if (!(arg instanceof Promise))
+        arg = Promise.resolve(arg)
+    return arg
+}
+
+/*  helper function for running the finally code of "run"  */
+function runFinally (onfinally?: () => void) {
+    if (!onfinally)
+        return
+    try { onfinally() }
+    catch (_arg: unknown) { /*  ignored  */ }
+}
+
+/*  helper type for ensuring T contains no Promise  */
+type runNoPromise<T> =
+    [ T ] extends [ Promise<any> ] ? never : T
+
+/*  run a synchronous or asynchronous action  */
+export function run<T, X extends runNoPromise<T> | never> (
+    action:      () => X,
+    oncatch?:    (error: Error) => X | never,
+    onfinally?:  () => void
+): X
+export function run<T, X extends runNoPromise<T> | never> (
+    description: string,
+    action:      () => X,
+    oncatch?:    (error: Error) => X | never,
+    onfinally?:  () => void
+): X
+export function run<T, X extends (T | Promise<T>)> (
+    action:      () => X,
+    oncatch?:    (error: Error) => X,
+    onfinally?:  () => void
+): Promise<T>
+export function run<T, X extends (T | Promise<T>)> (
+    description: string,
+    action:      () => X,
+    oncatch?:    (error: Error) => X,
+    onfinally?:  () => void
+): Promise<T>
+export function run<T> (
+    ...args: any[]
+): T | Promise<T> | never {
+    /*  support overloaded signatures  */
+    let description: string | undefined
+    let action:      () => T | Promise<T> | never
+    let oncatch:     (error: Error) => T | Promise<T> | never
+    let onfinally:   () => void
+    if (typeof args[0] === "string") {
+        description = args[0]
+        action      = args[1]
+        oncatch     = args[2]
+        onfinally   = args[3]
+    }
+    else {
+        action      = args[0]
+        oncatch     = args[1]
+        onfinally   = args[2]
+    }
+
+    /*  perform the action  */
+    let result: T | Promise<T>
+    try {
+        result = action()
+    }
+    catch (arg: unknown) {
+        /*  synchronous case (error branch)  */
+        let error = ensureError(arg, description)
+        if (oncatch) {
+            try {
+                result = oncatch(error)
+            }
+            catch (arg: unknown) {
+                error = ensureError(arg, description)
+                runFinally(onfinally)
+                throw error
+            }
+            runFinally(onfinally)
+            return result
+        }
+        runFinally(onfinally)
+        throw error
+    }
+    if (result instanceof Promise) {
+        /*  asynchronous case (result or error branch)  */
+        return result.catch((arg: unknown) => {
+            /*  asynchronous case (error branch)  */
+            let error = ensureError(arg, description)
+            if (oncatch) {
+                try {
+                    return ensurePromise(oncatch(error))
+                }
+                catch (arg: unknown) {
+                    error = ensureError(arg, description)
+                    return Promise.reject(error)
+                }
+            }
+            return Promise.reject(error)
+        }).finally(() => {
+            /*  asynchronous case (result and error branch)  */
+            runFinally(onfinally)
+        })
+    }
+    else {
+        /*  synchronous case (result branch)  */
+        runFinally(onfinally)
+        return result
+    }
+}
+
+/*  run a synchronous or asynchronous action  */
+/* eslint @typescript-eslint/unified-signatures: off */
+export function runner<T, X extends runNoPromise<T> | never, F extends (...args: any[]) => X> (
+    action:      F,
+    oncatch?:    (error: Error) => X | never,
+    onfinally?:  () => void
+): F
+export function runner<T, X extends runNoPromise<T> | never, F extends (...args: any[]) => X> (
+    description: string,
+    action:      F,
+    oncatch?:    (error: Error) => X | never,
+    onfinally?:  () => void
+): F
+export function runner<T, X extends (T | Promise<T>), F extends (...args: any[]) => Promise<T>> (
+    action:      F,
+    oncatch?:    (error: Error) => X,
+    onfinally?:  () => void
+): F
+export function runner<T, X extends (T | Promise<T>), F extends (...args: any[]) => Promise<T>> (
+    description: string,
+    action:      F,
+    oncatch?:    (error: Error) => X,
+    onfinally?:  () => void
+): F
+export function runner<T> (
+    ...args: any[]
+): (...args: any[]) => T | Promise<T> | never {
+    /*  support overloaded signatures  */
+    let description: string | undefined
+    let action:      (...args: any[]) => T | Promise<T> | never
+    let oncatch:     (error: Error) => T | Promise<T> | never
+    let onfinally:   () => void
+    if (typeof args[0] === "string") {
+        description = args[0]
+        action      = args[1]
+        oncatch     = args[2]
+        onfinally   = args[3]
+    }
+    else {
+        action      = args[0]
+        oncatch     = args[1]
+        onfinally   = args[2]
+    }
+
+    /*  wrap the "run" operation on "action" into function
+        which exposes the signature of "action"  */
+    return (...args: any[]) => {
+        if (description)
+            return run(description, () => action(...args), oncatch, onfinally)
+        else
+            return run(() => action(...args), oncatch, onfinally)
+    }
+}
+
+/*  import an object with parsing and strict error handling  */
+export function importObject<T>(name: string, arg: object | string, validator: Type<T, {}>): T {
+    const obj: object = typeof arg === "string" ?
+        run(`${name}: parsing JSON`, () => JSON.parse(arg)) :
+        arg
+    const result = validator(obj)
+    if (result instanceof type.errors)
+        throw new Error(`${name}: validation: ${result.summary}`)
+    return result as T
+}
+
 /*  calculate duration of an audio buffer  */
 export function audioBufferDuration (
     buffer: Buffer,
@@ -86,6 +275,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 +423,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 +461,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 +719,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)
+}

package/speechflow-cli/src/speechflow.ts

@@ -15,6 +15,7 @@ import Inert             from "@hapi/inert"
 import WebSocket         from "ws"
 import HAPIWebSocket     from "hapi-plugin-websocket"
 import HAPIHeader        from "hapi-plugin-header"
+import OSC               from "osc-js"
 
 /*  external dependencies  */
 import { DateTime }      from "luxon"
@@ -33,6 +34,7 @@ import chalk             from "chalk"
 
 /*  internal dependencies  */
 import SpeechFlowNode    from "./speechflow-node"
+import * as utils        from "./speechflow-utils"
 import pkg               from "../../package.json"
 
 /*  central CLI context  */
@@ -70,6 +72,7 @@ let debug = false
             "[-p|--port <tcp-port>] " +
             "[-C|--cache <directory>] " +
             "[-d|--dashboard <type>:<id>:<name>[,...]] " +
+            "[-o|--osc <ip-address>:<udp-port> " +
             "[-e|--expression <expression>] " +
             "[-f|--file <file>] " +
             "[-c|--config <id>@<yaml-config-file>] " +
@@ -137,6 +140,15 @@ let debug = false
             default:  "",
             describe: "list of dashboard block types and names"
         })
+        .option("o", {
+            alias:    "osc",
+            type:     "string",
+            array:    false,
+            coerce,
+            nargs:    1,
+            default:  "",
+            describe: "OSC/UDP endpoint to send dashboard information"
+        })
         .option("e", {
             alias:    "expression",
             type:     "string",
@@ -247,16 +259,7 @@ let debug = false
             throw new Error("invalid configuration file specification (expected \"<id>@<yaml-config-file>\")")
         const [ , id, file ] = m
         const yaml = await cli.input(file, { encoding: "utf8" })
-        let obj: any
-        try {
-            obj = jsYAML.load(yaml)
-        }
-        catch (err) {
-            if (err instanceof Error)
-                throw new Error(`failed to parse YAML configuration: ${err.message}`)
-            else
-                throw new Error(`failed to parse YAML configuration: ${err}`)
-        }
+        const obj: any = utils.run("parsing YAML configuration", () => jsYAML.load(yaml))
         if (obj[id] === undefined)
             throw new Error(`no such id "${id}" found in configuration file "${file}"`)
         config = obj[id] as string
@@ -267,17 +270,28 @@ let debug = false
 
     /*  load internal SpeechFlow nodes  */
     const pkgsI = [
+        "./speechflow-node-a2a-compressor.js",
+        "./speechflow-node-a2a-expander.js",
         "./speechflow-node-a2a-ffmpeg.js",
+        "./speechflow-node-a2a-filler.js",
+        "./speechflow-node-a2a-gain.js",
         "./speechflow-node-a2a-gender.js",
         "./speechflow-node-a2a-meter.js",
         "./speechflow-node-a2a-mute.js",
+        "./speechflow-node-a2a-rnnoise.js",
+        "./speechflow-node-a2a-speex.js",
         "./speechflow-node-a2a-vad.js",
         "./speechflow-node-a2a-wav.js",
+        "./speechflow-node-a2t-awstranscribe.js",
         "./speechflow-node-a2t-deepgram.js",
+        "./speechflow-node-a2t-openaitranscribe.js",
+        "./speechflow-node-t2a-awspolly.js",
         "./speechflow-node-t2a-elevenlabs.js",
         "./speechflow-node-t2a-kokoro.js",
+        "./speechflow-node-t2t-awstranslate.js",
         "./speechflow-node-t2t-deepl.js",
         "./speechflow-node-t2t-format.js",
+        "./speechflow-node-t2t-google.js",
         "./speechflow-node-t2t-ollama.js",
         "./speechflow-node-t2t-openai.js",
         "./speechflow-node-t2t-sentence.js",
@@ -329,6 +343,19 @@ let debug = false
         cacheDir:          args.C
     }
 
+    /*  provide access to internal communication busses  */
+    const busses = new Map<string, EventEmitter>()
+    const accessBus = (name: string): EventEmitter => {
+        let bus: EventEmitter
+        if (busses.has(name))
+            bus = busses.get(name)!
+        else {
+            bus = new EventEmitter()
+            busses.set(name, bus)
+        }
+        return bus
+    }
+
     /*  handle one-time status query of nodes  */
     if (args.S) {
         const table = new Table({
@@ -344,6 +371,7 @@ let debug = false
         for (const name of Object.keys(nodes)) {
             cli!.log("info", `gathering status of node <${name}>`)
             const node = new nodes[name](name, cfg, {}, [])
+            node._accessBus = accessBus
             const status = await Promise.race<{ [ key: string ]: string | number }>([
                 node.status(),
                 new Promise<never>((resolve, reject) => setTimeout(() =>
@@ -403,6 +431,7 @@ let debug = false
                     nodeNums.set(NodeClass, ++num)
                     const name = num === 1 ? id : `${id}:${num}`
                     node = new NodeClass(name, cfg, opts, args)
+                    node._accessBus = accessBus
                 }
                 catch (err) {
                     /*  fatal error  */
@@ -412,13 +441,14 @@ let debug = false
                         cli!.log("error", `creation of node <${id}> failed: ${err}`)
                     process.exit(1)
                 }
-                const params = Object.keys(node.params)
+                const params = Object.keys(node!.params)
+                    .filter((key) => !key.match(/key/))
                     .map((key) => `${key}: ${JSON.stringify(node.params[key])}`).join(", ")
-                cli!.log("info", `create node <${node.id}> (${params})`)
-                graphNodes.add(node)
-                return node
+                cli!.log("info", `create node <${node!.id}> (${params})`)
+                graphNodes.add(node!)
+                return node!
             },
-            connectNode (node1: SpeechFlowNode, node2: SpeechFlowNode) {
+            connectNodes (node1: SpeechFlowNode, node2: SpeechFlowNode) {
                 cli!.log("info", `connect node <${node1.id}> to node <${node2.id}>`)
                 node1.connect(node2)
             }
@@ -481,7 +511,7 @@ let debug = false
             new Promise<never>((resolve, reject) => setTimeout(() =>
                 reject(new Error("timeout")), 10 * 1000))
         ]).catch((err: Error) => {
-            cli!.log("error", `[${node.id}]: failed to open node <${node.id}>: ${err.message}`)
+            cli!.log("error", `<${node.id}>: failed to open node <${node.id}>: ${err.message}`)
             throw new Error(`failed to open node <${node.id}>: ${err.message}`)
         })
     }
@@ -631,8 +661,7 @@ let debug = false
     hapi.route({
         method: "GET",
         path:   "/api/{req}/{node}/{params*}",
-        options: {
-        },
+        options: {},
         handler: (request: HAPI.Request, h: HAPI.ResponseToolkit) => {
             const peer = request.info.remoteAddress
             const params = request.params.params as string ?? ""
@@ -644,11 +673,9 @@ let debug = false
                 args:    params.split("/").filter((seg) => seg !== "")
             }
             cli!.log("info", `HAPI: peer ${peer}: GET: ${JSON.stringify(req)}`)
-            return consumeExternalRequest(req).then(() => {
-                return h.response({ response: "OK" }).code(200)
-            }).catch((err) => {
-                return h.response({ response: "ERROR", data: err.message }).code(417)
-            })
+            return consumeExternalRequest(req)
+                .then(()     => h.response({ response: "OK" }).code(200))
+                .catch((error: unknown) => h.response({ response: "ERROR", data: utils.ensureError(error).message }).code(417))
         }
     })
     hapi.route({
@@ -691,11 +718,9 @@ let debug = false
             if (req instanceof arktype.type.errors)
                 return h.response({ response: "ERROR", data: `invalid request: ${req.summary}` }).code(417)
             cli!.log("info", `HAPI: peer ${peer}: POST: ${JSON.stringify(req)}`)
-            return consumeExternalRequest(req).then(() => {
-                return h.response({ response: "OK" }).code(200)
-            }).catch((err: Error) => {
-                return h.response({ response: "ERROR", data: err.message }).code(417)
-            })
+            return consumeExternalRequest(req)
+                .then(()            => h.response({ response: "OK" }).code(200))
+                .catch((err: Error) => h.response({ response: "ERROR", data: err.message }).code(417))
         }
     })
     await hapi.start()
@@ -713,10 +738,25 @@ let debug = false
         })
     }
 
-    /*  hook for dashboardInfo method of nodes  */
+    /*  establish OSC event emission  */
+    let sendOSC: (url: string, ...args: any[]) => void
+    if (args.o !== "") {
+        const osc = new OSC({ plugin: new OSC.DatagramPlugin({ type: "udp4" }) })
+        const m = args.o.match(/^(.+?):(\d+)$/)
+        if (m === null)
+            throw new Error("invalid OSC/UDP endpoint (expected <ip-adress>:<udp-port>)")
+        const host = m[1]
+        const port = m[2]
+        sendOSC = (url: string, ...args: any[]) => {
+            const msg = new OSC.Message(url, ...args)
+            osc.send(msg, { host, port })
+        }
+    }
+
+    /*  hook for send-dashboard method of nodes  */
     for (const node of graphNodes) {
-        node.on("dashboard-info", (info: {
-            type: string,
+        node.on("send-dashboard", (info: {
+            type: "audio" | "text",
             id:   string,
             kind: "final" | "intermediate",
             value: string | number
@@ -730,6 +770,17 @@ let debug = false
                 cli!.log("debug", `HAPI: dashboard peer ${peer}: send ${data}`)
                 info.ws.send(data)
             }
+            for (const node of graphNodes) {
+                Promise.race<void>([
+                    node.receiveDashboard(info.type, info.id, info.kind, info.value),
+                    new Promise<never>((resolve, reject) => setTimeout(() =>
+                        reject(new Error("timeout")), 10 * 1000))
+                ]).catch((err: Error) => {
+                    cli!.log("warning", `sending dashboard info to node <${node.id}> failed: ${err.message}`)
+                })
+            }
+            if (args.o !== "")
+                sendOSC("/speechflow/dashboard", info.type, info.id, info.kind, info.value)
         })
     }
 
@@ -777,8 +828,8 @@ let debug = false
                 Promise.all(closePromises),
                 new Promise((resolve, reject) =>
                     setTimeout(() => reject(new Error("timeout for all peers")), 5 * 1000))
-            ]).catch((err) => {
-                cli!.log("warning", `HAPI: WebSockets failed to close: ${err}`)
+            ]).catch((error: unknown) => {
+                cli!.log("warning", `HAPI: WebSockets failed to close: ${utils.ensureError(error).message}`)
             })
             wsPeers.clear()
         }