@framers/agentos 0.1.113 → 0.1.114

package/dist/voice-pipeline/WebRTCStreamTransport.js

@@ -0,0 +1,573 @@
+/**
+ * @module voice-pipeline/WebRTCStreamTransport
+ *
+ * A concrete {@link IStreamTransport} implementation that wraps a WebRTC
+ * `RTCPeerConnection` and its DataChannels for bidirectional audio/text
+ * streaming. Provides lower latency than WebSocket by using unreliable/
+ * unordered DataChannels (UDP-like semantics) for audio frames and a
+ * reliable/ordered channel for control messages.
+ *
+ * ## Channel architecture
+ *
+ * Two DataChannels are created on the connection:
+ *
+ * | Channel   | Label       | Ordered | Reliable | Purpose                          |
+ * |-----------|-------------|---------|----------|----------------------------------|
+ * | Audio     | `'audio'`   | No      | No       | Low-latency PCM frame transport  |
+ * | Control   | `'control'` | Yes     | Yes      | JSON control messages (lossless) |
+ *
+ * The audio channel uses `maxRetransmits: 0` (fire-and-forget) because
+ * real-time voice tolerates occasional packet loss better than added
+ * latency from retransmissions. The control channel uses default TCP-like
+ * reliability since protocol messages (mute/unmute/stop) must arrive.
+ *
+ * ## Wire protocol
+ *
+ * ### Audio channel (binary)
+ * Each message is a raw `ArrayBuffer` containing Float32Array PCM samples.
+ * The transport reconstructs the Float32Array and wraps it in an
+ * {@link AudioFrame} with the configured sample rate.
+ *
+ * ### Control channel (text)
+ * Each message is a JSON string conforming to {@link ClientTextMessage}
+ * (inbound) or {@link ServerTextMessage} (outbound). Malformed JSON
+ * emits an `'error'` event without crashing the transport.
+ *
+ * ## Native dependency
+ * Node.js does not ship a built-in WebRTC stack. This transport requires
+ * the `wrtc` npm package (or a compatible polyfill) as an optional peer
+ * dependency. A helpful error is thrown at construction time if the
+ * package is not installed.
+ *
+ * @see {@link IStreamTransport} for the interface contract.
+ * @see {@link WebSocketStreamTransport} for the WebSocket-based sibling.
+ * @see {@link VoicePipelineOrchestrator} which consumes this transport.
+ */
+import { EventEmitter } from 'node:events';
+import { randomUUID } from 'node:crypto';
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+/**
+ * Bidirectional voice pipeline transport backed by WebRTC DataChannels.
+ *
+ * Uses two DataChannels for optimal voice streaming:
+ * - An **unreliable, unordered** `audio` channel for PCM frames (minimal
+ *   latency, tolerates packet loss).
+ * - A **reliable, ordered** `control` channel for JSON control messages
+ *   (mute/unmute/stop/config).
+ *
+ * ## Lifecycle
+ *
+ * 1. Construct with an existing {@link RTCPeerConnectionLike}.
+ * 2. Call `initialize` to create DataChannels and wire up handlers.
+ * 3. The transport is `'open'` once both DataChannels reach `'open'` state.
+ * 4. Call `close` to tear down channels and the peer connection.
+ *
+ * ## Events emitted
+ *
+ * | Event            | Payload                      | Description                           |
+ * |------------------|------------------------------|---------------------------------------|
+ * | `'audio_frame'`  | {@link AudioFrame}           | Inbound audio from the remote peer.   |
+ * | `'control'`      | {@link ClientTextMessage}    | Inbound JSON control message.         |
+ * | `'connected'`    | *(none)*                     | Both DataChannels are open.           |
+ * | `'disconnected'` | *(none)*                     | Connection has been closed.           |
+ * | `'error'`        | `Error`                      | Transport-level error.                |
+ * | `'ice_candidate'`| ICE candidate object         | Local ICE candidate for signaling.    |
+ *
+ * @fires audio_frame - `(frame: AudioFrame)` for every inbound audio message.
+ * @fires control - `(msg: ClientTextMessage)` for every inbound control message.
+ * @fires connected - Both DataChannels have reached 'open' state.
+ * @fires disconnected - Peer connection has been closed.
+ * @fires error - Transport-level error occurred.
+ * @fires ice_candidate - Local ICE candidate available for the signaling layer.
+ *
+ * @see {@link IStreamTransport} for the interface contract.
+ * @see {@link WebSocketStreamTransport} for the WebSocket-based sibling.
+ *
+ * @example
+ * ```typescript
+ * import { WebRTCStreamTransport } from '../voice-pipeline/index.js';
+ *
+ * // Receive RTCPeerConnection from your signaling server
+ * const transport = new WebRTCStreamTransport(peerConnection, { sampleRate: 16000 });
+ * await transport.initialize();
+ *
+ * transport.on('audio_frame', (frame) => sttSession.pushAudio(frame));
+ * transport.on('control', (msg) => handleClientMessage(msg));
+ * transport.on('ice_candidate', (candidate) => signalingChannel.send(candidate));
+ * ```
+ */
+export class WebRTCStreamTransport extends EventEmitter {
+    // -------------------------------------------------------------------------
+    // Constructor
+    // -------------------------------------------------------------------------
+    /**
+     * Create a new WebRTC transport wrapping an existing peer connection.
+     *
+     * The transport starts in `'connecting'` state and transitions to
+     * `'open'` once both DataChannels are established and open.
+     *
+     * @param peerConnection - An existing RTCPeerConnection (from the `wrtc`
+     *   package or a browser-compatible polyfill). The connection should be
+     *   in `'new'` or `'connecting'` state — the transport will create
+     *   DataChannels on it.
+     * @param config - Transport-level configuration (must include sampleRate).
+     *
+     * @throws {Error} If `peerConnection` is null/undefined.
+     *
+     * @example
+     * ```typescript
+     * const pc = new RTCPeerConnection({ iceServers: [...] });
+     * const transport = new WebRTCStreamTransport(pc, { sampleRate: 16000 });
+     * ```
+     */
+    constructor(peerConnection, config) {
+        super();
+        /**
+         * Unreliable/unordered DataChannel for audio frame transport.
+         * Created during `initialize`. `null` until then.
+         */
+        this._audioChannel = null;
+        /**
+         * Reliable/ordered DataChannel for JSON control messages.
+         * Created during `initialize`. `null` until then.
+         */
+        this._controlChannel = null;
+        if (!peerConnection) {
+            throw new Error('WebRTCStreamTransport: peerConnection is required. ' +
+                'Pass an RTCPeerConnection instance from the `wrtc` package or a compatible polyfill.');
+        }
+        this._pc = peerConnection;
+        this._sampleRate = config.sampleRate;
+        this._config = config;
+        this.id = randomUUID();
+        // Always start as connecting — we need both DataChannels to be open
+        // before the transport is usable.
+        this._state = 'connecting';
+    }
+    // -------------------------------------------------------------------------
+    // IStreamTransport -- public surface
+    // -------------------------------------------------------------------------
+    /**
+     * Current connection state of the WebRTC transport.
+     *
+     * The transport is `'open'` only when both DataChannels (audio + control)
+     * have reached their `'open'` readyState. Any earlier state maps to
+     * `'connecting'`, and any teardown maps to `'closing'` or `'closed'`.
+     */
+    get state() {
+        return this._state;
+    }
+    /**
+     * Create DataChannels and wire up all event handlers.
+     *
+     * This must be called after construction and before any send operations.
+     * It creates the `audio` (unreliable) and `control` (reliable)
+     * DataChannels on the peer connection and sets up message handlers.
+     *
+     * The transport transitions to `'open'` once both channels report
+     * readyState `'open'`.
+     *
+     * @returns Resolves when DataChannels are created (not necessarily open yet).
+     *
+     * @example
+     * ```typescript
+     * const transport = new WebRTCStreamTransport(pc, { sampleRate: 16000 });
+     * await transport.initialize();
+     * // transport.state may still be 'connecting' until ICE completes
+     * ```
+     */
+    async initialize() {
+        // Create the unreliable audio channel — unordered + no retransmits
+        // gives UDP-like semantics ideal for real-time audio where latency
+        // matters more than guaranteed delivery.
+        this._audioChannel = this._pc.createDataChannel('audio', {
+            ordered: false,
+            maxRetransmits: 0,
+        });
+        this._audioChannel.binaryType = 'arraybuffer';
+        // Create the reliable control channel — ordered + reliable (defaults)
+        // ensures JSON protocol messages arrive in sequence and without loss.
+        this._controlChannel = this._pc.createDataChannel('control', {
+            ordered: true,
+        });
+        this._attachAudioChannelHandlers(this._audioChannel);
+        this._attachControlChannelHandlers(this._controlChannel);
+        this._attachPeerConnectionHandlers();
+    }
+    /**
+     * Send a synthesised audio chunk to the remote peer for playback.
+     *
+     * If the payload is an {@link EncodedAudioChunk} (has an `audio` Buffer
+     * property), that buffer's underlying ArrayBuffer is sent. If it is an
+     * {@link AudioFrame} (has a `samples` Float32Array), the samples'
+     * underlying ArrayBuffer is sent.
+     *
+     * @param chunk - Encoded audio chunk or raw PCM frame to deliver.
+     * @returns Resolves once the data has been handed to the DataChannel.
+     *
+     * @throws {Error} If the audio channel is not open or not initialized.
+     *
+     * @example
+     * ```typescript
+     * await transport.sendAudio({
+     *   audio: Buffer.from(opusBytes),
+     *   format: 'opus',
+     *   sampleRate: 24000,
+     *   durationMs: 20,
+     *   text: 'Hello!',
+     * });
+     * ```
+     */
+    sendAudio(chunk) {
+        return new Promise((resolve, reject) => {
+            if (!this._audioChannel) {
+                reject(new Error('WebRTCStreamTransport: audio channel not initialized. Call initialize() first.'));
+                return;
+            }
+            if (this._audioChannel.readyState !== 'open') {
+                reject(new Error(`WebRTCStreamTransport: audio channel is "${this._audioChannel.readyState}", not "open".`));
+                return;
+            }
+            try {
+                let arrayBuffer;
+                if ('audio' in chunk) {
+                    // EncodedAudioChunk path: extract the ArrayBuffer from the Buffer.
+                    // Buffer.buffer may be a shared pool allocation, so we slice to get
+                    // only the relevant portion.
+                    const buf = chunk.audio;
+                    arrayBuffer = buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);
+                }
+                else {
+                    // AudioFrame path: send the Float32Array's backing ArrayBuffer.
+                    // Same slicing concern as above — the Float32Array may be a view
+                    // into a larger buffer.
+                    const frame = chunk;
+                    arrayBuffer = frame.samples.buffer.slice(frame.samples.byteOffset, frame.samples.byteOffset + frame.samples.byteLength);
+                }
+                this._audioChannel.send(arrayBuffer);
+                resolve();
+            }
+            catch (err) {
+                reject(err);
+            }
+        });
+    }
+    /**
+     * Send a JSON control message to the remote peer.
+     *
+     * The message is JSON-stringified before transmission on the reliable
+     * control channel. Both {@link TransportControlMessage} and
+     * {@link ServerTextMessage} are accepted since they share the same
+     * serialisation path.
+     *
+     * @param msg - Server-side protocol message.
+     * @returns Resolves once the message has been handed to the DataChannel.
+     *
+     * @throws {Error} If the control channel is not open or not initialized.
+     *
+     * @example
+     * ```typescript
+     * await transport.sendControl({ type: 'mute' });
+     * ```
+     */
+    sendControl(msg) {
+        return new Promise((resolve, reject) => {
+            if (!this._controlChannel) {
+                reject(new Error('WebRTCStreamTransport: control channel not initialized. Call initialize() first.'));
+                return;
+            }
+            if (this._controlChannel.readyState !== 'open') {
+                reject(new Error(`WebRTCStreamTransport: control channel is "${this._controlChannel.readyState}", not "open".`));
+                return;
+            }
+            try {
+                this._controlChannel.send(JSON.stringify(msg));
+                resolve();
+            }
+            catch (err) {
+                reject(err);
+            }
+        });
+    }
+    /**
+     * Initiate a graceful close of the transport.
+     *
+     * Closes both DataChannels and the underlying peer connection.
+     * The `'disconnected'` event fires once the connection has fully closed.
+     *
+     * @param _code - Ignored for WebRTC (included for IStreamTransport compat).
+     * @param _reason - Ignored for WebRTC (included for IStreamTransport compat).
+     */
+    close(_code, _reason) {
+        this._state = 'closing';
+        // Close DataChannels first — this triggers their onclose handlers
+        // which will check whether the transport should transition to 'closed'.
+        if (this._audioChannel && this._audioChannel.readyState !== 'closed') {
+            this._audioChannel.close();
+        }
+        if (this._controlChannel && this._controlChannel.readyState !== 'closed') {
+            this._controlChannel.close();
+        }
+        // Close the peer connection, which releases all network resources.
+        if (this._pc.connectionState !== 'closed') {
+            this._pc.close();
+        }
+        this._state = 'closed';
+        this.emit('disconnected');
+    }
+    /**
+     * Add a remote ICE candidate received through the signaling channel.
+     *
+     * WebRTC requires ICE candidate exchange for NAT traversal. The signaling
+     * server should forward remote candidates to this method.
+     *
+     * @param candidate - The ICE candidate object from the remote peer, or
+     *   `null` to signal end-of-candidates.
+     * @returns Resolves when the candidate has been added to the connection.
+     *
+     * @throws {Error} If the candidate is invalid or the connection is closed.
+     *
+     * @example
+     * ```typescript
+     * signalingChannel.on('ice_candidate', async (candidate) => {
+     *   await transport.addIceCandidate(candidate);
+     * });
+     * ```
+     */
+    async addIceCandidate(candidate) {
+        await this._pc.addIceCandidate(candidate);
+    }
+    // -------------------------------------------------------------------------
+    // Private helpers
+    // -------------------------------------------------------------------------
+    /**
+     * Attach message and lifecycle handlers to the audio DataChannel.
+     *
+     * Inbound binary messages are decoded as Float32Array PCM samples and
+     * emitted as `'audio_frame'` events. This channel uses arraybuffer
+     * binary type for efficient binary transfer.
+     *
+     * @param channel - The audio DataChannel to attach handlers to.
+     */
+    _attachAudioChannelHandlers(channel) {
+        channel.onmessage = (event) => {
+            try {
+                // DataChannel messages arrive as ArrayBuffer when binaryType is set.
+                // Guard against unexpected string messages on the audio channel.
+                const raw = event.data;
+                if (!(raw instanceof ArrayBuffer)) {
+                    this.emit('error', new Error('WebRTCStreamTransport: received non-binary message on audio channel'));
+                    return;
+                }
+                // Create a Float32Array view over the received ArrayBuffer.
+                // Each float is 4 bytes, so byteLength / 4 gives the sample count.
+                const samples = new Float32Array(raw);
+                const frame = {
+                    samples,
+                    sampleRate: this._sampleRate,
+                    timestamp: Date.now(),
+                };
+                this.emit('audio_frame', frame);
+            }
+            catch (err) {
+                this.emit('error', new Error(`WebRTCStreamTransport: error processing audio message: ${String(err)}`));
+            }
+        };
+        channel.onopen = () => {
+            // Check if both channels are now open to transition the transport
+            this._checkBothChannelsOpen();
+        };
+        channel.onclose = () => {
+            // If the audio channel closes unexpectedly, surface the disconnection
+            if (this._state === 'open') {
+                this._state = 'closed';
+                this.emit('disconnected');
+            }
+        };
+        channel.onerror = (event) => {
+            this.emit('error', new Error(`WebRTCStreamTransport: audio channel error: ${String(event)}`));
+        };
+    }
+    /**
+     * Attach message and lifecycle handlers to the control DataChannel.
+     *
+     * Inbound text messages are JSON-parsed as {@link ClientTextMessage}
+     * and emitted as `'control'` events. Malformed JSON triggers an
+     * `'error'` event without crashing the transport.
+     *
+     * @param channel - The control DataChannel to attach handlers to.
+     */
+    _attachControlChannelHandlers(channel) {
+        channel.onmessage = (event) => {
+            try {
+                const text = typeof event.data === 'string' ? event.data : String(event.data);
+                const msg = JSON.parse(text);
+                this.emit('control', msg);
+            }
+            catch (err) {
+                // Malformed JSON should not crash the transport — emit an error
+                // and let the session continue processing valid messages.
+                this.emit('error', new Error(`WebRTCStreamTransport: failed to parse control message as JSON: ${String(err)}`));
+            }
+        };
+        channel.onopen = () => {
+            // Check if both channels are now open to transition the transport
+            this._checkBothChannelsOpen();
+        };
+        channel.onclose = () => {
+            // If the control channel closes unexpectedly, surface the disconnection
+            if (this._state === 'open') {
+                this._state = 'closed';
+                this.emit('disconnected');
+            }
+        };
+        channel.onerror = (event) => {
+            this.emit('error', new Error(`WebRTCStreamTransport: control channel error: ${String(event)}`));
+        };
+    }
+    /**
+     * Attach handlers to the peer connection for ICE candidate exchange
+     * and connection state monitoring.
+     *
+     * ICE candidates are re-emitted as `'ice_candidate'` events so the
+     * consumer can relay them to the remote peer via a signaling channel.
+     * Connection state changes are mapped to transport state transitions.
+     */
+    _attachPeerConnectionHandlers() {
+        // Forward local ICE candidates to the consumer for signaling.
+        // Without this, NAT traversal cannot complete because the remote
+        // peer won't know how to reach us.
+        this._pc.onicecandidate = (event) => {
+            if (event.candidate) {
+                this.emit('ice_candidate', event.candidate);
+            }
+        };
+        // Map peer connection state changes to transport lifecycle events.
+        // The connectionState property aggregates ICE + DTLS state into a
+        // single human-readable enum.
+        this._pc.onconnectionstatechange = () => {
+            const pcState = this._pc.connectionState;
+            switch (pcState) {
+                case 'connected':
+                    // Peer connection is fully established. DataChannel open events
+                    // may fire before or after this — _checkBothChannelsOpen handles
+                    // the actual 'open' transition.
+                    break;
+                case 'disconnected':
+                    // Transient network disruption — ICE may recover automatically.
+                    // We don't transition to 'closed' yet, but surface the event.
+                    if (this._state === 'open') {
+                        this.emit('error', new Error('WebRTCStreamTransport: peer connection disconnected (may recover)'));
+                    }
+                    break;
+                case 'failed':
+                    // ICE/DTLS negotiation failed permanently. Tear down the transport.
+                    this._state = 'closed';
+                    this.emit('error', new Error('WebRTCStreamTransport: peer connection failed'));
+                    this.emit('disconnected');
+                    break;
+                case 'closed':
+                    // Connection was closed (by us or the remote peer).
+                    if (this._state !== 'closed') {
+                        this._state = 'closed';
+                        this.emit('disconnected');
+                    }
+                    break;
+                default:
+                    // 'new' | 'connecting' — no action needed
+                    break;
+            }
+        };
+        // Handle DataChannels created by the remote peer (e.g. if the remote
+        // side creates channels instead of us). This supports both offerer
+        // and answerer roles.
+        this._pc.ondatachannel = (event) => {
+            const channel = event.channel;
+            if (channel.label === 'audio') {
+                channel.binaryType = 'arraybuffer';
+                this._audioChannel = channel;
+                this._attachAudioChannelHandlers(channel);
+            }
+            else if (channel.label === 'control') {
+                this._controlChannel = channel;
+                this._attachControlChannelHandlers(channel);
+            }
+        };
+    }
+    /**
+     * Check if both DataChannels are in the `'open'` readyState.
+     *
+     * Called from each channel's `onopen` handler. Only transitions the
+     * transport to `'open'` state once BOTH channels are ready, since
+     * sending on a non-open channel would throw.
+     */
+    _checkBothChannelsOpen() {
+        const audioOpen = this._audioChannel?.readyState === 'open';
+        const controlOpen = this._controlChannel?.readyState === 'open';
+        if (audioOpen && controlOpen && this._state === 'connecting') {
+            this._state = 'open';
+            this.emit('connected');
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Factory helper for creating a transport with a new RTCPeerConnection
+// ---------------------------------------------------------------------------
+/**
+ * Create a WebRTC transport with a fresh RTCPeerConnection from the `wrtc`
+ * package. This is a convenience factory for server-side usage where a
+ * pre-existing connection is not available.
+ *
+ * The `wrtc` package is loaded via dynamic import to keep it as an
+ * optional peer dependency. If the package is not installed, a descriptive
+ * error is thrown.
+ *
+ * @param config - Transport configuration including sample rate and ICE servers.
+ * @returns A new {@link WebRTCStreamTransport} wrapping a fresh peer connection.
+ *
+ * @throws {Error} If the `wrtc` package is not installed or importable.
+ *
+ * @example
+ * ```typescript
+ * const transport = await createWebRTCTransport({
+ *   sampleRate: 16000,
+ *   iceServers: [{ urls: 'stun:stun.l.google.com:19302' }],
+ * });
+ * await transport.initialize();
+ * ```
+ */
+export async function createWebRTCTransport(config) {
+    // Dynamic import so that `wrtc` is only loaded when actually needed.
+    // This keeps the package as an optional peer dependency — users who
+    // only use WebSocket transport never need to install the heavy native
+    // addon.
+    let RTCPeerConnection;
+    try {
+        // @ts-ignore — optional peer dependency; only needed for server-side WebRTC
+        const wrtcModule = await import('wrtc');
+        RTCPeerConnection =
+            wrtcModule.RTCPeerConnection ?? wrtcModule.default?.RTCPeerConnection;
+    }
+    catch {
+        throw new Error('WebRTCStreamTransport requires the `wrtc` package for server-side WebRTC. ' +
+            'Install it with: npm install wrtc\n\n' +
+            'Note: `wrtc` is a native addon and may require build tools (Python, C++ compiler). ' +
+            'See https://github.com/nicktomlin/wrtc for platform-specific instructions.');
+    }
+    if (!RTCPeerConnection) {
+        throw new Error('WebRTCStreamTransport: `wrtc` package was imported but RTCPeerConnection was not found. ' +
+            'Ensure you have a compatible version of the `wrtc` package installed.');
+    }
+    const pc = new RTCPeerConnection({
+        iceServers: config.iceServers ?? [
+            // Default to Google's public STUN server for basic NAT traversal.
+            // Production deployments should provide their own TURN servers for
+            // symmetric NAT scenarios.
+            { urls: 'stun:stun.l.google.com:19302' },
+        ],
+    });
+    return new WebRTCStreamTransport(pc, config);
+}
+//# sourceMappingURL=WebRTCStreamTransport.js.map

package/dist/voice-pipeline/WebRTCStreamTransport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebRTCStreamTransport.js","sourceRoot":"","sources":["../../src/voice-pipeline/WebRTCStreamTransport.ts"],"names":[],"mappings":"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"}

package/dist/voice-pipeline/WebSocketStreamTransport.d.ts

@@ -21,11 +21,11 @@
  * not crash the transport, allowing the session to continue.
  *
  * ### Binary frames (outbound)
- * {@link sendAudio} sends the raw `Buffer` from an {@link EncodedAudioChunk}
+ * `sendAudio()` sends the raw `Buffer` from an {@link EncodedAudioChunk}
  * (or converts a `Float32Array` to a `Buffer` for raw {@link AudioFrame}s).
  *
  * ### Text frames (outbound)
- * {@link sendControl} JSON-stringifies a {@link ServerTextMessage} and sends
+ * `sendControl()` JSON-stringifies a {@link ServerTextMessage} and sends
  * it as a text frame.
  *
  * ## Reconnection behaviour
@@ -100,7 +100,7 @@ export interface WebSocketLike extends NodeJS.EventEmitter {
  */
 export interface WebSocketStreamTransportConfig {
     /**
-     * Sample rate (in Hz) used to populate {@link AudioFrame.sampleRate} on
+     * Sample rate (in Hz) used to populate `AudioFrame.sampleRate` on
      * inbound binary messages. Must match the rate the remote client is sending.
      *
      * Common values: 16000 (telephony/STT), 24000 (TTS output), 48000 (high-fidelity).
@@ -123,8 +123,8 @@ export interface WebSocketStreamTransportConfig {
  *
  * | Method          | Behaviour                                              |
  * |-----------------|--------------------------------------------------------|
- * | {@link sendAudio}   | Serialises audio to a binary `Buffer` and calls `ws.send()`. |
- * | {@link sendControl} | JSON-stringifies the message and calls `ws.send()`.    |
+ * | `sendAudio()`   | Serialises audio to a binary `Buffer` and calls `ws.send()`. |
+ * | `sendControl()` | JSON-stringifies the message and calls `ws.send()`.    |
  *
  * ## Lifecycle events (re-emitted on `this`)
  *
@@ -161,13 +161,13 @@ export declare class WebSocketStreamTransport extends EventEmitter implements IS
     readonly id: string;
     /**
      * Current connection state. Updated internally by WebSocket event handlers.
-     * Read externally via the {@link state} getter.
+     * Read externally via the `state` getter.
      */
     private _state;
     /** The underlying WebSocket connection. */
     private readonly _ws;
     /**
-     * Audio sample rate propagated into every decoded {@link AudioFrame}.
+     * Audio sample rate propagated into every decoded `AudioFrame`.
      * Configured once at construction and never changed.
      */
     private readonly _sampleRate;
@@ -175,7 +175,7 @@ export declare class WebSocketStreamTransport extends EventEmitter implements IS
      * Create a new transport wrapping an existing WebSocket connection.
      *
      * The constructor inspects `ws.readyState` to determine the initial
-     * {@link state}: if the socket is already OPEN (readyState === 1) the state
+     * `state`: if the socket is already OPEN (readyState === 1) the state
      * is set to `'open'`; otherwise it is set to `'connecting'` and will
      * transition to `'open'` when the `'open'` event fires.
      *