speechflow 1.5.0 → 1.6.0

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

@@ -18,6 +18,7 @@ import HAPIWebSocket from "hapi-plugin-websocket"
 
 /*  internal dependencies  */
 import SpeechFlowNode, { SpeechFlowChunk } from "./speechflow-node"
+import * as utils                          from "./speechflow-utils"
 
 type wsPeerCtx = {
     peer: string
@@ -29,9 +30,9 @@ type wsPeerInfo = {
 }
 
 /*  SpeechFlow node for subtitle (text-to-text) "translations"  */
-export default class SpeechFlowNodeSubtitle extends SpeechFlowNode {
+export default class SpeechFlowNodeT2TSubtitle extends SpeechFlowNode {
     /*  declare official node name  */
-    public static name = "subtitle"
+    public static name = "t2t-subtitle"
 
     /*  internal state  */
     private sequenceNo = 1
@@ -43,11 +44,11 @@ export default class SpeechFlowNodeSubtitle extends SpeechFlowNode {
 
         /*  declare node configuration parameters  */
         this.configure({
-            format: { type: "string", pos: 0, val: "srt", match: /^(?:srt|vtt)$/ },
-            words:  { type: "boolean", val: false },
-            mode:   { type: "string",  val: "export", match: /^(?:export|render)$/ },
-            addr:   { type: "string",  val: "127.0.0.1" },
-            port:   { type: "number",  val: 8585 }
+            format: { type: "string",  pos: 0, val: "srt",    match: /^(?:srt|vtt)$/ },
+            words:  { type: "boolean",         val: false },
+            mode:   { type: "string",          val: "export", match: /^(?:export|render)$/ },
+            addr:   { type: "string",          val: "127.0.0.1" },
+            port:   { type: "number",          val: 8585 }
         })
 
         /*  declare node input/output format  */
@@ -145,8 +146,8 @@ export default class SpeechFlowNodeSubtitle extends SpeechFlowNode {
                                 chunkNew.payload = payload
                                 this.push(chunkNew)
                                 callback()
-                            }).catch((err) => {
-                                callback(err)
+                            }).catch((error: unknown) => {
+                                callback(utils.ensureError(error))
                             })
                         }
                     }

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

@@ -13,15 +13,16 @@ import * as Transformers from "@huggingface/transformers"
 
 /*  internal dependencies  */
 import SpeechFlowNode, { SpeechFlowChunk } from "./speechflow-node"
+import * as utils                          from "./speechflow-utils"
 
 /*  internal utility types  */
 type ConfigEntry = { systemPrompt: string, chat: Array<{ role: string, content: string }> }
 type Config      = { [ key: string ]: ConfigEntry }
 
 /*  SpeechFlow node for Transformers text-to-text translation  */
-export default class SpeechFlowNodeTransformers extends SpeechFlowNode {
+export default class SpeechFlowNodeT2TTransformers extends SpeechFlowNode {
     /*  declare official node name  */
-    public static name = "transformers"
+    public static name = "t2t-transformers"
 
     /*  internal state  */
     private translator: Transformers.TranslationPipeline    | null = null
@@ -212,8 +213,8 @@ export default class SpeechFlowNodeTransformers extends SpeechFlowNode {
                         chunk.payload = payload
                         this.push(chunk)
                         callback()
-                    }).catch((err) => {
-                        callback(err)
+                    }).catch((error: unknown) => {
+                        callback(utils.ensureError(error))
                     })
                 }
             },

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

@@ -12,9 +12,9 @@ import SpeechFlowNode, { SpeechFlowChunk } from "./speechflow-node"
 import * as utils                          from "./speechflow-utils"
 
 /*  SpeechFlow node for data flow filtering (based on meta information)  */
-export default class SpeechFlowNodeFilter extends SpeechFlowNode {
+export default class SpeechFlowNodeX2XFilter extends SpeechFlowNode {
     /*  declare official node name  */
-    public static name = "filter"
+    public static name = "x2x-filter"
 
     /*  cached regular expression instance  */
     private cachedRegExp = new utils.CachedRegExp()

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

@@ -14,9 +14,9 @@ import { Duration } from "luxon"
 import SpeechFlowNode, { SpeechFlowChunk } from "./speechflow-node"
 
 /*  SpeechFlow node for data flow tracing  */
-export default class SpeechFlowNodeTrace extends SpeechFlowNode {
+export default class SpeechFlowNodeX2XTrace extends SpeechFlowNode {
     /*  declare official node name  */
-    public static name = "trace"
+    public static name = "x2x-trace"
 
     /*  construct node  */
     constructor (id: string, cfg: { [ id: string ]: any }, opts: { [ id: string ]: any }, args: any[]) {

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

@@ -15,9 +15,9 @@ import SpeechFlowNode   from "./speechflow-node"
 import * as utils       from "./speechflow-utils"
 
 /*  SpeechFlow node for device access  */
-export default class SpeechFlowNodeDevice extends SpeechFlowNode {
+export default class SpeechFlowNodeXIODevice extends SpeechFlowNode {
     /*  declare official node name  */
-    public static name = "device"
+    public static name = "xio-device"
 
     /*  internal state  */
     private io: PortAudio.IoStreamRead

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

@@ -13,9 +13,9 @@ import SpeechFlowNode   from "./speechflow-node"
 import * as utils       from "./speechflow-utils"
 
 /*  SpeechFlow node for file access  */
-export default class SpeechFlowNodeFile extends SpeechFlowNode {
+export default class SpeechFlowNodeXIOFile extends SpeechFlowNode {
     /*  declare official node name  */
-    public static name = "file"
+    public static name = "xio-file"
 
     /*  construct node  */
     constructor (id: string, cfg: { [ id: string ]: any }, opts: { [ id: string ]: any }, args: any[]) {
@@ -59,6 +59,28 @@ export default class SpeechFlowNodeFile extends SpeechFlowNode {
         if (this.params.path === "")
             throw new Error("required parameter \"path\" has to be given")
 
+        /*  utility function: create a writable stream as chunker that
+            writes to process.stdout but properly handles finish events.
+            This ensures the writable side of the composed stream below
+            properly signals completion while keeping process.stdout open
+            (as it's a global stream that shouldn't be closed by individual nodes). */
+        const createStdoutChunker = () => {
+            return new Stream.Writable({
+                highWaterMark: this.params.type === "audio" ?
+                    highWaterMarkAudio : highWaterMarkText,
+                write (chunk: Buffer | string, encoding, callback) {
+                    const canContinue = process.stdout.write(chunk, encoding)
+                    if (canContinue)
+                        callback()
+                    else
+                        process.stdout.once("drain", callback)
+                },
+                final (callback) {
+                    callback()
+                }
+            })
+        }
+
         /*  dispatch according to mode and path  */
         if (this.params.mode === "rw") {
             if (this.params.path === "-") {
@@ -145,17 +167,13 @@ export default class SpeechFlowNodeFile extends SpeechFlowNode {
         else if (this.params.mode === "w") {
             if (this.params.path === "-") {
                 /*  standard I/O  */
-                let chunker: Stream.PassThrough
-                if (this.params.type === "audio") {
+                if (this.params.type === "audio")
                     process.stdout.setEncoding()
-                    chunker = new Stream.PassThrough({ highWaterMark: highWaterMarkAudio })
-                }
-                else {
+                else
                     process.stdout.setEncoding(this.config.textEncoding)
-                    chunker = new Stream.PassThrough({ highWaterMark: highWaterMarkText })
-                }
+                const chunker = createStdoutChunker()
                 const wrapper = utils.createTransformStreamForWritableSide()
-                this.stream = Stream.compose(wrapper, chunker, process.stdout)
+                this.stream = Stream.compose(wrapper, chunker)
             }
             else {
                 /*  file I/O  */
@@ -178,18 +196,22 @@ export default class SpeechFlowNodeFile extends SpeechFlowNode {
     async close () {
         /*  shutdown stream  */
         if (this.stream !== null) {
-            await new Promise<void>((resolve, reject) => {
-                if (this.stream instanceof Stream.Writable || this.stream instanceof Stream.Duplex) {
-                    this.stream.end((err?: Error) => {
-                        if (err)
-                            reject(err)
-                        else
+            await Promise.race([
+                new Promise<void>((resolve, reject) => {
+                    if (this.stream instanceof Stream.Writable || this.stream instanceof Stream.Duplex) {
+                        if (this.stream.writableEnded || this.stream.destroyed)
                             resolve()
-                    })
-                }
-                else
-                    resolve()
-            })
+                        else
+                            this.stream.end((err?: Error) => {
+                                if (err) reject(err)
+                                else     resolve()
+                            })
+                    }
+                    else
+                        resolve()
+                }),
+                new Promise<void>((resolve) => setTimeout(() => resolve(), 5000))
+            ])
             if (this.params.path !== "-")
                 this.stream.destroy()
             this.stream = null

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

@@ -16,9 +16,9 @@ import SpeechFlowNode, { SpeechFlowChunk } from "./speechflow-node"
 import * as utils                          from "./speechflow-utils"
 
 /*  SpeechFlow node for MQTT networking  */
-export default class SpeechFlowNodeMQTT extends SpeechFlowNode {
+export default class SpeechFlowNodeXIOMQTT extends SpeechFlowNode {
     /*  declare official node name  */
-    public static name = "mqtt"
+    public static name = "xio-mqtt"
 
     /*  internal state  */
     private broker: MQTT.MqttClient | null = null

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

@@ -16,9 +16,9 @@ import SpeechFlowNode, { SpeechFlowChunk } from "./speechflow-node"
 import * as utils                          from "./speechflow-utils"
 
 /*  SpeechFlow node for Websocket networking  */
-export default class SpeechFlowNodeWebsocket extends SpeechFlowNode {
+export default class SpeechFlowNodeXIOWebSocket extends SpeechFlowNode {
     /*  declare official node name  */
-    public static name = "websocket"
+    public static name = "xio-websocket"
 
     /*  internal state  */
     private server: ws.WebSocketServer | null = null

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

@@ -7,6 +7,7 @@
 /*  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"
@@ -16,6 +17,194 @@ 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 (_error: 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 oncatch(error)
+                }
+                catch (arg: unknown) {
+                    error = ensureError(arg, description)
+                    throw error
+                }
+            }
+            throw 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,
@@ -139,6 +328,11 @@ export function createTransformStreamForReadableSide (type: "text" | "audio", ge
         decodeStrings: false,
         highWaterMark: (type === "audio" ? 19200 : 65536),
         transform (chunk: Buffer | string, encoding, callback) {
+            if (chunk === null) {
+                this.push(null)
+                callback()
+                return
+            }
             const timeZero = getTimeZero()
             const start = DateTime.now().diff(timeZero)
             let end = start
@@ -146,7 +340,8 @@ export function createTransformStreamForReadableSide (type: "text" | "audio", ge
                 const duration = audioBufferDuration(chunk as Buffer)
                 end = start.plus(duration * 1000)
             }
-            const obj = new SpeechFlowChunk(start, end, "final", type, chunk)
+            const payload = ensureStreamChunk(type, chunk) as Buffer | string
+            const obj = new SpeechFlowChunk(start, end, "final", type, payload)
             this.push(obj)
             callback()
         },

package/speechflow-cli/src/speechflow.ts

@@ -34,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  */
@@ -258,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
@@ -290,15 +282,17 @@ let debug = false
         "./speechflow-node-a2a-speex.js",
         "./speechflow-node-a2a-vad.js",
         "./speechflow-node-a2a-wav.js",
-        "./speechflow-node-a2t-awstranscribe.js",
+        "./speechflow-node-a2t-amazon.js",
         "./speechflow-node-a2t-deepgram.js",
-        "./speechflow-node-a2t-openaitranscribe.js",
-        "./speechflow-node-t2a-awspolly.js",
+        "./speechflow-node-a2t-openai.js",
+        "./speechflow-node-t2a-amazon.js",
         "./speechflow-node-t2a-elevenlabs.js",
         "./speechflow-node-t2a-kokoro.js",
-        "./speechflow-node-t2t-awstranslate.js",
+        "./speechflow-node-t2t-amazon.js",
         "./speechflow-node-t2t-deepl.js",
         "./speechflow-node-t2t-format.js",
+        "./speechflow-node-t2t-google.js",
+        "./speechflow-node-t2t-modify.js",
         "./speechflow-node-t2t-ollama.js",
         "./speechflow-node-t2t-openai.js",
         "./speechflow-node-t2t-sentence.js",
@@ -448,11 +442,15 @@ let debug = false
                         cli!.log("error", `creation of node <${id}> failed: ${err}`)
                     process.exit(1)
                 }
-                const params = Object.keys(node.params)
-                    .map((key) => `${key}: ${JSON.stringify(node.params[key])}`).join(", ")
-                cli!.log("info", `create node <${node.id}> (${params})`)
-                graphNodes.add(node)
-                return node
+                const params = Object.keys(node!.params).map((key) => {
+                    if (key.match(/key/))
+                        return `${key}: [...]`
+                    else
+                        return `${key}: ${JSON.stringify(node.params[key])}`
+                }).join(", ")
+                cli!.log("info", `create node <${node!.id}> (${params})`)
+                graphNodes.add(node!)
+                return node!
             },
             connectNodes (node1: SpeechFlowNode, node2: SpeechFlowNode) {
                 cli!.log("info", `connect node <${node1.id}> to node <${node2.id}>`)
@@ -681,7 +679,7 @@ let debug = false
             cli!.log("info", `HAPI: peer ${peer}: GET: ${JSON.stringify(req)}`)
             return consumeExternalRequest(req)
                 .then(()     => h.response({ response: "OK" }).code(200))
-                .catch((err) => h.response({ response: "ERROR", data: err.message }).code(417))
+                .catch((error: unknown) => h.response({ response: "ERROR", data: utils.ensureError(error).message }).code(417))
         }
     })
     hapi.route({
@@ -712,6 +710,8 @@ let debug = false
                         const peer = ctx.peer
                         wsPeers.delete(peer)
                         ws.removeAllListeners()
+                        if (ws.readyState === WebSocket.OPEN)
+                            ws.close()
                         cli!.log("info", `HAPI: WebSocket: disconnect: peer ${peer}`)
                     }
                 }
@@ -834,8 +834,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()
         }