Creates a new Room instance.
Optionaloptions: RoomOptions<M>
Room configuration options.
// create a new room with default options
const room = new Room();
In TypeScript, pass the metadata type to type join(), me, verify,
and the metadata of peers in peers and events:
const room = new Room<{ name: string }>({ id: "my-room" });
room.on("connection:connected", (e) => console.log(e.peer.metadata?.name));
Indicates whether the room is currently active (joined).
Attachable extensions.
Unique room identifier.
Attaches an addon/extension to the Room instance. Attaching an addon that is already attached does nothing.
Addon instance to attach.
Detaches a previously attached addon/extension from the Room instance. Detaching an addon that is not attached does nothing.
Addon instance to detach.
Joins a room and starts listening for incoming connections.
If the room is already joined or joining, this method resolves with the existing local peer, and the given metadata is ignored. If the room is leaving, it joins again once the leave completes.
Optionalmetadata: M
Metadata to associate with the peer.
The local peer with its id and optional metadata.
Removes a previously registered event listener.
Event name.
Optionalhandler: (...args: RoomEvents<M>[K]) => void
Event handler to remove. If omitted, all handlers for the event will be removed.
Subscribes to a room event.
Event name.
Event handler.
Optionaloptions: ListenerOptions
Listener options, such as an AbortSignal that removes the handler.
A function that removes the handler.
Subscribes to an event and auto-unsubscribes after first invocation.
Event name.
Event handler.
Optionaloptions: ListenerOptions
Listener options, such as an AbortSignal that removes the handler.
A function that removes the handler.
Opens a data channel with the given label and options to all peers. 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.
It resolves once the channel is requested, not once it is open, so wait
for channel:open before sending through it.
Channel options or channel label.
Sends a message through data channels to all connected peers.
If options is a string, it is treated as the channel label. If a label
is not provided, it uses the default channel.
The send method works only with open channels that match the specified
label and are either ordered (reliable) without a protocol, or have a
protocol, which makes them raw. A raw channel accepts only strings and
binary data, and an unreliable one drops a message while its buffer is
backed up.
Without to, the message is sent to every peer whose channel is open,
and peers that are still connecting are skipped. With to, every target
must have an open channel, otherwise the send fails before anything is
sent. Failures are PeerixError instances with the
DATACHANNEL_ERROR code. A peer that fails mid-transfer doesn't stop the
others, and the send rejects with its failure once every transfer ends. A
transfer to a peer fails once the channel buffer stops draining for 10
seconds.
A ReadableStream sent to several peers is read as fast as the fastest
peer takes it, and its chunks are buffered for the slower ones.
Message payload to send.
Optionaloptions: string | SendOptions
Send options or channel label.
An iterable aggregated transfer progress across all connections or a promise which resolves when all transfers complete or error.
// send a message to default channel
await room.send("Hello, all peers!");
// send a message to specific peers only
await room.send("Hello, Bob!", { label: "chat", to: bobId });
// send large data with a progress handler
const file = new File([new Uint8Array(1024 * 1024)], "example.dat");
const transfer = room.send(file, {
label: "chat", // channel label
info: { filename: file.name }, // sent with the first chunk
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}%`);
}
Shares a new media stream or updates an existing one for all peers including new ones that join later.
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.
Stream descriptor or MediaStream instance.
Stops sharing a previously shared media stream with the given label and removes it from all peers.
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.
A stream label, MediaStream instance, or an object containing a label.
Manages WebRTC peer connections, media streams, and data channels.