openrtc-netcode 2.3.1 → 2.4.0

package/README.md

@@ -1,9 +1,9 @@
 # openrtc-netcode
 
 `openrtc-netcode` is a small multiplayer layer on top of OpenRTC. It treats
-OpenRTC rooms as lobbies, forms a deterministic P2P mesh between lobby members,
+OpenRTC rooms as lobbies, observes the runtime-owned P2P mesh between lobby members,
 and exposes reliable typed messages, lightweight replicated state, networked
-objects, and browser voice-chat signaling.
+objects, and browser voice-chat media.
 
 Gameplay payloads are sent over OpenRTC peer data paths only: Iroh
 relay/direct plus WebRTC or MoQ custom Iroh carriers when enabled. Live
@@ -27,7 +27,6 @@ const rtc = OpenRTC({
 const room = await rtc.rooms.join('duel-room', {
   access: 'capability',
   membership: 'ephemeral',
-  maxPeers: 4,
 });
 const netcode = createNetcode({ room });
 await netcode.joinLobby('duel-room');
@@ -50,8 +49,9 @@ await netcode.objects.spawn({
 });
 ```
 
-Voice chat uses OpenRTC netcode connections for SDP/ICE signaling and lets the
-browser WebRTC stack carry microphone media:
+Voice chat publishes microphone tracks through each already-established
+OpenRTC logical connection. Netcode does not create a second peer connection,
+exchange SDP/ICE, or own transport recovery:
 
 ```ts
 await netcode.voice.start();

package/dist/client.d.ts

@@ -1,3 +1,2 @@
 import type { NetcodeClient as NetcodeClientInterface, NetcodeOptions } from './types.js';
 export declare function createNetcode(options?: NetcodeOptions): NetcodeClientInterface;
-export declare function shouldInitiate(localPeerId: string, remotePeerId: string): boolean;

package/dist/client.js

@@ -10,7 +10,7 @@ const NETCODE_CHANNEL_ID = 'openrtc-netcode/v1';
 const PING_INTERVAL_MS = 2000;
 const MAX_SEEN_ENVELOPES = 2048;
 const CHANNEL_OPEN_TIMEOUT_MS = 15000;
-const UPGRADED_PAYLOAD_TRANSPORTS = new Set(['webrtc', 'webrtc-lan', 'moq']);
+const UPGRADED_PAYLOAD_TRANSPORTS = new Set(['webrtc', 'moq']);
 const textEncoder = new TextEncoder();
 const textDecoder = new TextDecoder();
 class ClientImpl {
@@ -38,7 +38,6 @@ class ClientImpl {
         this.channelsByPeer = new Map();
         this.pendingChannelsByPeer = new Map();
         this.connectionIds = new Set();
-        this.pendingPeerIds = new Set();
         this.directSendWarnings = new Set();
         this.introPeerIds = new Set();
         this.seenEnvelopeIds = new Set();
@@ -46,7 +45,9 @@ class ClientImpl {
         this.latestStateQueues = new Map();
         this.stateStore = new ReplicatedState((options) => this.resolveStateOwner(options), (key, value, owner) => this.broadcastLatestState(`state:${key}`, 'state.patch', { key, value, owner }));
         this.objectStore = new ObjectStore(() => this.localPeerId, (object) => this.broadcastLatestState(`object:${object.id}`, 'object.upsert', { object }), (id) => this.broadcastEnvelope('object.remove', { id }));
-        this.voiceController = new NetcodeVoiceController(() => this.localPeerId, () => this.peers, shouldInitiate, (peerId, signal) => this.sendEnvelope(peerId, 'voice.signal', { signal }));
+        this.voiceController = new NetcodeVoiceController(() => this.localPeerId, () => this.peers, (peerId) => this.connectionsByPeer.get(peerId)
+            ?? this.runtime?.getConnections().find((connection) => connection.remoteNodeId === peerId || connection.deviceId === peerId)
+            ?? null);
     }
     get peerId() {
         return this.localPeerId;
@@ -105,7 +106,6 @@ class ClientImpl {
         }
         this.connectionsByPeer.clear();
         this.connectionIds.clear();
-        this.pendingPeerIds.clear();
         this.directSendWarnings.clear();
         this.introPeerIds.clear();
         this.peerStatsById.clear();
@@ -127,6 +127,10 @@ class ClientImpl {
         await this.leaveLobby();
         const lobbyId = await runtime.createRoom(options.id);
         this.lobbyMetadata = { ...(options.metadata ?? {}) };
+        // Creating a lobby does not itself imply that an injected runtime has
+        // joined its membership scope. Join through the lifecycle owner before
+        // observing the room so it can establish and project peer routes.
+        await runtime.joinRoom(lobbyId, { bootstrapPeers: false });
         return this.activateLobby(lobbyId);
     }
     async joinLobby(lobbyId, options = {}) {
@@ -218,7 +222,6 @@ class ClientImpl {
         await this.closeNetcodeChannels();
         this.currentLobby = null;
         this.peersById.clear();
-        this.pendingPeerIds.clear();
         this.introPeerIds.clear();
         this.peerStatsById.clear();
         this.seenEnvelopeIds.clear();
@@ -299,7 +302,6 @@ class ClientImpl {
                 }
                 this.peersById.delete(peerId);
                 this.connectionsByPeer.delete(peerId);
-                this.pendingPeerIds.delete(peerId);
                 this.introPeerIds.delete(peerId);
                 this.peerStatsById.delete(peerId);
                 this.emitter.emit('peer:left', clonePeer(peer));
@@ -310,41 +312,12 @@ class ClientImpl {
         void this.reconcileMesh();
     }
     async reconcileMesh() {
-        if (!this.runtime || !this.localPeerId) {
-            return;
-        }
-        // An OpenRTC 2.0 room capability is the sole owner of its peer
-        // lifecycle. Calling connectByTicket here races that owner and can
-        // restart reciprocal application-key agreement on an already-admitted
-        // physical connection. Explicit legacy/test runtimes retain the
-        // deterministic mesh dial below.
-        if (this.runtime.lifecycle) {
-            return;
-        }
-        const maxPeers = this.options.maxPeers ?? DEFAULT_MAX_PEERS;
-        for (const peer of this.peersById.values()) {
-            if (this.connectionsByPeer.size >= maxPeers) {
-                return;
-            }
-            if (!peer.ticket || !shouldInitiate(this.localPeerId, peer.id)) {
-                continue;
-            }
-            if (this.connectionsByPeer.has(peer.id) || this.pendingPeerIds.has(peer.id)) {
-                continue;
-            }
-            this.pendingPeerIds.add(peer.id);
-            try {
-                const connection = await this.runtime.connectByTicket({ ticket: peer.ticket });
-                this.attachConnection(connection, peer.id);
-                await this.sendPeerIntro(peer.id, true);
-            }
-            catch (error) {
-                console.warn('[openrtc-netcode] peer dial failed; leaving peer disconnected', error);
-            }
-            finally {
-                this.pendingPeerIds.delete(peer.id);
-            }
-        }
+        // The runtime owns room membership, connection establishment,
+        // reconnection, and carrier changes. Netcode observes its projected
+        // connections through `onConnection` and readiness queries only.
+        // Keeping this boundary as an explicit no-op prevents protocol
+        // membership updates from becoming an independent dial lifecycle.
+        return;
     }
     attachConnection(connection, peerIdHint) {
         const connectionId = connection.id;
@@ -367,21 +340,22 @@ class ClientImpl {
         });
         if (payloadReady) {
             this.emitter.emit('peer:connected', clonePeer(peer));
-            void this.voiceController.handlePeerConnected(peerId);
+            this.startVoicePeer(peerId);
         }
         connection.onMessage((message) => {
             this.handleConnectionMessage(peerId, message);
         });
-        connection.onUpgradeStateChange?.(() => {
-            this.refreshPeerPayloadState(peerId);
-        });
         connection.onDisconnect(() => {
-            if (this.connectionsByPeer.get(peerId) === connection) {
+            const wasCurrentConnection = this.connectionsByPeer.get(peerId) === connection;
+            if (wasCurrentConnection) {
                 this.connectionsByPeer.delete(peerId);
             }
             if (connectionId) {
                 this.connectionIds.delete(connectionId);
             }
+            if (!wasCurrentConnection) {
+                return;
+            }
             const disconnected = this.upsertPeer(peerId, { connected: false });
             this.updatePeerStats(peerId, {
                 connected: false,
@@ -397,6 +371,14 @@ class ClientImpl {
             void this.sendEnvelope(peerId, 'ping', {});
         }
     }
+    startVoicePeer(peerId) {
+        void this.voiceController.handlePeerConnected(peerId).catch((error) => {
+            console.warn('[openrtc-netcode] media setup failed', {
+                peerId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        });
+    }
     async sendPeerIntro(peerId, force = false) {
         if (!this.localPeerId) {
             return;
@@ -477,9 +459,6 @@ class ClientImpl {
             case 'member.meta':
                 this.handleMemberMetadata(peerId, envelope.body);
                 break;
-            case 'voice.signal':
-                this.handleVoiceSignal(peerId, envelope.body);
-                break;
             case 'ping':
                 void this.sendEnvelope(peerId, 'pong', { pingSentAt: envelope.sentAt });
                 break;
@@ -603,14 +582,6 @@ class ClientImpl {
         this.upsertPeer(peerId, { metadata: metadata.values });
         this.emitter.emit('member:metadata', { peerId, values: metadata.values });
     }
-    handleVoiceSignal(peerId, body) {
-        if (!isRecord(body) || !isRecord(body.signal)) {
-            return;
-        }
-        const signal = { signal: body.signal };
-        this.emitter.emit('voice:signal', { peerId, ...signal });
-        void this.voiceController.handleSignal(peerId, signal.signal);
-    }
     handlePong(peerId, body) {
         if (!isRecord(body) || typeof body.pingSentAt !== 'number') {
             return;
@@ -656,7 +627,7 @@ class ClientImpl {
         if (payloadReady && peer && !peer.connected) {
             const connected = this.upsertPeer(peerId, { connected: true });
             this.emitter.emit('peer:connected', clonePeer(connected));
-            void this.voiceController.handlePeerConnected(peerId);
+            this.startVoicePeer(peerId);
             this.queuePeerIntro(peerId, true);
         }
         this.updatePeerStats(peerId, {
@@ -774,7 +745,6 @@ class ClientImpl {
             scope: NETCODE_CHANNEL_ID,
             channelId: NETCODE_CHANNEL_ID,
             timeoutMs: CHANNEL_OPEN_TIMEOUT_MS,
-            nativeLabel: true,
             framing: 'u32be',
         }).then((channel) => {
             this.attachNetcodeChannel(peerId, channel);
@@ -822,7 +792,7 @@ class ClientImpl {
             transport: this.resolvePeerTransport(peerId),
         });
         this.emitter.emit('peer:connected', clonePeer(peer));
-        void this.voiceController.handlePeerConnected(peerId);
+        this.startVoicePeer(peerId);
         this.queuePeerIntro(peerId, true);
     }
     registerIncomingNetcodeChannel() {
@@ -1030,9 +1000,6 @@ class ClientImpl {
 export function createNetcode(options = {}) {
     return new ClientImpl(options);
 }
-export function shouldInitiate(localPeerId, remotePeerId) {
-    return localPeerId.localeCompare(remotePeerId) < 0;
-}
 function normalizeLobbyId(lobbyId) {
     return lobbyId.trim().toUpperCase();
 }

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-export { createNetcode, shouldInitiate, } from './client.js';
+export { createNetcode, } from './client.js';
 export { runtimeFromRoom } from './roomRuntime.js';
 export { ObjectStore } from './objects.js';
 export { NETCODE_PROTOCOL, PROTOCOL_VERSION, decodeEnvelope, encodeEnvelope, isEnvelopeKind, } from './protocol.js';
-export type { HelloBody, MetadataBody, NetcodeEnvelope, NetcodeEnvelopeKind, ObjectRemoveBody, ObjectSnapshotBody, ObjectUpsertBody, StatePatchBody, StateSnapshotBody, UserMessageBody, VoiceSignalBody, } from './protocol.js';
-export type { CreateLobbyOptions, JoinLobbyOptions, NetVar, NetVarOptions, NetcodeClient, NetcodeEventHandler, NetcodeEventName, NetcodeEvents, NetcodeLobby, NetcodeMessage, MessageHandler, NetcodeObjectChange, NetcodeObjectState, NetcodeObjectStore, NetcodeObjectUpsert, NetcodeOptions, NetcodePeer, NetcodePeerStats, NetcodePhysicsState, NetcodeQuaternion, NetcodeReliability, NetcodeRuntime, NetcodeState, NetcodeTransform, NetcodeVector3, NetcodeVoice, NetcodeVoiceEvents, NetcodeVoiceOptions, NetcodeVoicePeer, NetcodeVoiceSignal, SendOptions, } from './types.js';
+export type { HelloBody, MetadataBody, NetcodeEnvelope, NetcodeEnvelopeKind, ObjectRemoveBody, ObjectSnapshotBody, ObjectUpsertBody, StatePatchBody, StateSnapshotBody, UserMessageBody, } from './protocol.js';
+export type { CreateLobbyOptions, JoinLobbyOptions, NetVar, NetVarOptions, NetcodeClient, NetcodeEventHandler, NetcodeEventName, NetcodeEvents, NetcodeLobby, NetcodeMessage, MessageHandler, NetcodeObjectChange, NetcodeObjectState, NetcodeObjectStore, NetcodeObjectUpsert, NetcodeOptions, NetcodePeer, NetcodePeerStats, NetcodePhysicsState, NetcodeQuaternion, NetcodeReliability, NetcodeRuntime, NetcodeState, NetcodeTransform, NetcodeVector3, NetcodeVoice, NetcodeVoiceEvents, NetcodeVoiceOptions, NetcodeVoicePeer, SendOptions, } from './types.js';

package/dist/index.js

@@ -1,4 +1,4 @@
-export { createNetcode, shouldInitiate, } from './client.js';
+export { createNetcode, } from './client.js';
 export { runtimeFromRoom } from './roomRuntime.js';
 export { ObjectStore } from './objects.js';
 export { NETCODE_PROTOCOL, PROTOCOL_VERSION, decodeEnvelope, encodeEnvelope, isEnvelopeKind, } from './protocol.js';

package/dist/protocol.d.ts

@@ -1,6 +1,6 @@
 export declare const NETCODE_PROTOCOL = "openrtc-netcode";
 export declare const PROTOCOL_VERSION = 1;
-export type NetcodeEnvelopeKind = 'hello' | 'peer' | 'user' | 'state.snapshot' | 'state.patch' | 'object.snapshot' | 'object.upsert' | 'object.remove' | 'lobby.meta' | 'member.meta' | 'voice.signal' | 'ping' | 'pong';
+export type NetcodeEnvelopeKind = 'hello' | 'peer' | 'user' | 'state.snapshot' | 'state.patch' | 'object.snapshot' | 'object.upsert' | 'object.remove' | 'lobby.meta' | 'member.meta' | 'ping' | 'pong';
 export interface NetcodeEnvelope<TBody = unknown> {
     protocol: typeof NETCODE_PROTOCOL;
     v: typeof PROTOCOL_VERSION;
@@ -41,9 +41,6 @@ export interface ObjectRemoveBody {
 export interface MetadataBody {
     values: Record<string, string>;
 }
-export interface VoiceSignalBody {
-    signal: unknown;
-}
 export declare function encodeEnvelope(envelope: NetcodeEnvelope): string;
 export declare function decodeEnvelope(value: unknown): NetcodeEnvelope | null;
 export declare function isEnvelopeKind(value: unknown): value is NetcodeEnvelopeKind;

package/dist/protocol.js

@@ -36,7 +36,6 @@ export function isEnvelopeKind(value) {
         || value === 'object.remove'
         || value === 'lobby.meta'
         || value === 'member.meta'
-        || value === 'voice.signal'
         || value === 'ping'
         || value === 'pong';
 }

package/dist/roomRuntime.js

@@ -21,13 +21,77 @@ function peerMember(peer) {
  * contract. It never creates a second room, user scope, or base space.
  */
 export function runtimeFromRoom(room) {
-    const connections = () => room.diagnostics.connections();
+    // Diagnostics expose raw core connections; only the avenue's public
+    // onConnection projection owns the stable media-enabled logical view.
+    const adaptedByPeer = new Map();
+    const listeners = new Set();
+    let stopConnectionObservation = null;
+    const rawConnections = () => room.diagnostics.connections();
+    const peerIdFor = (connection) => connection.peerId ?? connection.remoteNodeId ?? connection.deviceId ?? connection.id ?? '';
+    const rawForPeer = (peerId) => rawConnections().find((connection) => peerIdFor(connection) === peerId);
+    const readyPeerIds = (options = {}) => new Set(room.diagnostics.applicationReadyConnections(options).map(peerIdFor));
+    const adaptConnection = (connection) => {
+        const peerId = peerIdFor(connection);
+        let closed = false;
+        let adapted;
+        const removeFromProjection = () => {
+            closed = true;
+            if (adaptedByPeer.get(peerId) === adapted)
+                adaptedByPeer.delete(peerId);
+        };
+        adapted = {
+            id: connection.id,
+            deviceId: peerId,
+            remoteNodeId: peerId,
+            get isClosed() { return closed; },
+            media: connection.media,
+            getTransportStatus: () => rawForPeer(peerId)?.getTransportStatus?.() ?? {
+                activeTransport: 'unknown',
+                parallelTransport: null,
+            },
+            getAvailableTransports: () => rawForPeer(peerId)?.getAvailableTransports?.() ?? [],
+            isPayloadReady: (options = {}) => !closed && readyPeerIds(options).has(peerId),
+            send: (message) => connection.send(message),
+            onMessage: (callback) => connection.onMessage(callback),
+            onDisconnect: (callback) => connection.onClose(() => {
+                closed = true;
+                callback();
+            }),
+        };
+        connection.onClose(removeFromProjection);
+        return adapted;
+    };
+    const publish = (connection) => {
+        const peerId = peerIdFor(connection);
+        if (!peerId || adaptedByPeer.has(peerId))
+            return;
+        const adapted = adaptConnection(connection);
+        if (adapted.isClosed)
+            return;
+        adaptedByPeer.set(peerId, adapted);
+        for (const listener of listeners)
+            listener(adapted);
+    };
+    const ensureConnectionObservation = () => {
+        if (stopConnectionObservation)
+            return;
+        stopConnectionObservation = room.onConnection(publish);
+    };
+    const connections = () => {
+        ensureConnectionObservation();
+        return [...adaptedByPeer.values()];
+    };
     return {
         lifecycle: true,
         channels: room.channels,
         initialize: async () => undefined,
         start: async () => undefined,
-        stop: async () => undefined,
+        stop: async () => {
+            stopConnectionObservation?.();
+            stopConnectionObservation = null;
+            listeners.clear();
+            adaptedByPeer.clear();
+        },
         getNodeId: async () => {
             const status = await room.diagnostics.status();
             const nodeId = typeof status.localNodeId === 'string' ? status.localNodeId.trim() : '';
@@ -57,21 +121,11 @@ export function runtimeFromRoom(room) {
                 .map((peer) => peerMember(peer));
         },
         onConnection: (callback) => {
-            const seen = new Set();
-            const publish = (connection) => {
-                const id = String(connection.id ?? connection.remoteNodeId ?? '');
-                if (!id || seen.has(id))
-                    return;
-                seen.add(id);
-                callback(connection);
-            };
-            connections().forEach(publish);
-            return room.diagnostics.onConnection((connection) => {
-                publish(connection);
-            });
+            listeners.add(callback);
+            ensureConnectionObservation();
+            return () => listeners.delete(callback);
         },
         getConnections: connections,
-        connectByTicket: ({ ticket, timeoutMs }) => room.peers.connect({ ticket, timeoutMs }),
         // The room capability already authorized the peer route. A protocol
         // channel is not another admission avenue and must not replace that
         // lifecycle scope with the channel identifier (which would trigger a
@@ -82,7 +136,9 @@ export function runtimeFromRoom(room) {
             existingRouteOnly: true,
         }),
         onChannelStream: (channelId, callback) => room.channels.onIncomingChannel(channelId, callback),
-        readyConnections: () => connections().filter((connection) => typeof connection.isPayloadReady !== 'function'
-            || connection.isPayloadReady()),
+        readyConnections: (options = {}) => {
+            const ready = readyPeerIds(options);
+            return connections().filter((connection) => ready.has(connection.remoteNodeId ?? ''));
+        },
     };
 }

package/dist/types.d.ts

@@ -1,13 +1,18 @@
 import type { ReadinessOptions as OpenRtcApplicationPayloadReadinessOptions, IncomingStream, ScopedChannelOptions, ScopedLogicalChannel } from 'openrtc/runtime';
 import type { Room } from 'openrtc';
-import type { MetadataBody, NetcodeEnvelope, ObjectRemoveBody, ObjectSnapshotBody, ObjectUpsertBody, StatePatchBody, StateSnapshotBody, UserMessageBody, VoiceSignalBody } from './protocol.js';
+import type { MetadataBody, NetcodeEnvelope, ObjectRemoveBody, ObjectSnapshotBody, ObjectUpsertBody, StatePatchBody, StateSnapshotBody, UserMessageBody } from './protocol.js';
 export interface NetcodeRuntime {
     /**
      * The activated capability owns discovery and physical peer lifecycle.
      * Protocol layers must observe its connections instead of issuing a
      * second ticket dial for the same avenue.
      */
-    lifecycle?: boolean;
+    /**
+     * Marks the adapter as the authoritative owner of room membership and
+     * physical peer lifecycle. This is deliberately required: netcode only
+     * observes ready routes and must never create a parallel dial/retry loop.
+     */
+    readonly lifecycle: true;
     initialize?(): Promise<void> | void;
     start?(): Promise<void> | void;
     stop?(): Promise<void> | void;
@@ -21,10 +26,6 @@ export interface NetcodeRuntime {
     getRoomMembers(roomId: string): Promise<RuntimeMemberLike[]>;
     onConnection(callback: (connection: RuntimeConnectionLike) => void): () => void;
     getConnections(): RuntimeConnectionLike[];
-    connectByTicket(target: {
-        ticket: string;
-        timeoutMs?: number;
-    }): Promise<RuntimeConnectionLike>;
     connectScopedChannel(options: ScopedChannelOptions): Promise<ScopedLogicalChannel>;
     onChannelStream(channelId: string, callback: (stream: IncomingStream) => boolean | void): () => void;
     readyConnections(options?: ReadinessOptions): RuntimeConnectionLike[];
@@ -37,7 +38,6 @@ export interface NetcodeOptions {
     room?: Room;
     preferredTransports?: ReadinessOptions['preferredTransports'];
     displayName?: string;
-    maxPeers?: number;
     localFallback?: boolean;
 }
 export interface CreateLobbyOptions {
@@ -147,23 +147,16 @@ export interface NetcodeObjectStore {
     remove(id: string): Promise<void>;
     onChange(listener: (change: NetcodeObjectChange) => void): () => void;
 }
-export interface NetcodeVoiceSignal {
-    description?: RTCSessionDescriptionInit;
-    candidate?: RTCIceCandidateInit;
-}
 export interface NetcodeVoiceOptions {
     mediaStream?: MediaStream;
     mediaDevices?: Pick<MediaDevices, 'getUserMedia'>;
     audio?: boolean | MediaTrackConstraints;
-    rtcConfig?: RTCConfiguration;
-    createPeerConnection?: (config?: RTCConfiguration) => RTCPeerConnection;
     stopTracksOnStop?: boolean;
 }
 export interface NetcodeVoicePeer {
     peerId: string;
     stream: MediaStream | null;
-    connectionState: RTCPeerConnectionState;
-    iceConnectionState: RTCIceConnectionState;
+    connected: boolean;
 }
 export interface NetcodeVoiceEvents {
     'local:stream': MediaStream;
@@ -205,9 +198,6 @@ export interface NetcodeEvents {
     'member:metadata': MetadataBody & {
         peerId: string;
     };
-    'voice:signal': VoiceSignalBody & {
-        peerId: string;
-    };
 }
 export type NetcodeEventName = keyof NetcodeEvents;
 export type NetcodeEventHandler<K extends NetcodeEventName> = (payload: NetcodeEvents[K]) => void;
@@ -251,13 +241,29 @@ export type RuntimeConnectionLike = {
     };
     getAvailableTransports?(): string[];
     isPayloadReady?(options?: ReadinessOptions): boolean;
-    onUpgradeStateChange?(callback: (state: 'none' | 'upgrading' | 'upgraded' | 'failed') => void): void;
-    requestWebRTCUpgrade?(reason?: string): void;
+    media: RuntimeMediaConnectionLike;
     send(message: unknown): Promise<void> | void;
     onMessage(callback: (message: unknown) => void): void | (() => void);
     onDisconnect(callback: () => void): void | (() => void);
     disconnect?(): Promise<void> | void;
 };
+export type RuntimeMediaSenderLike = {
+    readonly id: string;
+    stop(): Promise<void> | void;
+};
+export type RuntimeMediaTrackEventLike = {
+    readonly track: MediaStreamTrack;
+    readonly streams: readonly MediaStream[];
+};
+export type RuntimeMediaConnectionLike = {
+    addTrack(track: MediaStreamTrack, options?: {
+        streams?: readonly MediaStream[];
+        codec?: string;
+        bitrate?: number;
+    }): Promise<RuntimeMediaSenderLike>;
+    removeTrack(sender: RuntimeMediaSenderLike): Promise<void>;
+    onTrack(callback: (event: RuntimeMediaTrackEventLike) => void): () => void;
+};
 export type ReadinessOptions = OpenRtcApplicationPayloadReadinessOptions;
 export type RuntimeMemberLike = {
     nodeId?: string;
@@ -268,4 +274,4 @@ export type RuntimeMemberLike = {
     expiresAt?: number;
     metadata?: string | Record<string, unknown> | null;
 };
-export type RuntimeEnvelopeBody = UserMessageBody | StateSnapshotBody | StatePatchBody | ObjectSnapshotBody | ObjectUpsertBody | ObjectRemoveBody | MetadataBody | VoiceSignalBody | Record<string, unknown>;
+export type RuntimeEnvelopeBody = UserMessageBody | StateSnapshotBody | StatePatchBody | ObjectSnapshotBody | ObjectUpsertBody | ObjectRemoveBody | MetadataBody | Record<string, unknown>;

package/dist/voice.d.ts

@@ -1,17 +1,17 @@
-import type { NetcodePeer, NetcodeVoice, NetcodeVoiceEvents, NetcodeVoiceOptions, NetcodeVoicePeer, NetcodeVoiceSignal } from './types.js';
+import type { NetcodePeer, NetcodeVoice, NetcodeVoiceEvents, NetcodeVoiceOptions, NetcodeVoicePeer, RuntimeConnectionLike } from './types.js';
+/** Voice is a media facade over the already-established logical peer route. */
 export declare class NetcodeVoiceController implements NetcodeVoice {
     private readonly localPeerId;
     private readonly peers;
-    private readonly shouldOffer;
-    private readonly sendSignal;
+    private readonly connectionForPeer;
     private readonly emitter;
     private readonly sessions;
-    private readonly pendingSignals;
+    private readonly closingSessions;
     private localMediaStream;
     private options;
     private active;
     private muted;
-    constructor(localPeerId: () => string | null, peers: () => NetcodePeer[], shouldOffer: (localPeerId: string, remotePeerId: string) => boolean, sendSignal: (peerId: string, signal: NetcodeVoiceSignal) => Promise<void>);
+    constructor(localPeerId: () => string | null, peers: () => NetcodePeer[], connectionForPeer: (peerId: string) => RuntimeConnectionLike | null);
     get enabled(): boolean;
     get localStream(): MediaStream | null;
     get isMuted(): boolean;
@@ -22,14 +22,9 @@ export declare class NetcodeVoiceController implements NetcodeVoice {
     on<K extends keyof NetcodeVoiceEvents>(event: K, handler: (payload: NetcodeVoiceEvents[K]) => void): () => void;
     handlePeerConnected(peerId: string): Promise<void>;
     handlePeerDisconnected(peerId: string): void;
-    handleSignal(peerId: string, signal: NetcodeVoiceSignal): Promise<void>;
-    private createAndSendOffer;
     private startPeerSession;
-    private flushPendingSignals;
-    private applySignal;
-    private flushPendingCandidates;
-    private ensureSession;
-    private createPeerConnection;
+    private closePeerSession;
+    private trackClosing;
     private captureAudio;
     private applyMuteState;
 }

package/dist/voice.js

@@ -1,13 +1,13 @@
 import { TypedEmitter } from './events.js';
+/** Voice is a media facade over the already-established logical peer route. */
 export class NetcodeVoiceController {
-    constructor(localPeerId, peers, shouldOffer, sendSignal) {
+    constructor(localPeerId, peers, connectionForPeer) {
         this.localPeerId = localPeerId;
         this.peers = peers;
-        this.shouldOffer = shouldOffer;
-        this.sendSignal = sendSignal;
+        this.connectionForPeer = connectionForPeer;
         this.emitter = new TypedEmitter();
         this.sessions = new Map();
-        this.pendingSignals = new Map();
+        this.closingSessions = new Set();
         this.localMediaStream = null;
         this.options = {};
         this.active = false;
@@ -26,38 +26,42 @@ export class NetcodeVoiceController {
         return Array.from(this.sessions.values()).map((session) => ({
             peerId: session.peerId,
             stream: session.remoteStream,
-            connectionState: session.connection.connectionState,
-            iceConnectionState: session.connection.iceConnectionState,
+            connected: session.connection.isClosed !== true,
         }));
     }
     async start(options = {}) {
-        if (this.active && this.localMediaStream) {
+        if (this.active && this.localMediaStream)
             return this.localMediaStream;
-        }
         this.options = options;
-        this.localMediaStream = options.mediaStream ?? await this.captureAudio(options);
+        const localStream = options.mediaStream ?? await this.captureAudio(options);
+        this.localMediaStream = localStream;
         this.active = true;
         this.applyMuteState();
-        this.emitter.emit('local:stream', this.localMediaStream);
+        this.emitter.emit('local:stream', localStream);
         const localPeerId = this.localPeerId();
         if (localPeerId) {
-            for (const peer of this.peers().filter((candidate) => candidate.connected)) {
-                void this.startPeerSession(peer.id, localPeerId);
+            try {
+                await Promise.all(this.peers()
+                    .filter((peer) => peer.connected)
+                    .map((peer) => this.startPeerSession(peer.id)));
+            }
+            catch (error) {
+                await this.stop();
+                throw error;
             }
         }
-        return this.localMediaStream;
+        if (!this.active || this.localMediaStream !== localStream) {
+            throw new Error('Voice start was superseded by stop.');
+        }
+        return localStream;
     }
     async stop() {
         this.active = false;
-        for (const session of this.sessions.values()) {
-            session.connection.close();
-        }
-        this.sessions.clear();
-        this.pendingSignals.clear();
+        const current = [...this.sessions.keys()].map((peerId) => this.closePeerSession(peerId));
+        await Promise.allSettled([...current, ...this.closingSessions]);
         if (this.options.stopTracksOnStop !== false) {
-            for (const track of this.localMediaStream?.getTracks() ?? []) {
+            for (const track of this.localMediaStream?.getTracks() ?? [])
                 track.stop();
-            }
         }
         this.localMediaStream = null;
         this.emitter.emit('peers', []);
@@ -71,139 +75,74 @@ export class NetcodeVoiceController {
         return this.emitter.on(event, handler);
     }
     async handlePeerConnected(peerId) {
-        if (!this.active) {
-            return;
-        }
-        const localPeerId = this.localPeerId();
-        if (!localPeerId) {
-            return;
-        }
-        await this.startPeerSession(peerId, localPeerId);
+        if (this.active)
+            await this.startPeerSession(peerId);
     }
     handlePeerDisconnected(peerId) {
-        const session = this.sessions.get(peerId);
-        if (!session) {
-            return;
-        }
-        session.connection.close();
-        this.sessions.delete(peerId);
-        this.emitter.emit('peer:left', { peerId });
-        this.emitter.emit('peers', this.listPeers());
-    }
-    async handleSignal(peerId, signal) {
-        if (!this.active) {
-            const pending = this.pendingSignals.get(peerId) ?? [];
-            pending.push(signal);
-            this.pendingSignals.set(peerId, pending);
-            return;
-        }
-        const session = this.ensureSession(peerId);
-        await this.applySignal(session, signal);
-    }
-    async createAndSendOffer(session) {
-        const offer = await session.connection.createOffer();
-        await session.connection.setLocalDescription(offer);
-        if (session.connection.localDescription) {
-            await this.sendSignal(session.peerId, { description: session.connection.localDescription.toJSON() });
-        }
-    }
-    async startPeerSession(peerId, localPeerId) {
-        try {
-            const session = this.ensureSession(peerId);
-            await this.flushPendingSignals(peerId);
-            if (this.shouldOffer(localPeerId, peerId)) {
-                await this.createAndSendOffer(session);
-            }
-        }
-        catch (error) {
-            console.warn('[openrtc-netcode] voice peer setup failed', error);
-        }
-    }
-    async flushPendingSignals(peerId) {
-        const pending = this.pendingSignals.get(peerId);
-        if (!pending?.length) {
-            return;
-        }
-        this.pendingSignals.delete(peerId);
-        const session = this.ensureSession(peerId);
-        for (const signal of pending) {
-            await this.applySignal(session, signal);
-        }
-    }
-    async applySignal(session, signal) {
-        if (signal.description) {
-            await session.connection.setRemoteDescription(signal.description);
-            await this.flushPendingCandidates(session);
-            if (signal.description.type === 'offer') {
-                const answer = await session.connection.createAnswer();
-                await session.connection.setLocalDescription(answer);
-                if (session.connection.localDescription) {
-                    await this.sendSignal(session.peerId, { description: session.connection.localDescription.toJSON() });
-                }
-            }
-        }
-        if (signal.candidate) {
-            if (!session.connection.remoteDescription) {
-                session.pendingCandidates.push(signal.candidate);
-                return;
-            }
-            await session.connection.addIceCandidate(signal.candidate);
-        }
+        this.trackClosing(this.closePeerSession(peerId));
     }
-    async flushPendingCandidates(session) {
-        if (!session.connection.remoteDescription || !session.pendingCandidates.length) {
+    async startPeerSession(peerId) {
+        const connection = this.connectionForPeer(peerId);
+        const localStream = this.localMediaStream;
+        if (!connection || !localStream)
             return;
-        }
-        const pending = session.pendingCandidates.splice(0);
-        for (const candidate of pending) {
-            await session.connection.addIceCandidate(candidate);
-        }
-    }
-    ensureSession(peerId) {
         const existing = this.sessions.get(peerId);
-        if (existing) {
-            return existing;
-        }
-        const connection = this.createPeerConnection();
+        if (existing?.connection === connection)
+            return;
+        if (existing)
+            await this.closePeerSession(peerId, false);
         const session = {
             peerId,
             connection,
+            senders: [],
             remoteStream: null,
-            pendingCandidates: [],
+            stopListening: () => undefined,
         };
-        const localStream = this.localMediaStream;
-        if (localStream) {
-            for (const track of localStream.getAudioTracks()) {
-                connection.addTrack(track, localStream);
-            }
-        }
-        connection.onicecandidate = (event) => {
-            if (event.candidate) {
-                void this.sendSignal(peerId, { candidate: event.candidate.toJSON() });
-            }
-        };
-        connection.ontrack = (event) => {
+        session.stopListening = connection.media.onTrack((event) => {
             session.remoteStream = event.streams[0] ?? null;
             if (session.remoteStream) {
                 this.emitter.emit('peer:stream', { peerId, stream: session.remoteStream });
             }
             this.emitter.emit('peers', this.listPeers());
-        };
-        connection.onconnectionstatechange = () => {
-            this.emitter.emit('peers', this.listPeers());
-        };
+        });
         this.sessions.set(peerId, session);
         this.emitter.emit('peers', this.listPeers());
-        return session;
-    }
-    createPeerConnection() {
-        if (this.options.createPeerConnection) {
-            return this.options.createPeerConnection(this.options.rtcConfig);
+        try {
+            await Promise.resolve();
+            for (const track of localStream.getAudioTracks()) {
+                const sender = await connection.media.addTrack(track, { streams: [localStream] });
+                if (this.sessions.get(peerId) !== session || !this.active || connection.isClosed === true) {
+                    await connection.media.removeTrack(sender);
+                    return;
+                }
+                session.senders.push(sender);
+            }
         }
-        if (typeof RTCPeerConnection === 'undefined') {
-            throw new Error('Voice chat requires RTCPeerConnection support in this environment.');
+        catch (error) {
+            if (this.sessions.get(peerId) === session) {
+                await this.closePeerSession(peerId, false);
+            }
+            else {
+                await Promise.allSettled(session.senders.map((sender) => connection.media.removeTrack(sender)));
+            }
+            throw error;
         }
-        return new RTCPeerConnection(this.options.rtcConfig);
+    }
+    async closePeerSession(peerId, emit = true) {
+        const session = this.sessions.get(peerId);
+        if (!session)
+            return;
+        this.sessions.delete(peerId);
+        session.stopListening();
+        await Promise.allSettled(session.senders.map((sender) => session.connection.media.removeTrack(sender)));
+        if (emit) {
+            this.emitter.emit('peer:left', { peerId });
+            this.emitter.emit('peers', this.listPeers());
+        }
+    }
+    trackClosing(operation) {
+        this.closingSessions.add(operation);
+        void operation.then(() => this.closingSessions.delete(operation), () => this.closingSessions.delete(operation));
     }
     async captureAudio(options) {
         const mediaDevices = options.mediaDevices ?? globalThis.navigator?.mediaDevices;
@@ -220,8 +159,7 @@ export class NetcodeVoiceController {
         });
     }
     applyMuteState() {
-        for (const track of this.localMediaStream?.getAudioTracks() ?? []) {
+        for (const track of this.localMediaStream?.getAudioTracks() ?? [])
             track.enabled = !this.muted;
-        }
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openrtc-netcode",
-  "version": "2.3.1",
+  "version": "2.4.0",
   "private": false,
   "type": "module",
   "sideEffects": false,
@@ -42,7 +42,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "openrtc": "^2.3.1"
+    "openrtc": "^2.4.0"
   },
   "devDependencies": {
     "@types/node": "^24.10.1",