speechflow 2.2.1 → 2.3.1

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

@@ -1,6 +1,6 @@
 /*
 **  SpeechFlow - Speech Processing Flow Graph
-**  Copyright (c) 2024-2025 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Copyright (c) 2024-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
 **  Licensed under GPL 3.0 <https://spdx.org/licenses/GPL-3.0-only>
 */
 
@@ -39,13 +39,14 @@ export default class SpeechFlowNodeXIOWebRTC extends SpeechFlowNode {
     /*  internal state  */
     private peerConnections                                       = new Map<string, WebRTCConnection>()
     private httpServer:  http.Server                       | null = null
-    private chunkQueue:  util.SingleQueue<SpeechFlowChunk> | null = null
+    private chunkQueue:  util.AsyncQueue<SpeechFlowChunk> | null = null
     private opusEncoder: OpusEncoder                       | null = null
     private opusDecoder: OpusEncoder                       | null = null
     private pcmBuffer                                             = Buffer.alloc(0)
     private rtpSequence                                           = 0
     private rtpTimestamp                                          = 0
     private rtpSSRC                                               = 0
+    private rtpMarkerNext                                         = true
     private maxConnections                                        = 10
 
     /*  Opus codec configuration: 48kHz, mono, 16-bit  */
@@ -177,7 +178,7 @@ export default class SpeechFlowNodeXIOWebRTC extends SpeechFlowNode {
             padding:        false,
             paddingSize:    0,
             extension:      false,
-            marker:         true,
+            marker:         this.rtpMarkerNext,
             payloadType:    111, /*  Opus payload type  */
             sequenceNumber: this.rtpSequence++ & 0xFFFF,
             timestamp:      this.rtpTimestamp,
@@ -186,6 +187,9 @@ export default class SpeechFlowNodeXIOWebRTC extends SpeechFlowNode {
             extensions:     []
         })
 
+        /*  clear marker (set only on first packet of a talkspurt per RFC 3551)  */
+        this.rtpMarkerNext = false
+
         /*  build RTP packet  */
         const rtpPacket = new RtpPacket(rtpHeader, opusPacket)
 
@@ -265,11 +269,11 @@ export default class SpeechFlowNodeXIOWebRTC extends SpeechFlowNode {
         const resourceId = crypto.randomUUID()
         const { pc, subscription } = this.createPeerConnection(resourceId)
 
-        /*  protocol-specific setup  */
-        const track = setupFn(pc, resourceId)
-
         /*  complete SDP offer/answer exchange and establish connection  */
         try {
+            /*  protocol-specific setup  */
+            const track = setupFn(pc, resourceId)
+
             /*  set remote description (offer from client)  */
             await pc.setRemoteDescription({ type: "offer", sdp: offer })
 
@@ -365,9 +369,10 @@ export default class SpeechFlowNodeXIOWebRTC extends SpeechFlowNode {
         this.rtpSequence  = Math.floor(Math.random() * 0x10000)
         this.rtpTimestamp = Math.floor(Math.random() * 0x100000000) >>> 0
         this.rtpSSRC      = Math.floor(Math.random() * 0x100000000) >>> 0
+        this.rtpMarkerNext = true
 
         /*  setup chunk queue for incoming audio  */
-        this.chunkQueue = new util.SingleQueue<SpeechFlowChunk>()
+        this.chunkQueue = new util.AsyncQueue<SpeechFlowChunk>()
 
         /*  parse listen address  */
         const listen = this.parseAddress(this.params.listen, 8085)
@@ -375,77 +380,89 @@ export default class SpeechFlowNodeXIOWebRTC extends SpeechFlowNode {
         /*  setup HTTP server for WHIP/WHEP signaling  */
         const self = this
         this.httpServer = http.createServer(async (req, res) => {
-            /*  determine URL  */
-            if (req.url === undefined) {
-                res.writeHead(400, { "Content-Type": "text/plain" })
-                res.end("Bad Request")
-                return
-            }
-            const host = req.headers.host?.replace(/[^a-zA-Z0-9:.\-_]/g, "") ?? "localhost"
-            const url = new URL(req.url, `http://${host}`)
-            const pathMatch = url.pathname === self.params.path
-            const resourceMatch = url.pathname.startsWith(self.params.path + "/")
-
-            /*  CORS headers for browser clients  */
-            res.setHeader("Access-Control-Allow-Origin",   "*")
-            res.setHeader("Access-Control-Allow-Methods",  "POST, DELETE, OPTIONS")
-            res.setHeader("Access-Control-Allow-Headers",  "Content-Type")
-            res.setHeader("Access-Control-Expose-Headers", "Location")
-
-            /*  handle CORS preflight  */
-            if (req.method === "OPTIONS") {
-                res.writeHead(204)
-                res.end()
-                return
-            }
-
-            /*  handle requests...  */
-            if (req.method === "POST" && pathMatch) {
-                /*  handle WHIP/WHEP POST  */
-                const body = await self.readRequestBody(req)
-
-                /*  sanity check content type  */
-                const contentType = req.headers["content-type"]
-                if (contentType !== "application/sdp") {
-                    res.writeHead(415, { "Content-Type": "text/plain" })
-                    res.end("Unsupported Media Type")
+            try {
+                /*  determine URL  */
+                if (req.url === undefined) {
+                    res.writeHead(400, { "Content-Type": "text/plain" })
+                    res.end("Bad Request")
+                    return
+                }
+                const host = req.headers.host?.replace(/[^a-zA-Z0-9:.\-_]/g, "") ?? "localhost"
+                const url = new URL(req.url, `http://${host}`)
+                const pathMatch = url.pathname === self.params.path
+                const resourceMatch = url.pathname.startsWith(self.params.path + "/")
+
+                /*  CORS headers for browser clients  */
+                res.setHeader("Access-Control-Allow-Origin",   "*")
+                res.setHeader("Access-Control-Allow-Methods",  "POST, DELETE, OPTIONS")
+                res.setHeader("Access-Control-Allow-Headers",  "Content-Type")
+                res.setHeader("Access-Control-Expose-Headers", "Location")
+
+                /*  handle CORS preflight  */
+                if (req.method === "OPTIONS") {
+                    res.writeHead(204)
+                    res.end()
                     return
                 }
 
-                /*  determine if WHIP (receiving) or WHEP (sending) based on SDP content  */
-                const hasSendonly  = /\ba=sendonly\b/m.test(body)
-                const hasSendrecv  = /\ba=sendrecv\b/m.test(body)
-                const hasRecvonly  = /\ba=recvonly\b/m.test(body)
-                const isPublisher  = hasSendonly || hasSendrecv
-                const isViewer     = hasRecvonly
-
-                /*  handle protocol based on mode  */
-                if (self.params.mode === "r" && isPublisher)
-                    /*  in read mode, accept WHIP publishers  */
-                    await self.handleWHIP(res, body)
-                else if (self.params.mode === "w" && isViewer)
-                    /*  in write mode, accept WHEP viewers  */
-                    await self.handleWHEP(res, body)
+                /*  handle requests...  */
+                if (req.method === "POST" && pathMatch) {
+                    /*  handle WHIP/WHEP POST  */
+                    const body = await self.readRequestBody(req)
+
+                    /*  sanity check content type  */
+                    const contentType = req.headers["content-type"]
+                    if (contentType !== "application/sdp") {
+                        res.writeHead(415, { "Content-Type": "text/plain" })
+                        res.end("Unsupported Media Type")
+                        return
+                    }
+
+                    /*  determine if WHIP (receiving) or WHEP (sending) based on SDP content  */
+                    const hasSendonly  = /\ba=sendonly\b/m.test(body)
+                    const hasSendrecv  = /\ba=sendrecv\b/m.test(body)
+                    const hasRecvonly  = /\ba=recvonly\b/m.test(body)
+                    const isPublisher  = hasSendonly || hasSendrecv
+                    const isViewer     = hasRecvonly
+
+                    /*  handle protocol based on mode  */
+                    if (self.params.mode === "r" && isPublisher)
+                        /*  in read mode, accept WHIP publishers  */
+                        await self.handleWHIP(res, body)
+                    else if (self.params.mode === "w" && isViewer)
+                        /*  in write mode, accept WHEP viewers  */
+                        await self.handleWHEP(res, body)
+                    else {
+                        res.writeHead(403, { "Content-Type": "text/plain" })
+                        res.end("Forbidden")
+                    }
+                }
+                else if (req.method === "DELETE" && resourceMatch) {
+                    /*  handle DELETE for connection teardown  */
+                    const resourceId = url.pathname.substring(self.params.path.length + 1)
+                    self.handleDELETE(res, resourceId)
+                }
                 else {
-                    res.writeHead(403, { "Content-Type": "text/plain" })
-                    res.end("Forbidden")
+                    /*  handle unknown requests  */
+                    res.writeHead(404, { "Content-Type": "text/plain" })
+                    res.end("Not Found")
                 }
             }
-            else if (req.method === "DELETE" && resourceMatch) {
-                /*  handle DELETE for connection teardown  */
-                const resourceId = url.pathname.substring(self.params.path.length + 1)
-                self.handleDELETE(res, resourceId)
-            }
-            else {
-                /*  handle unknown requests  */
-                res.writeHead(404, { "Content-Type": "text/plain" })
-                res.end("Not Found")
+            catch (err: unknown) {
+                self.log("error", `HTTP request handler failed: ${util.ensureError(err).message}`)
+                if (!res.headersSent) {
+                    res.writeHead(500, { "Content-Type": "text/plain" })
+                    res.end("Internal Server Error")
+                }
             }
         })
 
         /*  start HTTP server  */
-        await new Promise<void>((resolve) => {
+        await new Promise<void>((resolve, reject) => {
+            const onError = (err: Error) => { reject(err) }
+            this.httpServer!.once("error", onError)
             this.httpServer!.listen(listen.port, listen.host, () => {
+                this.httpServer!.removeListener("error", onError)
                 const mode = this.params.mode === "r" ? "WHIP" : "WHEP"
                 this.log("info", `WebRTC ${mode} server listening on http://${listen.host}:${listen.port}${this.params.path}`)
                 resolve()
@@ -470,6 +487,7 @@ export default class SpeechFlowNodeXIOWebRTC extends SpeechFlowNode {
                 }
                 if (self.peerConnections.size === 0) {
                     /*  silently drop if no viewers connected  */
+                    self.rtpMarkerNext = true
                     callback()
                     return
                 }
@@ -486,11 +504,15 @@ export default class SpeechFlowNodeXIOWebRTC extends SpeechFlowNode {
                     this.push(null)
                     return
                 }
-                reads.add(self.chunkQueue!.read().then((chunk) => {
+                if (self.chunkQueue === null)
+                    return
+                const queue = self.chunkQueue
+                reads.add(queue.read().then((chunk) => {
                     this.push(chunk, "binary")
                 }).catch((err: Error) => {
                     self.log("warning", `read on chunk queue operation failed: ${err}`)
-                    this.push(null)
+                    if (queue.destroyed)
+                        this.push(null)
                 }))
             }
         })
@@ -517,7 +539,7 @@ export default class SpeechFlowNodeXIOWebRTC extends SpeechFlowNode {
 
         /*  drain and clear chunk queue  */
         if (this.chunkQueue !== null) {
-            this.chunkQueue.drain()
+            this.chunkQueue.destroy()
             this.chunkQueue = null
         }
 

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

@@ -1,6 +1,6 @@
 /*
 **  SpeechFlow - Speech Processing Flow Graph
-**  Copyright (c) 2024-2025 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Copyright (c) 2024-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
 **  Licensed under GPL 3.0 <https://spdx.org/licenses/GPL-3.0-only>
 */
 
@@ -21,8 +21,9 @@ export default class SpeechFlowNodeXIOWebSocket extends SpeechFlowNode {
     public static name = "xio-websocket"
 
     /*  internal state  */
-    private server: ws.WebSocketServer | null = null
-    private client: ReconnWebSocket    | null = null
+    private server:     ws.WebSocketServer                    | null = null
+    private client:     ReconnWebSocket                       | null = null
+    private chunkQueue: util.AsyncQueue<SpeechFlowChunk>      | null = null
 
     /*  construct node  */
     constructor (id: string, cfg: { [ id: string ]: any }, opts: { [ id: string ]: any }, args: any[]) {
@@ -63,7 +64,7 @@ export default class SpeechFlowNodeXIOWebSocket extends SpeechFlowNode {
             /*  listen locally on a Websocket port  */
             const url = new URL(this.params.listen)
             const websockets = new Set<ws.WebSocket>()
-            const chunkQueue = new util.SingleQueue<SpeechFlowChunk>()
+            this.chunkQueue = new util.AsyncQueue<SpeechFlowChunk>()
             this.server = new ws.WebSocketServer({
                 host: url.hostname,
                 port: Number.parseInt(url.port, 10),
@@ -101,8 +102,13 @@ export default class SpeechFlowNodeXIOWebSocket extends SpeechFlowNode {
                         buffer = Buffer.from(data)
                     else
                         buffer = Buffer.concat(data)
-                    const chunk = util.streamChunkDecode(buffer)
-                    chunkQueue.write(chunk)
+                    try {
+                        const chunk = util.streamChunkDecode(buffer)
+                        this.chunkQueue?.write(chunk)
+                    }
+                    catch (_err: unknown) {
+                        this.log("warning", `received invalid CBOR chunk on URL ${this.params.listen} from peer ${peer}`)
+                    }
                 })
             })
             this.server.on("error", (error) => {
@@ -124,9 +130,11 @@ export default class SpeechFlowNodeXIOWebSocket extends SpeechFlowNode {
                         callback(new Error("still no WebSocket connections available"))
                     else {
                         const data = util.streamChunkEncode(chunk)
-                        const results: Promise<void>[] = []
+                        const sends:   Promise<void>[] = []
+                        const clients: ws.WebSocket[]  = []
                         for (const websocket of websockets.values()) {
-                            results.push(new Promise<void>((resolve, reject) => {
+                            clients.push(websocket)
+                            sends.push(new Promise<void>((resolve, reject) => {
                                 websocket.send(data, (error) => {
                                     if (error)
                                         reject(error)
@@ -135,10 +143,27 @@ export default class SpeechFlowNodeXIOWebSocket extends SpeechFlowNode {
                                 })
                             }))
                         }
-                        Promise.all(results).then(() => {
-                            callback()
-                        }).catch((error: unknown) => {
-                            callback(util.ensureError(error))
+                        Promise.allSettled(sends).then((results) => {
+                            let lastError: Error | null = null
+                            for (let i = 0; i < results.length; i++) {
+                                if (results[i].status === "rejected") {
+                                    const error = util.ensureError((results[i] as PromiseRejectedResult).reason)
+                                    self.log("warning", `failed to send to WebSocket client: ${error.message}`)
+                                    websockets.delete(clients[i])
+                                    clients[i].terminate()
+                                    lastError = error
+                                }
+                            }
+                            const failures = results.filter((r) => r.status === "rejected").length
+                            if (failures > 0 && failures < results.length)
+                                self.log("warning", "partial broadcast failure: " +
+                                    `${failures} of ${results.length} WebSocket clients failed`)
+                            if (lastError !== null && failures === results.length)
+                                callback(lastError)
+                            else
+                                callback()
+                        }).catch((err: Error) => {
+                            callback(err)
                         })
                     }
                 },
@@ -147,12 +172,20 @@ export default class SpeechFlowNodeXIOWebSocket extends SpeechFlowNode {
                     callback()
                 },
                 read (size: number) {
-                    if (self.params.mode === "w")
-                        throw new Error("read operation on write-only node")
-                    reads.add(chunkQueue.read().then((chunk) => {
+                    if (self.params.mode === "w") {
+                        self.log("error", "read operation on write-only node")
+                        this.push(null)
+                        return
+                    }
+                    if (self.chunkQueue === null)
+                        return
+                    const queue = self.chunkQueue
+                    reads.add(queue.read().then((chunk) => {
                         this.push(chunk, "binary")
                     }).catch((err: Error) => {
                         self.log("warning", `read on chunk queue operation failed: ${err}`)
+                        if (queue.destroyed)
+                            this.push(null)
                     }))
                 }
             })
@@ -178,7 +211,7 @@ export default class SpeechFlowNodeXIOWebSocket extends SpeechFlowNode {
                 const error = util.ensureError(ev.error)
                 this.log("error", `error of connection on URL ${this.params.connect}: ${error.message}`)
             })
-            const chunkQueue = new util.SingleQueue<SpeechFlowChunk>()
+            this.chunkQueue = new util.AsyncQueue<SpeechFlowChunk>()
             this.client.addEventListener("message", (ev: MessageEvent) => {
                 if (this.params.mode === "w") {
                     this.log("warning", `connection to URL ${this.params.connect}: ` +
@@ -191,8 +224,13 @@ export default class SpeechFlowNodeXIOWebSocket extends SpeechFlowNode {
                     return
                 }
                 const buffer = Buffer.from(ev.data)
-                const chunk = util.streamChunkDecode(buffer)
-                chunkQueue.write(chunk)
+                try {
+                    const chunk = util.streamChunkDecode(buffer)
+                    this.chunkQueue?.write(chunk)
+                }
+                catch (_err: unknown) {
+                    this.log("warning", `received invalid CBOR chunk from URL ${this.params.connect}`)
+                }
             })
             this.client.binaryType = "arraybuffer"
             const self = this
@@ -207,7 +245,7 @@ export default class SpeechFlowNodeXIOWebSocket extends SpeechFlowNode {
                         callback(new Error("write operation on read-only node"))
                     else if (chunk.type !== self.params.type)
                         callback(new Error(`written chunk is not of ${self.params.type} type`))
-                    else if (!self.client!.OPEN)
+                    else if (self.client!.readyState !== ReconnWebSocket.OPEN)
                         callback(new Error("still no WebSocket connection available"))
                     else {
                         const data = util.streamChunkEncode(chunk)
@@ -220,12 +258,20 @@ export default class SpeechFlowNodeXIOWebSocket extends SpeechFlowNode {
                     callback()
                 },
                 read (size: number) {
-                    if (self.params.mode === "w")
-                        throw new Error("read operation on write-only node")
-                    reads.add(chunkQueue.read().then((chunk) => {
+                    if (self.params.mode === "w") {
+                        self.log("error", "read operation on write-only node")
+                        this.push(null)
+                        return
+                    }
+                    if (self.chunkQueue === null)
+                        return
+                    const queue = self.chunkQueue
+                    reads.add(queue.read().then((chunk) => {
                         this.push(chunk, "binary")
                     }).catch((err: Error) => {
                         self.log("warning", `read on chunk queue operation failed: ${err}`)
+                        if (queue.destroyed)
+                            this.push(null)
                     }))
                 }
             })
@@ -234,8 +280,19 @@ export default class SpeechFlowNodeXIOWebSocket extends SpeechFlowNode {
 
     /*  close node  */
     async close () {
+        /*  drain and clear chunk queue reference  */
+        if (this.chunkQueue !== null) {
+            this.chunkQueue.destroy()
+            this.chunkQueue = null
+        }
+
         /*  close WebSocket server  */
         if (this.server !== null) {
+            /*  forcibly terminate all active client connections  */
+            for (const client of this.server.clients)
+                client.terminate()
+
+            /*  close connection  */
             await new Promise<void>((resolve, reject) => {
                 this.server!.close((error) => {
                     if (error) reject(error)

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

@@ -1,6 +1,6 @@
 /*
 **  SpeechFlow - Speech Processing Flow Graph
-**  Copyright (c) 2024-2025 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Copyright (c) 2024-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
 **  Licensed under GPL 3.0 <https://spdx.org/licenses/GPL-3.0-only>
 */
 
@@ -9,7 +9,10 @@ import Events, { EventEmitter } from "node:events"
 import Stream from "node:stream"
 
 /*  external dependencies  */
-import { DateTime, Duration } from "luxon"
+import { DateTime, Duration }   from "luxon"
+
+/*  internal dependencies  */
+import { deepClone }            from "./speechflow-util-misc"
 
 /*  the definition of a single payload chunk passed through the SpeechFlow nodes  */
 export class SpeechFlowChunk {
@@ -33,7 +36,7 @@ export class SpeechFlowChunk {
             this.kind,
             this.type,
             payload,
-            new Map(this.meta)
+            deepClone(this.meta)
         )
     }
 }
@@ -140,16 +143,12 @@ export default class SpeechFlowNode extends Events.EventEmitter {
                 if (typeof this.args[spec[name].pos] !== spec[name].type)
                     throw new Error(`invalid type of positional parameter "${name}" ` +
                         `(has to be ${spec[name].type})`)
-                if ("match" in spec[name]
-                    && this.args[spec[name].pos].match(spec[name].match) === null)
-                    throw new Error(`invalid value of positional parameter "${name}" ` +
-                        `(has to match ${spec[name].match})`)
                 if ("match" in spec[name]
                     && (   (   spec[name].match instanceof RegExp
                             && this.args[spec[name].pos].match(spec[name].match) === null)
                         || (   typeof spec[name].match === "function"
                             && !spec[name].match(this.args[spec[name].pos])    )          ))
-                    throw new Error(`invalid value "${this.opts[name]}" of positional parameter "${name}"`)
+                    throw new Error(`invalid value "${this.args[spec[name].pos!]}" of positional parameter "${name}"`)
                 this.params[name] = this.args[spec[name].pos]
             }
             else if ("val" in spec[name] && spec[name].val !== undefined)

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

@@ -1,6 +1,6 @@
 /*
 **  SpeechFlow - Speech Processing Flow Graph
-**  Copyright (c) 2024-2025 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Copyright (c) 2024-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
 **  Licensed under GPL 3.0 <https://spdx.org/licenses/GPL-3.0-only>
 */
 
@@ -15,7 +15,14 @@ interface StartCaptureMessage {
     chunkId: string
     expectedSamples: number
 }
-type WorkletMessage = InputChunkMessage | StartCaptureMessage
+interface CancelCaptureMessage {
+    type: "cancel-capture"
+    chunkId: string
+}
+interface CancelAllCapturesMessage {
+    type: "cancel-all-captures"
+}
+type WorkletMessage = InputChunkMessage | StartCaptureMessage | CancelCaptureMessage | CancelAllCapturesMessage
 interface ChunkData {
     data: Float32Array
     chunkId: string
@@ -24,6 +31,10 @@ interface ChunkStartedMessage {
     type: "chunk-started"
     chunkId: string
 }
+interface CaptureReadyMessage {
+    type: "capture-ready"
+    chunkId: string
+}
 interface CaptureCompleteMessage {
     type: "capture-complete"
     chunkId: string
@@ -43,9 +54,12 @@ class AudioSourceProcessor extends AudioWorkletProcessor {
 
         /*  receive input chunks  */
         this.port.addEventListener("message", (event: MessageEvent<WorkletMessage>) => {
-            const { type, chunkId } = event.data
+            const { type } = event.data
             if (type === "input-chunk")
-                this.pendingData.push({ data: event.data.data.pcmData, chunkId })
+                this.pendingData.push({
+                    data:    event.data.data.pcmData,
+                    chunkId: event.data.chunkId
+                })
         })
     }
 
@@ -114,7 +128,8 @@ class AudioSourceProcessor extends AudioWorkletProcessor {
 /*  audio capture node  */
 class AudioCaptureProcessor extends AudioWorkletProcessor {
     /*  internal state  */
-    private activeCaptures = new Map<string, { data: number[], expectedSamples: number }>()
+    private static readonly CAPTURE_TTL = 30 * 1000
+    private activeCaptures = new Map<string, { data: number[], expectedSamples: number, createdAt: number }>()
 
     /*  node construction  */
     constructor () {
@@ -122,13 +137,28 @@ class AudioCaptureProcessor extends AudioWorkletProcessor {
 
         /*  receive start of capturing command  */
         this.port.addEventListener("message", (event: MessageEvent<WorkletMessage>) => {
-            const { type, chunkId } = event.data
+            const { type } = event.data
             if (type === "start-capture") {
+                const chunkId = event.data.chunkId
                 this.activeCaptures.set(chunkId, {
                     data: [],
-                    expectedSamples: event.data.expectedSamples
+                    expectedSamples: event.data.expectedSamples,
+                    createdAt: Date.now()
                 })
+
+                /*  acknowledge capture registration  */
+                const ready: CaptureReadyMessage = {
+                    type: "capture-ready",
+                    chunkId
+                }
+                this.port.postMessage(ready)
             }
+            else if (type === "cancel-capture") {
+                const chunkId = event.data.chunkId
+                this.activeCaptures.delete(chunkId)
+            }
+            else if (type === "cancel-all-captures")
+                this.activeCaptures.clear()
         })
     }
 
@@ -145,6 +175,15 @@ class AudioCaptureProcessor extends AudioWorkletProcessor {
         const frameCount = input[0].length
         const channelCount = input.length
 
+        /*  evict stale captures (TTL safety net)  */
+        const currentTime = Date.now()
+        for (const [ chunkId, capture ] of this.activeCaptures) {
+            if ((currentTime - capture.createdAt) > AudioCaptureProcessor.CAPTURE_TTL)
+                this.activeCaptures.delete(chunkId)
+        }
+        if (this.activeCaptures.size === 0)
+            return true
+
         /*  iterate over all active captures  */
         for (const [ chunkId, capture ] of this.activeCaptures) {
             /*  convert planar to interleaved  */