speechflow 0.9.4 → 0.9.7

package/src/speechflow-node-t2a-elevenlabs.ts

@@ -0,0 +1,160 @@
+/*
+**  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 Stream                from "node:stream"
+
+/*  external dependencies  */
+import * as ElevenLabs       from "@elevenlabs/elevenlabs-js"
+import { getStreamAsBuffer } from "get-stream"
+import SpeexResampler        from "speex-resampler"
+
+/*  internal dependencies  */
+import SpeechFlowNode, { SpeechFlowChunk } from "./speechflow-node"
+
+/*  SpeechFlow node for Elevenlabs text-to-speech conversion  */
+export default class SpeechFlowNodeElevenlabs extends SpeechFlowNode {
+    /*  declare official node name  */
+    public static name = "elevenlabs"
+
+    /*  internal state  */
+    private elevenlabs: ElevenLabs.ElevenLabsClient | null = null
+    private static speexInitialized = false
+
+    /*  construct node  */
+    constructor (id: string, cfg: { [ id: string ]: any }, opts: { [ id: string ]: any }, args: any[]) {
+        super(id, cfg, opts, args)
+
+        /*  declare node configuration parameters  */
+        this.configure({
+            key:      { type: "string", val: process.env.SPEECHFLOW_KEY_ELEVENLABS },
+            voice:    { type: "string", val: "Brian",   pos: 0, match: /^(?:.+)$/ },
+            language: { type: "string", val: "en",      pos: 1, match: /^(?:de|en)$/ },
+            speed:    { type: "number", val: 1.05,      pos: 2, match: (n: number) => n >= 0.7 && n <= 1.2 },
+            optimize: { type: "string", val: "latency", pos: 3, match: /^(?:latency|quality)$/ }
+        })
+
+        /*  declare node input/output format  */
+        this.input  = "text"
+        this.output = "audio"
+    }
+
+    /*  open node  */
+    async open () {
+        /*  establish ElevenLabs API connection  */
+        this.elevenlabs = new ElevenLabs.ElevenLabsClient({
+            apiKey: this.params.key
+        })
+
+        /*  determine maximum sample rate of ElevenLabs tier  */
+        const maxSampleRates = {
+            "free":                  16000,
+            "starter":               22050,
+            "creator":               24000,
+            "independent_publisher": 44100,
+            "growing_business":      44100,
+            "enterprise":            44100
+        }
+        const sub = await this.elevenlabs.user.subscription.get()
+        const tier = (sub.tier ?? "free") as keyof typeof maxSampleRates
+        this.log("info", `determined ElevenLabs tier: "${tier}"`)
+        let maxSampleRate = 16000
+        if (maxSampleRates[tier] !== undefined)
+            maxSampleRate = maxSampleRates[tier]
+        this.log("info", `determined maximum audio sample rate: ${maxSampleRate}`)
+
+        /*  determine voice for text-to-speech operation
+            (for details see https://elevenlabs.io/text-to-speech)  */
+        const voices = await this.elevenlabs.voices.getAll()
+        let voice = voices.voices.find((voice) => voice.name === this.params.voice)
+        if (voice === undefined) {
+            voice = voices.voices.find((voice) => voice.name!.startsWith(this.params.voice))
+            if (voice === undefined)
+                throw new Error(`invalid ElevenLabs voice "${this.params.voice}"`)
+        }
+        const info = Object.keys(voice.labels ?? {}).length > 0 ?
+            (", " + Object.entries(voice.labels!)
+                .map(([ key, val ]) => `${key}: "${val}"`).join(", ")) : ""
+        this.log("info", `selected voice: name: "${voice.name}"${info}`)
+
+        /*  perform text-to-speech operation with Elevenlabs API  */
+        const model = this.params.optimize === "quality" ?
+            "eleven_multilingual_v2" :
+            "eleven_flash_v2_5"
+        const speechStream = (text: string) => {
+            this.log("info", `ElevenLabs: send text "${text}"`)
+            return this.elevenlabs!.textToSpeech.convert(voice.voiceId, {
+                text,
+                modelId:          model,
+                languageCode:     this.params.language,
+                outputFormat:     `pcm_${maxSampleRate}` as ElevenLabs.ElevenLabs.OutputFormat,
+                seed:             815, /* arbitrary, but fixated by us */
+                voiceSettings: {
+                    speed:        this.params.speed
+                }
+            }, {
+                timeoutInSeconds: 30,
+                maxRetries:       10
+            })
+        }
+
+        /*  establish resampler from ElevenLabs's maximum 24Khz
+            output to our standard audio sample rate (48KHz)  */
+        if (!SpeechFlowNodeElevenlabs.speexInitialized) {
+            /*  at least once initialize resampler  */
+            await SpeexResampler.initPromise
+            SpeechFlowNodeElevenlabs.speexInitialized = true
+        }
+        const resampler = new SpeexResampler(1, maxSampleRate, this.config.audioSampleRate, 7)
+
+        /*  create transform stream and connect it to the ElevenLabs API  */
+        const log = (level: string, msg: string) => { this.log(level, msg) }
+        this.stream = new Stream.Transform({
+            writableObjectMode: true,
+            readableObjectMode: true,
+            decodeStrings:      false,
+            transform (chunk: SpeechFlowChunk, encoding, callback) {
+                if (Buffer.isBuffer(chunk.payload))
+                    callback(new Error("invalid chunk payload type"))
+                else {
+                    speechStream(chunk.payload).then((stream) => {
+                        getStreamAsBuffer(stream).then((buffer) => {
+                            const bufferResampled = resampler.processChunk(buffer)
+                            log("info", `ElevenLabs: received audio (buffer length: ${buffer.byteLength})`)
+                            const chunkNew = chunk.clone()
+                            chunkNew.type = "audio"
+                            chunkNew.payload = bufferResampled
+                            this.push(chunkNew)
+                            callback()
+                        }).catch((error) => {
+                            callback(error)
+                        })
+                    }).catch((error) => {
+                        callback(error)
+                    })
+                }
+            },
+            final (callback) {
+                this.push(null)
+                callback()
+            }
+        })
+    }
+
+    /*  close node  */
+    async close () {
+        /*  destroy stream  */
+        if (this.stream !== null) {
+            this.stream.destroy()
+            this.stream = null
+        }
+
+        /*  destroy ElevenLabs API  */
+        if (this.elevenlabs !== null)
+            this.elevenlabs = null
+    }
+}
+

package/src/{speechflow-node-deepl.ts → speechflow-node-t2t-deepl.ts}

@@ -6,13 +6,12 @@
 
 /*  standard dependencies  */
 import Stream           from "node:stream"
-import { EventEmitter } from "node:events"
 
 /*  external dependencies  */
 import * as DeepL       from "deepl-node"
 
 /*  internal dependencies  */
-import SpeechFlowNode   from "./speechflow-node"
+import SpeechFlowNode, { SpeechFlowChunk } from "./speechflow-node"
 
 /*  SpeechFlow node for DeepL text-to-text translations  */
 export default class SpeechFlowNodeDeepL extends SpeechFlowNode {
@@ -23,17 +22,21 @@ export default class SpeechFlowNodeDeepL extends SpeechFlowNode {
     private deepl: DeepL.Translator | null = null
 
     /*  construct node  */
-    constructor (id: string, opts: { [ id: string ]: any }, args: any[]) {
-        super(id, opts, args)
+    constructor (id: string, cfg: { [ id: string ]: any }, opts: { [ id: string ]: any }, args: any[]) {
+        super(id, cfg, opts, args)
 
         /*  declare node configuration parameters  */
         this.configure({
             key:      { type: "string", val: process.env.SPEECHFLOW_KEY_DEEPL },
-            src:      { type: "string", pos: 0, val: "de",      match: /^(?:de|en-US)$/ },
-            dst:      { type: "string", pos: 1, val: "en-US",   match: /^(?:de|en-US)$/ },
+            src:      { type: "string", pos: 0, val: "de",      match: /^(?:de|en)$/ },
+            dst:      { type: "string", pos: 1, val: "en",      match: /^(?:de|en)$/ },
             optimize: { type: "string", pos: 2, val: "latency", match: /^(?:latency|quality)$/ }
         })
 
+        /*  sanity check situation  */
+        if (this.params.src === this.params.dst)
+            throw new Error("source and destination languages cannot be the same")
+
         /*  declare node input/output format  */
         this.input  = "text"
         this.output = "text"
@@ -46,7 +49,9 @@ export default class SpeechFlowNodeDeepL extends SpeechFlowNode {
 
         /*  provide text-to-text translation  */
         const translate = async (text: string) => {
-            const result = await this.deepl!.translateText(text, this.params.src, this.params.dst, {
+            const src = this.params.src === "en" ? "en-US" : this.params.src
+            const dst = this.params.dst === "en" ? "en-US" : this.params.dst
+            const result = await this.deepl!.translateText(text, src, dst, {
                 splitSentences: "off",
                 modelType: this.params.optimize === "latency" ?
                     "latency_optimized" : "prefer_quality_optimized",
@@ -57,32 +62,38 @@ export default class SpeechFlowNodeDeepL extends SpeechFlowNode {
         }
 
         /*  establish a duplex stream and connect it to DeepL translation  */
-        const queue = new EventEmitter()
-        this.stream = new Stream.Duplex({
-            write (chunk: Buffer, encoding, callback) {
-                const data = chunk.toString()
-                if (data === "") {
-                    queue.emit("result", "")
-                    callback()
-                }
+        this.stream = new Stream.Transform({
+            readableObjectMode: true,
+            writableObjectMode: true,
+            decodeStrings:      false,
+            transform (chunk: SpeechFlowChunk, encoding, callback) {
+                if (Buffer.isBuffer(chunk.payload))
+                    callback(new Error("invalid chunk payload type"))
                 else {
-                    translate(data).then((result) => {
-                        queue.emit("result", result)
+                    if (chunk.payload === "") {
+                        this.push(chunk)
                         callback()
-                    }).catch((err) => {
-                        callback(err)
-                    })
+                    }
+                    else {
+                        translate(chunk.payload).then((payload) => {
+                            const chunkNew = chunk.clone()
+                            chunkNew.payload = payload
+                            this.push(chunkNew)
+                            callback()
+                        }).catch((err) => {
+                            callback(err)
+                        })
+                    }
                 }
             },
-            read (size: number) {
-                queue.once("result", (result: string) => {
-                    this.push(result)
-                })
+            final (callback) {
+                this.push(null)
+                callback()
             }
         })
     }
 
-    /*  open node  */
+    /*  close node  */
     async close () {
         /*  close stream  */
         if (this.stream !== null) {

package/src/speechflow-node-t2t-format.ts

@@ -0,0 +1,85 @@
+/*
+**  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 Stream           from "node:stream"
+
+/*  external dependencies  */
+import wrapText         from "wrap-text"
+
+/*  internal dependencies  */
+import SpeechFlowNode, { SpeechFlowChunk } from "./speechflow-node"
+
+/*  SpeechFlow node for text-to-text formatting  */
+export default class SpeechFlowNodeFormat extends SpeechFlowNode {
+    /*  declare official node name  */
+    public static name = "format"
+
+    /*  construct node  */
+    constructor (id: string, cfg: { [ id: string ]: any }, opts: { [ id: string ]: any }, args: any[]) {
+        super(id, cfg, opts, args)
+
+        /*  declare node configuration parameters  */
+        this.configure({
+            width: { type: "number", val: 80 }
+        })
+
+        /*  declare node input/output format  */
+        this.input  = "text"
+        this.output = "text"
+    }
+
+    /*  open node  */
+    async open () {
+        /*  provide text-to-text formatter  */
+        const format = async (text: string) => {
+            text = wrapText(text, this.params.width)
+            text = text.replace(/([^\n])$/, "$1\n")
+            return text
+        }
+
+        /*  establish a duplex stream and connect it to DeepL translation  */
+        this.stream = new Stream.Transform({
+            readableObjectMode: true,
+            writableObjectMode: true,
+            decodeStrings:      false,
+            transform (chunk: SpeechFlowChunk, encoding, callback) {
+                if (Buffer.isBuffer(chunk.payload))
+                    callback(new Error("invalid chunk payload type"))
+                else {
+                    if (chunk.payload === "") {
+                        this.push(chunk)
+                        callback()
+                    }
+                    else {
+                        format(chunk.payload).then((payload) => {
+                            const chunkNew = chunk.clone()
+                            chunkNew.payload = payload
+                            this.push(chunkNew)
+                            callback()
+                        }).catch((err) => {
+                            callback(err)
+                        })
+                    }
+                }
+            },
+            final (callback) {
+                this.push(null)
+                callback()
+            }
+        })
+    }
+
+    /*  open node  */
+    async close () {
+        /*  close stream  */
+        if (this.stream !== null) {
+            this.stream.destroy()
+            this.stream = null
+        }
+    }
+}
+

package/src/{speechflow-node-gemma.ts → speechflow-node-t2t-gemma.ts}

@@ -6,13 +6,12 @@
 
 /*  standard dependencies  */
 import Stream           from "node:stream"
-import { EventEmitter } from "node:events"
 
 /*  external dependencies  */
 import { Ollama }       from "ollama"
 
 /*  internal dependencies  */
-import SpeechFlowNode   from "./speechflow-node"
+import SpeechFlowNode, { SpeechFlowChunk } from "./speechflow-node"
 
 /*  internal utility types  */
 type ConfigEntry = { systemPrompt: string, chat: Array<{ role: string, content: string }> }
@@ -28,6 +27,69 @@ export default class SpeechFlowNodeGemma extends SpeechFlowNode {
 
     /*  internal LLM setup  */
     private setup: Config = {
+        /*  English (EN) spellchecking only  */
+        "en-en": {
+            systemPrompt:
+                "You are a proofreader and spellchecker for English.\n" +
+                "Output only the corrected text.\n" +
+                "Do NOT use markdown.\n" +
+                "Do NOT give any explanations.\n" +
+                "Do NOT give any introduction.\n" +
+                "Do NOT give any comments.\n" +
+                "Do NOT give any preamble.\n" +
+                "Do NOT give any prolog.\n" +
+                "Do NOT give any epilog.\n" +
+                "Do NOT change the gammar.\n" +
+                "Do NOT use synonyms for words.\n" +
+                "Keep all words.\n" +
+                "Fill in missing commas.\n" +
+                "Fill in missing points.\n" +
+                "Fill in missing question marks.\n" +
+                "Fill in missing hyphens.\n" +
+                "Focus ONLY on the word spelling.\n" +
+                "The text you have to correct is:\n",
+            chat: [
+                { role: "user",   content: "I luve my wyfe" },
+                { role: "system", content: "I love my wife." },
+                { role: "user",   content: "The weether is wunderfull!" },
+                { role: "system", content: "The weather is wonderful!" },
+                { role: "user",   content: "The live awesome but I'm hungry." },
+                { role: "system", content: "The live is awesome, but I'm hungry." }
+            ]
+        },
+
+        /*  German (DE) spellchecking only  */
+        "de-de": {
+            systemPrompt:
+                "Du bist ein Korrekturleser und Rechtschreibprüfer für Deutsch.\n" +
+                "Gib nur den korrigierten Text aus.\n" +
+                "Benutze KEIN Markdown.\n" +
+                "Gib KEINE Erklärungen.\n" +
+                "Gib KEINE Einleitung.\n" +
+                "Gib KEINE Kommentare.\n" +
+                "Gib KEINE Preamble.\n" +
+                "Gib KEINEN Prolog.\n" +
+                "Gib KEINEN Epilog.\n" +
+                "Ändere NICHT die Grammatik.\n" +
+                "Verwende KEINE Synonyme für Wörter.\n" +
+                "Behalte alle Wörter bei.\n" +
+                "Füge fehlende Kommas ein.\n" +
+                "Füge fehlende Punkte ein.\n" +
+                "Füge fehlende Fragezeichen ein.\n" +
+                "Füge fehlende Bindestriche ein.\n" +
+                "Füge fehlende Gedankenstriche ein.\n" +
+                "Fokussiere dich NUR auf die Rechtschreibung der Wörter.\n" +
+                "Der von dir zu korrigierende Text ist:\n",
+            chat: [
+                { role: "user",   content: "Ich ljebe meine Frao" },
+                { role: "system", content: "Ich liebe meine Frau." },
+                { role: "user",   content: "Die Wedter ist wunderschoen." },
+                { role: "system", content: "Das Wetter ist wunderschön." },
+                { role: "user",   content: "Das Leben einfach großartig aber ich bin hungrig." },
+                { role: "system", content: "Das Leben ist einfach großartig, aber ich bin hungrig." }
+            ]
+        },
+
         /*  English (EN) to German (DE) translation  */
         "en-de": {
             systemPrompt:
@@ -78,8 +140,8 @@ export default class SpeechFlowNodeGemma extends SpeechFlowNode {
     }
 
     /*  construct node  */
-    constructor (id: string, opts: { [ id: string ]: any }, args: any[]) {
-        super(id, opts, args)
+    constructor (id: string, cfg: { [ id: string ]: any }, opts: { [ id: string ]: any }, args: any[]) {
+        super(id, cfg, opts, args)
 
         /*  declare node configuration parameters  */
         this.configure({
@@ -88,10 +150,6 @@ export default class SpeechFlowNodeGemma extends SpeechFlowNode {
             dst: { type: "string", pos: 1, val: "en", match: /^(?:de|en)$/ }
         })
 
-        /*  sanity check situation  */
-        if (this.params.src === this.params.dst)
-            throw new Error("source and destination languages cannot be the same")
-
         /*  declare node input/output format  */
         this.input  = "text"
         this.output = "text"
@@ -126,27 +184,33 @@ export default class SpeechFlowNodeGemma extends SpeechFlowNode {
         }
 
         /*  establish a duplex stream and connect it to Ollama  */
-        const queue = new EventEmitter()
-        this.stream = new Stream.Duplex({
-            write (chunk: Buffer, encoding, callback) {
-                const data = chunk.toString()
-                if (data === "") {
-                    queue.emit("result", "")
-                    callback()
-                }
+        this.stream = new Stream.Transform({
+            readableObjectMode: true,
+            writableObjectMode: true,
+            decodeStrings:      false,
+            transform (chunk: SpeechFlowChunk, encoding, callback) {
+                if (Buffer.isBuffer(chunk.payload))
+                    callback(new Error("invalid chunk payload type"))
                 else {
-                    translate(data).then((result) => {
-                        queue.emit("result", result)
+                    if (chunk.payload === "") {
+                        this.push(chunk)
                         callback()
-                    }).catch((err) => {
-                        callback(err)
-                    })
+                    }
+                    else {
+                        translate(chunk.payload).then((payload) => {
+                            const chunkNew = chunk.clone()
+                            chunkNew.payload = payload
+                            this.push(chunkNew)
+                            callback()
+                        }).catch((err) => {
+                            callback(err)
+                        })
+                    }
                 }
             },
-            read (size) {
-                queue.once("result", (result: string) => {
-                    this.push(result)
-                })
+            final (callback) {
+                this.push(null)
+                callback()
             }
         })
     }

package/src/speechflow-node-t2t-opus.ts

@@ -0,0 +1,111 @@
+/*
+**  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"
+import Stream           from "node:stream"
+
+/*  external dependencies  */
+import * as Transformers from "@huggingface/transformers"
+
+/*  internal dependencies  */
+import SpeechFlowNode, { SpeechFlowChunk } from "./speechflow-node"
+
+/*  SpeechFlow node for OPUS text-to-text translation  */
+export default class SpeechFlowNodeOPUS extends SpeechFlowNode {
+    /*  declare official node name  */
+    public static name = "opus"
+
+    /*  internal state  */
+    private translator: Transformers.TranslationPipeline | null = null
+
+    /*  construct node  */
+    constructor (id: string, cfg: { [ id: string ]: any }, opts: { [ id: string ]: any }, args: any[]) {
+        super(id, cfg, opts, args)
+
+        /*  declare node configuration parameters  */
+        this.configure({
+            src: { type: "string", pos: 0, val: "de", match: /^(?:de|en)$/ },
+            dst: { type: "string", pos: 1, val: "en", match: /^(?:de|en)$/ }
+        })
+
+        /*  sanity check situation  */
+        if (this.params.src === this.params.dst)
+            throw new Error("source and destination languages cannot be the same")
+
+        /*  declare node input/output format  */
+        this.input  = "text"
+        this.output = "text"
+    }
+
+    /*  open node  */
+    async open () {
+        /*  instantiate OPUS  */
+        const model = `onnx-community/opus-mt-${this.params.src}-${this.params.dst}`
+        this.translator = await Transformers.pipeline("translation", model, {
+            cache_dir: path.join(this.config.cacheDir, "opus"),
+            dtype:     "q4",
+            device:    "gpu"
+        })
+        if (this.translator === null)
+            throw new Error("failed to instantiate translator pipeline")
+
+        /*  provide text-to-text translation  */
+        const translate = async (text: string) => {
+            const result = await this.translator!(text)
+            return Array.isArray(result) ?
+                (result[0] as Transformers.TranslationSingle).translation_text :
+                (result as Transformers.TranslationSingle).translation_text
+        }
+
+        /*  establish a duplex stream and connect it to Ollama  */
+        this.stream = new Stream.Transform({
+            readableObjectMode: true,
+            writableObjectMode: true,
+            decodeStrings:      false,
+            transform (chunk: SpeechFlowChunk, encoding, callback) {
+                if (Buffer.isBuffer(chunk.payload))
+                    callback(new Error("invalid chunk payload type"))
+                else {
+                    if (chunk.payload === "") {
+                        this.push(chunk)
+                        callback()
+                    }
+                    else {
+                        translate(chunk.payload).then((payload) => {
+                            const chunkNew = chunk.clone()
+                            chunkNew.payload = payload
+                            this.push(chunkNew)
+                            callback()
+                        }).catch((err) => {
+                            callback(err)
+                        })
+                    }
+                }
+            },
+            final (callback) {
+                this.push(null)
+                callback()
+            }
+        })
+    }
+
+    /*  close node  */
+    async close () {
+        /*  close stream  */
+        if (this.stream !== null) {
+            this.stream.destroy()
+            this.stream = null
+        }
+
+        /*  shutdown OPUS  */
+        if (this.translator !== null) {
+            this.translator.dispose()
+            this.translator = null
+        }
+    }
+}
+