UNPKG

@vonage/video

Version:

Package to interact with the Vonage Video API (Not OpenTok Compatible)

674 lines 28.9 kB
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