@lakutata/webrtc 0.0.0-stage → 3.1.4

package/dist/cjs/peer/PeerConnection.d.ts

@@ -0,0 +1,603 @@
+import { Provider } from '@lakutata/core';
+import type { SignalingCandidate, SignalingDescription, SignalingIceServer } from '../protocol/SignalingProtocol.js';
+import type { DataChannelOptions } from '../shared/Connections.js';
+import { type DOMEventListener, type ListenerOptions } from './Events.js';
+import { type MediaKind, MediaTrack } from './MediaTrack.js';
+import { PeerChannel } from './PeerChannel.js';
+import { type RtpReceiver, type RtpSender, type RtpTransceiver, type RtpTransceiverDirection } from './RtpTransceiver.js';
+/**
+ * The configuration of a {@link PeerConnection}: the options of `RTCConfiguration` it supports, and the ones of a
+ * server.
+ */
+export interface PeerConnectionOptions {
+    /**
+     * The STUN and TURN servers.
+     * @default []
+     */
+    iceServers?: SignalingIceServer[];
+    /**
+     * `relay` to use only the TURN relays.
+     * @default 'all'
+     */
+    iceTransportPolicy?: 'all' | 'relay';
+    /**
+     * The UDP ports of the local candidates, as `[first, last]`: the range opened in the firewall or published by the
+     * container.
+     * @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, an address normally left out (the loopback).
+     * @default none
+     */
+    iceAdditionalHostAddresses?: string[];
+    /**
+     * Whether to gather IPv4 candidates.
+     * @default true
+     */
+    iceUseIpv4?: boolean;
+    /**
+     * Whether to gather IPv6 candidates.
+     * @default true
+     */
+    iceUseIpv6?: boolean;
+    /**
+     * The audio and video codecs offered and accepted, as MIME types in the order of preference: `audio/opus`,
+     * `audio/PCMU`, `video/VP8`, `video/H264`, `video/VP9`.
+     * @default ['audio/opus', 'audio/PCMU', 'video/VP8', 'video/H264', 'video/VP9']
+     */
+    codecs?: string[];
+    /**
+     * Whether to negotiate the RTP header extensions a media server uses: the media identification (`mid`), the
+     * transport-wide sequence numbers with their feedback (`transport-cc`, from which each side estimates the bandwidth
+     * available for what it sends), the absolute send time and the audio level. The other peer uses those it supports;
+     * when `false`, the offers and the answers have none.
+     * @default false
+     */
+    headerExtensions?: boolean;
+    /**
+     * The name of a {@link PeerThreads} component: the engine of the connection (ICE, DTLS, SCTP, SRTP) runs in one of
+     * its worker threads, to use more cores. The connection is used the same way: its methods are carried to the
+     * thread and resolve once done there, its states are the ones the thread last reported, and its events, the
+     * messages of its channels and the packets of the tracks it receives come back to the main thread, while the
+     * packets of the tracks it sends go to the thread.
+     * @default none: the engine runs in the main thread
+     */
+    threads?: string;
+}
+/**
+ * The options of `PeerConnection.addTransceiver()`.
+ */
+export interface RtpTransceiverInit {
+    /**
+     * The direction.
+     * @default 'sendrecv'
+     */
+    direction?: RtpTransceiverDirection;
+    /**
+     * The streams of the track sent, by their ids (the `MediaStream`s of `streams` in the browsers): the other peer
+     * groups the tracks of a stream (`event.streams` in the browsers, to play the audio and the video together).
+     * @default none
+     */
+    streams?: string[];
+}
+/**
+ * The `track` event of a {@link PeerConnection} in the W3C style, as `RTCTrackEvent`.
+ */
+export interface PeerTrackEvent {
+    /**
+     * The track received.
+     */
+    readonly track: MediaTrack;
+    /**
+     * The streams of the track, as the other peer grouped them: their ids.
+     */
+    readonly streams: ReadonlyArray<{
+        readonly id: string;
+    }>;
+    /**
+     * The receiver of the track.
+     */
+    readonly receiver: RtpReceiver;
+    /**
+     * The transceiver of the track.
+     */
+    readonly transceiver: RtpTransceiver;
+}
+/**
+ * The events of a {@link PeerConnection}, with the arguments of their listeners in the Node.js style (`on`).
+ */
+export type PeerConnectionEvents = {
+    /**
+     * A local candidate to send to the other peer; `null` once all are gathered.
+     */
+    icecandidate: [candidate: SignalingCandidate | null];
+    /**
+     * A data channel the other peer created.
+     */
+    datachannel: [channel: PeerChannel];
+    /**
+     * An audio or video track of the other peer, with the ids of its streams and its transceiver.
+     */
+    track: [track: MediaTrack, streamIds: string[], transceiver: RtpTransceiver];
+    /**
+     * A new offer is needed (a channel or a track was added, ICE was restarted).
+     */
+    negotiationneeded: [];
+    /**
+     * `connectionState` changed.
+     */
+    connectionstatechange: [state: string];
+    /**
+     * `iceConnectionState` changed.
+     */
+    iceconnectionstatechange: [state: string];
+    /**
+     * `iceGatheringState` changed.
+     */
+    icegatheringstatechange: [state: string];
+    /**
+     * `signalingState` changed.
+     */
+    signalingstatechange: [state: string];
+};
+/**
+ * A peer-to-peer connection of Node.js (and of Bun, of the main process of Electron), implemented in TypeScript: the
+ * same interface as `RTCPeerConnection` of the browsers (offers and answers, candidates, data channels, audio and video
+ * tracks, ICE restart, perfect negotiation), so the code and the signaling are the ones of a browser. Its events may be
+ * listened to in the W3C style (`addEventListener`, the `on…` properties) or in the Node.js style
+ * (`on('datachannel', (channel) => …)`). The tracks carry encoded audio and video, as RTP packets: see
+ * {@link MediaTrack}.
+ *
+ * Get a new one each time with `getObject(PeerConnection, options)` (it is `@Transient`, and needs no registration);
+ * `close()` closes it and destroys the object, and the ones still open are closed when the application stops. With the
+ * signaling of this package, `SignalingClient` creates the connections itself.
+ * @example
+ * ```typescript
+ * import {Component} from 'lakutata'
+ * import {PeerConnection, type PeerChannel, type SignalingCandidate, type SignalingDescription} from '@lakutata/webrtc'
+ *
+ * class Device extends Component {
+ *     //Answer an offer received some other way (an HTTP request, a QR code)
+ *     public async answer(offer: SignalingDescription): Promise<SignalingDescription | null> {
+ *         const connection: PeerConnection = await this.getObject(PeerConnection, {iceServers: [{urls: 'stun:stun.example.com:3478'}]})
+ *         connection.on('datachannel', (channel: PeerChannel): void => {
+ *             channel.on('message', (data: string | Buffer | ArrayBuffer): void => channel.send(`echo: ${data.toString()}`))
+ *         })
+ *         await connection.setRemoteDescription(offer)
+ *         await connection.setLocalDescription()
+ *         //Wait for the candidates, to answer without trickle ICE
+ *         await new Promise<void>((resolve: () => void): void => {
+ *             connection.on('icecandidate', (candidate: SignalingCandidate | null): void => {
+ *                 if (!candidate) resolve()
+ *             })
+ *         })
+ *         return connection.localDescription
+ *     }
+ * }
+ * ```
+ */
+export declare class PeerConnection extends Provider {
+    #private;
+    /**
+     * The STUN and TURN servers.
+     */
+    protected readonly iceServers: SignalingIceServer[];
+    /**
+     * `all`, or `relay` to use only the TURN relays.
+     */
+    protected readonly iceTransportPolicy: 'all' | 'relay';
+    /**
+     * The UDP ports of the local candidates.
+     */
+    protected readonly icePortRange?: [number, number];
+    /**
+     * More addresses given as local candidates.
+     */
+    protected readonly iceAdditionalHostAddresses?: string[];
+    /**
+     * Whether to gather IPv4 candidates.
+     */
+    protected readonly iceUseIpv4: boolean;
+    /**
+     * Whether to gather IPv6 candidates.
+     */
+    protected readonly iceUseIpv6: boolean;
+    /**
+     * The audio and video codecs, in the order of preference.
+     */
+    protected readonly codecs: string[];
+    /**
+     * Whether to negotiate the RTP header extensions of a media server.
+     */
+    protected readonly headerExtensions: boolean;
+    /**
+     * The name of the component of the worker threads serving the connection.
+     */
+    protected readonly threads?: string;
+    /**
+     * Create the connection.
+     * @protected
+     */
+    protected init(): Promise<void>;
+    /**
+     * Close the connection.
+     * @protected
+     */
+    protected destroy(): Promise<void>;
+    /**
+     * `new`, `connecting`, `connected`, `disconnected`, `failed` or `closed`.
+     */
+    get connectionState(): 'new' | 'connecting' | 'connected' | 'disconnected' | 'failed' | 'closed';
+    /**
+     * The state of ICE: `new`, `checking`, `connected`, `completed`, `disconnected`, `failed` or `closed`.
+     */
+    get iceConnectionState(): string;
+    /**
+     * The state of the gathering of the local candidates: `new`, `gathering` or `complete`.
+     */
+    get iceGatheringState(): string;
+    /**
+     * The state of the offer and answer exchange: `stable`, `have-local-offer`, `have-remote-offer`,
+     * `have-local-pranswer`, `have-remote-pranswer` or `closed`.
+     */
+    get signalingState(): string;
+    /**
+     * The local description: the pending one during a negotiation, else the current one.
+     */
+    get localDescription(): SignalingDescription | null;
+    /**
+     * The remote description: the pending one during a negotiation, else the current one.
+     */
+    get remoteDescription(): SignalingDescription | null;
+    /**
+     * The SCTP transport of the data channels, once negotiated: `maxMessageSize` is the largest message the other peer
+     * accepts, in bytes.
+     */
+    get sctp(): {
+        maxMessageSize: number;
+    } | null;
+    /**
+     * The listener of `icecandidate`, given an event whose `candidate` is the candidate (`null` at the end).
+     */
+    get onicecandidate(): DOMEventListener | null;
+    set onicecandidate(listener: DOMEventListener | null);
+    /**
+     * The listener of `datachannel`, given an event whose `channel` is the {@link PeerChannel}.
+     */
+    get ondatachannel(): DOMEventListener | null;
+    set ondatachannel(listener: DOMEventListener | null);
+    /**
+     * The listener of `track`, given a {@link PeerTrackEvent}: the track, its streams, its receiver and transceiver.
+     */
+    get ontrack(): ((event: PeerTrackEvent) => void) | null;
+    set ontrack(listener: ((event: PeerTrackEvent) => void) | null);
+    /**
+     * The listener of `negotiationneeded`.
+     */
+    get onnegotiationneeded(): DOMEventListener | null;
+    set onnegotiationneeded(listener: DOMEventListener | null);
+    /**
+     * The listener of `connectionstatechange`.
+     */
+    get onconnectionstatechange(): DOMEventListener | null;
+    set onconnectionstatechange(listener: DOMEventListener | null);
+    /**
+     * The listener of `iceconnectionstatechange`.
+     */
+    get oniceconnectionstatechange(): DOMEventListener | null;
+    set oniceconnectionstatechange(listener: DOMEventListener | null);
+    /**
+     * The listener of `icegatheringstatechange`.
+     */
+    get onicegatheringstatechange(): DOMEventListener | null;
+    set onicegatheringstatechange(listener: DOMEventListener | null);
+    /**
+     * The listener of `signalingstatechange`.
+     */
+    get onsignalingstatechange(): DOMEventListener | null;
+    set onsignalingstatechange(listener: DOMEventListener | null);
+    /**
+     * Create an offer.
+     * @param options `iceRestart` to gather new candidates.
+     * @returns The offer, to give to `setLocalDescription()`.
+     * @example
+     * ```typescript
+     * import type {PeerConnection, SignalingDescription} from '@lakutata/webrtc'
+     *
+     * declare const connection: PeerConnection
+     * const offer: SignalingDescription = await connection.createOffer()
+     * await connection.setLocalDescription(offer)
+     * ```
+     */
+    createOffer(options?: {
+        iceRestart?: boolean;
+    }): Promise<SignalingDescription>;
+    /**
+     * Create an answer to the remote offer.
+     * @returns The answer, to give to `setLocalDescription()`.
+     * @example
+     * ```typescript
+     * import type {PeerConnection, SignalingDescription} from '@lakutata/webrtc'
+     *
+     * declare const connection: PeerConnection
+     * declare const offer: SignalingDescription
+     * await connection.setRemoteDescription(offer)
+     * await connection.setLocalDescription(await connection.createAnswer())
+     * ```
+     */
+    createAnswer(): Promise<SignalingDescription>;
+    /**
+     * Set the local description; without one, the offer or the answer the state calls for is created.
+     * @param description The offer, the answer, a rollback, or none.
+     * @returns Resolves once it is set.
+     * @example
+     * ```typescript
+     * import type {PeerConnection} from '@lakutata/webrtc'
+     *
+     * declare const connection: PeerConnection
+     * await connection.setLocalDescription()
+     * console.log(connection.localDescription)
+     * ```
+     */
+    setLocalDescription(description?: SignalingDescription): Promise<void>;
+    /**
+     * Set the remote description; an offer received while an offer of this side is pending rolls it back.
+     * @param description The offer or the answer of the other peer.
+     * @returns Resolves once it is set.
+     * @example
+     * ```typescript
+     * import type {PeerConnection, SignalingDescription} from '@lakutata/webrtc'
+     *
+     * declare const connection: PeerConnection
+     * declare const answer: SignalingDescription
+     * await connection.setRemoteDescription(answer)
+     * ```
+     */
+    setRemoteDescription(description: SignalingDescription): Promise<void>;
+    /**
+     * Add a candidate of the other peer.
+     * @param candidate The candidate; none, or an empty one, for the end of the candidates.
+     * @returns Resolves once it is added.
+     * @example
+     * ```typescript
+     * import type {PeerConnection, SignalingCandidate} from '@lakutata/webrtc'
+     *
+     * declare const connection: PeerConnection
+     * declare const candidate: SignalingCandidate
+     * await connection.addIceCandidate(candidate)
+     * ```
+     */
+    addIceCandidate(candidate?: SignalingCandidate | null): Promise<void>;
+    /**
+     * Create a data channel; the first one makes the connection negotiate (`negotiationneeded`).
+     * @param label The label of the channel.
+     * @param options Whether it is ordered, reliable, negotiated.
+     * @returns The channel.
+     * @example
+     * ```typescript
+     * import type {PeerChannel, PeerConnection} from '@lakutata/webrtc'
+     *
+     * declare const connection: PeerConnection
+     * //Unordered and unreliable: a lost position is not sent again
+     * const channel: PeerChannel = connection.createDataChannel('position', {ordered: false, maxRetransmits: 0})
+     * ```
+     */
+    createDataChannel(label: string, options?: DataChannelOptions): PeerChannel;
+    /**
+     * Add a track to send: it gets a transceiver (a new one, or one the other peer offered and nothing is sent on), and
+     * the connection negotiates (`negotiationneeded`).
+     * @param track The track: one to send, or one received from another connection (to forward it).
+     * @param streamIds The ids of its streams: the other peer groups the tracks of a stream (to play the audio and the
+     * video together).
+     * @returns Its sender.
+     * @example
+     * ```typescript
+     * import {MediaTrack, type PeerConnection, type RtpSender} from '@lakutata/webrtc'
+     *
+     * declare const connection: PeerConnection
+     * const audio: MediaTrack = new MediaTrack('audio', {codec: 'audio/opus'})
+     * const video: MediaTrack = new MediaTrack('video', {codec: 'video/H264'})
+     * //One stream: the browser plays them together (event.streams[0])
+     * const senders: RtpSender[] = [connection.addTrack(audio, 'camera'), connection.addTrack(video, 'camera')]
+     * ```
+     */
+    addTrack(track: MediaTrack, ...streamIds: string[]): RtpSender;
+    /**
+     * Stop sending the track of a sender (its transceiver stays, receiving only); the connection negotiates.
+     * @param sender The sender, given by `addTrack()`.
+     * @example
+     * ```typescript
+     * import type {PeerConnection, RtpSender} from '@lakutata/webrtc'
+     *
+     * declare const connection: PeerConnection
+     * declare const sender: RtpSender
+     * connection.removeTrack(sender)
+     * ```
+     */
+    removeTrack(sender: RtpSender): void;
+    /**
+     * Add a transceiver: for a track to send, or of a kind, to receive one (`recvonly`); the connection negotiates.
+     * @param trackOrKind The track to send, or `audio` or `video`.
+     * @param init The direction, the ids of the streams of the track.
+     * @returns The transceiver.
+     * @example
+     * ```typescript
+     * import type {MediaTrack, PeerConnection} from '@lakutata/webrtc'
+     *
+     * declare const connection: PeerConnection
+     * //Offer to receive the camera and the microphone of the other peer
+     * connection.addTransceiver('audio', {direction: 'recvonly'})
+     * connection.addTransceiver('video', {direction: 'recvonly'})
+     * connection.on('track', (track: MediaTrack): void => console.log(`${track.kind} received`))
+     * ```
+     */
+    addTransceiver(trackOrKind: MediaTrack | MediaKind, init?: RtpTransceiverInit): RtpTransceiver;
+    /**
+     * The transceivers, in the order of their lines.
+     * @returns The transceivers.
+     * @example
+     * ```typescript
+     * import type {PeerConnection, RtpTransceiver} from '@lakutata/webrtc'
+     *
+     * declare const connection: PeerConnection
+     * connection.getTransceivers().forEach((transceiver: RtpTransceiver): void => console.log(transceiver.mid, transceiver.currentDirection))
+     * ```
+     */
+    getTransceivers(): RtpTransceiver[];
+    /**
+     * The senders of the transceivers.
+     * @returns The senders.
+     * @example
+     * ```typescript
+     * import type {PeerConnection, RtpSender} from '@lakutata/webrtc'
+     *
+     * declare const connection: PeerConnection
+     * const sending: RtpSender[] = connection.getSenders().filter((sender: RtpSender): boolean => sender.track !== null)
+     * ```
+     */
+    getSenders(): RtpSender[];
+    /**
+     * The receivers of the transceivers.
+     * @returns The receivers.
+     * @example
+     * ```typescript
+     * import type {PeerConnection, RtpReceiver} from '@lakutata/webrtc'
+     *
+     * declare const connection: PeerConnection
+     * const receivers: RtpReceiver[] = connection.getReceivers()
+     * ```
+     */
+    getReceivers(): RtpReceiver[];
+    /**
+     * Restart ICE: the next offer gathers new candidates (`negotiationneeded` fires), for a connection whose network
+     * changed.
+     * @example
+     * ```typescript
+     * import type {PeerConnection} from '@lakutata/webrtc'
+     *
+     * declare const connection: PeerConnection
+     * connection.on('connectionstatechange', (state: string): void => {
+     *     if (state === 'failed') connection.restartIce()
+     * })
+     * ```
+     */
+    restartIce(): void;
+    /**
+     * The configuration.
+     * @returns The ICE servers and the transport policy.
+     * @example
+     * ```typescript
+     * import type {PeerConnection} from '@lakutata/webrtc'
+     *
+     * declare const connection: PeerConnection
+     * console.log(connection.getConfiguration().iceServers)
+     * ```
+     */
+    getConfiguration(): {
+        iceServers: SignalingIceServer[];
+        iceTransportPolicy: 'all' | 'relay';
+    };
+    /**
+     * Change the ICE servers (new TURN credentials) or the transport policy; they are used from the next gathering.
+     * @param configuration The ICE servers, the transport policy.
+     * @example
+     * ```typescript
+     * import type {PeerConnection} from '@lakutata/webrtc'
+     *
+     * declare const connection: PeerConnection
+     * connection.setConfiguration({iceServers: [{urls: 'turn:turn.example.com:3478', username: 'u', credential: 'p'}]})
+     * ```
+     */
+    setConfiguration(configuration: {
+        iceServers?: SignalingIceServer[];
+        iceTransportPolicy?: 'all' | 'relay';
+    }): void;
+    /**
+     * Close the connection and its channels, and destroy the object.
+     * @example
+     * ```typescript
+     * import type {PeerConnection} from '@lakutata/webrtc'
+     *
+     * declare const connection: PeerConnection
+     * connection.close()
+     * ```
+     */
+    close(): void;
+    /**
+     * Add a listener of an event, given an event object (the W3C style).
+     * @param type The event: `icecandidate`, `datachannel`, `track`, `negotiationneeded`, `connectionstatechange`,
+     * `iceconnectionstatechange`, `icegatheringstatechange`, `signalingstatechange`.
+     * @param listener The listener.
+     * @param options `once`, `signal`.
+     * @example
+     * ```typescript
+     * import type {PeerConnection, SignalingCandidate} from '@lakutata/webrtc'
+     *
+     * declare const connection: PeerConnection
+     * connection.addEventListener('icecandidate', (event: {candidate: SignalingCandidate | null}): void => console.log(event.candidate))
+     * ```
+     */
+    addEventListener(type: string, listener: DOMEventListener, options?: boolean | ListenerOptions): void;
+    /**
+     * Remove a listener added with `addEventListener`.
+     * @param type The event.
+     * @param listener The listener.
+     * @param options `capture`.
+     * @example
+     * ```typescript
+     * import type {PeerConnection} from '@lakutata/webrtc'
+     *
+     * declare const connection: PeerConnection
+     * const listener = (): void => console.log(connection.connectionState)
+     * connection.addEventListener('connectionstatechange', listener)
+     * connection.removeEventListener('connectionstatechange', listener)
+     * ```
+     */
+    removeEventListener(type: string, listener: DOMEventListener, options?: boolean | ListenerOptions): void;
+    /**
+     * Add a listener of an event, given the value of the event (the Node.js style).
+     * @param event The event.
+     * @param listener The listener: given the candidate, the channel, the track, the new state.
+     * @returns The connection.
+     * @example
+     * ```typescript
+     * import type {PeerChannel, PeerConnection} from '@lakutata/webrtc'
+     *
+     * declare const connection: PeerConnection
+     * connection.on('datachannel', (channel: PeerChannel): void => console.log(channel.label))
+     * ```
+     */
+    on<Event extends keyof PeerConnectionEvents>(event: Event, listener: (...args: PeerConnectionEvents[Event]) => void): this;
+    /**
+     * Add a listener of the next emission of an event, given the value of the event.
+     * @param event The event.
+     * @param listener The listener.
+     * @returns The connection.
+     * @example
+     * ```typescript
+     * import type {PeerChannel, PeerConnection} from '@lakutata/webrtc'
+     *
+     * declare const connection: PeerConnection
+     * connection.once('datachannel', (channel: PeerChannel): void => console.log(channel.label))
+     * ```
+     */
+    once<Event extends keyof PeerConnectionEvents>(event: Event, listener: (...args: PeerConnectionEvents[Event]) => void): this;
+    /**
+     * Remove a listener added with `on` or `once`.
+     * @param event The event.
+     * @param listener The listener.
+     * @returns The connection.
+     * @example
+     * ```typescript
+     * import type {PeerConnection} from '@lakutata/webrtc'
+     *
+     * declare const connection: PeerConnection
+     * const listener = (state: string): void => console.log(state)
+     * connection.on('connectionstatechange', listener)
+     * connection.off('connectionstatechange', listener)
+     * ```
+     */
+    off<Event extends keyof PeerConnectionEvents>(event: Event, listener: (...args: PeerConnectionEvents[Event]) => void): this;
+}