@lakutata/webrtc 0.0.0-stage → 3.1.4

package/dist/esm/peer/RtpPacket.js

@@ -0,0 +1,86 @@
+import { RtpHeader, RtpPacket as EngineRtpPacket } from '../lib/rtp/rtp/rtp.js';
+/**
+ * An RTP packet: a piece of encoded audio or video, with the fields of its header the applications use. The packets of
+ * a received {@link MediaTrack} come as these (its `rtp` event); a track to send takes these or the bytes of RTP
+ * packets (`writeRtp()`), such as the ones an encoder like ffmpeg or GStreamer sends to a UDP port.
+ * @example
+ * ```typescript
+ * import {RtpPacket} from '@lakutata/webrtc'
+ *
+ * declare const datagram: Buffer
+ * //A packet read from the bytes an encoder sent
+ * const packet: RtpPacket = RtpPacket.parse(datagram)
+ * console.log(packet.payloadType, packet.sequenceNumber, packet.marker)
+ * ```
+ */
+export class RtpPacket {
+    /**
+     * Create a packet.
+     * @param init The fields of the packet.
+     */
+    constructor(init) {
+        this.payloadType = init.payloadType;
+        this.sequenceNumber = init.sequenceNumber;
+        this.timestamp = init.timestamp;
+        this.ssrc = init.ssrc ?? 0;
+        this.marker = init.marker ?? false;
+        this.payload = Buffer.isBuffer(init.payload) ? init.payload : Buffer.from(init.payload.buffer, init.payload.byteOffset, init.payload.byteLength);
+    }
+    /**
+     * Read a packet from its bytes (its header extensions and contributing sources are left out).
+     * @param data The bytes of an RTP packet.
+     * @returns The packet.
+     * @example
+     * ```typescript
+     * import {RtpPacket} from '@lakutata/webrtc'
+     *
+     * declare const datagram: Buffer
+     * const packet: RtpPacket = RtpPacket.parse(datagram)
+     * ```
+     */
+    static parse(data) {
+        return rtpPacketOf(EngineRtpPacket.deSerialize(Buffer.isBuffer(data) ? data : Buffer.from(data.buffer, data.byteOffset, data.byteLength)));
+    }
+    /**
+     * The bytes of the packet.
+     * @returns The bytes.
+     * @example
+     * ```typescript
+     * import {RtpPacket} from '@lakutata/webrtc'
+     *
+     * const packet: RtpPacket = new RtpPacket({payloadType: 96, sequenceNumber: 1, timestamp: 3000, payload: Buffer.from([0x10])})
+     * const bytes: Buffer = packet.toBuffer()
+     * ```
+     */
+    toBuffer() {
+        return enginePacketOf(this).serialize();
+    }
+}
+/**
+ * The packet of a packet of the engine
+ * @param packet
+ */
+export function rtpPacketOf(packet) {
+    const { header } = packet;
+    return new RtpPacket({
+        payloadType: header.payloadType,
+        sequenceNumber: header.sequenceNumber,
+        timestamp: header.timestamp,
+        ssrc: header.ssrc,
+        marker: header.marker,
+        payload: packet.payload
+    });
+}
+/**
+ * The packet of the engine of a packet
+ * @param packet
+ */
+export function enginePacketOf(packet) {
+    return new EngineRtpPacket(new RtpHeader({
+        payloadType: packet.payloadType,
+        sequenceNumber: packet.sequenceNumber,
+        timestamp: packet.timestamp,
+        ssrc: packet.ssrc,
+        marker: packet.marker
+    }), packet.payload);
+}

package/dist/esm/peer/RtpTransceiver.js

@@ -0,0 +1,225 @@
+import { MediaStream } from '../lib/peer/media/track.js';
+import { engineTrackOf, trackOf } from './MediaTrack.js';
+/**
+ * The senders of the engine of the senders
+ */
+const engineSenders = new WeakMap();
+/**
+ * The sending side of a {@link RtpTransceiver}, as `RTCRtpSender`: the track it sends.
+ * @example
+ * ```typescript
+ * import {MediaTrack, type PeerConnection, type RtpSender} from '@lakutata/webrtc'
+ *
+ * declare const connection: PeerConnection
+ * const sender: RtpSender = connection.addTrack(new MediaTrack('audio', {codec: 'audio/opus'}))
+ * //Send another source, without negotiating again
+ * await sender.replaceTrack(new MediaTrack('audio', {codec: 'audio/opus'}))
+ * ```
+ */
+export class RtpSender {
+    #sender;
+    /**
+     * Wrap a sender of the engine
+     * @param sender
+     * @internal
+     */
+    constructor(sender) {
+        this.#sender = sender;
+        engineSenders.set(this, sender);
+    }
+    /**
+     * The track sent; `null` when none.
+     */
+    get track() {
+        return this.#sender.track ? trackOf(this.#sender.track) : null;
+    }
+    /**
+     * Send another track, of any codec negotiated (the other peer accepts each of them), without negotiating again;
+     * `null` stops sending.
+     * @param track The track, or `null`.
+     * @returns Resolves once replaced.
+     * @throws {DOMException} When the codec of the track is none of the ones negotiated (`InvalidModificationError`).
+     * @example
+     * ```typescript
+     * import type {MediaTrack, RtpSender} from '@lakutata/webrtc'
+     *
+     * declare const sender: RtpSender
+     * declare const backup: MediaTrack
+     * await sender.replaceTrack(backup)
+     * ```
+     */
+    async replaceTrack(track) {
+        await this.#sender.replaceTrack(track ? engineTrackOf(track) : null);
+    }
+    /**
+     * Change the streams the track sent belongs to, as `RTCRtpSender.setStreams()`: the other peer groups the tracks of
+     * a stream. A new negotiation is needed.
+     * @param streamIds The ids of the streams.
+     * @example
+     * ```typescript
+     * import type {RtpSender} from '@lakutata/webrtc'
+     *
+     * declare const sender: RtpSender
+     * sender.setStreams('screen')
+     * ```
+     */
+    setStreams(...streamIds) {
+        this.#sender.setStreams(streamIds.map((id) => new MediaStream({ id: id })));
+    }
+}
+/**
+ * The receiving side of a {@link RtpTransceiver}, as `RTCRtpReceiver`: the track it receives.
+ * @example
+ * ```typescript
+ * import type {MediaTrack, PeerConnection, RtpReceiver} from '@lakutata/webrtc'
+ *
+ * declare const connection: PeerConnection
+ * const tracks: MediaTrack[] = connection.getReceivers().map((receiver: RtpReceiver): MediaTrack => receiver.track)
+ * ```
+ */
+export class RtpReceiver {
+    #receiver;
+    /**
+     * Wrap a receiver of the engine
+     * @param receiver
+     * @internal
+     */
+    constructor(receiver) {
+        this.#receiver = receiver;
+    }
+    /**
+     * The track received.
+     */
+    get track() {
+        return trackOf(this.#receiver.track, this.#receiver);
+    }
+}
+/**
+ * The senders, receivers and transceivers of the ones of the engine
+ */
+const senders = new WeakMap();
+const receivers = new WeakMap();
+const transceivers = new WeakMap();
+/**
+ * An audio or video line of a {@link PeerConnection}, as `RTCRtpTransceiver`: a sender and a receiver, and the
+ * direction the media goes. `addTrack()` creates one (or reuses one the other peer offered), `addTransceiver()` creates
+ * one of a given direction: `recvonly` to receive without sending.
+ * @example
+ * ```typescript
+ * import type {PeerConnection, RtpTransceiver} from '@lakutata/webrtc'
+ *
+ * declare const connection: PeerConnection
+ * //Receive the video of the other peer, send none
+ * const transceiver: RtpTransceiver = connection.addTransceiver('video', {direction: 'recvonly'})
+ * ```
+ */
+export class RtpTransceiver {
+    #transceiver;
+    /**
+     * Wrap a transceiver of the engine
+     * @param transceiver
+     * @internal
+     */
+    constructor(transceiver) {
+        this.#transceiver = transceiver;
+    }
+    /**
+     * The media id of its line in the description; `null` until negotiated.
+     */
+    get mid() {
+        return this.#transceiver.mid;
+    }
+    /**
+     * `audio` or `video`.
+     */
+    get kind() {
+        return this.#transceiver.kind;
+    }
+    /**
+     * The direction wanted; changing it makes the connection negotiate.
+     */
+    get direction() {
+        return this.#transceiver.direction;
+    }
+    /**
+     * Change the direction wanted.
+     * @param direction The direction.
+     */
+    set direction(direction) {
+        this.#transceiver.direction = direction;
+    }
+    /**
+     * The direction negotiated, `stopped` once stopped; `null` until negotiated.
+     */
+    get currentDirection() {
+        return this.#transceiver.currentDirection;
+    }
+    /**
+     * The sending side.
+     */
+    get sender() {
+        return senderOf(this.#transceiver.sender);
+    }
+    /**
+     * The receiving side.
+     */
+    get receiver() {
+        return receiverOf(this.#transceiver.receiver);
+    }
+    /**
+     * Stop the transceiver: it sends and receives no more, and the connection negotiates.
+     * @example
+     * ```typescript
+     * import type {RtpTransceiver} from '@lakutata/webrtc'
+     *
+     * declare const transceiver: RtpTransceiver
+     * transceiver.stop()
+     * ```
+     */
+    stop() {
+        this.#transceiver.stop();
+    }
+}
+/**
+ * The sender of a sender of the engine, created once
+ * @param sender
+ */
+export function senderOf(sender) {
+    let wrapped = senders.get(sender);
+    if (!wrapped) {
+        wrapped = new RtpSender(sender);
+        senders.set(sender, wrapped);
+    }
+    return wrapped;
+}
+/**
+ * The sender of the engine of a sender
+ * @param sender
+ */
+export function engineSenderOf(sender) {
+    return engineSenders.get(sender);
+}
+/**
+ * The receiver of a receiver of the engine, created once
+ * @param receiver
+ */
+export function receiverOf(receiver) {
+    let wrapped = receivers.get(receiver);
+    if (!wrapped) {
+        wrapped = new RtpReceiver(receiver);
+        receivers.set(receiver, wrapped);
+    }
+    return wrapped;
+}
+/**
+ * The transceiver of a transceiver of the engine, created once
+ * @param transceiver
+ */
+export function transceiverOf(transceiver) {
+    let wrapped = transceivers.get(transceiver);
+    if (!wrapped) {
+        wrapped = new RtpTransceiver(transceiver);
+        transceivers.set(transceiver, wrapped);
+    }
+    return wrapped;
+}

package/dist/esm/peer/SignalingClient.js

@@ -0,0 +1,249 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { randomUUID } from 'node:crypto';
+import { DTO, Provider } from '@lakutata/core';
+import { Autoload, Configurable, Transient } from '@lakutata/core/decorator/di';
+import { SignalingSession } from '../shared/SignalingSession.js';
+import { JSONRPCTransport, SocketIOTransport } from '../shared/Transports.js';
+import { SignalingConnectionException } from '../exceptions/SignalingConnectionException.js';
+import { PeerConnection } from './PeerConnection.js';
+/**
+ * A lakutata application as a member of the rooms of a signaling server of this package (`Signaling` and
+ * `SignalingController`, on this application or another one): it joins rooms and connects to their other members,
+ * browsers or applications, with {@link PeerConnection}s. Over Socket.IO (an `http:` or `https:` URL, with the package
+ * `socket.io-client`) or JSON-RPC over WebSocket (a `ws:` or `wss:` URL, with the `WebSocket` of Node.js 22 and of Bun);
+ * it reconnects by itself and joins its rooms again, keeping the peer-to-peer connections.
+ *
+ * Get a new one with `getObject(SignalingClient, options)` (it is `@Transient`, and needs no registration); `close()`
+ * leaves the rooms and closes the connections.
+ * @example
+ * ```typescript
+ * import {Component} from 'lakutata'
+ * import {type Peer, type PeerChannel, type Room, SignalingClient} from '@lakutata/webrtc'
+ *
+ * //A service of a device: sends its telemetry to whoever joins its room
+ * class TelemetryService extends Component {
+ *     protected async init(): Promise<void> {
+ *         const signaling: SignalingClient = await this.getObject(SignalingClient, {url: 'https://example.com', id: 'device-7'})
+ *         const room: Room = await signaling.join('device-7')
+ *         room.on('peer', (peer: Peer): void => {
+ *             const channel: PeerChannel = peer.createDataChannel('telemetry')
+ *             const timer: NodeJS.Timeout = setInterval((): void => {
+ *                 if (channel.readyState === 'open') channel.send(JSON.stringify({temperature: 21.5}))
+ *             }, 1000)
+ *             peer.on('close', (): void => clearInterval(timer))
+ *         })
+ *     }
+ * }
+ * ```
+ */
+let SignalingClient = class SignalingClient extends Provider {
+    #clientId;
+    #socket;
+    #session;
+    #closed = false;
+    /**
+     * Connect to the signaling (the requests wait for the connection).
+     * @protected
+     */
+    async init() {
+        this.#clientId = this.id ?? randomUUID();
+        const transport = await this.transport();
+        this.#session = new SignalingSession(transport, {
+            iceTransportPolicy: this.iceTransportPolicy,
+            createPeerConnection: (configuration) => this.getObject(PeerConnection, {
+                ...configuration,
+                icePortRange: this.icePortRange,
+                iceAdditionalHostAddresses: this.iceAdditionalHostAddresses,
+                ...this.codecs ? { codecs: this.codecs } : {},
+                ...this.threads ? { threads: this.threads } : {}
+            })
+        });
+    }
+    /**
+     * Leave the rooms and disconnect.
+     * @protected
+     */
+    async destroy() {
+        this.#closed = true;
+        await this.#session?.close();
+        this.#socket?.disconnect();
+    }
+    /**
+     * The client id: the member's id in the rooms.
+     */
+    get clientId() {
+        return this.#clientId;
+    }
+    /**
+     * Whether the signaling is connected.
+     */
+    get connected() {
+        return this.#session.connected;
+    }
+    /**
+     * The rooms joined.
+     */
+    get rooms() {
+        return this.#session.rooms;
+    }
+    /**
+     * The ICE servers given by the server, with the TURN credentials (renewed before they expire).
+     */
+    get iceServers() {
+        return this.#session.iceServers;
+    }
+    /**
+     * Join a room: its `peer` event gives the other members, each with its {@link PeerConnection}.
+     * @param room The room.
+     * @param options The metadata the other members get.
+     * @returns The room.
+     * @throws {SignalingRequestError} When the server refuses (`E_SIGNALING_DENIED`, `E_SIGNALING_LIMIT`) or does not
+     * answer (`E_SIGNALING_TIMEOUT`).
+     * @example
+     * ```typescript
+     * import type {Room, SignalingClient} from '@lakutata/webrtc'
+     *
+     * declare const signaling: SignalingClient
+     * const room: Room = await signaling.join('meeting', {metadata: {name: 'Recorder'}})
+     * ```
+     */
+    async join(room, options = {}) {
+        return await this.#session.join(room, options);
+    }
+    /**
+     * Listen to the signaling: `connected` (again, after a disconnection; the rooms are joined again), `disconnected`
+     * (the peer-to-peer connections stay up), `error` (a background task failed).
+     * @param event The event.
+     * @param listener The listener.
+     * @returns The client.
+     * @example
+     * ```typescript
+     * import type {SignalingClient} from '@lakutata/webrtc'
+     *
+     * declare const signaling: SignalingClient
+     * signaling.on('disconnected', (): void => console.log('signaling lost, reconnecting'))
+     * ```
+     */
+    on(event, listener) {
+        this.#session.on(event, listener);
+        return this;
+    }
+    /**
+     * Remove a listener added with `on`.
+     * @param event The event.
+     * @param listener The listener.
+     * @returns The client.
+     * @example
+     * ```typescript
+     * import type {SignalingClient} from '@lakutata/webrtc'
+     *
+     * declare const signaling: SignalingClient
+     * const listener = (error: Error): void => console.error(error)
+     * signaling.on('error', listener)
+     * signaling.off('error', listener)
+     * ```
+     */
+    off(event, listener) {
+        this.#session.off(event, listener);
+        return this;
+    }
+    /**
+     * Leave the rooms, close their connections, disconnect, and destroy the object.
+     * @returns Resolves once done.
+     * @example
+     * ```typescript
+     * import type {SignalingClient} from '@lakutata/webrtc'
+     *
+     * declare const signaling: SignalingClient
+     * await signaling.close()
+     * ```
+     */
+    async close() {
+        if (this.#closed)
+            return;
+        await this.dispose();
+    }
+    /**
+     * The transport of the URL: Socket.IO or JSON-RPC over WebSocket
+     * @protected
+     */
+    async transport() {
+        const url = new URL(this.url);
+        if (url.protocol === 'ws:' || url.protocol === 'wss:') {
+            const WebSocketClass = globalThis.WebSocket;
+            if (!WebSocketClass)
+                throw new SignalingConnectionException('JSON-RPC over WebSocket needs the global WebSocket (Node.js 22 and later)');
+            url.searchParams.set('id', this.#clientId);
+            const address = url.toString();
+            return new JSONRPCTransport(() => new WebSocketClass(address), this.timeout);
+        }
+        let io;
+        try {
+            const module = 'socket.io-client';
+            io = (await import(module)).io;
+        }
+        catch {
+            throw new SignalingConnectionException('Socket.IO needs the package socket.io-client: npm install socket.io-client');
+        }
+        const socket = io(this.url, {
+            path: this.path,
+            auth: { ...this.auth, id: this.#clientId },
+            transports: ['websocket']
+        });
+        this.#socket = socket;
+        return new SocketIOTransport(socket, this.timeout);
+    }
+};
+__decorate([
+    Configurable(DTO.String().uri({ scheme: ['http', 'https', 'ws', 'wss'] }).required()),
+    __metadata("design:type", String)
+], SignalingClient.prototype, "url", void 0);
+__decorate([
+    Configurable(DTO.String().min(1).max(200).optional()),
+    __metadata("design:type", String)
+], SignalingClient.prototype, "id", void 0);
+__decorate([
+    Configurable(DTO.String().optional().default('/socket.io')),
+    __metadata("design:type", String)
+], SignalingClient.prototype, "path", void 0);
+__decorate([
+    Configurable(DTO.Object().optional().default({})),
+    __metadata("design:type", Object)
+], SignalingClient.prototype, "auth", void 0);
+__decorate([
+    Configurable(DTO.Number().integer().positive().optional().default(15000)),
+    __metadata("design:type", Number)
+], SignalingClient.prototype, "timeout", void 0);
+__decorate([
+    Configurable(DTO.String().valid('all', 'relay').optional().default('all')),
+    __metadata("design:type", String)
+], SignalingClient.prototype, "iceTransportPolicy", void 0);
+__decorate([
+    Configurable(DTO.Array().items(DTO.Number().port()).length(2).optional()),
+    __metadata("design:type", Array)
+], SignalingClient.prototype, "icePortRange", void 0);
+__decorate([
+    Configurable(DTO.Array().items(DTO.String()).optional()),
+    __metadata("design:type", Array)
+], SignalingClient.prototype, "iceAdditionalHostAddresses", void 0);
+__decorate([
+    Configurable(DTO.Array().items(DTO.String()).optional()),
+    __metadata("design:type", Array)
+], SignalingClient.prototype, "codecs", void 0);
+__decorate([
+    Configurable(DTO.String().optional()),
+    __metadata("design:type", String)
+], SignalingClient.prototype, "threads", void 0);
+SignalingClient = __decorate([
+    Autoload(),
+    Transient()
+], SignalingClient);
+export { SignalingClient };

package/dist/esm/protocol/SignalingProtocol.js

@@ -0,0 +1,62 @@
+/**
+ * The version of the signaling protocol, returned by `webrtc.join`; a later version stays compatible with the clients
+ * of this one.
+ */
+export const SIGNALING_PROTOCOL_VERSION = 1;
+/**
+ * The methods of the signaling requests: a request is a service call whose pattern is `{method}` (the JSON-RPC method of
+ * a JSON-RPC request, the `method` field of a Socket.IO message).
+ */
+export const SignalingMethod = {
+    /**
+     * Join a room: `{room, metadata?, session?}`, answered with a {@link SignalingJoinResult}. The session is a random
+     * string the client chooses once per connection object: joining again with the same one (after a reconnection of the
+     * signaling) keeps the connections of the other members, a new one (a reloaded page) replaces them.
+     */
+    join: 'webrtc.join',
+    /**
+     * Send a description or a candidate to a member of a room: `{room, to, description?, candidate?}`, answered with
+     * `{delivered}`.
+     */
+    signal: 'webrtc.signal',
+    /**
+     * Leave a room: `{room}`, answered with `{}`.
+     */
+    leave: 'webrtc.leave',
+    /**
+     * Get the ICE servers again, with new TURN credentials: `{}`, answered with `{iceServers}`.
+     */
+    iceServers: 'webrtc.iceServers',
+    /**
+     * Tell the server the client is still there: `{}`, answered with `{}`. A client sends it every `heartbeatInterval`
+     * milliseconds of the join result when it is not 0 (the server cannot see the client's disconnection).
+     */
+    heartbeat: 'webrtc.heartbeat'
+};
+/**
+ * The events pushed by the server to the members of a room (`Entrypoint.notify`): a Socket.IO event, a JSON-RPC
+ * notification.
+ */
+export const SignalingEvent = {
+    /**
+     * A member joined a room the client is in: a {@link SignalingPeerEvent}.
+     */
+    peerJoined: 'webrtc:peer-joined',
+    /**
+     * A member left a room the client is in, or was disconnected: a {@link SignalingPeerLeftEvent}.
+     */
+    peerLeft: 'webrtc:peer-left',
+    /**
+     * A description or a candidate from a member: a {@link SignalingSignalEvent}.
+     */
+    signal: 'webrtc:signal'
+};
+/**
+ * The data channel of a member's connection to the media server of its room on which the member controls what it
+ * receives: both sides create it, negotiated, with this label and this id; its messages are
+ * {@link SignalingControlMessage}s in JSON.
+ */
+export const SignalingControlChannel = {
+    label: 'webrtc.control',
+    id: 1023
+};