Class RemotePeer

Represents a remote peer connection. Do not create RemotePeer instances manually.

Index

Accessors

channels connection id metadata room state streams

Methods

close dispose emit off on open send share toJSON unshare

Accessors

channels

get channels(): Map<string, RTCDataChannel>
Negotiated data channels keyed by channel label.

Returns Map<string, RTCDataChannel>
- Defined in src/remote.ts:57

connection

get connection(): RTCPeerConnection
Native WebRTC peer connection to the remote peer.

Returns RTCPeerConnection
- Defined in src/remote.ts:49

id

get id(): string
Remote peer identifier.

Returns string
- Defined in src/remote.ts:33

metadata

get metadata(): unknown
Metadata advertised by the remote peer.

Returns unknown
- Defined in src/remote.ts:41

room

get room(): string
Room name the peer is associated with.

Returns string
- Defined in src/remote.ts:37

state

get state(): PeerConnectionState
Peer connection state, updated on connection state changes.

Returns PeerConnectionState
- Defined in src/remote.ts:45

streams

get streams(): Map<string, MediaStream>
Remote media streams keyed by stream label.

Returns Map<string, MediaStream>
- Defined in src/remote.ts:53

Methods

close

close(options: string | { label: string }): Promise<void>
Closes a previously opened data channel to the current remote peer.
Parameters
- options: string | { label: string }
  Channel label or object containing label.
Returns Promise<void>
Example
```
// close the channel with label "chat"
await remote.close({ label: "chat" });
```
- Defined in src/remote.ts:487

dispose

dispose(): void
Closes and frees all connection resources.

Returns void
- Defined in src/remote.ts:289

emit

emit<K extends keyof RemotePeerEvents>(
event: K | K[],
...args: RemotePeerEvents[K],
): void
Emits an event with optional payload to the registered event handlers.
Type Parameters
- K extends keyof RemotePeerEvents
Parameters
- event: K | K[]
  Event type to emit.
- ...args: RemotePeerEvents[K]
  Optional arguments to pass to the event handlers.
Returns void
- Defined in src/remote.ts:279

off

off<K extends keyof RemotePeerEvents>(
event: K | K[],
handler: (...args: RemotePeerEvents[K]) => void,
): void
Unregisters an event handler for a specific event type emitted by the remote peer connection.
Type Parameters
- K extends keyof RemotePeerEvents
Parameters
- event: K | K[]
  Event type to stop listening for.
- handler: (...args: RemotePeerEvents[K]) => void
  Callback function to remove from the event listeners.
Returns void
- Defined in src/remote.ts:266

on

on<K extends keyof RemotePeerEvents>(
event: K | K[],
handler: (...args: RemotePeerEvents[K]) => void,
): void
Registers an event handler for a specific event type emitted by the remote peer connection.
Type Parameters
- K extends keyof RemotePeerEvents
Parameters
- event: K | K[]
- handler: (...args: RemotePeerEvents[K]) => void
Returns void
Example
```
// subscribe to the "connection" event
peer.on("connection", (e) => {
  console.log("Connection state is changed:", e.state);
});
```
@param event Event type to listen for. @param handler Callback function to handle the event.
- Defined in src/remote.ts:253

open

open(options: string | ChannelOptions): Promise<void>
Opens a data channel to the current remote peer.

If a channel with the same label already exists, it will be reused.

You can open a channel with the same label on both local and remote peers or only on one side. In any case, only one channel will be created for each label. You can send data through the channel in both directions.
Parameters
- options: string | ChannelOptions
  Channel options or channel label.
Returns Promise<void>
Example
```
// open a channel with label "chat"
await remote.open({ label: "chat" });
```
- Defined in src/remote.ts:463

send

send(
message: unknown,
options?: string | SendOptions,
): ReadableStream<TransferProgress> & Promise<void>

Sends a message through a data channel.

If options is a string, it is treated as the channel label. If no label is provided, it uses the default channel.

The send method works only with open channels that have no protocol specified, are ordered (reliable), and match the specified label.

Parameters

message: unknown
Message payload to send.
Optionaloptions: string | SendOptions
Send options or channel label.

Returns ReadableStream<TransferProgress> & Promise<void>

A ReadableStream of transfer progress status or a Promise.

Example

// send a message to default channel
await remote.send("Hello, peer!");
// send large data with a progress handler
const file = new File([new Uint8Array(1024 * 1024)], "example.dat");
const transfer = remote.send(file, {
  label: "chat", // channel label
  info: { filename: file.name }, // metadata
  signal: AbortSignal.timeout(10000), // abort signal
});
// optionally handle the progress
for await (const progress of transfer) {
  const { id, label, current, total } = progress;
  const percent = Math.round((current / total) * 100);
  console.log(`[${id}:${label}] Sending... ${percent}%`);
}

share(options: MediaStream | StreamOptions): Promise<void | MediaStream>
Shares a new media stream to the current remote peer or updates an existing one.

If you pass a MediaStream instance directly, it will be shared under a label equal to the stream id. Otherwise, you can specify an explicit label in the options object. If a stream with the same label already exists, it will be updated and its tracks will be added/removed as needed to minimize renegotiations.

If the stream is shared with the managed option, its tracks will be automatically stopped when the stream is unshared or replaced with a new stream.
Parameters
- options: MediaStream | StreamOptions
  Stream descriptor or MediaStream instance.
Returns Promise<void | MediaStream>
The shared MediaStream instance if successful, or undefined.
Example
```
// get a media stream from the user's camera and microphone
const stream = await navigator.mediaDevices.getUserMedia({ video: true, audio: true });

// share a media stream with an explicit label
const sharedStream = await remote.share({ label: "camera", stream, managed: true });
```
- Defined in src/remote.ts:339

toJSON

toJSON(): {
    channels: string[];
    id: string;
    metadata: unknown;
    room: string;
    state: PeerConnectionState;
    streams: string[];
}
Serializes the remote peer to a JSON-compatible object.

Returns {
    channels: string[];
    id: string;
    metadata: unknown;
    room: string;
    state: PeerConnectionState;
    streams: string[];
}
A serializable representation of the peer.
- Defined in src/remote.ts:624

unshare

unshare(
options: string | MediaStream | { label?: string },
): Promise<void | MediaStream>
Stops sharing a previously shared media stream to the current remote peer.

If you pass a MediaStream instance directly, it will be unshared using its id as the label. Otherwise, you can specify the label in the options object or pass it directly as a string.

If the stream was shared with the managed option, its tracks will be stopped automatically.
Parameters
- options: string | MediaStream | { label?: string }
  A stream label, MediaStream instance, or an object containing a label.
Returns Promise<void | MediaStream>
The unshared MediaStream instance, or undefined.
Example
```
// unshare a media stream with an explicit label
await remote.unshare({ label: "camera" });
```
- Defined in src/remote.ts:413

Class RemotePeer

Index

Accessors

Methods

Accessors

channels

Returns Map<string, RTCDataChannel>

connection

Returns RTCPeerConnection

id

Returns string

metadata

Returns unknown

room

Returns string

state

Returns PeerConnectionState

streams

Returns Map<string, MediaStream>

Methods

close

Parameters

Returns Promise<void>

Example

dispose

Returns void

emit

Type Parameters

Parameters

Returns void

off

Type Parameters

Parameters

Returns void

on

Type Parameters

Parameters

Returns void

Example

open

Parameters

Returns Promise<void>

Example

send

Parameters

Returns ReadableStream<TransferProgress> & Promise<void>

Example

share

Parameters

Returns Promise<void | MediaStream>

Example

toJSON

Returns { channels: string[]; id: string; metadata: unknown; room: string; state: PeerConnectionState; streams: string[];}

unshare

Parameters

Returns Promise<void | MediaStream>

Example

Settings

On This Page

Returns {
channels: string[];
id: string;
metadata: unknown;
room: string;
state: PeerConnectionState;
streams: string[];
}