@lakutata/webrtc 0.0.0-stage → 3.1.1

package/dist/types/peer/RemoteConnection.d.ts

@@ -0,0 +1,314 @@
+import { Event } from '../lib/common/event.js';
+import { type MediaStream, MediaStreamTrack } from '../lib/peer/media/track.js';
+import type { SignalingCandidate, SignalingDescription, SignalingIceServer } from '../protocol/SignalingProtocol.js';
+import type { DataChannelOptions } from '../shared/Connections.js';
+import { type MediaKind } from './MediaTrack.js';
+import type { PeerChannelInfo, PeerConnectionState, PeerFromWorker, PeerToWorker, PeerTransceiverChange, PeerTransceiverInfo } from './PeerThreadProtocol.js';
+import type { RtpTransceiverDirection } from './RtpTransceiver.js';
+/**
+ * What a connection served in a worker thread needs of its thread
+ */
+export interface PeerThreadLink {
+    request<Result>(message: PeerToWorker, transfer?: ArrayBuffer[]): Promise<Result>;
+    post(message: PeerToWorker, transfer?: ArrayBuffer[]): void;
+    postOrExtend(extend: (last: PeerToWorker) => boolean, message: () => PeerToWorker, transfer?: ArrayBuffer[]): void;
+    pack(data: Uint8Array): {
+        bytes: Uint8Array;
+        transfer?: ArrayBuffer[];
+    };
+    release(conn: number): void;
+}
+/**
+ * The state of a connection before its thread tells it
+ */
+export declare const INITIAL_STATE: PeerConnectionState;
+/**
+ * A data channel of a connection served in a worker thread, in the main thread: the members of a channel of the engine
+ * that PeerChannel uses. Its state is the one the thread last reported; the amount buffered counts the messages on
+ * their way to the thread
+ */
+export declare class RemoteDataChannel {
+    #private;
+    readonly stateChanged: Event<[PeerChannelInfo['readyState']]>;
+    readonly onMessage: Event<[string | Buffer]>;
+    readonly bufferedAmountLow: Event<[]>;
+    readonly error: Event<[Error]>;
+    /**
+     * Mirror a channel
+     * @param connection
+     * @param ref
+     * @param info
+     */
+    constructor(connection: RemoteConnection, ref: string, info: PeerChannelInfo);
+    get label(): string;
+    get id(): number | null;
+    get protocol(): string;
+    get ordered(): boolean;
+    get maxRetransmits(): number | null;
+    get maxPacketLifeTime(): number | null;
+    get negotiated(): boolean;
+    get readyState(): PeerChannelInfo['readyState'];
+    get bufferedAmount(): number;
+    get bufferedAmountLowThreshold(): number;
+    set bufferedAmountLowThreshold(value: number);
+    /**
+     * Send a message: copied, the caller may reuse its buffer
+     * @param data
+     */
+    send(data: Buffer | string): void;
+    /**
+     * Close the channel: closing at once, closed when the thread says so
+     */
+    close(): void;
+    /**
+     * The state the thread reported
+     * @param readyState
+     * @param id
+     * @internal
+     */
+    state(readyState: PeerChannelInfo['readyState'], id: number | null): void;
+    /**
+     * A message received
+     * @param data
+     * @internal
+     */
+    message(data: string | Uint8Array): void;
+    /**
+     * The amount the engine buffers, and the bytes of the messages from here it was given so far
+     * @param amount
+     * @param applied
+     * @internal
+     */
+    buffered(amount: number, applied: number): void;
+}
+/**
+ * The sender of a transceiver of a connection served in a worker thread: the members of a sender of the engine that
+ * RtpSender and PeerConnection use. Its track is a track of the main thread, whose packets are copied to the thread
+ */
+export declare class RemoteSender {
+    #private;
+    readonly onPictureLossIndication: Event<[]>;
+    /**
+     * The sender of a transceiver
+     * @param transceiver
+     */
+    constructor(transceiver: RemoteTransceiver);
+    get track(): MediaStreamTrack | null;
+    replaceTrack(track: MediaStreamTrack | null): Promise<void>;
+    setStreams(streams: MediaStream[]): void;
+    /**
+     * Its track, as known in the main thread
+     * @param track
+     * @internal
+     */
+    set(track: MediaStreamTrack | null): void;
+}
+/**
+ * The receiver of a transceiver of a connection served in a worker thread: its track is the one received in the
+ * thread, its packets coming from there while they are wanted
+ */
+export declare class RemoteReceiver {
+    #private;
+    /**
+     * The receiver of a transceiver, its track the one of a new transceiver until the thread tells it
+     * @param kind
+     */
+    constructor(kind: MediaKind);
+    get track(): MediaStreamTrack;
+    /**
+     * Its track, as the thread reported
+     * @param track
+     * @internal
+     */
+    set(track: MediaStreamTrack): void;
+}
+/**
+ * A transceiver of a connection served in a worker thread, in the main thread: the members of a transceiver of the
+ * engine that RtpTransceiver uses. Its state is the one the thread last reported, or the one the changes made here give
+ * until the thread tells it
+ */
+export declare class RemoteTransceiver {
+    #private;
+    readonly connection: RemoteConnection;
+    readonly ref: string;
+    readonly kind: MediaKind;
+    readonly sender: RemoteSender;
+    readonly receiver: RemoteReceiver;
+    mid: string | null;
+    currentDirection: RtpTransceiverDirection | 'stopped' | null;
+    reusable: boolean;
+    /**
+     * A transceiver of a connection
+     * @param connection
+     * @param ref
+     * @param kind
+     * @param direction
+     */
+    constructor(connection: RemoteConnection, ref: string, kind: MediaKind, direction: RtpTransceiverDirection);
+    get direction(): RtpTransceiverDirection;
+    set direction(direction: RtpTransceiverDirection);
+    stop(): void;
+    /**
+     * The state the thread reported
+     * @param info
+     * @param sending The track sent, as known here
+     * @param receiving The track received
+     * @internal
+     */
+    update(info: PeerTransceiverInfo, sending: MediaStreamTrack | null, receiving: MediaStreamTrack): void;
+    /**
+     * The direction a change made here gives, until the thread tells it
+     * @param direction
+     * @internal
+     */
+    changed(direction: RtpTransceiverDirection): void;
+}
+/**
+ * A connection served in a worker thread, in the main thread: the members of a connection of the engine that
+ * PeerConnection uses. Its methods are requests to the thread; its state is the one the thread last reported (with its
+ * events, and with the reply to each request, so it is the one of the thread once a method resolves). The changes of
+ * its transceivers are numbered: the transceivers the thread tells are taken once it did all those made here
+ */
+export declare class RemoteConnection {
+    #private;
+    readonly onIceCandidate: Event<[SignalingCandidate | undefined]>;
+    readonly onDataChannel: Event<[RemoteDataChannel]>;
+    readonly onTransceiverAdded: Event<[RemoteTransceiver]>;
+    readonly onNegotiationneeded: Event<[]>;
+    readonly connectionStateChange: Event<[string]>;
+    readonly iceConnectionStateChange: Event<[string]>;
+    readonly iceGatheringStateChange: Event<[string]>;
+    readonly signalingStateChange: Event<[string]>;
+    /**
+     * A connection of a thread
+     * @param link
+     * @param conn
+     */
+    constructor(link: PeerThreadLink, conn: number);
+    /**
+     * Its number in its thread
+     * @internal
+     */
+    get conn(): number;
+    get connectionState(): PeerConnectionState['connectionState'];
+    get iceConnectionState(): string;
+    get iceGatheringState(): string;
+    get signalingState(): string;
+    get localDescription(): SignalingDescription | null;
+    get remoteDescription(): SignalingDescription | null;
+    get sctpTransport(): {
+        remoteMaxMessageSize: number;
+    } | undefined;
+    /**
+     * The largest message the other peer accepts, once known (0: no limit)
+     * @internal
+     */
+    get maxMessageSize(): number | null;
+    /**
+     * Listen to the track event
+     * @param event
+     * @param listener
+     */
+    on(event: 'track', listener: (...args: unknown[]) => void): this;
+    createOffer(options?: {
+        iceRestart?: boolean;
+    }): Promise<SignalingDescription>;
+    createAnswer(): Promise<SignalingDescription>;
+    setLocalDescription(description?: SignalingDescription): Promise<void>;
+    setRemoteDescription(description: SignalingDescription): Promise<void>;
+    addIceCandidate(candidate: {
+        candidate: string;
+        sdpMid?: string;
+        sdpMLineIndex?: number;
+        usernameFragment?: string;
+    }): Promise<void>;
+    createDataChannel(label: string, options?: DataChannelOptions): RemoteDataChannel;
+    /**
+     * Add a track to send, as the engine does: to a transceiver that may take it (one of a direction that sends first),
+     * else to a new one; the thread does the same with the transceiver chosen here
+     * @param track
+     * @param streams
+     */
+    addTrack(track: MediaStreamTrack, ...streams: MediaStream[]): RemoteSender;
+    removeTrack(sender: RemoteSender): void;
+    addTransceiver(trackOrKind: MediaStreamTrack | MediaKind, init?: {
+        direction?: RtpTransceiverDirection;
+        streams?: MediaStream[];
+    }): RemoteTransceiver;
+    getTransceivers(): RemoteTransceiver[];
+    getSenders(): RemoteSender[];
+    getReceivers(): RemoteReceiver[];
+    restartIce(): void;
+    getConfiguration(): {
+        iceServers: SignalingIceServer[];
+        iceTransportPolicy: 'all' | 'relay';
+    };
+    setConfiguration(configuration: {
+        iceServers?: SignalingIceServer[];
+        iceTransportPolicy?: 'all' | 'relay';
+    }): void;
+    /**
+     * Close the connection in its thread; resolves once closed there
+     */
+    close(): Promise<void>;
+    /**
+     * Send a message of the connection to its thread
+     * @param message
+     * @param transfer
+     * @internal
+     */
+    post(message: PeerToWorker, transfer?: ArrayBuffer[]): void;
+    /**
+     * A copy of bytes to send to the thread
+     * @param data
+     * @internal
+     */
+    pack(data: Uint8Array): {
+        bytes: Uint8Array;
+        transfer?: ArrayBuffer[];
+    };
+    /**
+     * Add to the last message waiting for the thread, or send a new one
+     * @param extend
+     * @param message
+     * @param transfer
+     * @internal
+     */
+    postOrExtend(extend: (last: PeerToWorker) => boolean, message: () => PeerToWorker, transfer?: ArrayBuffer[]): void;
+    /**
+     * Send a change of the transceivers, numbered
+     * @param change
+     * @internal
+     */
+    change(change: DistributiveOmit<PeerTransceiverChange, 'conn' | 'op'>): void;
+    /**
+     * Send the track of a sender in place of the one it sends
+     * @param transceiver
+     * @param track
+     * @internal
+     */
+    replaceTrack(transceiver: RemoteTransceiver, track: MediaStreamTrack | null): Promise<void>;
+    /**
+     * The state of the connection once open in its thread
+     * @param state
+     * @internal
+     */
+    opened(state: PeerConnectionState): void;
+    /**
+     * A message of its thread
+     * @param message
+     * @internal
+     */
+    handle(message: PeerFromWorker): void;
+    /**
+     * Its thread stopped: the connection fails, then closes, with its channels and its tracks
+     * @param failed Whether it failed (a thread stopping by itself), or was closed (the threads stopped)
+     * @internal
+     */
+    lost(failed: boolean): void;
+}
+/**
+ * Omit, for each member of a union
+ */
+type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+export {};

package/dist/types/peer/RtpPacket.d.ts

@@ -0,0 +1,112 @@
+import { RtpPacket as EngineRtpPacket } from '../lib/rtp/rtp/rtp.js';
+/**
+ * The fields of an {@link RtpPacket}.
+ */
+export interface RtpPacketInit {
+    /**
+     * The payload type: the codec of the payload, as the description numbers it.
+     */
+    payloadType: number;
+    /**
+     * The sequence number, from 0 to 65535, one more for each packet.
+     */
+    sequenceNumber: number;
+    /**
+     * The timestamp, in the units of the clock rate of the codec (90000 per second for the video, 48000 for Opus).
+     */
+    timestamp: number;
+    /**
+     * The synchronization source: the id of the stream of packets.
+     * @default 0
+     */
+    ssrc?: number;
+    /**
+     * The marker: set on the last packet of a video frame.
+     * @default false
+     */
+    marker?: boolean;
+    /**
+     * The payload: a piece of encoded audio or video.
+     */
+    payload: Uint8Array;
+}
+/**
+ * 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 declare class RtpPacket {
+    /**
+     * The payload type: the codec of the payload, as the description numbers it.
+     */
+    payloadType: number;
+    /**
+     * The sequence number, from 0 to 65535, one more for each packet.
+     */
+    sequenceNumber: number;
+    /**
+     * The timestamp, in the units of the clock rate of the codec.
+     */
+    timestamp: number;
+    /**
+     * The synchronization source: the id of the stream of packets.
+     */
+    ssrc: number;
+    /**
+     * The marker: set on the last packet of a video frame.
+     */
+    marker: boolean;
+    /**
+     * The payload: a piece of encoded audio or video.
+     */
+    payload: Buffer;
+    /**
+     * Create a packet.
+     * @param init The fields of the packet.
+     */
+    constructor(init: RtpPacketInit);
+    /**
+     * 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: Uint8Array): RtpPacket;
+    /**
+     * 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(): Buffer;
+}
+/**
+ * The packet of a packet of the engine
+ * @param packet
+ */
+export declare function rtpPacketOf(packet: EngineRtpPacket): RtpPacket;
+/**
+ * The packet of the engine of a packet
+ * @param packet
+ */
+export declare function enginePacketOf(packet: RtpPacket): EngineRtpPacket;

package/dist/types/peer/RtpTransceiver.d.ts

@@ -0,0 +1,167 @@
+import type { RTCRtpReceiver } from '../lib/peer/media/rtpReceiver.js';
+import type { RTCRtpSender } from '../lib/peer/media/rtpSender.js';
+import type { RTCRtpTransceiver } from '../lib/peer/media/rtpTransceiver.js';
+import { type MediaKind, MediaTrack } from './MediaTrack.js';
+/**
+ * The direction of a {@link RtpTransceiver}: `sendrecv`, `sendonly`, `recvonly` or `inactive`.
+ */
+export type RtpTransceiverDirection = 'sendrecv' | 'sendonly' | 'recvonly' | 'inactive';
+/**
+ * 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 declare class RtpSender {
+    #private;
+    /**
+     * Wrap a sender of the engine
+     * @param sender
+     * @internal
+     */
+    constructor(sender: RTCRtpSender);
+    /**
+     * The track sent; `null` when none.
+     */
+    get track(): MediaTrack | 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)
+     * ```
+     */
+    replaceTrack(track: MediaTrack | null): Promise<void>;
+    /**
+     * 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: string[]): void;
+}
+/**
+ * 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 declare class RtpReceiver {
+    #private;
+    /**
+     * Wrap a receiver of the engine
+     * @param receiver
+     * @internal
+     */
+    constructor(receiver: RTCRtpReceiver);
+    /**
+     * The track received.
+     */
+    get track(): MediaTrack;
+}
+/**
+ * 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 declare class RtpTransceiver {
+    #private;
+    /**
+     * Wrap a transceiver of the engine
+     * @param transceiver
+     * @internal
+     */
+    constructor(transceiver: RTCRtpTransceiver);
+    /**
+     * The media id of its line in the description; `null` until negotiated.
+     */
+    get mid(): string | null;
+    /**
+     * `audio` or `video`.
+     */
+    get kind(): MediaKind;
+    /**
+     * The direction wanted; changing it makes the connection negotiate.
+     */
+    get direction(): RtpTransceiverDirection;
+    /**
+     * Change the direction wanted.
+     * @param direction The direction.
+     */
+    set direction(direction: RtpTransceiverDirection);
+    /**
+     * The direction negotiated, `stopped` once stopped; `null` until negotiated.
+     */
+    get currentDirection(): RtpTransceiverDirection | 'stopped' | null;
+    /**
+     * The sending side.
+     */
+    get sender(): RtpSender;
+    /**
+     * The receiving side.
+     */
+    get receiver(): RtpReceiver;
+    /**
+     * 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(): void;
+}
+/**
+ * The sender of a sender of the engine, created once
+ * @param sender
+ */
+export declare function senderOf(sender: RTCRtpSender): RtpSender;
+/**
+ * The sender of the engine of a sender
+ * @param sender
+ */
+export declare function engineSenderOf(sender: RtpSender): RTCRtpSender;
+/**
+ * The receiver of a receiver of the engine, created once
+ * @param receiver
+ */
+export declare function receiverOf(receiver: RTCRtpReceiver): RtpReceiver;
+/**
+ * The transceiver of a transceiver of the engine, created once
+ * @param transceiver
+ */
+export declare function transceiverOf(transceiver: RTCRtpTransceiver): RtpTransceiver;