speechflow 1.7.1 → 2.0.0

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

@@ -32,7 +32,7 @@ type TextChunk = {
     text:  string
 }
 
-/*  SpeechFlow node for subtitle (text-to-text) "translations"  */
+/*  SpeechFlow node for subtitle (text-to-text) conversions  */
 export default class SpeechFlowNodeT2TSubtitle extends SpeechFlowNode {
     /*  declare official node name  */
     public static name = "t2t-subtitle"
@@ -311,7 +311,7 @@ export default class SpeechFlowNodeT2TSubtitle extends SpeechFlowNode {
                 final (callback) {
                     /*  process any remaining buffer content  */
                     if (buffer.trim() !== "") {
-                        try {
+                        util.shield(() => {
                             /*  parse entries  */
                             const entries = self.params.format === "srt" ? parseSRT(buffer) : parseVTT(buffer)
 
@@ -320,10 +320,7 @@ export default class SpeechFlowNodeT2TSubtitle extends SpeechFlowNode {
                                 const chunkNew = new SpeechFlowChunk(entry.start, entry.end, "final", "text", entry.text)
                                 this.push(chunkNew)
                             }
-                        }
-                        catch (_error: unknown) {
-                            /*  ignore parse errors on final flush  */
-                        }
+                        })
                     }
                     callback()
                 }

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

@@ -0,0 +1,229 @@
+/*
+**  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"
+
+/*  internal dependencies  */
+import SpeechFlowNode, { SpeechFlowChunk } from "./speechflow-node"
+import * as util                           from "./speechflow-util"
+import { LLM, type LLMCompleteMessage }    from "./speechflow-util-llm"
+
+/*  internal utility types  */
+type ConfigEntry = { systemPrompt: string, chat: LLMCompleteMessage[] }
+type Config      = { [ key: string ]: ConfigEntry }
+
+/*  SpeechFlow node for text-to-text summarization  */
+export default class SpeechFlowNodeT2TSummary extends SpeechFlowNode {
+    /*  declare official node name  */
+    public static name = "t2t-summary"
+
+    /*  internal state  */
+    private llm: LLM | null = null
+    private accumulatedText = ""
+    private sentencesSinceLastSummary = 0
+
+    /*  internal LLM setup  */
+    private setup: Config = {
+        /*  English (EN) summarization  */
+        "en": {
+            systemPrompt:
+                "You are a text summarizer.\n" +
+                "Output only the summary.\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" +
+                "Get to the point.\n" +
+                "Summarize the following text into %N% sentences.\n" +
+                "The text is:\n",
+            chat: [
+                { role: "user",      content: "The weather today is sunny and warm. Birds are singing in the trees. People are enjoying the outdoors." },
+                { role: "assistant", content: "The weather is pleasant with sunshine, birdsong, and people outdoors." },
+                { role: "user",      content: "John went to the store to buy groceries. He needed milk, bread, and eggs. The store was crowded but he found everything he needed." },
+                { role: "assistant", content: "John successfully bought milk, bread, and eggs from a crowded store." }
+            ]
+        },
+
+        /*  German (DE) summarization  */
+        "de": {
+            systemPrompt:
+                "Du bist ein Textzusammenfasser.\n" +
+                "Gib nur die Zusammenfassung aus.\n" +
+                "Benutze KEIN Markdown.\n" +
+                "Gib KEINE Erklärungen.\n" +
+                "Gib KEINE Einleitung.\n" +
+                "Gib KEINE Kommentare.\n" +
+                "Gib KEINE Prämbel.\n" +
+                "Gib KEINEN Prolog.\n" +
+                "Gib KEINEN Epilog.\n" +
+                "Komme auf den Punkt.\n" +
+                "Fasse den folgenden Text in %N% Sätzen zusammen.\n" +
+                "Der Text ist:\n",
+            chat: [
+                { role: "user",      content: "Das Wetter heute ist sonnig und warm. Vögel singen in den Bäumen. Die Menschen genießen die Zeit im Freien." },
+                { role: "assistant", content: "Das Wetter ist angenehm mit Sonnenschein, Vogelgesang und Menschen im Freien." },
+                { role: "user",      content: "Hans ging in den Laden, um Lebensmittel zu kaufen. Er brauchte Milch, Brot und Eier. Der Laden war voll, aber er fand alles, was er brauchte." },
+                { role: "assistant", content: "Hans kaufte erfolgreich Milch, Brot und Eier in einem vollen Laden." }
+            ]
+        }
+    }
+
+    /*  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({
+            provider: { type: "string",         val: "ollama",                 match: /^(?:openai|anthropic|google|ollama|transformers)$/ },
+            api:      { type: "string",         val: "http://127.0.0.1:11434", match: /^https?:\/\/.+?(:\d+)?$/ },
+            model:    { type: "string",         val: "gemma3:4b-it-q4_K_M",    match: /^.+$/ },
+            key:      { type: "string",         val: "",                       match: /^.*$/ },
+            lang:     { type: "string", pos: 0, val: "en",                     match: /^(?:en|de)$/ },
+            size:     { type: "number", pos: 1, val: 4,                        match: (n: number) => n >= 1 && n <= 20 },
+            trigger:  { type: "number", pos: 2, val: 8,                        match: (n: number) => n >= 1 && n <= 100 }
+        })
+
+        /*  tell effective mode  */
+        this.log("info", `summarizing language "${this.params.lang}" ` +
+            `via ${this.params.provider} LLM (model: ${this.params.model}), ` +
+            `triggering every new ${this.params.trigger} sentences, ` +
+            `summarizing into ${this.params.size} sentences`)
+
+        /*  declare node input/output format  */
+        this.input  = "text"
+        this.output = "text"
+    }
+
+    /*  count sentences in text  */
+    private countSentences (text: string): number {
+        const matches = text.match(/[.;?!]/g)
+        return matches ? matches.length : 0
+    }
+
+    /*  open node  */
+    async open () {
+        /*  reset internal state  */
+        this.accumulatedText = ""
+        this.sentencesSinceLastSummary = 0
+
+        /*  instantiate LLM  */
+        this.llm = new LLM({
+            provider:    this.params.provider,
+            api:         this.params.api,
+            model:       this.params.model,
+            key:         this.params.key,
+            temperature: 0.7,
+            topP:        0.5
+        })
+        this.llm.on("log", (level: string, message: string) => {
+            this.log(level as "info" | "warning" | "error", message)
+        })
+        await this.llm.open()
+
+        /*  provide text summarization  */
+        const llm = this.llm!
+        const summarize = async (text: string) => {
+            const cfg = this.setup[this.params.lang]
+            if (!cfg)
+                throw new Error(`unsupported language: ${this.params.lang}`)
+            return llm.complete({
+                system:   cfg.systemPrompt.replace(/%N%/, this.params.size),
+                messages: cfg.chat,
+                prompt:   text
+            })
+        }
+
+        /*  establish a transform stream for summarization  */
+        const self = this
+        this.stream = new Stream.Transform({
+            readableObjectMode: true,
+            writableObjectMode: true,
+            decodeStrings:      false,
+            highWaterMark:      1,
+            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 {
+                    /*  accumulate text  */
+                    if (self.accumulatedText.length > 0)
+                        self.accumulatedText += " "
+                    self.accumulatedText += chunk.payload
+
+                    /*  count new sentences  */
+                    const newSentences = self.countSentences(chunk.payload)
+                    self.sentencesSinceLastSummary += newSentences
+                    self.log("info", `accumulated ${self.sentencesSinceLastSummary} sentences ` +
+                        `(trigger: ${self.params.trigger})`)
+
+                    /*  check if we should generate a summary  */
+                    if (self.sentencesSinceLastSummary >= self.params.trigger) {
+                        self.sentencesSinceLastSummary = 0
+                        self.log("info", `generating summary of accumulated text`)
+                        const textToSummarize = self.accumulatedText
+                        self.accumulatedText = ""
+                        summarize(textToSummarize).then((summary) => {
+                            const chunkNew = chunk.clone()
+                            chunkNew.payload = summary
+                            this.push(chunkNew)
+                            callback()
+                        }).catch((error: unknown) => {
+                            callback(util.ensureError(error))
+                        })
+                    }
+                    else
+                        callback()
+                }
+            },
+            final (callback) {
+                /*  generate final summary if there is accumulated text  */
+                if (self.accumulatedText.length > 0 && self.sentencesSinceLastSummary > 0) {
+                    self.sentencesSinceLastSummary = 0
+                    self.log("info", `generating final summary of accumulated text`)
+                    const textToSummarize = self.accumulatedText
+                    self.accumulatedText = ""
+                    summarize(textToSummarize).then((summary) => {
+                        const chunkNew = new SpeechFlowChunk(
+                            self.timeZeroOffset, self.timeZeroOffset,
+                            "final", "text", summary)
+                        this.push(chunkNew)
+                        callback()
+                    }).catch((error: unknown) => {
+                        callback(util.ensureError(error))
+                    })
+                }
+                else
+                    callback()
+            }
+        })
+    }
+
+    /*  close node  */
+    async close () {
+        /*  reset internal state  */
+        this.accumulatedText = ""
+        this.sentencesSinceLastSummary = 0
+
+        /*  shutdown stream  */
+        if (this.stream !== null) {
+            await util.destroyStream(this.stream)
+            this.stream = null
+        }
+
+        /*  shutdown LLM  */
+        if (this.llm !== null) {
+            await this.llm.close()
+            this.llm = null
+        }
+    }
+}

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

@@ -0,0 +1,181 @@
+/*
+**  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"
+
+/*  internal dependencies  */
+import SpeechFlowNode, { SpeechFlowChunk } from "./speechflow-node"
+import * as util                           from "./speechflow-util"
+import { LLM, type LLMCompleteMessage }    from "./speechflow-util-llm"
+
+/*  internal utility types  */
+type ConfigEntry = { systemPrompt: string, chat: LLMCompleteMessage[] }
+type Config      = { [ key: string ]: ConfigEntry }
+
+/*  SpeechFlow node for LLM-based text-to-text translation  */
+export default class SpeechFlowNodeT2TTranslate extends SpeechFlowNode {
+    /*  declare official node name  */
+    public static name = "t2t-translate"
+
+    /*  internal state  */
+    private llm: LLM | null = null
+
+    /*  internal LLM setup  */
+    private setup: Config = {
+        /*  English (EN) to German (DE) translation  */
+        "en-de": {
+            systemPrompt:
+                "You are a translator.\n" +
+                "Output only the requested text.\n" +
+                "Do not use markdown.\n" +
+                "Do not chat.\n" +
+                "Do not show any explanations.\n" +
+                "Do not show any introduction.\n" +
+                "Do not show any preamble.\n" +
+                "Do not show any prolog.\n" +
+                "Do not show any epilog.\n" +
+                "Get to the point.\n" +
+                "Preserve the original meaning, tone, and nuance.\n" +
+                "Directly translate text from English (EN) to fluent and natural German (DE) language.\n",
+            chat: [
+                { role: "user",      content: "I love my wife." },
+                { role: "assistant", content: "Ich liebe meine Frau." },
+                { role: "user",      content: "The weather is wonderful." },
+                { role: "assistant", content: "Das Wetter ist wunderschön." },
+                { role: "user",      content: "The life is awesome." },
+                { role: "assistant", content: "Das Leben ist einfach großartig." }
+            ]
+        },
+
+        /*  German (DE) to English (EN) translation  */
+        "de-en": {
+            systemPrompt:
+                "You are a translator.\n" +
+                "Output only the requested text.\n" +
+                "Do not use markdown.\n" +
+                "Do not chat.\n" +
+                "Do not show any explanations.\n" +
+                "Do not show any introduction.\n" +
+                "Do not show any preamble.\n" +
+                "Do not show any prolog.\n" +
+                "Do not show any epilog.\n" +
+                "Get to the point.\n" +
+                "Preserve the original meaning, tone, and nuance.\n" +
+                "Directly translate text from German (DE) to fluent and natural English (EN) language.\n",
+            chat: [
+                { role: "user",      content: "Ich liebe meine Frau." },
+                { role: "assistant", content: "I love my wife." },
+                { role: "user",      content: "Das Wetter ist wunderschön." },
+                { role: "assistant", content: "The weather is wonderful." },
+                { role: "user",      content: "Das Leben ist einfach großartig." },
+                { role: "assistant", content: "The life is awesome." }
+            ]
+        }
+    }
+
+    /*  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)$/ },
+            provider: { type: "string",         val: "ollama",                 match: /^(?:openai|anthropic|google|ollama|transformers)$/ },
+            api:      { type: "string",         val: "http://127.0.0.1:11434", match: /^https?:\/\/.+?(:\d+)?$/ },
+            model:    { type: "string",         val: "gemma3:4b-it-q4_K_M",    match: /^.+$/ },
+            key:      { type: "string",         val: "",                       match: /^.*$/ }
+        })
+
+        /*  validate translation direction  */
+        if (this.params.src === this.params.dst)
+            throw new Error("source and destination language must be different for translation")
+
+        /*  tell effective mode  */
+        this.log("info", `translating from language "${this.params.src}" to language "${this.params.dst}" ` +
+            `via ${this.params.provider} LLM (model: ${this.params.model})`)
+
+        /*  declare node input/output format  */
+        this.input  = "text"
+        this.output = "text"
+    }
+
+    /*  open node  */
+    async open () {
+        /*  instantiate LLM  */
+        this.llm = new LLM({
+            provider:    this.params.provider,
+            api:         this.params.api,
+            model:       this.params.model,
+            key:         this.params.key,
+            temperature: 0.7,
+            topP:        0.5
+        })
+        this.llm.on("log", (level: string, message: string) => {
+            this.log(level as "info" | "warning" | "error", message)
+        })
+        await this.llm.open()
+
+        /*  provide text-to-text translation  */
+        const llm = this.llm!
+        const translate = async (text: string) => {
+            const key = `${this.params.src}-${this.params.dst}`
+            const cfg = this.setup[key]
+            if (!cfg)
+                throw new Error(`unsupported language pair: ${key}`)
+            return llm.complete({
+                system:   cfg.systemPrompt,
+                messages: cfg.chat,
+                prompt:   text
+            })
+        }
+
+        /*  establish a transform stream and connect it to LLM  */
+        this.stream = new Stream.Transform({
+            readableObjectMode: true,
+            writableObjectMode: true,
+            decodeStrings:      false,
+            highWaterMark:      1,
+            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((error: unknown) => {
+                        callback(util.ensureError(error))
+                    })
+                }
+            },
+            final (callback) {
+                callback()
+            }
+        })
+    }
+
+    /*  close node  */
+    async close () {
+        /*  shutdown stream  */
+        if (this.stream !== null) {
+            await util.destroyStream(this.stream)
+            this.stream = null
+        }
+
+        /*  shutdown LLM  */
+        if (this.llm !== null) {
+            await this.llm.close()
+            this.llm = null
+        }
+    }
+}

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

@@ -0,0 +1,210 @@
+/*
+**  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 { execa, type Subprocess, type Options } from "execa"
+import shellParser                from "shell-parser"
+
+/*  internal dependencies  */
+import SpeechFlowNode             from "./speechflow-node"
+import * as util                  from "./speechflow-util"
+
+/*  SpeechFlow node for external command execution  */
+export default class SpeechFlowNodeXIOExec extends SpeechFlowNode {
+    /*  declare official node name  */
+    public static name = "xio-exec"
+
+    /*  internal state  */
+    private subprocess: Subprocess | 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({
+            command:    { type: "string", pos: 0, val: "" },
+            mode:       { type: "string", pos: 1, val: "r",     match: /^(?:r|w|rw)$/ },
+            type:       { type: "string", pos: 2, val: "audio", match: /^(?:audio|text)$/ },
+            chunkAudio: { type: "number",         val: 200,     match: (n: number) => n >= 10 && n <= 1000 },
+            chunkText:  { type: "number",         val: 65536,   match: (n: number) => n >= 1024 && n <= 131072 }
+        })
+
+        /*  sanity check parameters  */
+        if (this.params.command === "")
+            throw new Error("required parameter \"command\" has to be given")
+
+        /*  declare node input/output format  */
+        if (this.params.mode === "rw") {
+            this.input  = this.params.type
+            this.output = this.params.type
+        }
+        else if (this.params.mode === "r") {
+            this.input  = "none"
+            this.output = this.params.type
+        }
+        else if (this.params.mode === "w") {
+            this.input  = this.params.type
+            this.output = "none"
+        }
+    }
+
+    /*  open node  */
+    async open () {
+        /*  determine how many bytes we need per chunk when
+            the chunk should be of the required duration/size  */
+        const highWaterMarkAudio = (
+            this.config.audioSampleRate *
+            (this.config.audioBitDepth / 8)
+        ) / (1000 / this.params.chunkAudio)
+        const highWaterMarkText = this.params.chunkText
+
+        /*  parse command into executable and arguments
+            (SECURITY: caller must ensure command parameter is properly validated
+            and does not contain untrusted user input to prevent command injection)  */
+        const cmdParts = shellParser(this.params.command)
+        if (cmdParts.length === 0)
+            throw new Error("failed to parse command: no executable found")
+
+        /*  warn about potentially dangerous shell metacharacters  */
+        if (/[;&|`$()<>]/.test(this.params.command))
+            this.log("warning", "command contains shell metacharacters -- ensure input is trusted")
+        const executable = cmdParts[0]
+        const args = cmdParts.slice(1)
+
+        /*  determine subprocess options  */
+        const encoding = (this.params.type === "text" ?
+            this.config.textEncoding : "buffer") as Options["encoding"]
+
+        /*  spawn subprocess  */
+        this.log("info", `executing command: ${this.params.command}`)
+        this.subprocess = execa(executable, args, {
+            buffer: false,
+            encoding,
+            ...(this.params.mode === "rw" ? { stdin: "pipe",   stdout: "pipe"   } : {}),
+            ...(this.params.mode === "r"  ? { stdin: "ignore", stdout: "pipe"   } : {}),
+            ...(this.params.mode === "w"  ? { stdin: "pipe",   stdout: "ignore" } : {})
+        })
+
+        /*  handle subprocess errors  */
+        this.subprocess.on("error", (err) => {
+            this.log("error", `subprocess error: ${err.message}`)
+            this.emit("error", err)
+            if (this.stream !== null)
+                this.stream.emit("error", err)
+        })
+
+        /*  handle subprocess exit  */
+        this.subprocess.on("exit", (code, signal) => {
+            if (code !== 0 && code !== null)
+                this.log("warning", `subprocess exited with code ${code}`)
+            else if (signal)
+                this.log("warning", `subprocess terminated by signal ${signal}`)
+            else
+                this.log("info", "subprocess terminated gracefully")
+        })
+
+        /*  determine high water mark based on type  */
+        const highWaterMark = this.params.type === "audio" ? highWaterMarkAudio : highWaterMarkText
+
+        /*  configure stream encoding  */
+        if (this.subprocess.stdout && this.params.type === "text")
+            this.subprocess.stdout.setEncoding(this.config.textEncoding)
+        if (this.subprocess.stdin)
+            this.subprocess.stdin.setDefaultEncoding(this.params.type === "text" ?
+                this.config.textEncoding : "binary")
+
+        /*  dispatch according to mode  */
+        if (this.params.mode === "rw") {
+            /*  bidirectional mode: both stdin and stdout  */
+            this.stream = Stream.Duplex.from({
+                readable: this.subprocess.stdout,
+                writable: this.subprocess.stdin
+            })
+            const wrapper1 = util.createTransformStreamForWritableSide(this.params.type, highWaterMark)
+            const wrapper2 = util.createTransformStreamForReadableSide(
+                this.params.type, () => this.timeZero, highWaterMark)
+            this.stream = Stream.compose(wrapper1, this.stream, wrapper2)
+        }
+        else if (this.params.mode === "r") {
+            /*  read-only mode: stdout only  */
+            const wrapper = util.createTransformStreamForReadableSide(
+                this.params.type, () => this.timeZero, highWaterMark)
+            this.stream = Stream.compose(this.subprocess.stdout!, wrapper)
+        }
+        else if (this.params.mode === "w") {
+            /*  write-only mode: stdin only  */
+            const wrapper = util.createTransformStreamForWritableSide(
+                this.params.type, highWaterMark)
+            this.stream = Stream.compose(wrapper, this.subprocess.stdin!)
+        }
+    }
+
+    /*  close node  */
+    async close () {
+        /*  terminate subprocess  */
+        if (this.subprocess !== null) {
+            /*  gracefully end stdin if in write or read/write mode  */
+            if ((this.params.mode === "w" || this.params.mode === "rw") && this.subprocess.stdin &&
+                !this.subprocess.stdin.destroyed && !this.subprocess.stdin.writableEnded) {
+                await Promise.race([
+                    new Promise<void>((resolve, reject) => {
+                        this.subprocess!.stdin!.end((err?: Error) => {
+                            if (err) reject(err)
+                            else     resolve()
+                        })
+                    }),
+                    util.timeout(2000)
+                ]).catch((err: unknown) => {
+                    const error = util.ensureError(err)
+                    this.log("warning", `failed to gracefully close stdin: ${error.message}`)
+                })
+            }
+
+            /*  wait for subprocess to exit gracefully  */
+            await Promise.race([
+                this.subprocess,
+                util.timeout(5000, "subprocess exit timeout")
+            ]).catch(async (err: unknown) => {
+                /*  force kill with SIGTERM  */
+                const error = util.ensureError(err)
+                if (error.message.includes("timeout")) {
+                    this.log("warning", "subprocess did not exit gracefully, forcing termination")
+                    this.subprocess!.kill("SIGTERM")
+                    return Promise.race([
+                        this.subprocess,
+                        util.timeout(2000)
+                    ])
+                }
+            }).catch(async () => {
+                /*  force kill with SIGKILL  */
+                this.log("warning", "subprocess did not respond to SIGTERM, forcing SIGKILL")
+                this.subprocess!.kill("SIGKILL")
+                return Promise.race([
+                    this.subprocess,
+                    util.timeout(1000)
+                ])
+            }).catch(() => {
+                this.log("error", "subprocess did not terminate even after SIGKILL")
+            })
+
+            /*  remove event listeners to prevent memory leaks  */
+            this.subprocess.removeAllListeners("error")
+            this.subprocess.removeAllListeners("exit")
+
+            this.subprocess = null
+        }
+
+        /*  shutdown stream  */
+        if (this.stream !== null) {
+            await util.destroyStream(this.stream)
+            this.stream = null
+        }
+    }
+}