@byteplus/rtc 4.52.2 → 4.54.0

package/index.d.ts

@@ -694,7 +694,12 @@ declare enum ErrorCode {
 	/** 
 	 * @brief The client side failed to identity error codes sent by cloud media processing. Please contact the technical support.
 	 */
-	SUBTITLE_ERR_UNKNOWN = "SUBTITLE_ERR_UNKNOWN"
+	SUBTITLE_ERR_UNKNOWN = "SUBTITLE_ERR_UNKNOWN",
+	
+	/** 
+	 * @brief Unexpected cross-room media stream forwarding API call. For example, calling `stopForwardStreamToRooms` when media forwarding has already stopped.
+	 */
+	UNEXPECTED_INVOKE_FORWARD_STREAM = "UNEXPECTED_INVOKE_FORWARD_STREAM"
 }
 declare enum AudioMixingError {
 	
@@ -990,7 +995,6 @@ export interface onSEIMessageEvent {
 }
 
 /** 
- * @hidden
  * @brief The SEI carried by the public video stream.
  */
 export interface PublicStreamSEIMessageEvent {
@@ -1204,6 +1208,12 @@ export interface RemoteAudioStats {
 	 */
 	e2eDelay: number;
 	
+	/** 
+	 * @brief The round-trip transmission time delay in ms.
+	 * @notes For FireFox, the value is not accurate.
+	 */
+	totalRtt: number;
+	
 	/** 
 	 * @hidden
 	 * @brief Sample rate of the playback
@@ -1322,6 +1332,12 @@ export interface RemoteVideoStats {
 	 */
 	e2eDelay: number;
 	
+	/** 
+	 * @brief The round-trip transmission time delay in ms.
+	 * @notes For FireFox, the value is not accurate.
+	 */
+	totalRtt: number;
+	
 	/** 
 	 * @brief Whether it is a screen-sharing stream
 	 */
@@ -1507,6 +1523,9 @@ export interface ConnectionStateChangeEvent {
 	 */
 	state: ConnectionState;
 }
+export interface VendorConnectionStateChangeEvent extends ConnectionStateChangeEvent {
+	userId: string;
+}
 
 /** 
  * @brief Event related to the player
@@ -1894,7 +1913,12 @@ declare enum EngineEventsTypes {
 	onLocalVideoSizeChanged = "onLocalVideoSizeChanged",
 	onSubtitleStateChanged = "onSubtitleStateChanged",
 	onSubtitleMessageReceived = "onSubtitleMessageReceived",
-	onServerParamsSetResult = "onServerParamsSetResult"
+	onServerParamsSetResult = "onServerParamsSetResult",
+	onLocalStreamTrackChangedByExtension = "onLocalStreamTrackChangedByExtension",
+	onVendorConnectionStateChanged = "onVendorConnectionStateChanged",
+	onForwardStreamError = "onForwardStreamError",
+	onRejoinWithTcp = "onRejoinWithTcp",
+	onIceConnectWithTcp = "onIceConnectWithTcp"
 }
 
 /** 
@@ -1932,6 +1956,14 @@ export interface IEngineEvents {
 	 */
 	[EngineEventsTypes.onConnectionStateChanged]: (event: ConnectionStateChangeEvent) => void;
 	
+	/** 
+	 * @hidden
+	 * @brief Vendor ICE connection state changed
+	 * @param event
+	 * @region Network Event
+	 */
+	[EngineEventsTypes.onVendorConnectionStateChanged]: (event: VendorConnectionStateChangeEvent) => void;
+	
 	/** 
 	 * @brief Callback on new media streams captured by camera/microphone in the room.
 	 * @notes You will receive this callback after a remote user successfully publishes media streams captured by camera/microphone in the room with [publishStream](104478#publishstream). Then you can choose whether to call [subscribeStream](104478#subscribestream) to subscribe to the streams or not.
@@ -2087,6 +2119,10 @@ export interface IEngineEvents {
 		 */
 		isScreen: boolean;
 	}) => void;
+	
+	/** 
+	 * @internal
+	 */
 	[EngineEventsTypes.onTrackMute]: (event: {
 		
 		/** 
@@ -2099,6 +2135,10 @@ export interface IEngineEvents {
 		 */
 		isScreen: boolean;
 	}) => void;
+	
+	/** 
+	 * @internal
+	 */
 	[EngineEventsTypes.onTrackUnmute]: (event: {
 		
 		/** 
@@ -2558,6 +2598,30 @@ export interface IEngineEvents {
 	 * + If the client losts connection after the call of [setServerParams](104478#setserverparams) this event notifies once the client reconnects.
 	 */
 	[EngineEventsTypes.onServerParamsSetResult]: (error?: ErrorCode) => void;
+	
+	/** 
+	 * @hidden
+	 */
+	[EngineEventsTypes.onLocalStreamTrackChangedByExtension]: (e: {
+		streamIndex: StreamIndex;
+		type: "video" | "audio";
+	}) => void;
+	
+	/** 
+	 * @brief Event of failing to forward stream across rooms.
+	 * @param e Status information for forwarding media stream across rooms.
+	 */
+	[EngineEventsTypes.onForwardStreamError]: (e: ForwardStreamStateInfo) => void;
+	
+	/** 
+	 * @hidden
+	 */
+	[EngineEventsTypes.onRejoinWithTcp]: () => void;
+	
+	/** 
+	 * @hidden
+	 */
+	[EngineEventsTypes.onIceConnectWithTcp]: () => void;
 }
 
 /** 
@@ -2574,12 +2638,7 @@ export interface IRTCEngine extends EnhancedEventEmitter<IEngineEvents> {
 	 *         You need to bring Token to enter the room. When testing, you can use the console to generate temporary tokens. The official launch requires the use of the key SDK to generate and issue tokens at your server level. See [Use Token to complete authentication](70121) for token validity and generation method.
 	 *         Apps with different AppIDs are not interoperable.
 	 *         Make sure that the AppID used to generate the Token is the same as the AppID used to create the engine, otherwise it will cause the join room to fail.
-	 * @param roomId  The ID of the room to be added.
-	 *     The room ID is a non-empty string with a length of less than 128 bytes, and the following character set ranges are supported:
-	 *      1. 26 capital letters A~ Z.
-	 *      2. 26 lowercase letters a~ z.
-	 *      3. 10 numbers 0~ 9.
-	 *      4. Underscore "_", the at sign "@", and the minus sign "-".
+	 * @param roomId  The Room ID. The string must conform to the regular expression: `[a-zA-Z0-9_@\-\.]{1,128}`.
 	 * @param userInfo  User information.
 	 * @param roomConfig  Room parameter configuration, set the room mode and whether to automatically publish or subscribe to the flow.
 	 * @return
@@ -2896,13 +2955,13 @@ export interface IRTCEngine extends EnhancedEventEmitter<IEngineEvents> {
 	
 	/** 
 	 * @brief Send SEI message carried by video frames
-	 * @param streamIndex
-	 * @param message SEI message within 4kb. Empty message or message exceeding this size will not be sent with respective error prompt.
-	 * @param repeatCount Number of message sending repetitions. The value range is [0,30].
+	 * @param streamIndex Stream index.
+	 * @param message SEI message within 4 KB. Empty message or message exceeding this size will not be sent with respective error prompt.
+	 * @param repeatCount Number of message sending repetitions. The value range is [0, max{29, %{video frame rate}-1}]. Recommended range: [2,4].
 	 *                    Calling this API to add SEI data to consecutive `repeatCount` video frames starting from the current one.
 	 * @notes + Call this API to add SEI message to the video frame captured by the internal video capture module.
-	 *         + SDK will abandon the SEI message if no video frame in 2s after you call this API.
-	 *         + Users receiving the stream will receive the SEI message via [onSEIMessageReceived](104479#onseimessagereceived) once the SEI message is sent successfully.
+	 *        + SDK will abandon the SEI message if no video frame in 2s after you call this API.
+	 *        + Users receiving the stream will receive the SEI message via [onSEIMessageReceived](104479#onseimessagereceived) once the SEI message is sent successfully.
 	 * @region Message
 	 */
 	sendSEIMessage: (streamIndex: StreamIndex, message: Uint8Array | string, repeatCount: number) => void;
@@ -3096,15 +3155,13 @@ export interface IRTCEngine extends EnhancedEventEmitter<IEngineEvents> {
 	/** 
 	 * @brief Log in to the RTM server.
 	 * Call this method before users within the same `appID` can communicate with each other via messages.
-	 * @param token Dynamic key. It is used for authentication and verification of users entering the room.
-	 *         You need to bring Token to enter the room. When testing, you can use the console to generate temporary tokens. The official launch requires the use of the key SDK to generate and issue tokens at your server level.
-	 *         Apps with different AppIDs are not interoperable.
-	 * @param userInfo  User information.
+	 * @param token Token for authentication.
+	 *         During testing, you can use generate a temporary Token on [Console](https://console.byteplus.com/auth/login), and fill in any value with `roomId`.
+	 *         To officially go live, you need to use the implement token generation at your server. The `roomId` field should be empty. See [Authentication with Token](70121).
+	 * @param userId  User ID.
 	 * @return
-	 * @notes
-	 *        + Call [logout](#logout) to log out the IM server.
+	 * @notes + Call [logout](#logout) to log out the IM server.
 	 *        + In the same App ID, the user ID of each user must be unique. The user will be logged out when a user with the same userID joins the room because of the error of `RTM_DUPLICATE_LOGIN`.
-	 * @region Room Management
 	 */
 	login: (token: string | null, userId: string) => Promise<void>;
 	
@@ -3429,8 +3486,7 @@ export interface IRTCEngine extends EnhancedEventEmitter<IEngineEvents> {
 	 *        After calling this method, you can choose between the recognition and translation modes based on your needs. In the recognition mode, the speech of the speaker in the room will be recognized and converted into captions. In the translation mode, the transcribed text will be translated.You will receive the [onSubtitleMessageReceived](104479#onsubtitlemessagereceived) callback to informs you of related information about subtitles.
 	 *        After calling this method, you will receive the [onSubtitleStateChanged](104479#onsubtitlestatechanged) to inform you of whether subtitles are on.
 	 * @param config Subtitle configrations.
-	 * @return +  `0`: Success.
-	 *         + `!0`: Failure.
+	 * @return
 	 * @notes
 	 *        You must call this method after joining the room.
 	 *        You can set your source language by calling `joinRoom`  and importing a json formatted string `"source_language": "zh"` through the paramater of extraInfo. Only chinese, English and Japanese are supported.
@@ -3489,6 +3545,51 @@ export interface IRTCEngine extends EnhancedEventEmitter<IEngineEvents> {
 	 *        + If the playing has not yet started when you call this API, the setting will take effect after it starts.
 	 */
 	setPublicStreamVolume: (publicStreamId: string, volume: number) => void;
+	
+	/** 
+	 * @brief Start forwarding media stream across rooms. See [Forward media stream across rooms](https://docs.byteplus.com/en/byteplus-rtc/docs/104398) for details.
+	 *        After calling [joinRoom]({{api}}#RTCEngine.joinRoom), you can call this API to publish the media stream to multiple rooms. This feature is suitable for scenarios such as co-host PK and online karaoke.
+	 * @param forwardStreamInfos Information of the target rooms where the stream will be forwarded.
+	 * @return Status information for forwarding media stream across rooms.
+	 * @notes + Once the forwarding begins, other users in the target room will receive [onUserJoined]({{callback}}#EngineEvents.onUserJoined) and [onUserPublishStream]({{callback}}#EngineEvents.onUserPublishStream)/[onUserPublishScreen]({{callback}}#EngineEvents.onUserPublishScreen).
+	 *        + Call [updateForwardStreamToRooms]({{api}}#RTCEngine.updateForwardStreamToRooms) to add or remove the target room(s).
+	 *        + Call [stopForwardStreamToRooms]({{api}}#RTCEngine.stopForwardStreamToRooms) to stop forwarding media stream to all rooms.
+	 *        + Call [pauseForwardStreamToAllRooms]({{api}}#RTCEngine.pauseForwardStreamToAllRooms) to pause forwarding media stream to all rooms.
+	 */
+	startForwardStreamToRooms: (forwardStreamInfos: ForwardStreamInfo[]) => Promise<ForwardStreamStateInfo[]>;
+	
+	/** 
+	 * @brief Update information of the rooms where the stream will be forwarded after calling [startForwardStreamToRooms]({{api}}#RTCEngine.startForwardStreamToRooms).
+	 * @param forwardStreamInfos Information of the target rooms where the stream will be forwarded.
+	 * @return Status information for forwarding media stream across rooms.
+	 * @notes + Users in the added room will receive [onUserJoined]({{callback}}#EngineEvents.onUserJoined) and [onUserPublishStream]({{callback}}#EngineEvents.onUserPublishStream)/[onUserPublishScreen]({{callback}}#EngineEvents.onUserPublishScreen).
+	 *        + Users in the removed room will receive [onUserUnpublishStream]({{callback}}#EngineEvents.onUserUnpublishStream)/[onUserUnpublishScreen]({{callback}}#EngineEvents.onUserUnpublishScreen) and [onUserLeave]({{callback}}#EngineEvents.onUserLeave).
+	 */
+	updateForwardStreamToRooms: (forwardStreamInfos: ForwardStreamInfo[]) => Promise<ForwardStreamStateInfo[]>;
+	
+	/** 
+	 * @brief Stop forwarding media stream to all rooms.
+	 * @return Status information for forwarding media stream across rooms.
+	 * @notes + Users in the former target rooms will receive [onUserUnpublishStream]({{callback}}#EngineEvents.onUserUnpublishStream)/[onUserUnpublishScreen]({{callback}}#EngineEvents.onUserUnpublishScreen) and [onUserLeave]({{callback}}#EngineEvents.onUserLeave).
+	 *        + Call [updateForwardStreamToRooms]({{api}}#RTCEngine.updateForwardStreamToRooms) to stop forwarding media stream to specific rooms.
+	 *        + Call [pauseForwardStreamToAllRooms]({{api}}#RTCEngine.pauseForwardStreamToAllRooms) and [resumeForwardStreamToAllRooms]({{api}}#RTCEngine.resumeForwardStreamToAllRooms) to pause and resume fowarding media stream to all rooms.
+	 */
+	stopForwardStreamToRooms: () => Promise<ForwardStreamStateInfo[]>;
+	
+	/** 
+	 * @brief Pause forwarding media stream to all rooms.
+	 *        After calling this API, call [resumeForwardStreamToAllRooms]({{api}}#RTCEngine.resumeForwardStreamToAllRooms) to resume.
+	 * @return Status information for forwarding media stream across rooms.
+	 * @notes Users in the target rooms will receive [onUserUnpublishStream]({{callback}}#EngineEvents.onUserUnpublishStream)/[onUserUnpublishScreen]({{callback}}#EngineEvents.onUserUnpublishScreen) and [onUserLeave]({{callback}}#EngineEvents.onUserLeave).
+	 */
+	pauseForwardStreamToAllRooms: () => Promise<ForwardStreamStateInfo[]>;
+	
+	/** 
+	 * @brief Resume forwarding media stream to all rooms.
+	 * @return Status information for forwarding media stream across rooms.
+	 * @notes Users in the target room will receive [onUserJoined]({{callback}}#EngineEvents.onUserJoined) and [onUserPublishStream]({{callback}}#EngineEvents.onUserPublishStream)/[onUserPublishScreen]({{callback}}#EngineEvents.onUserPublishScreen).
+	 */
+	resumeForwardStreamToAllRooms: () => Promise<ForwardStreamStateInfo[]>;
 }
 
 /** 
@@ -3715,7 +3816,7 @@ export interface VideoPlayerOption {
 	renderDom?: string | HTMLElement;
 	
 	/** 
-	 * @brief Rendering modes: optional  `RENDER_MODE_HIDDEN` and `RENDER_MODE_FIT` .
+	 * @brief Rendering mode.
 	 */
 	renderMode?: VideoRenderMode;
 	
@@ -3735,16 +3836,22 @@ export interface VideoPlayerOption {
 export declare enum VideoRenderMode {
 	
 	/** 
-	 * @brief Windows fill priority.
-	 * Scale the video frame at the original equal ratio until the window is filled with video. If the video frame aspect ratio is different from that of the window, the over-brims of the video frame will not be displayed.
+	 * @brief (Default value for main stream) Fills the entire window with the video frame.
+	 *        The video frame is scaled until the window is filled. If the video frame's aspect ratio is different from that of the window, the extra part of the video frame will be cropped.
 	 */
 	RENDER_MODE_HIDDEN = 0,
 	
 	/** 
-	 * @brief All video frame contents are fit to display in the window.
-	 * Scale the video frame at the original equal ratio until the whole video frame has been displayed in the window. If the video frame aspect ratio is different from that of the window, the area on the window that is not filled by the video frame will be blacked out.
+	 * @brief (Default value for screen-sharing stream) Makes the entire video frame fit within the window while maintaining the video frame's original aspect ratio.
+	 *        There may be empty space at the margins of the window.
+	 */
+	RENDER_MODE_FIT = 1,
+	
+	/** 
+	 * @brief Stretch the video frame until the window is filled.
+	 *        The video frame's aspect ratio can be changed as it is automatically stretched to fill the window.
 	 */
-	RENDER_MODE_FIT = 1
+	RENDER_MODE_FILL = 2
 }
 
 /** 
@@ -3975,19 +4082,19 @@ export interface ScreenConfig {
 export interface VideoEncoderConfig {
 	
 	/** 
-	 * @brief Video width in pixels. The default value is 640 px。
+	 * @brief Video width in pixels. The default value is 640 px.
 	 *        The input can be a number or a [ConstrainULong](https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints#constrainulong).
 	 */
 	width: ConstrainULong;
 	
 	/** 
-	 * @brief Video height in pixels. The default value is 480 px。
+	 * @brief Video height in pixels. The default value is 480 px.
 	 *        The input can be a number or a [ConstrainULong](https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints#constrainulong).
 	 */
 	height: ConstrainULong;
 	
 	/** 
-	 * @brief Video framerate in FPS. The default value is 15 FPS。
+	 * @brief Video framerate in FPS. The default value is 15 FPS.
 	 *        The input can be a number or a [ConstrainDouble](https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints#constraindouble).
 	 */
 	frameRate: ConstrainDouble;
@@ -4004,19 +4111,19 @@ export interface VideoEncoderConfig {
 export interface ScreenEncoderConfig {
 	
 	/** 
-	 * @brief Video width in pixels. The default value is 1920 px。
+	 * @brief Video width in pixels. The default value is 1920 px.
 	 *        The input can be a number or a [ConstrainULong](https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints#constrainulong).
 	 */
 	width: ConstrainULong;
 	
 	/** 
-	 * @brief Video height in pixels. The default value is 1080 px。
+	 * @brief Video height in pixels. The default value is 1080 px.
 	 *        The input can be a number or a [ConstrainULong](https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints#constrainulong).
 	 */
 	height: ConstrainULong;
 	
 	/** 
-	 * @brief Video framerate in FPS. The default value is 15 FPS。
+	 * @brief Video framerate in FPS. The default value is 15 FPS.
 	 *        The input can be a number or a [ConstrainDouble](https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints#constraindouble).
 	 */
 	frameRate: ConstrainDouble;
@@ -4063,10 +4170,10 @@ export declare enum MirrorType {
 export interface AudioPropertiesConfig {
 	
 	/** 
-	 * @brief Prompt interval in ms, the default value is 100.
-	 *        + `<= 0`: Turn off prompt
-	 *        + `(0,100]`: Invalid interval value, and will be automatically reset to 100ms.
-	 *        + `> 100`: The actual value of interval
+	 * @brief Prompt interval in ms, the default value is 100.  </br>
+	 *     &ensp; + `≤0`: Turn off prompt.
+	 *     &ensp; + `(0,100)`: Invalid interval value, and will be automatically reset to 100ms.
+	 *     &ensp; + `≥100`: Enable prompt and set the prompt interval to the set value.
 	 */
 	interval?: number;
 	
@@ -4492,7 +4599,7 @@ export declare enum SubscribeFallbackOption {
 	DISABLE = 0,
 	
 	/** 
-	 * @brief When the downstream network quality is bad, the video stream fallbacks to stream of lower resolution and then to voice only. See [Media Stream Fallback](https://www.volcengine.com/docs/6348/70137) for fallback rules.
+	 * @brief When the downstream network quality is bad, the video stream fallbacks to stream of lower resolution and then to voice only. See [Media Stream Fallback](https://docs.byteplus.com/en/byteplus-rtc/docs/70137) for fallback rules.
 	 *        This setting takes effect only when the publisher enables simulcast mode through [EnableSimulcastMode](104478#enablesimulcastmode).
 	 */
 	VIDEO_STREAM_LOW = 1,
@@ -4909,6 +5016,90 @@ export interface CloudProxyInfo {
 	configProxy: string;
 }
 
+/** 
+ * @brief Information of the target rooms where the stream will be forwarded.
+ */
+export interface ForwardStreamInfo {
+	
+	/** 
+	 * @brief The target room ID for forwarding media streams.
+	 */
+	roomId: string;
+	
+	/** 
+	 * @brief Tokens generated using the target room's roomId and userId.
+	 *        You can use the temporary token generated on the [console](https://console.byteplus.com/rtc/workplaceRTC) for testing purposes only. The official launch requires token generated by your server.
+	 */
+	token: string;
+}
+
+/** 
+ * @brief Status information for forwarding media stream across rooms.
+ */
+export interface ForwardStreamStateInfo {
+	
+	/** 
+	 * @brief The target room ID for forwarding media streams.
+	 */
+	roomId: string;
+	
+	/** 
+	 * @brief Status information for forwarding media stream across rooms.
+	 */
+	state: ForwardStreamState;
+	
+	/** 
+	 * @brief Forward stream error code.
+	 */
+	error: ForwardStreamError;
+}
+
+/** 
+ * @brief Status information for forwarding media stream across rooms.
+ */
+export declare enum ForwardStreamState {
+	
+	/** 
+	 * @brief Success.
+	 */
+	FORWARD_STREAM_STATE_SUCCESS = 0,
+	
+	/** 
+	 * @brief Failure.
+	 */
+	FORWARD_STREAM_STATE_FAILURE = 1
+}
+
+/** 
+ * @brief Forward stream error code.
+ */
+export declare enum ForwardStreamError {
+	
+	/** 
+	 * @brief Success.
+	 */
+	FORWARD_STREAM_ERROR_OK = 0,
+	
+	/** 
+	 * @brief Target room's token is invalid.
+	 */
+	FORWARD_STREAM_ERROR_INVALID_TOKEN = 1202,
+	
+	/** 
+	 * @brief Server side error.
+	 */
+	FORWARD_STREAM_ERROR_RESPONSE = 1203,
+	
+	/** 
+	 * @brief The source room is set as the target room.
+	 */
+	FORWARD_STREAM_ERROR_REMOTE_KICKED = 1204,
+	/**
+	 * @hidden
+	 */
+	FORWARD_STREAM_ERROR_NOT_SUPPORT = 1205
+}
+
 /** 
  * @brief Point-to-point text message
  */
@@ -4993,7 +5184,11 @@ export interface CloudProxyConnectedEvent {
 declare const Config: {
 	[key: string]: any;
 };
-declare function setParameter(key: keyof typeof Config, value: any): void;
+declare function setParameter(key: keyof typeof Config, value: any): {
+	useTcpAfterJoinTimeout: boolean;
+	joinWithTcpOnly: boolean;
+	joinWithTcpOnlyDelay: number;
+} | undefined;
 declare function getParameter(key: keyof typeof Config): any;
 
 /** 
@@ -5154,6 +5349,7 @@ declare class VERTC implements IVERTC {
 	events: typeof EngineEventsTypes;
 	ErrorCode: typeof ErrorCode;
 	platform: string;
+	commitInfo: string;
 	downloadLog: (key?: string | undefined) => void;
 	setLogConfig: ({ logLevel, LogfileSize }: {
 		logLevel?: "none" | "error" | "info" | "warning" | "trace" | undefined;