@fishjam-cloud/ts-client 0.5.1

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

@@ -0,0 +1,299 @@
+import type { MediaEvent, SerializedMediaEvent } from './mediaEvent';
+import type TypedEmitter from 'typed-emitter';
+import type { BandwidthLimit, Config, Encoding, SimulcastConfig, TrackBandwidthLimit, TrackContext, WebRTCEndpointEvents } from './types';
+import type { EndpointWithTrackContext } from './internal';
+import { ConnectionManager } from './ConnectionManager';
+declare const WebRTCEndpoint_base: new <EndpointMetadata_1, TrackMetadata_1>() => TypedEmitter<Required<WebRTCEndpointEvents<EndpointMetadata_1, TrackMetadata_1>>>;
+/**
+ * Main class that is responsible for connecting to the RTC Engine, sending and receiving media.
+ */
+export declare class WebRTCEndpoint<EndpointMetadata = any, TrackMetadata = any> extends WebRTCEndpoint_base<EndpointMetadata, TrackMetadata> {
+    private readonly endpointMetadataParser;
+    private readonly trackMetadataParser;
+    private readonly localTrackManager;
+    private readonly remote;
+    private readonly local;
+    private readonly commandsQueue;
+    bandwidthEstimation: bigint;
+    connectionManager?: ConnectionManager;
+    private clearConnectionCallbacks;
+    constructor(config?: Config<EndpointMetadata, TrackMetadata>);
+    /**
+     * Tries to connect to the RTC Engine. If user is successfully connected then {@link WebRTCEndpointEvents.connected}
+     * will be emitted.
+     *
+     * @param metadata - Any information that other endpoints will receive in {@link WebRTCEndpointEvents.endpointAdded}
+     * after accepting this endpoint
+     *
+     * @example
+     * ```ts
+     * let webrtc = new WebRTCEndpoint();
+     * webrtc.connect({displayName: "Bob"});
+     * ```
+     */
+    connect: (metadata: EndpointMetadata) => void;
+    /**
+     * Feeds media event received from RTC Engine to {@link WebRTCEndpoint}.
+     * This function should be called whenever some media event from RTC Engine
+     * was received and can result in {@link WebRTCEndpoint} generating some other
+     * media events.
+     *
+     * @param mediaEvent - String data received over custom signalling layer.
+     *
+     * @example
+     * This example assumes phoenix channels as signalling layer.
+     * As phoenix channels require objects, RTC Engine encapsulates binary data into
+     * map with one field that is converted to object with one field on the TS side.
+     * ```ts
+     * webrtcChannel.on("mediaEvent", (event) => webrtc.receiveMediaEvent(event.data));
+     * ```
+     */
+    receiveMediaEvent: (mediaEvent: SerializedMediaEvent) => Promise<void>;
+    private getEndpointId;
+    private onTrackReady;
+    /**
+     * Retrieves statistics related to the RTCPeerConnection.
+     * These statistics provide insights into the performance and status of the connection.
+     *
+     * @return {Promise<RTCStatsReport>}
+     *
+     * @external RTCPeerConnection#getStats()
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/getStats | MDN Web Docs: RTCPeerConnection.getStats()}
+     */
+    getStatistics(selector?: MediaStreamTrack | null): Promise<RTCStatsReport>;
+    /**
+     * Returns a snapshot of currently received remote tracks.
+     *
+     * @example
+     * if (webRTCEndpoint.getRemoteTracks()[trackId]?.simulcastConfig?.enabled) {
+     *   webRTCEndpoint.setTargetTrackEncoding(trackId, encoding);
+     * }
+     */
+    getRemoteTracks(): Record<string, TrackContext<EndpointMetadata, TrackMetadata>>;
+    /**
+     * Returns a snapshot of currently received remote endpoints.
+     */
+    getRemoteEndpoints(): Record<string, EndpointWithTrackContext<EndpointMetadata, TrackMetadata>>;
+    getLocalEndpoint(): EndpointWithTrackContext<EndpointMetadata, TrackMetadata>;
+    getBandwidthEstimation(): bigint;
+    private handleMediaEvent;
+    private onSdpAnswer;
+    /**
+     * Adds track that will be sent to the RTC Engine.
+     * @param track - Audio or video track e.g. from your microphone or camera.
+     * @param trackMetadata - Any information about this track that other endpoints will
+     * receive in {@link WebRTCEndpointEvents.endpointAdded}. E.g. this can source of the track - whether it's
+     * screensharing, webcam or some other media device.
+     * @param simulcastConfig - Simulcast configuration. By default simulcast is disabled.
+     * For more information refer to {@link SimulcastConfig}.
+     * @param maxBandwidth - maximal bandwidth this track can use.
+     * Defaults to 0 which is unlimited.
+     * This option has no effect for simulcast and audio tracks.
+     * For simulcast tracks use `{@link WebRTCEndpoint.setTrackBandwidth}.
+     * @returns {string} Returns id of added track
+     * @example
+     * ```ts
+     * let localStream: MediaStream = new MediaStream();
+     * try {
+     *   localAudioStream = await navigator.mediaDevices.getUserMedia(
+     *     AUDIO_CONSTRAINTS
+     *   );
+     *   localAudioStream
+     *     .getTracks()
+     *     .forEach((track) => localStream.addTrack(track));
+     * } catch (error) {
+     *   console.error("Couldn't get microphone permission:", error);
+     * }
+     *
+     * try {
+     *   localVideoStream = await navigator.mediaDevices.getUserMedia(
+     *     VIDEO_CONSTRAINTS
+     *   );
+     *   localVideoStream
+     *     .getTracks()
+     *     .forEach((track) => localStream.addTrack(track));
+     * } catch (error) {
+     *  console.error("Couldn't get camera permission:", error);
+     * }
+     *
+     * localStream
+     *  .getTracks()
+     *  .forEach((track) => webrtc.addTrack(track, localStream));
+     * ```
+     */
+    addTrack(track: MediaStreamTrack, trackMetadata?: TrackMetadata, simulcastConfig?: SimulcastConfig, maxBandwidth?: TrackBandwidthLimit): Promise<string>;
+    /**
+     * Replaces a track that is being sent to the RTC Engine.
+     * @param trackId - Audio or video track.
+     * @param {string} trackId - Id of audio or video track to replace.
+     * @param {MediaStreamTrack} newTrack
+     * @param {any} [newTrackMetadata] - Optional track metadata to apply to the new track. If no
+     *                              track metadata is passed, the old track metadata is retained.
+     * @returns {Promise<boolean>} success
+     * @example
+     * ```ts
+     * // setup camera
+     * let localStream: MediaStream = new MediaStream();
+     * try {
+     *   localVideoStream = await navigator.mediaDevices.getUserMedia(
+     *     VIDEO_CONSTRAINTS
+     *   );
+     *   localVideoStream
+     *     .getTracks()
+     *     .forEach((track) => localStream.addTrack(track));
+     * } catch (error) {
+     *   console.error("Couldn't get camera permission:", error);
+     * }
+     * let oldTrackId;
+     * localStream
+     *  .getTracks()
+     *  .forEach((track) => trackId = webrtc.addTrack(track, localStream));
+     *
+     * // change camera
+     * const oldTrack = localStream.getVideoTracks()[0];
+     * let videoDeviceId = "abcd-1234";
+     * navigator.mediaDevices.getUserMedia({
+     *      video: {
+     *        ...(VIDEO_CONSTRAINTS as {}),
+     *        deviceId: {
+     *          exact: videoDeviceId,
+     *        },
+     *      }
+     *   })
+     *   .then((stream) => {
+     *     let videoTrack = stream.getVideoTracks()[0];
+     *     webrtc.replaceTrack(oldTrackId, videoTrack);
+     *   })
+     *   .catch((error) => {
+     *     console.error('Error switching camera', error);
+     *   })
+     * ```
+     */
+    replaceTrack(trackId: string, newTrack: MediaStreamTrack | null, newTrackMetadata?: any): Promise<void>;
+    /**
+     * Updates maximum bandwidth for the track identified by trackId.
+     * This value directly translates to quality of the stream and, in case of video, to the amount of RTP packets being sent.
+     * In case trackId points at the simulcast track bandwidth is split between all of the variant streams proportionally to their resolution.
+     *
+     * @param {string} trackId
+     * @param {BandwidthLimit} bandwidth in kbps
+     * @returns {Promise<boolean>} success
+     */
+    setTrackBandwidth(trackId: string, bandwidth: BandwidthLimit): Promise<void>;
+    /**
+     * Updates maximum bandwidth for the given simulcast encoding of the given track.
+     *
+     * @param {string} trackId - id of the track
+     * @param {string} rid - rid of the encoding
+     * @param {BandwidthLimit} bandwidth - desired max bandwidth used by the encoding (in kbps)
+     * @returns
+     */
+    setEncodingBandwidth(trackId: string, rid: string, bandwidth: BandwidthLimit): Promise<void>;
+    /**
+     * Removes a track from connection that was sent to the RTC Engine.
+     * @param {string} trackId - Id of audio or video track to remove.
+     * @example
+     * ```ts
+     * // setup camera
+     * let localStream: MediaStream = new MediaStream();
+     * try {
+     *   localVideoStream = await navigator.mediaDevices.getUserMedia(
+     *     VIDEO_CONSTRAINTS
+     *   );
+     *   localVideoStream
+     *     .getTracks()
+     *     .forEach((track) => localStream.addTrack(track));
+     * } catch (error) {
+     *   console.error("Couldn't get camera permission:", error);
+     * }
+     *
+     * let trackId
+     * localStream
+     *  .getTracks()
+     *  .forEach((track) => trackId = webrtc.addTrack(track, localStream));
+     *
+     * // remove track
+     * webrtc.removeTrack(trackId)
+     * ```
+     */
+    removeTrack(trackId: string): Promise<void>;
+    /**
+     * Sets track variant that server should send to the client library.
+     *
+     * The variant will be sent whenever it is available.
+     * If chosen variant is temporarily unavailable, some other variant
+     * will be sent until the chosen variant becomes active again.
+     *
+     * @param {string} trackId - id of track
+     * @param {Encoding} variant - variant to receive
+     * @example
+     * ```ts
+     * webrtc.setTargetTrackEncoding(incomingTrackCtx.trackId, "l")
+     * ```
+     */
+    setTargetTrackEncoding(trackId: string, variant: Encoding): void;
+    /**
+     * Enables track encoding so that it will be sent to the server.
+     * @param {string} trackId - id of track
+     * @param {Encoding} encoding - encoding that will be enabled
+     * @example
+     * ```ts
+     * const trackId = webrtc.addTrack(track, stream, {}, {enabled: true, activeEncodings: ["l", "m", "h"]});
+     * webrtc.disableTrackEncoding(trackId, "l");
+     * // wait some time
+     * webrtc.enableTrackEncoding(trackId, "l");
+     * ```
+     */
+    enableTrackEncoding: (trackId: string, encoding: Encoding) => Promise<void>;
+    /**
+     * Disables track encoding so that it will be no longer sent to the server.
+     * @param {string} trackId - id of track
+     * @param {Encoding} encoding - encoding that will be disabled
+     * @example
+     * ```ts
+     * const trackId = webrtc.addTrack(track, stream, {}, {enabled: true, activeEncodings: ["l", "m", "h"]});
+     * webrtc.disableTrackEncoding(trackId, "l");
+     * ```
+     */
+    disableTrackEncoding: (trackId: string, encoding: Encoding) => Promise<void>;
+    /**
+     * Updates the metadata for the current endpoint.
+     * @param metadata - Data about this endpoint that other endpoints will receive upon being added.
+     *
+     * If the metadata is different from what is already tracked in the room, the optional
+     * event `endpointUpdated` will be emitted for other endpoint in the room.
+     */
+    updateEndpointMetadata: (metadata: any) => void;
+    /**
+     * Updates the metadata for a specific track.
+     * @param trackId - trackId (generated in addTrack) of audio or video track.
+     * @param trackMetadata - Data about this track that other endpoint will receive upon being added.
+     *
+     * If the metadata is different from what is already tracked in the room, the optional
+     * event `trackUpdated` will be emitted for other endpoints in the room.
+     */
+    updateTrackMetadata: (trackId: string, trackMetadata: any) => void;
+    /**
+     * Disconnects from the room. This function should be called when user disconnects from the room
+     * in a clean way e.g. by clicking a dedicated, custom button `disconnect`.
+     * As a result there will be generated one more media event that should be
+     * sent to the RTC Engine. Thanks to it each other endpoint will be notified
+     * that endpoint was removed in {@link WebRTCEndpointEvents.endpointRemoved},
+     */
+    disconnect: () => void;
+    /**
+     * Cleans up {@link WebRTCEndpoint} instance.
+     */
+    cleanUp: () => void;
+    private getTrackId;
+    sendMediaEvent: (mediaEvent: MediaEvent) => void;
+    private createAndSendOffer;
+    private onOfferData;
+    private setConnection;
+    private onRemoteCandidate;
+    private onLocalCandidate;
+    private onIceCandidateError;
+    private onConnectionStateChange;
+    private onIceConnectionStateChange;
+}
+export {};