membrane_rtc_engine

import { SerializedMediaEvent } from "./mediaEvent";
/**
 * Interface describing Peer.
 */
export interface Peer {
    /**
     * Peer's id. It is assigned by user in custom logic that use backend API.
     */
    id: string;
    /**
     * Any information that was provided in {@link join}.
     */
    metadata: any;
    /**
     * Mapping between track's id (generated by rtc engine) and its metadata. Track metadata
     * can be set using {@link addTrack}. Track id is generated by RTC engine.
     */
    trackIdToMetadata: Map<string, any>;
}
/**
 * Type describing track's Bandwidth limit in kbps. 0 is interpreted as unlimited bandwidth.
 */
export declare type BandwidthLimit = number;
/**
 * Config passed to {@link MembraneWebRTC}.
 */
export interface MembraneWebRTCConfig {
    callbacks: Callbacks;
    rtcConfig?: RTCConfiguration;
}
/**
 * Track's context i.e. all data that can be useful when operating on track.
 */
export interface TrackContext {
    track: MediaStreamTrack | null;
    /**
     * Stream this track belongs to.
     */
    stream: MediaStream | null;
    /**
     * Peer this track comes from.
     */
    peer: Peer;
    /**
     * Track id. It is generated by RTC engine and takes form `peer_id:<random_uuidv4>`.
     * It is WebRTC agnostic i.e. it does not contain `mid` or `stream id`.
     */
    trackId: string;
    /**
     * Flag indicating whether track is a simulcast one or not.
     */
    isSimulcast: boolean;
    /**
     * Any info that was passed in {@link addTrack}.
     */
    metadata: any;
    maxBandwidth?: BandwidthLimit;
}
/**
 * Type describing possible track encodings.
 * At the moment, if track was added as a simulcast one ({@link addTrack})
 * it will be transmitted to the server in two versions - low and high.
 */
export declare type TrackEncoding = "l" | "h";
/**
 * Callbacks that has to be implemented by user.
 */
export interface Callbacks {
    /**
     * Called each time MembraneWebRTC need to send some data to the server.
     */
    onSendMediaEvent: (mediaEvent: SerializedMediaEvent) => void;
    /**
     * Called when peer was accepted. Triggered by {@link join}
     */
    onJoinSuccess?: (peerId: string, peersInRoom: [Peer]) => void;
    /**
     * Called when peer was not accepted. Triggered by {@link join}
     * @param metadata - Passthru for client application to communicate further actions to frontend
     */
    onJoinError?: (metadata: any) => void;
    /**
     * Called when data in a new track arrives.
     *
     * This callback is always called after {@link onTrackAdded}.
     * It informs user that data related to the given track arrives and can be played or displayed.
     */
    onTrackReady?: (ctx: TrackContext) => void;
    /**
     * Called each time the peer 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 onTrackReady}
     */
    onTrackAdded?: (ctx: TrackContext) => void;
    /**
     * Called when some track will no longer be sent.
     *
     * It will also be called before {@link onPeerLeft} for each track of this peer.
     */
    onTrackRemoved?: (ctx: TrackContext) => void;
    /**
     * Called each time peer has its track metadata updated.
     */
    onTrackUpdated?: (ctx: TrackContext) => void;
    /**
     * Called each time new peer joins the room.
     */
    onPeerJoined?: (peer: Peer) => void;
    /**
     * Called each time peer leaves the room.
     */
    onPeerLeft?: (peer: Peer) => void;
    /**
     * Called each time peer has its metadata updated.
     */
    onPeerUpdated?: (peer: Peer) => void;
    /**
     * Called in case of errors related to multimedia session e.g. ICE connection.
     */
    onConnectionError?: (message: string) => void;
    /**
     * Called 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
     */
    onTracksPriorityChanged?: (enabledTracks: TrackContext[], disabledTracks: TrackContext[]) => void;
    /**
     * Called each time track encoding has changed.
     *
     * Track encoding can change in the following cases:
     * * when user requested a change
     * * when there was a significant change in network bandwidth and client library is
     * no longer able to receive given encoding
     * * when sender stopped sending some encoding (because of bandwidth change)
     *
     * @param {string} peerId - id of peer that owns track
     * @param {string} trackId - id of track that changed encoding
     * @param {TrackEncoding} encoding - new encoding
     */
    onTrackEncodingChanged?: (peerId: string, trackId: string, encoding: TrackEncoding) => void;
    /**
     * Called every time a local peer is removed by the server.
     */
    onRemoved?: (reason: string) => void;
}
/**
 * Main class that is responsible for connecting to the RTC Engine, sending and receiving media.
 */
export declare class MembraneWebRTC {
    private localTracksWithStreams;
    private trackIdToTrack;
    private connection?;
    private idToPeer;
    private localPeer;
    private localTrackIdToTrack;
    private midToTrackId;
    private disabledTrackEncodings;
    private rtcConfig;
    private readonly callbacks;
    constructor(config: MembraneWebRTCConfig);
    /**
     * Tries to join to the RTC Engine. If user is accepted then {@link onJoinSuccess}
     * will be called. In other case {@link onJoinError} is invoked.
     *
     * @param peerMetadata - Any information that other peers will receive in {@link onPeerJoined}
     * after accepting this peer
     *
     * @example
     * ```ts
     * let webrtc = new MembraneWebRTC(...)
     * webrtc.join({displayName: "Bob"})
     * ```
     */
    join: (peerMetadata: any) => void;
    /**
     * Feeds media event received from RTC Engine to {@link MembraneWebRTC}.
     * This function should be called whenever some media event from RTC Engine
     * was received and can result in {@link MembraneWebRTC} generating some other
     * media events.
     *
     * @param mediaEvent - String data received over custom signalling layer.
     *
     * @example
     * This example assumes pheonix 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) => void;
    private handleMediaEvent;
    /**
     * Adds track that will be sent to the RTC Engine.
     * @param track - Audio or video track e.g. from your microphone or camera.
     * @param stream  - Stream that this track belongs to.
     * @param trackMetadata - Any information about this track that other peers will
     * receive in {@link onPeerJoined}. E.g. this can source of the track - wheather it's
     * screensharing, webcam or some other media device.
     * @param isSimulcast - Defines whether track should be simulcasted or not.
     * At the moment simulcast track is sent in three versions - low, medium and high.
     * High resolution is the original track resolution, while medium and low resolutions
     * are the original track resoultion scaled down by 2 and 4 respectively.
     * Those settings are not configurable at the moment.
     * @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, stream: MediaStream, trackMetadata?: any, isSimulcast?: boolean, maxBandwidth?: BandwidthLimit): string;
    private addTrackToConnection;
    /**
     * Replaces a track that is being sent to the RTC Engine.
     * @param track - Audio or video track.
     * @param {string} trackId - Id of audio or video track to replace.
     * @param {MediaStreamTrack} newTrack
     * @param {any} [newMetadata] - 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, newTrackMetadata?: any): Promise<boolean>;
    /**
     * 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
     * @returns {Promise<boolean>} success
     */
    setTrackBandwidth(trackId: string, bandwidth: BandwidthLimit): Promise<boolean>;
    /**
     * Removes a track from connection that was being 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): void;
    /**
     * Prioritizes a track in connection to be always sent to browser.
     * @param {string} trackId - Id of video track to prioritize.
     */
    prioritizeTrack(trackId: string): void;
    /**
     * Unprioritizes a track.
     * @param {string} trackId - Id of video track to unprioritize.
     */
    unprioritizeTrack(trackId: string): void;
    /**
     * This function allows to adjust resolution and number of video tracks sent by an SFU to a client.
     *
     * @param {number} bigScreens - number of screens with big size
     * (if simulcast is used this will limit number of tracks sent with highest quality).
     * @param {number} smallScreens - number of screens with small size
     * (if simulcast is used this will limit number of tracks sent with lowest quality).
     * @param {number} mediumScreens - number of screens with medium size
     * (if simulcast is used this will limit number of tracks sent with medium quality).
     * @param {boolean} allSameSize - flag that indicates whether all screens should use the same quality
     */
    setPreferedVideoSizes(bigScreens: number, smallScreens: number, mediumScreens?: number, allSameSize?: boolean): void;
    /**
     * Selects track encoding that server should send to the client library.
     * @param {string} peerId - id of peer that owns track
     * @param {string} trackId - id of track
     * @param {TrackEncoding} encoding - encoding to receive
     * @example
     * ```ts
     * webrtc.selectTrackEncoding(incomingTrackCtx.peer.id, incomingTrackCtx.trackId, "l")
     * ```
     */
    selectTrackEncoding(peerId: string, trackId: string, encoding: TrackEncoding): void;
    /**
     * Enables track encoding so that it will be sent to the server.
     * @param {string} trackId - id of track
     * @param {TrackEncoding} encoding - encoding that will be enabled
     * @example
     * ```ts
     * const trackId = webrtc.addTrack(track, stream, {}, true);
     * webrtc.disableTrackEncoding(trackId, "l");
     * // wait some time
     * webrtc.enableTrackEncoding(trackId, "l");
     * ```
     */
    enableTrackEncoding(trackId: string, encoding: TrackEncoding): void;
    /**
     * Disables track encoding so that it will be no longer sent to the server.
     * @param {string} trackId - id of track
     * @param {rackEncoding} encoding - encoding that will be disabled
     * @example
     * ```ts
     * const trackId = webrtc.addTrack(track, stream, {}, true);
     * webrtc.disableTrackEncoding(trackId, "l");
     * ```
     */
    disableTrackEncoding(trackId: string, encoding: TrackEncoding): void;
    private findSender;
    /**
     * Updates the metadata for the current peer.
     * @param peerMetadata - Data about this peer that other peers will receive upon joining.
     *
     * If the metadata is different from what is already tracked in the room, the optional
     * callback `onPeerUpdated` will be triggered for other peers in the room.
     */
    updatePeerMetadata: (peerMetadata: 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 peers will receive upon joining.
     *
     * If the metadata is different from what is already tracked in the room, the optional
     * callback `onTrackUpdated` will be triggered for other peers in the room.
     */
    updateTrackMetadata: (trackId: string, trackMetadata: any) => void;
    private getMidToTrackId;
    /**
     * Leaves the room. This function should be called when user leaves 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 peer will be notified
     * that peer left in {@link onPeerLeft},
     */
    leave: () => void;
    /**
     * Cleans up {@link MembraneWebRTC} instance.
     */
    cleanUp: () => void;
    private getTrackId;
    private sendMediaEvent;
    private onAnswer;
    private addTransceiversIfNeeded;
    private createAndSendOffer;
    private getTrackIdToMetadata;
    private checkIfTrackBelongToPeer;
    private onOfferData;
    private onRemoteCandidate;
    private onLocalCandidate;
    private onTrack;
    private setTurns;
    private addPeer;
    private erasePeer;
    private eraseTrack;
    private getPeerId;
}
//# sourceMappingURL=membraneWebRTC.d.ts.map