@simplito/privmx-webendpoint/dist/service/StreamApi.d.ts

PrivMX Web Endpoint library

import { Types } from "../ServerTypes";
import * as EndpointTypes from "../Types";
import { AudioLevelsStats, WebRtcClient } from "../webStreams/WebRtcClient";
import { DataChannelMeta } from "../webStreams/types/ApiTypes";
import { BaseApi } from "./BaseApi";
import { ContainerPolicy, PagingList, PagingQuery, StreamInfo, StreamEventSelectorType, StreamEventType, StreamRoom, UserWithPubKey, StreamHandle, StreamSubscription, StreamPublishResult, RemoteStreamListener } from "../Types";
import { StreamApiNative } from "../api/StreamApiNative";
export interface StreamTrack {
    id: Types.StreamTrackId;
    streamHandle: StreamHandle;
    track?: MediaStreamTrack;
    dataChannelMeta: DataChannelMeta;
    published: Boolean;
    markedToRemove?: boolean;
}
/**
 * `StreamApi` is a class representing Endpoint's API for Stream Rooms.
 */
export declare class StreamApi extends BaseApi {
    private native;
    private client;
    constructor(native: StreamApiNative, ptr: number, client: WebRtcClient);
    private streams;
    private streamTracks;
    /**
     * Creates a new Stream Room in given Context.
     *
     * @param {string} contextId ID of the Context to create the Stream Room in
     * @param {UserWithPubKey[]} users array of UserWithPubKey structs which indicates who will have access to the created Stream Room
     * @param {UserWithPubKey[]} managers array of UserWithPubKey structs which indicates who will have access (and management rights) to the created Stream Room
     * @param {Uint8Array} publicMeta public (unencrypted) metadata
     * @param {Uint8Array} privateMeta private (encrypted) metadata
     * @param {ContainerPolicy} policies Stream Room's policies (pass `undefined` to use defaults)
     * @returns {string} ID of the created Stream Room
     */
    createStreamRoom(contextId: string, users: UserWithPubKey[], managers: UserWithPubKey[], publicMeta: Uint8Array, privateMeta: Uint8Array, policies?: ContainerPolicy): Promise<Types.StreamRoomId>;
    /**
     * Updates an existing Stream Room.
     *
     * @param {string} streamRoomId ID of the Stream Room to update
     * @param {UserWithPubKey[]} users array of UserWithPubKey structs which indicates who will have access to the Stream Room
     * @param {UserWithPubKey[]} managers array of UserWithPubKey structs which indicates who will have access (and management rights) to the Stream Room
     * @param {Uint8Array} publicMeta public (unencrypted) metadata
     * @param {Uint8Array} privateMeta private (encrypted) metadata
     * @param {number} version current version of the updated Stream Room
     * @param {boolean} force force update (without checking version)
     * @param {boolean} forceGenerateNewKey force to regenerate a key for the Stream Room
     * @param {ContainerPolicy} policies Stream Room's policies (pass `undefined` to keep current/defaults)
     */
    updateStreamRoom(streamRoomId: Types.StreamRoomId, users: UserWithPubKey[], managers: UserWithPubKey[], publicMeta: Uint8Array, privateMeta: Uint8Array, version: number, force: boolean, forceGenerateNewKey: boolean, policies?: ContainerPolicy): Promise<void>;
    /**
     * Gets a list of Stream Rooms in given Context.
     *
     * @param {string} contextId ID of the Context to get the Stream Rooms from
     * @param {PagingQuery} query struct with list query parameters
     * @returns {PagingList<StreamRoom>} list of Stream Rooms
     */
    listStreamRooms(contextId: string, query: PagingQuery): Promise<PagingList<StreamRoom>>;
    /**
     * Joins a Stream Room.
     *
     * This is required before calling `createStream`/`publishStream` and before subscribing to remote streams
     * in the room.
     *
     * @param {string} streamRoomId ID of the Stream Room to join
     */
    joinStreamRoom(streamRoomId: Types.StreamRoomId): Promise<void>;
    /**
     * Leaves a Stream Room.
     *
     * @param {string} streamRoomId ID of the Stream Room to leave
     */
    leaveStreamRoom(streamRoomId: Types.StreamRoomId): Promise<void>;
    /**
     * Enables server-side recording for the Stream Room.
     *
     * @param {string} streamRoomId ID of the Stream Room
     */
    enableStreamRoomRecording(streamRoomId: Types.StreamRoomId): Promise<void>;
    /**
     * Gets encryption keys used for Stream Room recordings.
     *
     * @param {string} streamRoomId ID of the Stream Room
     * @returns {EndpointTypes.RecordingEncKey[]} list of recording encryption keys
     */
    getStreamRoomRecordingKeys(streamRoomId: Types.StreamRoomId): Promise<EndpointTypes.RecordingEncKey[]>;
    /**
     * Gets a single Stream Room by given Stream Room ID.
     *
     * @param {string} streamRoomId ID of the Stream Room to get
     * @returns {StreamRoom} information about the Stream Room
     */
    getStreamRoom(streamRoomId: Types.StreamRoomId): Promise<StreamRoom>;
    /**
     * Deletes a Stream Room by given Stream Room ID.
     *
     * @param {string} streamRoomId ID of the Stream Room to delete
     */
    deleteStreamRoom(streamRoomId: Types.StreamRoomId): Promise<void>;
    /**
     * Creates a local Stream handle for publishing media in given Stream Room.
     *
     * Call `addStreamTrack`/`removeStreamTrack` to stage tracks and `publishStream`/`updateStream` to send
     * changes to the server.
     *
     * @param {string} streamRoomId ID of the Stream Room to create the stream in
     * @returns {StreamHandle} handle to a local Stream instance
     */
    createStream(streamRoomId: Types.StreamRoomId): Promise<StreamHandle>;
    /**
     * Gets a list of currently published streams in given Stream Room.
     *
     * @param {string} streamRoomId ID of the Stream Room to list streams from
     * @returns {StreamInfo[]} list of StreamInfo structs describing currently published streams
     */
    listStreams(streamRoomId: Types.StreamRoomId): Promise<StreamInfo[]>;
    /**
     * Adds a local media track definition to a Stream handle.
     *
     * The track is staged locally and becomes visible to others after `publishStream`/`updateStream`.
     *
     * @param {StreamHandle} streamHandle handle returned by `createStream`
     * @param {Types.StreamTrackInit} meta track/data channel metadata (track: `MediaStreamTrack`, dataChannel: `DataChannelMeta`)
     * @returns {string} StreamTrackId assigned locally for this track
     * @throws {Error} when the given `streamHandle` does not exist or the same browser track is already staged
     */
    addStreamTrack(streamHandle: StreamHandle, meta: Types.StreamTrackInit): Promise<Types.StreamTrackId>;
    /**
     * Removes a previously added media track from a Stream handle.
     *
     * For already published streams the removal is applied on `updateStream`.
     *
     * @param {StreamHandle} streamHandle handle returned by `createStream`
     * @param {Types.StreamTrackInit} meta media track metadata previously passed to `addStreamTrack`
     * @throws {Error} when the given `streamHandle` does not exist
     */
    removeStreamTrack(streamHandle: StreamHandle, meta: Types.StreamTrackInit): Promise<void>;
    /**
     * Publishes the Stream (with currently staged tracks) to the server.
     *
     * @param {StreamHandle} streamHandle handle returned by `createStream`
     * @param {(state: RTCPeerConnectionState) => void} onStreamState optional callback invoked on RTCPeerConnection state changes
     * @returns {StreamPublishResult} result of the publish operation
     * @throws {Error} when the given `streamHandle` does not exist
     */
    publishStream(streamHandle: StreamHandle, onStreamState?: (state: RTCPeerConnectionState) => void): Promise<StreamPublishResult>;
    /**
     * Updates a published Stream after adding/removing tracks.
     *
     * @param {StreamHandle} streamHandle handle returned by `createStream`
     * @returns {StreamPublishResult} result of the update operation
     * @throws {Error} when the given `streamHandle` does not exist
     */
    updateStream(streamHandle: StreamHandle): Promise<StreamPublishResult>;
    private filterMapByValue;
    /**
     * Stops publishing the Stream.
     *
     * @param {StreamHandle} streamHandle handle returned by `createStream`
     * @throws {Error} when the given `streamHandle` does not exist
     */
    unpublishStream(streamHandle: StreamHandle): Promise<void>;
    /**
     * Subscribes to selected remote streams (and optionally specific tracks) in the Stream Room.
     *
     * @param {string} streamRoomId ID of the Stream Room
     * @param {EndpointTypes.StreamSubscription[]} subscriptions list of remote streams/tracks to subscribe to
     */
    subscribeToRemoteStreams(streamRoomId: Types.StreamRoomId, subscriptions: EndpointTypes.StreamSubscription[]): Promise<void>;
    /**
     * Modifies current remote streams subscriptions.
     *
     * @param {string} streamRoomId ID of the Stream Room
     * @param {EndpointTypes.StreamSubscription[]} subscriptionsToAdd list of subscriptions to add
     * @param {StreamSubscription[]} subscriptionsToRemove list of subscriptions to remove
     */
    modifyRemoteStreamsSubscriptions(streamRoomId: Types.StreamRoomId, subscriptionsToAdd: EndpointTypes.StreamSubscription[], subscriptionsToRemove: StreamSubscription[]): Promise<void>;
    /**
     * Unsubscribes from selected remote streams (and optionally specific tracks) in the Stream Room.
     *
     * @param {string} streamRoomId ID of the Stream Room
     * @param {StreamSubscription[]} subscriptions list of subscriptions to remove
     */
    unsubscribeFromRemoteStreams(streamRoomId: Types.StreamRoomId, subscriptions: StreamSubscription[]): Promise<void>;
    /**
     * Registers a listener for remote tracks in the Stream Room.
     *
     * @param {RemoteStreamListener} listener listener configuration
     * @param {string} listener.streamRoomId ID of the Stream Room
     * @param {number} [listener.streamId] optional remote Stream ID to filter events (omit for all streams)
     * @param {(event: RTCTrackEvent) => void} listener.onRemoteStreamTrack callback invoked for incoming remote tracks
     */
    addRemoteStreamListener(listener: RemoteStreamListener): void;
    /**
     * Subscribe for the Stream Room events on the given subscription query.
     *
     * @param {string[]} subscriptionQueries list of queries
     * @return list of subscriptionIds in maching order to subscriptionQueries
     */
    subscribeFor(subscriptionQueries: string[]): Promise<string[]>;
    /**
     * Unsubscribe from events for the given subscriptionId.
     * @param {string[]} subscriptionIds list of subscriptionId
     */
    unsubscribeFrom(subscriptionIds: string[]): Promise<void>;
    /**
     * Generate subscription Query for the Stream Room events.
     * @param {EventType} eventType type of event which you listen for
     * @param {EventSelectorType} selectorType scope on which you listen for events
     * @param {string} selectorId ID of the selector
     * @returns {string} subscription ID
     */
    buildSubscriptionQuery(eventType: StreamEventType, selectorType: StreamEventSelectorType, selectorId: string): Promise<string>;
    /**
     * Registers a callback for audio level statistics produced by the WebRTC client.
     *
     * @param {(stats: AudioLevelsStats) => void} onStats callback invoked with current audio levels stats
     */
    addAudioLevelStatsListener(onStats: (stats: AudioLevelsStats) => void): Promise<void>;
    /**
     * Sends binary data over a WebRTC DataChannel associated with a published Stream data track.
     *
     * @param {Types.StreamTrackId} streamTrackId StreamTrackId of the data track created via `addStreamTrack`
     * @param {Uint8Array} data bytes to send to remote participants
     * @throws {Error} when there is no DataTrack (or DataChannel) for the given `streamTrackId`
     */
    sendData(streamTrackId: Types.StreamTrackId, data: Uint8Array): Promise<void>;
}