@byokit/realtime 0.2.1 → 0.3.1

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## Unreleased
 
+## 0.3.1 (2026-10-01)
+
+
+
+- SECURITY: Lazy WebRTC capture no longer opens the Android microphone or sends untapped speech before `attachMic()`; `releaseMic()` closes recording while keeping the call connected. Apps using lazy capture should update.
+
+## 0.3.0 (2026-10-01)
+
+
+
+- Add opt-in lazy WebRTC microphone capture: preconnect without a microphone lease, attach and release capture without renegotiation, and release pending capture on close.
+
 ## 0.2.1 (2026-09-30)
 
 

package/README.md

@@ -169,6 +169,48 @@ The main entry is portable for web and React Native and loads no native code. `.
 
 `AudioPorts` requires microphone acquisition/release, PCM capture, playback admission/drain and audio routing. The app owns permissions and its microphone service. Acquire must resolve only after that service is ready. The client awaits it before capture. Each client owns its ports; the app must arbitrate shared microphones.
 
+## Preconnect without microphone capture
+
+Set `capture: 'lazy'` for a browser or React Native WebRTC session. Startup
+negotiates one `sendrecv` audio transceiver with no sender track: it calls
+neither `audio.microphone.acquire()` nor `getUserMedia`, so the app's microphone
+foreground service stays stopped. The playback route remains available.
+
+```ts
+import { realtimeClient, type AudioPorts, type RealtimeStream } from '@byokit/realtime';
+import { webRtcPeer } from '@byokit/realtime/webrtc';
+declare const audio: AudioPorts;
+declare const openVoiceStream: () => Promise<RealtimeStream>;
+const client = realtimeClient({
+  open: openVoiceStream, audio, webrtc: webRtcPeer, capture: 'lazy',
+  onStatus() {}, onTurn() {},
+});
+// Once WebRTC setup has started, await this before accepting speech:
+async function beginTalking() { await client.attachMic(); }
+// When idle, release hardware capture while keeping the call connected:
+async function becomeIdle() { await client.releaseMic(); }
+// End the call and release all media:
+function endCall() { client.stop(); }
+```
+
+`attachMic()` awaits the app's microphone permission/service lease, captures
+an audio track and uses `sender.replaceTrack(track)` before enabling the sender's
+encoding. Lazy peers negotiate `sendrecv` with an inactive encoding: Android's
+audio device cannot start recording just because an answer is applied.
+`releaseMic()` disables that encoding before `replaceTrack(null)`, stops capture tracks and releases the lease so the app
+can stop its microphone service and clear the OS indicator. Neither operation
+renegotiates. Repeated calls are safe; release or stop during pending capture
+cleans up when that capture resolves. Reconnecting starts another lazy peer;
+the app explicitly attaches again when it needs input.
+
+The built-in `webRtcPeer` handle also exposes both methods for direct use.
+Custom peer factories may implement these optional methods; client attach
+rejects if the current peer does not support them or setup has not started.
+The default is eager capture, and PCM capture is unchanged. `setMuted()` still
+only toggles track delivery; use `releaseMic()` to relinquish capture. Mute
+state persists when a new track is attached. Each client owns its `AudioPorts`;
+`microphone.release()` must stop the app-owned foreground service.
+
 Close the client and engine when the call ends. `client.interrupt()` clears playback and aborts unfinished tools; old response output is fenced. Transient provider and transport failures retry twice, after 500 and 1,000 ms, with a fresh budget after 30 healthy seconds. Sent audio, speech and tool calls are never replayed. The app can mark transport closure terminal with `retryableClose`. Explicit ChatGPT interruption opens a fresh call; explicit Gemini interruption rotates its provider session. Native speech interruption remains provider-driven. No STT/LLM/TTS chain is exported. See [the lift contract](../../docs/realtime-kit.md) for bounds, events and usage.
 
 ## Reconnect and host policy

package/dist/client.d.ts

@@ -2,6 +2,8 @@ import type { RealtimeClientOptions } from './types.ts';
 /** Provider-blind client with bounded reconnects and exclusive media ownership. */
 export declare function realtimeClient(options: RealtimeClientOptions): {
     stop: (reason?: string) => void;
+    attachMic(): Promise<void>;
+    releaseMic(): Promise<void>;
     interrupt(): void;
     setMuted(value: boolean): void;
     speak(text: string): void;

package/dist/client.js

@@ -18,6 +18,7 @@ export function realtimeClient(options) {
             audio.player.unbind(current.stream);
         await current.media?.catch(() => { });
         current.peer?.stop();
+        await current.peer?.releaseMic?.();
         await current.routeRelease;
         try {
             await current.capture?.release();
@@ -205,7 +206,7 @@ export function realtimeClient(options) {
                         break;
                     if (!options.webrtc)
                         throw new Error('Voice media is unsupported.');
-                    current.media = options.webrtc({ label: frame.dataChannelLabel, audio: { ...audio, unroute() { return current.routeRelease = audio.unroute(); } }, signal: current.signal.signal,
+                    current.media = options.webrtc({ label: frame.dataChannelLabel, capture: options.capture, audio: { ...audio, unroute() { return current.routeRelease = audio.unroute(); } }, signal: current.signal.signal,
                         onOffer(sdp) { if (active() && !current.stream?.send({ type: 'realtime.webrtc.offer', sdp }))
                             reconnect(current, 'Voice offer could not be sent.'); },
                         onData(data) { if (active() && !current.stream?.send({ type: 'realtime.webrtc.data', data }))
@@ -303,6 +304,22 @@ export function realtimeClient(options) {
     connect();
     return {
         stop,
+        async attachMic() {
+            const current = attempt;
+            if (stopped || !current?.media)
+                throw new Error('Voice media is unavailable.');
+            await current.media;
+            if (stopped || attempt !== current || !current.peer?.attachMic)
+                throw new Error('Voice media is unavailable.');
+            await current.peer.attachMic();
+        },
+        async releaseMic() {
+            const current = attempt;
+            if (!current?.media)
+                return;
+            await current.media;
+            await current.peer?.releaseMic?.();
+        },
         interrupt() { if (stopped)
             return; audio.player.clear(); speech.length = 0; if (!attempt?.stream?.send({ type: 'realtime.control', action: 'interrupt' })) {
             if (attempt)

package/dist/rn-webrtc.d.ts

@@ -1,5 +1,8 @@
 import { type WebRtcOptions } from './webrtc.ts';
 export type { WebRtcOptions, WebRtcHandle } from './webrtc.ts';
 /** Native media stays unloaded until the app actually starts a voice session. */
-export declare function webRtcPeer(options: WebRtcOptions): Promise<import("./webrtc.ts").WebRtcHandle>;
+export declare function webRtcPeer(options: WebRtcOptions): Promise<import("./webrtc.ts").WebRtcHandle & {
+    attachMic(): Promise<void>;
+    releaseMic(): Promise<void>;
+}>;
 export { webRtcPeer as reactNativeWebRtcPeer };

package/dist/types.d.ts

@@ -89,6 +89,8 @@ export type RealtimeClientOptions = {
     /** Retain ready PCM capture and the playback tail across carrier reconnects.
      * WebRTC still needs a fresh peer. Pending microphone acquisition is never retained. */
     preserveMediaOnReconnect?: boolean;
+    /** WebRTC only: negotiate without capture, then use attachMic/releaseMic. PCM is unchanged. */
+    capture?: 'eager' | 'lazy';
     webrtc?: (options: import('./webrtc.ts').WebRtcOptions) => Promise<import('./webrtc.ts').WebRtcHandle>;
     onStatus(status: 'connecting' | 'connected' | 'thinking' | 'speaking' | 'disconnected', reason?: string): void;
     onTurn(role: 'user' | 'agent', text: string): void;

package/dist/webrtc.d.ts

@@ -3,11 +3,15 @@ export type WebRtcHandle = {
     acceptAnswer(sdp: string): Promise<void>;
     sendData(data: string): boolean;
     setMuted(muted: boolean): void;
+    attachMic?(): Promise<void>;
+    releaseMic?(): Promise<void>;
     stop(): void;
 };
 export type WebRtcOptions = {
     label: string;
     audio: Pick<AudioPorts, 'microphone' | 'route' | 'unroute'>;
+    /** Lazy WebRTC starts with no microphone lease or capture; attach explicitly when speaking. */
+    capture?: 'eager' | 'lazy';
     signal?: AbortSignal;
     platform?: {
         createPeer(): RTCPeerConnection;
@@ -20,5 +24,8 @@ export type WebRtcOptions = {
     onInterruption(active: boolean): void;
     onError(error: Error): void;
 };
-/** One peer per handle. Microphone permission/service readiness precedes media capture. */
-export declare function webRtcPeer(options: WebRtcOptions): Promise<WebRtcHandle>;
+/** One peer per handle. Microphone permission/service readiness precedes each capture. */
+export declare function webRtcPeer(options: WebRtcOptions): Promise<WebRtcHandle & {
+    attachMic(): Promise<void>;
+    releaseMic(): Promise<void>;
+}>;

package/dist/webrtc.js

@@ -4,27 +4,40 @@ function sdp(value) {
         throw new Error('Invalid voice connection answer.');
     return value;
 }
-/** One peer per handle. Microphone permission/service readiness precedes media capture. */
+/** One peer per handle. Microphone permission/service readiness precedes each capture. */
 export async function webRtcPeer(options) {
     if (!/^[A-Za-z0-9._-]{1,64}$/.test(options.label))
         throw new Error('Invalid voice channel.');
     const platform = options.platform ?? { createPeer: () => new RTCPeerConnection({ bundlePolicy: 'max-bundle', rtcpMuxPolicy: 'require' }), getUserMedia: () => navigator.mediaDevices.getUserMedia({ audio: true, video: false }) };
     let acquired = false, stopped = false, stream, peer, channel;
+    let sender, muted = false, micEpoch = 0;
+    let micOperation = Promise.resolve();
+    const serializeMic = (run) => {
+        const operation = micOperation.then(run);
+        micOperation = operation.catch(() => { });
+        return operation;
+    };
+    const clearMic = () => {
+        const previous = stream;
+        stream = undefined;
+        previous?.getTracks().forEach(track => { track.onmute = null; track.onunmute = null; track.onended = null; track.stop(); });
+        if (acquired) {
+            acquired = false;
+            options.audio.microphone.release();
+        }
+    };
     const queue = [];
     let queuedBytes = 0;
     const stop = () => {
         if (stopped)
             return;
         stopped = true;
-        stream?.getTracks().forEach(track => track.stop());
+        micEpoch++;
+        clearMic();
         channel?.close();
         peer?.close();
         queue.length = 0;
         void options.audio.unroute().catch(() => { });
-        if (acquired) {
-            options.audio.microphone.release();
-            acquired = false;
-        }
         options.signal?.removeEventListener('abort', stop);
         options.onRemoteAudio(false);
         options.onConnectionState('disconnected');
@@ -34,26 +47,121 @@ export async function webRtcPeer(options) {
         options.onError(error);
         stop();
     } };
+    const setSending = async (active) => {
+        if (options.capture !== 'lazy')
+            return;
+        const parameters = sender.getParameters();
+        if (!parameters.encodings.length)
+            throw new Error('Voice capture control is unavailable.');
+        parameters.encodings.forEach(encoding => { encoding.active = active; });
+        await sender.setParameters(parameters);
+        // The native bridge can resolve even when the engine rejects setParameters.
+        const applied = sender.getParameters().encodings;
+        if (!applied.length || applied.some(encoding => encoding.active !== active))
+            throw new Error('Voice capture control failed.');
+    };
+    const captureMic = async (generation) => {
+        await options.audio.microphone.acquire();
+        acquired = true;
+        if (stopped || generation !== micEpoch) {
+            clearMic();
+            return;
+        }
+        stream = await platform.getUserMedia();
+        if (stopped || generation !== micEpoch) {
+            clearMic();
+            return;
+        }
+        const input = stream.getAudioTracks()[0];
+        if (!input)
+            throw new Error('Microphone is unavailable.');
+        input.enabled = !muted;
+        input.onmute = () => options.onInterruption(true);
+        input.onunmute = () => options.onInterruption(false);
+        input.onended = () => fail(new Error('Microphone ended.'));
+        return stream;
+    };
+    const attachMic = () => {
+        const generation = micEpoch;
+        return serializeMic(async () => {
+            if (stopped)
+                throw new Error('Voice is closed.');
+            if (generation !== micEpoch || stream)
+                return;
+            try {
+                const captured = await captureMic(generation);
+                if (captured) {
+                    await sender.replaceTrack(captured.getAudioTracks()[0]);
+                    if (!stopped && generation === micEpoch)
+                        await setSending(true);
+                    if (stopped || generation !== micEpoch) {
+                        if (!stopped) {
+                            await setSending(false);
+                            await sender.replaceTrack(null);
+                        }
+                        clearMic();
+                    }
+                }
+            }
+            catch (error) {
+                // Never leave a trackless native send stream recording after a failure.
+                try {
+                    if (!stopped && options.capture === 'lazy') {
+                        await setSending(false);
+                        await sender.replaceTrack(null);
+                    }
+                }
+                catch {
+                    stop();
+                }
+                clearMic();
+                throw error;
+            }
+        });
+    };
+    const releaseMic = () => {
+        micEpoch++;
+        stream?.getAudioTracks().forEach(track => { track.enabled = false; });
+        return serializeMic(async () => {
+            try {
+                if (!stopped && stream) {
+                    await setSending(false);
+                    await sender.replaceTrack(null);
+                }
+            }
+            catch (error) {
+                if (options.capture === 'lazy')
+                    stop();
+                throw error;
+            }
+            finally {
+                clearMic();
+            }
+        });
+    };
     try {
         options.onConnectionState('connecting');
         if (options.signal?.aborted)
             throw new Error('Voice is closed.');
-        await options.audio.microphone.acquire();
-        acquired = true;
-        if (stopped) {
-            options.audio.microphone.release();
-            acquired = false;
-            throw new Error('Voice is closed.');
+        if (options.capture !== 'lazy') {
+            await options.audio.microphone.acquire();
+            acquired = true;
+            if (stopped) {
+                clearMic();
+                throw new Error('Voice is closed.');
+            }
         }
         await options.audio.route();
         if (stopped) {
             await options.audio.unroute();
             throw new Error('Voice is closed.');
         }
-        stream = await platform.getUserMedia();
-        if (stopped) {
-            stream.getTracks().forEach(track => track.stop());
-            throw new Error('Voice is closed.');
+        if (options.capture !== 'lazy') {
+            stream = await platform.getUserMedia();
+            if (stopped) {
+                clearMic();
+                throw new Error('Voice is closed.');
+            }
         }
         peer = platform.createPeer();
         channel = peer.createDataChannel(options.label);
@@ -79,13 +187,21 @@ export async function webRtcPeer(options) {
             options.onConnectionState('connecting'); };
         current.ontrack = event => { const track = event.track; if (track.kind !== 'audio' || stopped)
             return; options.onRemoteAudio(!track.muted); track.onmute = () => options.onRemoteAudio(false); track.onunmute = () => options.onRemoteAudio(true); track.onended = () => options.onRemoteAudio(false); };
-        const input = stream.getAudioTracks()[0];
-        if (!input)
-            throw new Error('Microphone is unavailable.');
-        input.onmute = () => options.onInterruption(true);
-        input.onunmute = () => options.onInterruption(false);
-        input.onended = () => fail(new Error('Microphone ended.'));
-        current.addTrack(input, stream);
+        if (options.capture === 'lazy') {
+            // Android starts the device module for an active send stream even without
+            // a track. Disable the encoding before either description can be applied.
+            sender = current.addTransceiver('audio', { direction: 'sendrecv', sendEncodings: [{ active: false }] }).sender;
+            await setSending(false);
+        }
+        else {
+            const input = stream.getAudioTracks()[0];
+            if (!input)
+                throw new Error('Microphone is unavailable.');
+            input.onmute = () => options.onInterruption(true);
+            input.onunmute = () => options.onInterruption(false);
+            input.onended = () => fail(new Error('Microphone ended.'));
+            sender = current.addTrack(input, stream);
+        }
         await current.setLocalDescription(await current.createOffer());
         if (current.iceGatheringState !== 'complete')
             await new Promise((resolve, reject) => {
@@ -124,7 +240,7 @@ export async function webRtcPeer(options) {
                 flush();
                 return true;
             },
-            setMuted(muted) { stream?.getAudioTracks().forEach(track => { track.enabled = !muted; }); }, stop,
+            setMuted(value) { muted = value; stream?.getAudioTracks().forEach(track => { track.enabled = !value; }); }, attachMic, releaseMic, stop,
         };
     }
     catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/realtime",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Realtime voice sessions with host-held credentials and injected audio.",
   "license": "Apache-2.0",
   "type": "module",