@fishjam-cloud/ts-client 0.5.1

package/dist/src/webrtc/tracks/RemoteTrack.js

@@ -0,0 +1,64 @@
+import { isTrackKind } from '../internal';
+/**
+ * This is a wrapper over `TrackContext` that adds additional properties such as:
+ * - `MLineId`: required to generate sdpOffer
+ *
+ * # Lifecycle, state transitions
+ *
+ * I identified the following states
+ * - on `trackAdded`
+ *   - trackContext.stream === null
+ *   - trackContext.track === null
+ *   - trackContext.trackKind === null
+ *   - mLineId === null
+ * - on `onSdpAnswer`
+ *   - trackContext.stream === null
+ *   - trackContext.track === null
+ *   - trackContext.trackKind === null
+ *   - mLineId !== null
+ * - on `trackReady`
+ *   - trackContext.stream !== null
+ *   - trackContext.track !== null
+ *   - trackContext.trackKind !== null
+ *   - mLineId !== null
+ */
+export class RemoteTrack {
+    id;
+    mLineId = null;
+    trackContext;
+    encodings = { h: false, m: false, l: false };
+    // todo this field is not exposed
+    targetEncoding = null;
+    constructor(id, trackContext) {
+        this.id = id;
+        this.trackContext = trackContext;
+    }
+    setMLineId = (mLineId) => {
+        this.mLineId = mLineId;
+    };
+    setReady = (stream, track) => {
+        if (!isTrackKind(track.kind))
+            throw new Error('Track has no kind');
+        this.trackContext.stream = stream;
+        this.trackContext.track = track;
+        this.trackContext.trackKind = track.kind;
+    };
+    disableTrackEncoding = (encoding) => {
+        this.encodings[encoding] = false;
+    };
+    enableTrackEncoding = (encoding) => {
+        this.encodings[encoding] = true;
+    };
+    setTargetTrackEncoding = (variant) => {
+        // todo implement validation
+        this.targetEncoding = variant;
+        const trackContext = this.trackContext;
+        if (!trackContext.simulcastConfig?.enabled) {
+            throw new Error('The track does not support changing its target variant');
+        }
+        const isValidTargetEncoding = !trackContext.simulcastConfig.activeEncodings.includes(variant);
+        if (isValidTargetEncoding) {
+            throw new Error(`The track does not support variant ${variant}`);
+        }
+    };
+}

package/dist/src/webrtc/tracks/TrackCommon.d.ts

@@ -0,0 +1,8 @@
+import type { MLineId, Encoding } from '../types';
+export type TrackId = string;
+export type EndpointId = string;
+export type TrackEncodings = Record<Encoding, boolean>;
+export interface TrackCommon {
+    mLineId: MLineId | null;
+    encodings: TrackEncodings;
+}

package/dist/src/webrtc/tracks/TrackCommon.js

@@ -0,0 +1 @@
+export {};

package/dist/src/webrtc/tracks/bandwidth.d.ts

@@ -0,0 +1 @@
+export declare const splitBandwidth: (rtcRtpEncodingParameters: RTCRtpEncodingParameters[], maxBandwidth: number) => RTCRtpEncodingParameters[];

package/dist/src/webrtc/tracks/bandwidth.js

@@ -0,0 +1,27 @@
+export const splitBandwidth = (rtcRtpEncodingParameters, maxBandwidth) => {
+    const bandwidth = maxBandwidth * 1024;
+    if (bandwidth === 0) {
+        return rtcRtpEncodingParameters.map((encoding) => ({
+            ...encoding,
+            maxBitrate: undefined,
+        }));
+    }
+    if (rtcRtpEncodingParameters.length === 0) {
+        // This most likely is a race condition. Log an error and prevent catastrophic failure
+        console.error("Attempted to limit bandwidth of the track that doesn't have any encodings");
+        return rtcRtpEncodingParameters.map((encoding) => ({ ...encoding }));
+    }
+    if (!rtcRtpEncodingParameters[0])
+        throw new Error('RTCRtpEncodingParameters is in invalid state');
+    // We are solving the following equation:
+    // x + (k0/k1)^2 * x + (k0/k2)^2 * x + ... + (k0/kn)^2 * x = bandwidth
+    // where x is the bitrate for the first encoding, kn are scaleResolutionDownBy factors
+    // square is dictated by the fact that k0/kn is a scale factor, but we are interested in the total number of pixels in the image
+    const firstScaleDownBy = rtcRtpEncodingParameters[0].scaleResolutionDownBy || 1;
+    const bitrate_parts = rtcRtpEncodingParameters.reduce((acc, value) => acc + (firstScaleDownBy / (value.scaleResolutionDownBy || 1)) ** 2, 0);
+    const x = bandwidth / bitrate_parts;
+    return rtcRtpEncodingParameters.map((encoding) => ({
+        ...encoding,
+        maxBitrate: x * (firstScaleDownBy / (encoding.scaleResolutionDownBy || 1)) ** 2,
+    }));
+};

package/dist/src/webrtc/tracks/encodings.d.ts

@@ -0,0 +1 @@
+export declare const getEncodingParameters: (parameters: RTCRtpSendParameters, bandwidth: number) => RTCRtpEncodingParameters[];

package/dist/src/webrtc/tracks/encodings.js

@@ -0,0 +1,7 @@
+import { splitBandwidth } from './bandwidth';
+export const getEncodingParameters = (parameters, bandwidth) => {
+    const unlimitedEncodings = [{}];
+    return parameters.encodings.length === 0
+        ? unlimitedEncodings
+        : splitBandwidth(parameters.encodings, bandwidth);
+};

package/dist/src/webrtc/tracks/transceivers.d.ts

@@ -0,0 +1,2 @@
+import type { TrackContextImpl } from '../internal';
+export declare const createTransceiverConfig: (trackContext: TrackContextImpl<unknown, unknown>) => RTCRtpTransceiverInit;

package/dist/src/webrtc/tracks/transceivers.js

@@ -0,0 +1,78 @@
+import { splitBandwidth } from './bandwidth';
+export const createTransceiverConfig = (trackContext) => {
+    if (!trackContext.track)
+        throw new Error(`Cannot create transceiver config for `);
+    if (trackContext.track.kind === 'audio') {
+        return createAudioTransceiverConfig(trackContext.stream);
+    }
+    return createVideoTransceiverConfig(trackContext, trackContext.maxBandwidth);
+};
+const createAudioTransceiverConfig = (stream) => {
+    return {
+        direction: 'sendonly',
+        streams: stream ? [stream] : [],
+    };
+};
+const createVideoTransceiverConfig = (trackContext, maxBandwidth) => {
+    if (!trackContext.simulcastConfig)
+        throw new Error(`Simulcast config for track ${trackContext.trackId} not found.`);
+    if (typeof maxBandwidth !== 'number' &&
+        trackContext.simulcastConfig.enabled) {
+        return createSimulcastTransceiverConfig(trackContext, maxBandwidth);
+    }
+    if (typeof maxBandwidth === 'number') {
+        return createNonSimulcastTransceiverConfig(trackContext, maxBandwidth);
+    }
+    throw new Error('LocalTrack is in invalid state!');
+};
+const createNonSimulcastTransceiverConfig = (trackContext, maxBandwidth) => {
+    return {
+        direction: 'sendonly',
+        sendEncodings: splitBandwidth([{ active: true }], maxBandwidth),
+        streams: trackContext.stream ? [trackContext.stream] : [],
+    };
+};
+const createSimulcastTransceiverConfig = (trackContext, maxBandwidth) => {
+    if (!trackContext.simulcastConfig)
+        throw new Error(`Simulcast config for track ${trackContext.trackId} not found.`);
+    const activeEncodings = trackContext.simulcastConfig.activeEncodings;
+    const encodings = [
+        {
+            rid: 'l',
+            active: activeEncodings.includes('l'),
+            // maxBitrate: 4_000_000,
+            scaleResolutionDownBy: 4.0,
+            //   scalabilityMode: "L1T" + TEMPORAL_LAYERS_COUNT,
+        },
+        {
+            rid: 'm',
+            active: activeEncodings.includes('m'),
+            scaleResolutionDownBy: 2.0,
+        },
+        {
+            rid: 'h',
+            active: activeEncodings.includes('h'),
+            // maxBitrate: 4_000_000,
+            // scalabilityMode: "L1T" + TEMPORAL_LAYERS_COUNT,
+        },
+    ];
+    return {
+        direction: 'sendonly',
+        // keep this array from low resolution to high resolution
+        // in other case lower resolution encoding can get
+        // higher max_bitrate
+        sendEncodings: calculateSimulcastEncodings(encodings, maxBandwidth),
+    };
+};
+const calculateSimulcastEncodings = (encodings, maxBandwidth) => {
+    return encodings
+        .filter((encoding) => encoding.rid)
+        .map((encoding) => {
+        const rid = encoding.rid;
+        const limit = maxBandwidth.get(rid) || 0;
+        return {
+            ...encoding,
+            maxBitrate: limit > 0 ? limit * 1024 : undefined,
+        };
+    });
+};

package/dist/src/webrtc/types.d.ts

@@ -0,0 +1,306 @@
+import type TypedEmitter from 'typed-emitter';
+import type { SerializedMediaEvent } from './mediaEvent';
+export type MetadataParser<ParsedMetadata> = (rawMetadata: unknown) => ParsedMetadata;
+export type LocalTrackId = string;
+export type MLineId = string;
+export type MediaStreamTrackId = string;
+export type RemoteTrackId = string;
+export type TrackKind = 'audio' | 'video';
+/**
+ * Type describing Voice Activity Detection statuses.
+ *
+ * - `speech` - voice activity has been detected
+ * - `silence` - lack of voice activity has been detected
+ */
+export type VadStatus = 'speech' | 'silence';
+/**
+ * Type describing maximal bandwidth that can be used, in kbps. 0 is interpreted as unlimited bandwidth.
+ */
+export type BandwidthLimit = number;
+/**
+ * Type describing bandwidth limit for simulcast track.
+ * It is a mapping (encoding => BandwidthLimit).
+ * If encoding isn't present in this mapping, it will be assumed that this particular encoding shouldn't have any bandwidth limit
+ */
+export type SimulcastBandwidthLimit = Map<Encoding, BandwidthLimit>;
+/**
+ * Type describing bandwidth limitation of a Track, including simulcast and non-simulcast tracks.
+ * A sum type of `BandwidthLimit` and `SimulcastBandwidthLimit`
+ */
+export type TrackBandwidthLimit = BandwidthLimit | SimulcastBandwidthLimit;
+/**
+ * Type describing possible reasons for currently selected encoding.
+ * - `other` - the exact reason couldn't be determined
+ * - `encodingInactive` - previously selected encoding became inactive
+ * - `lowBandwidth` - there is no longer enough bandwidth to maintain previously selected encoding
+ */
+export type EncodingReason = 'other' | 'encodingInactive' | 'lowBandwidth';
+/**
+ * Simulcast configuration passed to {@link WebRTCEndpoint.addTrack}.
+ *
+ * At the moment, simulcast track is initialized in three versions - low, medium and high.
+ * High resolution is the original track resolution, while medium and low resolutions
+ * are the original track resolution scaled down by 2 and 4 respectively.
+ */
+export interface SimulcastConfig {
+    /**
+     * Whether to simulcast track or not.
+     */
+    enabled: boolean;
+    /**
+     * List of initially active encodings.
+     *
+     * Encoding that is not present in this list might still be
+     * enabled using {@link WebRTCEndpoint.enableTrackEncoding}.
+     */
+    activeEncodings: Encoding[];
+    /**
+     * List of disabled encodings.
+     *
+     * Encoding that is present in this list was
+     * disabled using {@link WebRTCEndpoint.disableTrackEncoding}.
+     */
+    disabledEncodings: Encoding[];
+}
+/**
+ * Track's context i.e. all data that can be useful when operating on track.
+ */
+interface TrackContextFields<EndpointMetadata, TrackMetadata> {
+    readonly track: MediaStreamTrack | null;
+    /**
+     * Stream this track belongs to.
+     */
+    readonly stream: MediaStream | null;
+    /**
+     * Endpoint this track comes from.
+     */
+    readonly endpoint: Endpoint<EndpointMetadata, TrackMetadata>;
+    /**
+     * Track id. It is generated by RTC engine and takes form `endpoint_id:<random_uuidv4>`.
+     * It is WebRTC agnostic i.e. it does not contain `mid` or `stream id`.
+     */
+    readonly trackId: string;
+    /**
+     * Simulcast configuration.
+     * Only present for local tracks.
+     */
+    readonly simulcastConfig?: SimulcastConfig;
+    /**
+     * Any info that was passed in {@link WebRTCEndpoint.addTrack}.
+     */
+    readonly metadata?: TrackMetadata;
+    readonly rawMetadata: any;
+    readonly metadataParsingError?: any;
+    readonly maxBandwidth?: TrackBandwidthLimit;
+    readonly vadStatus: VadStatus;
+    /**
+     * Encoding that is currently received.
+     * Only present for remote tracks.
+     */
+    readonly encoding?: Encoding;
+    /**
+     * The reason of currently selected encoding.
+     * Only present for remote tracks.
+     */
+    readonly encodingReason?: EncodingReason;
+}
+export interface TrackContextEvents<EndpointMetadata, TrackMetadata> {
+    /**
+     * Emitted each time track encoding has changed.
+     *
+     * Track encoding can change in the following cases:
+     * - when user requested a change
+     * - when sender stopped sending some encoding (because of bandwidth change)
+     * - when receiver doesn't have enough bandwidth
+     *
+     * Some of those reasons are indicated in {@link TrackContext.encodingReason}.
+     */
+    encodingChanged: (context: TrackContext<EndpointMetadata, TrackMetadata>) => void;
+    /**
+     * Emitted every time an update about voice activity is received from the server.
+     */
+    voiceActivityChanged: (context: TrackContext<EndpointMetadata, TrackMetadata>) => void;
+}
+export interface TrackContext<EndpointMetadata, TrackMetadata> extends TrackContextFields<EndpointMetadata, TrackMetadata>, TypedEmitter<Required<TrackContextEvents<EndpointMetadata, TrackMetadata>>> {
+}
+export type TrackNegotiationStatus = 'awaiting' | 'offered' | 'done';
+/**
+ * Type describing possible track encodings.
+ * - `"h"` - original encoding
+ * - `"m"` - original encoding scaled down by 2
+ * - `"l"` - original encoding scaled down by 4
+ *
+ * Notice that to make all encodings work, the initial
+ * resolution has to be at least 1280x720.
+ * In other case, browser might not be able to scale
+ * some encodings down.
+ */
+export type Encoding = 'l' | 'm' | 'h';
+export declare const isEncoding: (encoding: string) => encoding is Encoding;
+/**
+ * Events emitted by the {@link WebRTCEndpoint} instance.
+ */
+export interface WebRTCEndpointEvents<EndpointMetadata, TrackMetadata> {
+    /**
+     * Emitted each time WebRTCEndpoint need to send some data to the server.
+     */
+    sendMediaEvent: (mediaEvent: SerializedMediaEvent) => void;
+    /**
+     * Emitted when endpoint of this {@link WebRTCEndpoint} instance is ready. Triggered by {@link WebRTCEndpoint.connect}
+     */
+    connected: (endpointId: string, otherEndpoints: Endpoint<EndpointMetadata, TrackMetadata>[]) => void;
+    /**
+     * Emitted when endpoint of this {@link WebRTCEndpoint} instance was removed.
+     */
+    disconnected: () => void;
+    /**
+     * Emitted when data in a new track arrives.
+     *
+     * This event is always emitted after {@link trackAdded}.
+     * It informs the user that data related to the given track arrives and can be played or displayed.
+     */
+    trackReady: (ctx: TrackContext<EndpointMetadata, TrackMetadata>) => void;
+    /**
+     * Emitted each time the endpoint which was already in the room, adds new track. Fields track and stream will be set to null.
+     * These fields will be set to non-null value in {@link trackReady}
+     */
+    trackAdded: (ctx: TrackContext<EndpointMetadata, TrackMetadata>) => void;
+    /**
+     * Emitted when some track will no longer be sent.
+     *
+     * It will also be emitted before {@link endpointRemoved} for each track of this endpoint.
+     */
+    trackRemoved: (ctx: TrackContext<EndpointMetadata, TrackMetadata>) => void;
+    /**
+     * Emitted each time endpoint has its track metadata updated.
+     */
+    trackUpdated: (ctx: TrackContext<EndpointMetadata, TrackMetadata>) => void;
+    /**
+     * Emitted each time new endpoint is added to the room.
+     */
+    endpointAdded: (endpoint: Endpoint<EndpointMetadata, TrackMetadata>) => void;
+    /**
+     * Emitted each time endpoint is removed, emitted only for other endpoints.
+     */
+    endpointRemoved: (endpoint: Endpoint<EndpointMetadata, TrackMetadata>) => void;
+    /**
+     * Emitted each time endpoint has its metadata updated.
+     */
+    endpointUpdated: (endpoint: Endpoint<EndpointMetadata, TrackMetadata>) => void;
+    /**
+     * Emitted in case of errors related to multimedia session e.g. ICE connection.
+     */
+    connectionError: (error: {
+        message: string;
+        event: Event;
+    }) => void;
+    /**
+     * Emitted in case of errors related to multimedia session e.g. ICE connection.
+     */
+    signalingError: (error: {
+        message: string;
+    }) => void;
+    /**
+     * Currently, this event is only emitted when DisplayManager in RTC Engine is
+     * enabled and simulcast is disabled.
+     *
+     * Emitted when priority of video tracks have changed.
+     * @param enabledTracks - list of tracks which will be sent to client from SFU
+     * @param disabledTracks - list of tracks which will not be sent to client from SFU
+     */
+    tracksPriorityChanged: (enabledTracks: TrackContext<EndpointMetadata, TrackMetadata>[], disabledTracks: TrackContext<EndpointMetadata, TrackMetadata>[]) => void;
+    /**
+     * Emitted every time the server estimates client's bandwidth.
+     *
+     * @param {bigint} estimation - client's available incoming bitrate estimated
+     * by the server. It's measured in bits per second.
+     */
+    bandwidthEstimationChanged: (estimation: bigint) => void;
+    /**
+     * Emitted each time track encoding has been disabled.
+     */
+    trackEncodingDisabled: (context: TrackContext<EndpointMetadata, TrackMetadata>, encoding: string) => void;
+    /**
+     * Emitted each time track encoding has been enabled.
+     */
+    trackEncodingEnabled: (context: TrackContext<EndpointMetadata, TrackMetadata>, encoding: string) => void;
+    targetTrackEncodingRequested: (event: {
+        trackId: string;
+        variant: Encoding;
+    }) => void;
+    disconnectRequested: (event: any) => void;
+    localTrackAdded: (event: {
+        trackId: string;
+        track: MediaStreamTrack;
+        stream: MediaStream;
+        trackMetadata?: TrackMetadata;
+        simulcastConfig: SimulcastConfig;
+        maxBandwidth: TrackBandwidthLimit;
+    }) => void;
+    localTrackRemoved: (event: {
+        trackId: string;
+    }) => void;
+    localTrackReplaced: (event: {
+        trackId: string;
+        track: MediaStreamTrack | null;
+        metadata?: TrackMetadata;
+    }) => void;
+    localTrackMuted: (event: {
+        trackId: string;
+    }) => void;
+    localTrackUnmuted: (event: {
+        trackId: string;
+    }) => void;
+    localTrackBandwidthSet: (event: {
+        trackId: string;
+        bandwidth: BandwidthLimit;
+    }) => void;
+    localTrackEncodingBandwidthSet: (event: {
+        trackId: string;
+        rid: string;
+        bandwidth: BandwidthLimit;
+    }) => void;
+    localTrackEncodingEnabled: (event: {
+        trackId: string;
+        encoding: Encoding;
+    }) => void;
+    localTrackEncodingDisabled: (event: {
+        trackId: string;
+        encoding: Encoding;
+    }) => void;
+    localEndpointMetadataChanged: (event: {
+        metadata: EndpointMetadata;
+    }) => void;
+    localTrackMetadataChanged: (event: {
+        trackId: string;
+        metadata: TrackMetadata;
+    }) => void;
+}
+export type Config<EndpointMetadata, TrackMetadata> = {
+    endpointMetadataParser?: MetadataParser<EndpointMetadata>;
+    trackMetadataParser?: MetadataParser<TrackMetadata>;
+};
+/**
+ * Interface describing Endpoint.
+ */
+export interface Endpoint<EndpointMetadata, TrackMetadata> {
+    /**
+     * Endpoint's id. It is assigned by user in custom logic that use backend API.
+     */
+    id: string;
+    /**
+     * Type of the endpoint, e.g. "webrtc", "hls" or "rtsp".
+     */
+    type: string;
+    /**
+     * Any information that was provided in {@link WebRTCEndpoint.connect}.
+     */
+    metadata?: EndpointMetadata;
+    rawMetadata: any;
+    metadataParsingError?: any;
+    /**
+     * List of tracks that are sent by the endpoint.
+     */
+    tracks: Map<string, TrackContext<EndpointMetadata, TrackMetadata>>;
+}
+export {};

package/dist/src/webrtc/types.js

@@ -0,0 +1,2 @@
+const trackEncodings = ['l', 'm', 'h'];
+export const isEncoding = (encoding) => trackEncodings.includes(encoding);

package/dist/src/webrtc/voiceActivityDetection.d.ts

@@ -0,0 +1,2 @@
+import type { VadStatus } from './types';
+export declare const isVadStatus: (status: string) => status is VadStatus;

package/dist/src/webrtc/voiceActivityDetection.js

@@ -0,0 +1,2 @@
+const vadStatuses = ['speech', 'silence'];
+export const isVadStatus = (status) => vadStatuses.includes(status);