@lakutata/webrtc 0.0.0-stage → 3.1.1

package/dist/cjs/sfu/SFU.d.ts

@@ -0,0 +1,356 @@
+import { type ResourceLimits } from 'node:worker_threads';
+import { Component, type ComponentOptions } from '@lakutata/core';
+import type { MediaKind, MediaTrack } from '../peer/MediaTrack.js';
+import type { SignalingPeer } from '../protocol/SignalingProtocol.js';
+/**
+ * A track published in a room of the media server.
+ */
+export interface SFUTrack {
+    /**
+     * The room.
+     */
+    room: string;
+    /**
+     * The id of the member publishing it.
+     */
+    peerId: string;
+    /**
+     * Its id: the one the member gave it (the track id of its MSID), else the media id of its transceiver.
+     */
+    id: string;
+    /**
+     * `audio` or `video`.
+     */
+    kind: MediaKind;
+    /**
+     * The MIME type of its codec (`video/VP8`).
+     */
+    codec: string;
+    /**
+     * The id of its stream on the connection of the member; empty when it has none.
+     */
+    stream: string;
+}
+/**
+ * Decides whether a member receives a track published in its room (the `select` option of {@link SFU}).
+ * @param subscriber The member: its id and its metadata.
+ * @param track The track, and the member publishing it.
+ * @returns Whether the member receives it.
+ */
+export type SFUSelect = (subscriber: SignalingPeer, track: SFUTrack) => boolean;
+/**
+ * What joins a room of the media servers of a cluster: a member, a stream published with WHIP, or a viewer of WHEP.
+ */
+export interface SFUPlacement {
+    /**
+     * The room.
+     */
+    room: string;
+    /**
+     * The id of the member (`whip:…` for a stream of WHIP, `whep:…` for a viewer).
+     */
+    peerId: string;
+    /**
+     * `member`, `whip` or `viewer`.
+     */
+    kind: 'member' | 'whip' | 'viewer';
+}
+/**
+ * A node of the cluster with a media server, as it announces itself.
+ */
+export interface SFUNode {
+    /**
+     * The id of the node.
+     */
+    id: string;
+    /**
+     * Its labels (a zone, a region: the `labels` of its `Cluster`).
+     */
+    labels: Readonly<Record<string, string>>;
+    /**
+     * Whether it is this node.
+     */
+    local: boolean;
+    /**
+     * The members it has (the streams of WHIP included).
+     */
+    members: number;
+    /**
+     * The viewers of WHEP it has.
+     */
+    viewers: number;
+    /**
+     * The members it takes at most; 0 for no limit.
+     */
+    maxMembers: number;
+    /**
+     * Whether it has members of the room already.
+     */
+    serving: boolean;
+}
+/**
+ * Chooses the node whose media server a member, a stream of WHIP or a viewer of WHEP connects to (the `selectSFU`
+ * option of {@link SFU}), the node closest to it for example, by the labels of the nodes.
+ * @param placement The room, and what joins it.
+ * @param nodes The nodes with a media server, this one included.
+ * @returns The id of the node, or undefined for the default choice. When the node chosen is full or does not answer,
+ * the default choice is made.
+ */
+export type SFUSelectNode = (placement: SFUPlacement, nodes: SFUNode[]) => string | undefined | Promise<string | undefined>;
+/**
+ * The options of a {@link SFU} (see {@link buildSFUOptions}).
+ */
+export interface SFUOptions {
+    /**
+     * The name of the {@link Signaling} component whose rooms the server serves.
+     * @default 'signaling'
+     */
+    signaling?: string;
+    /**
+     * The name of the `Cluster` component: the media servers of the nodes share the rooms. Each member, stream of WHIP
+     * and viewer of WHEP is given the media server of a node (see `selectSFU`); the nodes of a room forward its tracks to
+     * each other. The signaling of the node must be in the same cluster.
+     * @default none: the media server of this node serves the members joining through it
+     */
+    cluster?: string;
+    /**
+     * Chooses the node whose media server a member, a stream of WHIP or a viewer of WHEP connects to, with a cluster. By
+     * default, a room without members on any node goes to this node when it is not full, else to the least loaded node;
+     * a room with members on some nodes goes to the least loaded of those that is not full, else to the least loaded
+     * node of all.
+     * @default the default choice
+     */
+    selectSFU?: SFUSelectNode;
+    /**
+     * Which rooms the server serves; the others stay peer to peer.
+     * @default all the rooms
+     */
+    serves?: (room: string) => boolean;
+    /**
+     * The codecs the members may publish, as MIME types in the order of preference (see `PeerConnection`); the server
+     * does not transcode, so a member receives only the tracks of the codecs it supports.
+     * @default ['audio/opus', 'audio/PCMU', 'video/VP8', 'video/H264', 'video/VP9']
+     */
+    codecs?: string[];
+    /**
+     * The UDP ports of the connections to the members, as `[first, last]`: the range opened in the firewall. Each
+     * connection (a member, a stream of WHIP, a viewer of WHEP, another node's media server) takes a port on each address
+     * of the machine.
+     * @default any free port
+     */
+    icePortRange?: [number, number];
+    /**
+     * More addresses given as local candidates: the public address of a NAT forwarding `icePortRange` with the same
+     * port numbers.
+     * @default none
+     */
+    iceAdditionalHostAddresses?: string[];
+    /**
+     * The members of all the rooms at most; a member joining once it is reached is refused
+     * (`SignalingLimitException`). 0 for no limit.
+     * @default 0
+     */
+    maxMembers?: number;
+    /**
+     * Decides which member receives which track. It is asked again for a member that joins the room again with other
+     * metadata; the tracks the member receives follow the new answers. When it throws, the member does not receive the
+     * track, and the error goes to the debug messages (`webrtc/sfu`, see `setDebugHandler`).
+     * @default every member receives every track of the others
+     */
+    select?: SFUSelect;
+    /**
+     * Worker threads that forward the rooms, to use more cores: each room is forwarded in one of them (the one
+     * forwarding the fewest members and viewers when the room opens), with its connections, its UDP ports and its
+     * relaying, while the hooks and the events stay in the main thread. `icePortRange`, when given, is split among the
+     * threads and needs at least one port for each. A thread that stops (only a bug stops one) closes its rooms; the
+     * server joins them again in another thread, and their members connect to it again. With 0, the rooms are forwarded
+     * in the main thread.
+     * @default 0
+     */
+    workers?: number;
+    /**
+     * The limits of the heap and of the stack of each worker thread (`resourceLimits` of `node:worker_threads`). Each
+     * thread has a heap of its own, with the large young generation V8 gives it for speed: a smaller one
+     * (`maxYoungGenerationSizeMb`) takes less memory for a little more CPU, the garbage being collected more often. A
+     * thread reaching `maxOldGenerationSizeMb` stops, as one stopped by a bug. Bun ignores these limits.
+     * @default the limits of V8
+     */
+    workerResourceLimits?: ResourceLimits;
+}
+/**
+ * The media server of the rooms of a {@link Signaling} (a selective forwarding unit): each member connects to the
+ * server only, publishes its tracks once, and receives the tracks of the others from the server, which forwards their
+ * packets without decoding them. A room of many members then costs each of them one connection and one upload, instead
+ * of one of each per other member.
+ *
+ * The server is a member of each room it serves (its id starts with `sfu:`, its role is `sfu`); the clients of this
+ * package (`SignalingClient`, `SignalingConnection` of `./client`) connect to it by themselves, and their rooms and
+ * peers work as without it: `room.publish()` sends a track to every member, each peer emits the tracks of its member,
+ * and a data channel to a member goes through the server, which relays its messages (unlike between two members, the
+ * server sees them; with a cluster, the servers of both members relay them). The key frame requests of the members go
+ * to the publisher, at most every 500 ms; the lost packets are sent again by the server; the bandwidth of each
+ * connection is estimated from the transport-wide feedback. A member receiving the messages of a channel slower than
+ * they are sent makes the sender wait, without the server keeping more than a few megabytes of them.
+ *
+ * Events: `publish` and `unpublish` (an {@link SFUTrack}) when a member of this node starts and stops publishing a
+ * track (with a cluster, they are emitted on the node of the member only), `unsupported` (the room, the id of the
+ * member or of the viewer of WHEP, the track) when a member or a viewer does not support the codec of a track it should
+ * receive, `congestion` (the room, the id of the member, whether it is congested, the bit rate estimated in bits per
+ * second) when the bandwidth to a member is too low, and when it is enough again.
+ *
+ * Register it with {@link buildSFUOptions}, and bootstrap it: it attaches itself to the signaling when it starts.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildEntrypoints} from 'lakutata/com/entrypoint'
+ * import {socketIOServiceEntrypoint} from 'lakutata/adapter/socket.io'
+ * import {buildSFUOptions, buildSignalingOptions, SignalingController} from '@lakutata/webrtc'
+ *
+ * Application.run(() => ({
+ *     id: 'meet.app',
+ *     name: 'Meet',
+ *     components: {
+ *         signaling: buildSignalingOptions(),
+ *         //The meetings go through the server; the other rooms stay peer to peer
+ *         sfu: buildSFUOptions({
+ *             serves: (room: string): boolean => room.startsWith('meeting-'),
+ *             iceAdditionalHostAddresses: ['203.0.113.10'],
+ *             icePortRange: [40000, 40999]
+ *         }),
+ *         entrypoint: buildEntrypoints({
+ *             controllers: [SignalingController],
+ *             service: socketIOServiceEntrypoint({port: 3000})
+ *         })
+ *     },
+ *     bootstrap: ['sfu', 'entrypoint']
+ * }))
+ * ```
+ */
+export declare class SFU extends Component {
+    #private;
+    /**
+     * The name of the signaling component.
+     */
+    protected readonly signaling: string;
+    /**
+     * The name of the cluster component.
+     */
+    protected readonly cluster?: string;
+    /**
+     * Chooses the node of a member.
+     */
+    protected readonly selectSFU?: SFUSelectNode;
+    /**
+     * Which rooms the server serves.
+     */
+    protected readonly serves?: (room: string) => boolean;
+    /**
+     * The codecs the members may publish.
+     */
+    protected readonly codecs?: string[];
+    /**
+     * The UDP ports of the connections.
+     */
+    protected readonly icePortRange?: [number, number];
+    /**
+     * More addresses given as local candidates.
+     */
+    protected readonly iceAdditionalHostAddresses?: string[];
+    /**
+     * The members of all the rooms at most.
+     */
+    protected readonly maxMembers: number;
+    /**
+     * Which member receives which track.
+     */
+    protected readonly select?: SFUSelect;
+    /**
+     * The worker threads forwarding the rooms.
+     */
+    protected readonly workers: number;
+    /**
+     * The limits of the heap and of the stack of each worker thread.
+     */
+    protected readonly workerResourceLimits?: ResourceLimits;
+    /**
+     * Attach the server to the signaling.
+     * @protected
+     */
+    protected init(): Promise<void>;
+    /**
+     * Detach the server, and leave the rooms.
+     * @protected
+     */
+    protected destroy(): Promise<void>;
+    /**
+     * The rooms the server is in, with their members on this node, the tracks these members publish and the number of
+     * viewers of WHEP on this node; with a cluster, each node reports its own. With `workers`, each thread reports its
+     * rooms: a change made in a thread (a session of WHEP ending) shows here a moment later.
+     * @returns For each room, the ids of its members, its tracks and its viewers.
+     * @example
+     * ```typescript
+     * import type {SFU} from '@lakutata/webrtc'
+     *
+     * declare const sfu: SFU
+     * for (const [room, {members, tracks}] of Object.entries(sfu.rooms())) console.log(room, members.length, tracks.length)
+     * ```
+     */
+    rooms(): Record<string, {
+        members: string[];
+        tracks: SFUTrack[];
+        viewers: number;
+    }>;
+    /**
+     * A track published in a room, to read its packets (to record them) or to send it on another connection. With a
+     * cluster, a track of a member of another node is received from that node while it is read here.
+     * @param room The room.
+     * @param peerId The member publishing it.
+     * @param trackId The id of the track ({@link SFUTrack.id}).
+     * @returns The track, or undefined when it is not published.
+     * @example
+     * ```typescript
+     * import type {RtpPacket, SFU, SFUTrack} from '@lakutata/webrtc'
+     *
+     * declare const sfu: SFU
+     * //Record the audio of the members of the room
+     * sfu.on('publish', (track: SFUTrack): void => {
+     *     if (track.kind === 'audio') sfu.track(track.room, track.peerId, track.id)?.on('rtp', (packet: RtpPacket): void => console.log(packet.timestamp))
+     * })
+     * ```
+     */
+    track(room: string, peerId: string, trackId: string): MediaTrack | undefined;
+    /**
+     * Give a member joining a room a media server, once the server is in the room: this one, or with a cluster the one
+     * of the node chosen (`selectSFU`)
+     * @param room The room.
+     * @param peerId The id of the member.
+     * @param kind A member, a stream of WHIP, or a viewer of WHEP (`maxMembers` does not count the viewers).
+     * @returns The id of the member of the server, or undefined for a room the servers do not serve.
+     * @throws {SignalingLimitException} When no media server takes the member.
+     * @protected
+     */
+    protected assign(room: string, peerId: string, kind?: SFUPlacement['kind']): Promise<string | undefined>;
+}
+/**
+ * Build the options of a {@link SFU} component, for the `components` of an application.
+ * @param options The signaling, the rooms served, the codecs, the ports, the limits, the selection of the tracks (all
+ * optional).
+ * @returns The component options.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildSFUOptions, buildSignalingOptions} from '@lakutata/webrtc'
+ *
+ * Application.run(() => ({
+ *     id: 'meet.app',
+ *     name: 'Meet',
+ *     components: {
+ *         signaling: buildSignalingOptions(),
+ *         //The members whose metadata says they only listen receive the audio only
+ *         sfu: buildSFUOptions({select: (subscriber, track): boolean => track.kind === 'audio' || (subscriber.metadata as {listener?: boolean})?.listener !== true})
+ *     },
+ *     bootstrap: ['sfu']
+ * }))
+ * ```
+ */
+export declare function buildSFUOptions(options?: SFUOptions): ComponentOptions<SFUOptions>;