@vonage/video
Version:
Package to interact with the Vonage Video API (Not OpenTok Compatible)
674 lines • 28.9 kB
TypeScript
import { AuthenticationType, Client } from '@vonage/server-client';
import { MediaMode } from './enums';
import { ArchiveLayout, ArchiveMode, ArchiveOptions, ArchiveSearchFilter, BroadcastConfig, BroadcastDetailsResponse, BroadcastSearchFilter, BroadcastUpdateConfig, CaptionOptions, CaptionStatusResponse, ClientTokenOptions, EnableCaptionResponse, ExperienceComposerListFilter, ExperienceComposerOptions, ExperienceComposerResponse, MultiArchiveResponse, MultiBroadcastResponse, MultiExperienceComposerResponse, MultiStreamLayoutResponse, ProjectDetailsResponse, SIPCallOptions, SIPCallResponse, Session, Signal, SingleArchiveResponse, SingleArchiveResponseBase, SingleStreamLayoutResponse, StreamClassList, WebSocketConfig, WebSocketConnectResponse } from './types';
/**
* Video Client for managing and interacting with video-related operations in your application.
* This client allows you to control sessions, streams, archives, broadcasts, and various video-related features.
*
* Usage:
* - Create and manage video sessions with customizable settings.
* - Control video streams, including muting, adding, and removing streams.
* - Initiate SIP calls and establish WebSockets for real-time communication.
* - Enable and disable captions for improved accessibility.
* - Start, stop, and manage video archives and broadcasts.
* - Render experiences and access detailed information about streams and archives.
* - Generate client tokens for secure session connections.
* - Perform various video-related operations with ease.
*
* @remarks
* The Video Client is designed to simplify video management tasks within your application.
* It provides a comprehensive set of methods and options to configure and control video interactions seamlessly.
*
* @example
* Create a standalone Video client
*
* ```ts
* import { Video } from '@vonage/video';
*
* const videoClient = new Video({
* apiKey: VONAGE_API_KEY,
* apiSecret: VONAGE_API_SECRET
* });
* ```
*
* @example
* Create an Video client from the Vonage client
*
* ```ts
* import { Vonage } from '@vonage/server-client';
*
* const vonage = new Vonage({
* apiKey: VONAGE_API_KEY,
* apiSecret: VONAGE_API_SECRET
* });
*
* const videoClient = vonage.video;
* ```
*/
export declare class Video extends Client {
protected authType: AuthenticationType;
/**
* Adds a stream to an existing archive, allowing you to include additional streams in the archive recording.
*
* @param {string} archiveId - The ID of the archive to which you want to add a stream.
* @param {string} streamId - The ID of the stream you want to add to the archive.
* @param {boolean} [audio=true] - Whether to include audio from the added stream (default: true).
* @param {boolean} [video=true] - Whether to include video from the added stream (default: true).
* @return {Promise<void>} A promise that resolves when the stream has been successfully added to the archive.
* @throws {Error} If an error occurs while adding the stream to the archive.
*
* @example
* ```ts
* await videoClient.addArchiveStream(ARCHIVE_ID, STREAM_ID);
* ```
*/
addArchiveStream(archiveId: string, streamId: string, audio?: boolean, video?: boolean): Promise<void>;
/**
* Adds a stream to an existing broadcast, allowing you to include additional streams in the live broadcast.
*
* @param {string} broadcastId - The ID of the broadcast to which you want to add a stream.
* @param {string} streamId - The ID of the stream you want to add to the broadcast.
* @return {Promise<void>} A promise that resolves when the stream has been successfully added to the broadcast.
* @throws {Error} If an error occurs while adding the stream to the broadcast.
*
* @example
* ```ts
* await videoClient.addStreamToBroadcast(BROADCAST_ID, STREAM_ID);
* ```
*/
addStreamToBroadcast(broadcastId: string, streamId: string): Promise<void>;
/**
* Connects to a WebSocket for a specified session using the provided client token and WebSocket configuration.
*
* @param {string} sessionId - The ID of the session to which you want to connect via WebSocket.
* @param {string} clientToken - The client token generated for authentication.
* @param {WebSocketConfig} config - The WebSocket configuration specifying the URI and optional parameters.
* @return {Promise<WebSocketConnectResponse>} A promise that resolves with WebSocket connection details upon successful connection.
* @throws {Error} If an error occurs during the WebSocket connection process.
*
* @example
* ```ts
* const result = await videoClient.connectToWebsocket(
* SESSION_ID,
* CLIENT_TOKEN,
* {
* uri: 'wss://example.com',
* },
* )
*
* console.log(result.id);
* ```
*/
connectToWebsocket(sessionId: string, clientToken: string, config: WebSocketConfig): Promise<WebSocketConnectResponse>;
/**
* Creates a new session with the specified options.
*
* @param {Object} [sessionOptions] - Optional session configuration options.
* @param {ArchiveMode} [sessionOptions.archiveMode=ArchiveMode.MANUAL] - The archive mode for the session.
* @param {MediaMode} [sessionOptions.mediaMode=MediaMode.ROUTED] - The media mode for the session.
* @param {string} [sessionOptions.location] - The location for the session.
* @return {Promise<Session>} A promise that resolves with details of the newly created session.
* @throws {Error} If an error occurs during the session creation process.
*
* @example
* Create a session with default options
* ```ts
* const session = await videoClient.createSession({});
* console.log(session.sessionId);
* ```
*
* @example
* Create a session with archive mode set to manual
* ```ts
* import { ArchiveMode } from '@vonage/video';
*
* const session = await videoClient.createSession({
* archiveMode: ArchiveMode.MANUAL,
* });
* console.log(session.sessionId);
* ```
*
* @example
* Create a session with location set to a specific region
* ```ts
* const session = await videoClient.createSession({
* location: 'eu',
* });
* console.log(session.sessionId);
* ```
*
* @example
* Create a session with media mode set to routed
* ```ts
* import { MediaMode } from '@vonage/video';
*
* const session = await videoClient.createSession({
* mediaMode: MediaMode.ROUTED,
* });
* console.log(session.sessionId);
* ```
*/
createSession(sessionOptions?: {
archiveMode?: ArchiveMode;
location?: string;
mediaMode?: MediaMode;
}): Promise<Session>;
/**
* Deletes an archive with the specified archive ID.
*
* @param {string} archiveId - The ID of the archive to delete.
* @return {Promise<void>} A promise that resolves when the archive is successfully deleted.
* @throws {Error} If an error occurs while deleting the archive or if the archive with the given ID does not exist.
*
* @example
* ```ts
* await videoClient.deleteArchive(ARCHIVE_ID);
* ```
*/
deleteArchive(archiveId: string): Promise<void>;
/**
* Disables captions for a specific caption ID.
*
* @param {string} captionId - The ID of the caption to disable.
* @return {Promise<void>} A promise that resolves when the captions are successfully disabled.
* @throws {Error} If an error occurs while disabling captions or if the caption with the given ID does not exist.
*
* @example
* ```ts
* await videoClient.disableCaptions(CAPTION_ID);
* ```
*/
disableCaptions(captionId: string): Promise<void>;
/**
* Disables force mute for a session, allowing audio for all streams.
*
* @param {string} sessionId - The ID of the session for which to disable force mute.
* @param {string[]} excludedStreamIds - An optional array of stream IDs to exclude from the force mute operation.
* @return {Promise<void>} A promise that resolves when the force mute is successfully disabled for the session.
* @throws {Error} If an error occurs while disabling force mute or if the session with the given ID does not exist.
*
* @example
* ```ts
* const forceMute = await videoClient.disableForceMute(SESSION_ID);
* console.log(forceMute.status);
* ```
*/
disableForceMute(sessionId: string, excludedStreamIds?: string[]): Promise<ProjectDetailsResponse>;
/**
* Disconnects a client from a session.
*
* @param {string} sessionId - The ID of the session from which to disconnect the client.
* @param {string} connectionId - The ID of the client's connection to disconnect.
* @return {Promise<void>} A promise that resolves when the client is successfully disconnected from the session.
* @throws {Error} If an error occurs while disconnecting the client or if the session or connection with the given IDs do not exist.
*
* @example
* ```ts
* await videoClient.disconnectClient(SESSION_ID, CONNECTION_ID);
* ```
*/
disconnectClient(sessionId: string, connectionId: string): Promise<void>;
/**
* Disconnects a WebSocket connection associated with a call or session.
*
* @param {string} callId - The ID of the call or session to which the WebSocket connection is associated.
* @return {Promise<void>} A promise that resolves when the WebSocket connection is successfully disconnected.
* @throws {Error} If an error occurs while disconnecting the WebSocket connection or if the call or session with the given ID does not exist.
*
* @example
* ```ts
* await videoClient.disconnectWebsocket(CALL_ID);
* ```
*/
disconnectWebsocket(callId: string): Promise<void>;
/**
* Enables captions for a session using the specified client token and caption options.
*
* @param {string} sessionId - The ID of the session to enable captions for.
* @param {string} clientToken - The client token associated with the session, used for authentication.
* @param {CaptionOptions} [captionOptions] - Optional caption options to configure caption behavior.
* @return {Promise<EnableCaptionResponse>} A promise that resolves with an `EnableCaptionResponse` containing information about the enabled captions.
* @throws {Error} If an error occurs while enabling captions or if the session with the given ID does not exist.
*
* @example
* ```ts
* const result = await videoClient.enableCaptions(SESSION_ID, CLIENT_TOKEN);
* console.log(result.captionId);
* ```
*/
enableCaptions(sessionId: string, clientToken: string, captionOptions?: CaptionOptions): Promise<EnableCaptionResponse>;
/**
* Forces muting of all streams in a session, except those specified in the `excludedStreamIds` array.
*
* @param {string} sessionId - The ID of the session in which to force mute streams.
* @param {string[]} [excludedStreamIds] - An optional array of stream IDs to exclude from muting.
* @return {Promise<ProjectDetailsResponse>} A promise that resolves with a `ProjectDetailsResponse` containing updated session details after muting.
* @throws {Error} If an error occurs while muting the streams or if the session with the given ID does not exist.
*
* @example
* ```ts
* const forceMute = await videoClient.forceMuteAll(SESSION_ID);
* console.log(forceMute.status);
* ```
*/
forceMuteAll(sessionId: string, excludedStreamIds?: string[]): Promise<ProjectDetailsResponse>;
/**
* Generates a client token for connecting to a session with the specified options.
*
* @param {string} sessionId - The ID of the session to generate the client token for.
* @param {ClientTokenOptions} [tokenOptions] - Optional token options including role, data, and expiration time.
* @return {string} A client token that can be used for authentication when connecting to a session.
*
* @example
* ```ts
* const token = videoClient.generateClientToken(SESSION_ID);
* console.log(`The token is ${token}`);
* ```
*/
generateClientToken(sessionId: string, tokenOptions?: ClientTokenOptions): string;
/**
* Retrieves information about a specific archive by its ID.
*
* @param {string} archiveId - The ID of the archive to retrieve.
* @return {Promise<SingleArchiveResponse>} A promise that resolves to the details of the requested archive.
*
* @example
* ```ts
* const archive = await videoClient.getArchive(ARCHIVE_ID);
* console.log(archive.createdAt);
* ```
*/
getArchive<T extends SingleArchiveResponseBase = SingleArchiveResponse>(archiveId: string): Promise<T>;
/**
* Retrieves information about a specific broadcast by its ID.
*
* @param {string} broadcastId - The ID of the broadcast to retrieve.
* @return {Promise<BroadcastDetailsResponse>} A promise that resolves to the details of the requested broadcast.
*
* ```ts
* const broadcast = await videoClient.getBroadcast(BROADCAST_ID);
* console.log(broadcast.createdAt);
* ```
*/
getBroadcast(broadcastId: string): Promise<BroadcastDetailsResponse>;
/**
* Retrieves the status of a caption by its ID.
*
* @param {string} captionId - The ID of the caption to retrieve the status for.
* @return {Promise<CaptionStatusResponse>} A promise that resolves to the status of the requested caption.
*
* @example
* ```ts
* const captionStatus = await videoClient.getCaptionStatus(CAPTION_ID);
* console.log(captionStatus.status);
* ```
*/
getCaptionStatus(captionId: string): Promise<CaptionStatusResponse>;
/**
* Retrieves the details of an Experience Composer render by its ID.
*
* @param {string} renderId - The ID of the Experience Composer render to retrieve.
* @return {Promise<ExperienceComposerResponse>} A promise that resolves to the details of the requested Experience Composer render.
*
* @example
* ```ts
* const render = await videoClient.getExperienceComposerRender(RENDER_ID);
* console.log(render.createdAt);
* ```
*/
getExperienceComposerRender(renderId: string): Promise<ExperienceComposerResponse>;
/**
* Retrieves information about one or more streams in a session.
*
* @param {string} sessionId - The ID of the session to retrieve stream information from.
* @param {string | undefined} [streamId] - Optional. The ID of a specific stream to retrieve information for.
* @return {Promise<MultiStreamLayoutResponse | SingleStreamLayoutResponse>} A promise that resolves to stream information. If a specific `streamId` is provided, it resolves to a single stream's information (SingleStreamLayoutResponse), otherwise, it resolves to multiple streams' information (MultiStreamLayoutResponse).
*
* @example
* ```ts
* const streamInfo = await videoClient.getStreamInfo(SESSION_ID);
*
* if (streamInfo.items) {
* streamInfo.items.forEach((item) => {
* console.log(item.id);
* });
* } else {
* console.log(streamInfo.id);
* }
* ```
*/
getStreamInfo(sessionId: string, streamId?: string): Promise<MultiStreamLayoutResponse | SingleStreamLayoutResponse>;
private stripBlankValues;
/**
* Initiates a SIP call within a session.
*
* @param {string} sessionId - The ID of the session in which to initiate the SIP call.
* @param {SIPCallOptions} options - The options for initiating the SIP call.
* @return {Promise<SIPCallResponse>} A promise that resolves to the SIP call response, including the call ID and other details.
*
* @example
* Start a SIP call with default options
* ```ts
* const sipCall = await videoClient.intiateSIPCall(SESSION_ID);
* console.log(sipCall.id);
* ```
*
* @example
* Start a SIP call with custom options
* ```ts
* const sipCall = await videoClient.intiateSIPCall(
* SESSION_ID,
* {
* uri: 'sip://example.com',
* }
* );
* console.log(sipCall.id);
* ```
*/
intiateSIPCall(sessionId: string, options: SIPCallOptions): Promise<SIPCallResponse>;
/**
* Lists Experience Composer renders based on the specified filter criteria.
*
* @param {ExperienceComposerListFilter} filter - An optional filter to apply when listing Experience Composer renders.
* @return {Promise<MultiExperienceComposerResponse>} A promise that resolves to a list of Experience Composer renders matching the filter criteria.
*
* @example
* ```ts
* const renders = await videoClient.listExperienceComposerRenders();
* for (const render of renders.items) {
* console.log(render.id);
* }
* ```
*/
listExperienceComposerRenders(filter: ExperienceComposerListFilter): Promise<MultiExperienceComposerResponse>;
/**
* Mutes or unmutes all streams in a session, optionally excluding specific stream IDs from muting.
*
* @param {string} sessionId - The ID of the session in which to mute or unmute streams.
* @param {boolean} active - `true` to mute all streams, `false` to unmute all streams.
* @param {string[]} excludedStreamIds - An optional array of stream IDs to exclude from muting/unmuting.
* @return {Promise<ProjectDetailsResponse>} A promise that resolves to the updated session details.
*
* @example
* ```ts
* const forceMute = await videoClient.muteAll(SESSION_ID);
* console.log(forceMute.status);
* ```
*/
protected muteAllStreams(sessionId: string, active: boolean, excludedStreamIds?: string[]): Promise<ProjectDetailsResponse>;
/**
* Mutes or unmutes a specific stream in a session.
*
* @param {string} sessionId - The ID of the session containing the stream.
* @param {string} streamId - The ID of the stream to mute or unmute.
* @return {Promise<ProjectDetailsResponse>} A promise that resolves to the updated session details.
*
* @example
* ```ts
* const forceMute = await videoClient.muteStream(SESSION_ID, STREAM_ID);
* console.log(forceMute.status);
* ```
*/
muteStream(sessionId: string, streamId: string): Promise<ProjectDetailsResponse>;
/**
* Sends DTMF (Dual-Tone Multi-Frequency) tones to a specific session or connection.
*
* @param {string} sessionId - The ID of the session to send DTMF tones to.
* @param {string} digits - The DTMF tones to play.
* @param {string} [connectionId] - Optional. The ID of the connection within the session to send DTMF tones to.
* @return {Promise<void>} A promise that resolves when the DTMF tones have been played.
*
* @example
* ```ts
* await videoClient.playDTMF(SESSION_ID, '1234');
* ```
*/
playDTMF(sessionId: string, digits: string, connectionId?: string): Promise<void>;
/**
* Removes a stream from an archive.
*
* @param {string} archiveId - The ID of the archive from which to remove the stream.
* @param {string} streamId - The ID of the stream to remove from the archive.
* @return {Promise<void>} A promise that resolves when the stream has been successfully removed from the archive.
*
* @example
* ```ts
* await videoClient.removeArchiveStream(ARCHIVE_ID, STREAM_ID);
* ```
*/
removeArchiveStream(archiveId: string, streamId: string): Promise<void>;
/**
* Removes a stream from a broadcast.
*
* @param {string} broadcastId - The ID of the broadcast from which to remove the stream.
* @param {string} streamId - The ID of the stream to remove from the broadcast.
* @return {Promise<void>} A promise that resolves when the stream has been successfully removed from the broadcast.
*
* @example
* ```ts
* await videoClient.removeStreamFromBroadcast(BROADCAST_ID, STREAM_ID);
* ```
*/
removeStreamFromBroadcast(broadcastId: string, streamId: string): Promise<void>;
/**
* Searches for archives based on the specified filter criteria.
*
* @param {ArchiveSearchFilter} [filter] - Optional filter criteria to narrow down the search.
* @return {Promise<MultiArchiveResponse>} A promise that resolves with the search results, including multiple archive items.
*
* @example
* ```ts
* const archives = await videoClient.searchArchives();
* for (const archive of archives.items) {
* console.log(archive.id);
* }
* ```
* @example
* Search for archives for a session
* ```ts
* const archives = await videoClient.searchArchives({
* sessionId: SESSION_ID,
* });
*
* for (const archive of archives.items) {
* console.log(archive.id);
* }
* ```
*/
searchArchives(filter?: ArchiveSearchFilter): Promise<MultiArchiveResponse>;
/**
* Searches for broadcasts based on the specified filter criteria.
*
* @param {BroadcastSearchFilter} [filter] - Optional filter criteria to narrow down the search.
* @return {Promise<MultiBroadcastResponse>} A promise that resolves with the search results, including multiple broadcast items.
*
* @example
* ```ts
* const broadcasts = await videoClient.searchBroadcasts();
* for (const broadcast of broadcasts.items) {
* console.log(broadcast.id);
* }
* ```
*
* @example
* Get braodcasts for a session
* ```ts
* const broadcasts = await videoClient.searchBroadcasts({
* sessionId: SESSION_ID,
* })
* for (const broadcast of broadcasts.items) {
* console.log(broadcast.id);
* }
* ```
*/
searchBroadcasts(filter?: BroadcastSearchFilter): Promise<MultiBroadcastResponse>;
/**
* Sends a signal to a session or a specific connection within a session.
*
* @param {Signal} signal - The signal to send, including a type and data.
* @param {string} sessionId - The ID of the session to which the signal will be sent.
* @param {string} [connectionId] - Optional. The ID of the connection within the session to which the signal will be sent. If not provided, the signal will be sent to the entire session.
* @return {Promise<void>} A promise that resolves when the signal is successfully sent.
*
* @example
* await videoClient.sendSignal(
* {
* type: 'text',
* data: 'Hello world!',
* },
* SESSION_ID,
* );
* ```
*/
sendSignal(signal: Signal, sessionId: string, connectionId?: string): Promise<void>;
/**
* Sets the stream class lists for one or more streams within a session.
*
* @param {string} sessionId - The ID of the session for which stream class lists will be set.
* @param {StreamClassList[]} settings - An array of objects specifying the stream ID and corresponding class lists to be set.
* @return {Promise<void>} A promise that resolves when the stream class lists are successfully set.
*
* @example
*
* ```ts
* await videoClient.setStreamClassLists(
* SESSION_ID,
* [
* {
* id: STREAM_ID,
* layoutClassList: ['full'],
* }
* ]
* )
* ```
*/
setStreamClassLists(sessionId: string, settings: StreamClassList[]): Promise<void>;
/**
* Starts an archive for a given session with optional configuration.
*
* @param {string} sessionId - The ID of the session to archive.
* @param {ArchiveOptions} [options] - Optional configuration for the archive, such as audio/video settings, layout, and more.
* @return {Promise<SingleArchiveResponse>} A promise that resolves with information about the started archive.
*
* @example
* ```ts
* const archive = await videoClient.startArchive(SESSION_ID);
* console.log(archive.id);
* ```
*/
startArchive<T extends SingleArchiveResponseBase = SingleArchiveResponse>(sessionId: string, options?: ArchiveOptions): Promise<T>;
/**
* Starts a broadcast for a given session with the specified configuration.
*
* @param {string} sessionId - The ID of the session to start broadcasting.
* @param {BroadcastConfig} config - Configuration for the broadcast, including stream settings, layout, and more.
* @return {Promise<BroadcastDetailsResponse>} A promise that resolves with information about the started broadcast.
*
* @example
* ```ts
* const broadcast = await videoClient.startBroadcast(
* SESSION_ID,
* {
* outputs: {
* hls: {
* lowLatency: true,
* }
* rtmp: [{
* serverUrl: 'rtmp://example.com',
* }],
* }
* }
* );
* ```
*/
startBroadcast(sessionId: string, config: BroadcastConfig): Promise<BroadcastDetailsResponse>;
/**
* Starts rendering an experience composer with the provided configuration.
*
* @param {string} sessionId - The ID of the session associated with the experience composer.
* @param {string} token - The client token for authentication.
* @param {ExperienceComposerOptions} config - Configuration options for the experience composer rendering.
* @return {Promise<ExperienceComposerResponse>} A promise that resolves with information about the started experience composer rendering.
*
* @example
* ```ts
*
* const render = await videoClient.startExperienceComposerRender(
* SESSION_ID,
* token,
* )
*
* console.log(render.id);
* ```
*/
startExperienceComposerRender(sessionId: string, token: string, config: ExperienceComposerOptions): Promise<ExperienceComposerResponse>;
/**
* Stops an archive with the given archive ID.
*
* @param {string} archiveId - The ID of the archive to stop.
* @return {Promise<SingleArchiveResponse>} A promise that resolves with information about the stopped archive.
*
* @example
* ```ts
* const archive = await videoClient.stopArchive(ARCHIVE_ID);
*
* console.log(archive.status);
* ```
*/
stopArchive(archiveId: string): Promise<SingleArchiveResponse>;
/**
* Stops a broadcast with the given broadcast ID.
*
* @param {string} broadcastId - The ID of the broadcast to stop.
* @return {Promise<BroadcastDetailsResponse>} A promise that resolves with information about the stopped broadcast.
*
* @example
* ```ts
* const broadcast = await videoClient.stopBroadcast(BROADCAST_ID);
* console.log(broadcast.status);
* ```
*/
stopBroadcast(broadcastId: string): Promise<BroadcastDetailsResponse>;
/**
* Stops an Experience Composer render with the given render ID.
*
* @param {string} renderId - The ID of the Experience Composer render to stop.
* @return {Promise<void>} A promise that resolves when the render is successfully stopped.
*
* @example
* ```ts
* await videoClient.stopExperienceComposerRender(RENDER_ID);
* ```
*/
stopExperienceComposerRender(renderId: string): Promise<void>;
/**
* Updates the layout of an archive with the given archive ID.
*
* @param {string} archiveId - The ID of the archive to update the layout for.
* @param {ArchiveLayout} layout - The new layout configuration to set for the archive.
* @return {Promise<void>} A promise that resolves when the layout is successfully updated.
*
* @example
* ```ts
* await videoClient.updateArchiveLayout(
* ```
*/
updateArchiveLayout(archiveId: string, layout: ArchiveLayout): Promise<void>;
/**
* Updates the configuration of a broadcast with the given broadcast ID.
*
* @param {BroadcastUpdateConfig} config - The configuration options to update the broadcast.
* @return {Promise<void>} A promise that resolves when the broadcast is successfully updated.
*
* @example
* ```ts
*
* await videoClient.updateBroadcast({
* broadcastId: BROADCAST_ID,
* hasAudio: true,
* })
* ```
*/
updateBroadcast(config: BroadcastUpdateConfig): Promise<void>;
}
//# sourceMappingURL=video.d.ts.map