trtc-electron-sdk 12.2.701 → 12.2.702-beta.0

package/liteav/trtc.d.ts

@@ -1,7 +1,7 @@
 /// <reference types="node" />
 import { EventEmitter } from 'events';
 import { TRTCConfig } from './Renderer/util';
-import { AudioMusicParam, Rect, TRTCAppScene, TRTCAudioEffectParam, TRTCAudioQuality, TRTCBeautyStyle, TRTCDeviceState, TRTCDeviceType, TRTCLogLevel, TRTCRenderParams, TRTCRoleType, TRTCSpeedTestResult, TRTCStatistics, TRTCSwitchRoomParam, TRTCVideoBufferType, TRTCVideoFillMode, TRTCAudioFrame, TRTCVideoPixelFormat, TRTCVideoRotation, TRTCVideoStreamType, TRTCVolumeInfo, TRTCWaterMarkSrcType, TRTCQualityInfo, TRTCPluginType, TRTCPluginInfo, TRTCVideoProcessPluginOptions, TRTCMediaEncryptDecryptPluginOptions, TRTCAudioRecordingParams, TRTCScreenCaptureSourceInfo, TRTCScreenCaptureProperty, TRTCSpeedTestParams, TRTCRecordType, TRTCDeviceInfo, TRTCCameraCaptureParams, TRTCImageBuffer, TRTCInitConfig, TRTCAudioParallelParams, TRTCVoiceReverbType, TRTCVoiceChangerType, TRTCMusicPlayObserver, TRTCAudioFrameCallback, TRTCAudioProcessPluginOptions } from './trtc_define';
+import { AudioMusicParam, Rect, TRTCAppScene, TRTCAudioEffectParam, TRTCAudioQuality, TRTCBeautyStyle, TRTCDeviceState, TRTCDeviceType, TRTCLogLevel, TRTCRenderParams, TRTCRoleType, TRTCSpeedTestResult, TRTCStatistics, TRTCSwitchRoomParam, TRTCVideoBufferType, TRTCVideoFillMode, TRTCAudioFrame, TRTCVideoPixelFormat, TRTCVideoRotation, TRTCVideoStreamType, TRTCVolumeInfo, TRTCWaterMarkSrcType, TRTCQualityInfo, TRTCPluginType, TRTCPluginInfo, TRTCVideoProcessPluginOptions, TRTCMediaEncryptDecryptPluginOptions, TRTCAudioRecordingParams, TRTCScreenCaptureSourceInfo, TRTCScreenCaptureProperty, TRTCSpeedTestParams, TRTCRecordType, TRTCDeviceInfo, TRTCCameraCaptureParams, TRTCImageBuffer, TRTCInitConfig, TRTCAudioParallelParams, TRTCVoiceReverbType, TRTCVoiceChangerType, TRTCMusicPlayObserver, TRTCAudioFrameCallback, TRTCAudioProcessPluginOptions, TRTCPublishTarget, TRTCStreamEncoderParam, TRTCStreamMixingConfig } from './trtc_define';
 import TRTCMediaMixingManager from './extensions/MediaMixingManager';
 export * from './trtc_define';
 export * from './trtc_code';
@@ -48,6 +48,10 @@ declare class TRTCCloud extends EventEmitter {
     private videoProcessPixelFormat;
     private videoRenderFPS;
     private localVideoRenderController;
+    private deviceManager;
+    private audioEffectManager;
+    private pluginManager;
+    private mediaMixingManager;
     private localRotation;
     private localMirrorType;
     private remoteMainStreamFillMode;
@@ -518,6 +522,7 @@ declare class TRTCCloud extends EventEmitter {
      * @event TRTCCallback#onStartPublishing
      * @param {Number} errCode - 0 表示成功，其余值表示失败
      * @param {String} errMsg  - 具体错误原因
+     * @deprecated
      */
     handleOnStartPublishing(errCode: number, errMsg: string): void;
     /**
@@ -526,6 +531,7 @@ declare class TRTCCloud extends EventEmitter {
      * @event TRTCCallback#onStopPublishing
      * @param {Number} errCode - 0 表示成功，其余值表示失败
      * @param {String} errMsg  - 具体错误原因
+     * @deprecated
      */
     handleOnStopPublishing(errCode: number, errMsg: string): void;
     /**
@@ -538,6 +544,7 @@ declare class TRTCCloud extends EventEmitter {
      * @event TRTCCallback#onStartPublishCDNStream
      * @param {Number} errCode - 错误码
      * @param {String} errMsg  - 错误详细信息
+     * @deprecated
      */
     handleOnStartPublishCDNStream(errCode: number, errMsg: string): void;
     /**
@@ -548,6 +555,7 @@ declare class TRTCCloud extends EventEmitter {
      * @event TRTCCallback#onStopPublishCDNStream
      * @param {Number} errCode - 错误码
      * @param {String} errMsg  - 错误详细信息
+     * @deprecated
      */
     handleOnStopPublishCDNStream(errCode: number, errMsg: string): void;
     /**
@@ -558,8 +566,59 @@ declare class TRTCCloud extends EventEmitter {
      * @event TRTCCallback#onSetMixTranscodingConfig
      * @param {Number} errCode - 错误码
      * @param {String} errMsg  - 错误详细信息
+     * @deprecated
      */
     handleOnSetMixTranscodingConfig(errCode: number, errMsg: string): void;
+    /**
+     * 开始发布媒体流的事件回调
+     *
+     * 当您调用 [startPublishMediaStream]{@link TRTCCloud#startPublishMediaStream} 开始向 TRTC 后台服务发布媒体流时，SDK 会立刻将这一指令同步给云端服务器，随后 SDK 会收到来自云端服务器的处理结果，并将指令的执行结果通过本事件回调通知给您。
+     *
+     * @event TRTCCallback#onStartPublishMediaStream
+     * @param taskId {String} - 当请求成功时，TRTC 后台会在回调中提供给您这项任务的 taskId，后续您可以通过该 taskId 结合 [updatePublishMediaStream]{@link TRTCCloud#updatePublishMediaStream} 和 [stopPublishMediaStream]{@link TRTCCloud#stopPublishMediaStream} 进行更新和停止。
+     * @param code {Number} - 回调结果，0 表示成功，其余值表示失败。
+     * @param message {String} - 具体回调信息。
+     */
+    private handleOnStartPublishMediaStream;
+    /**
+     * 更新媒体流的事件回调
+     *
+     * 当您调用媒体流发布接口 ([updatePublishMediaStream]{@link TRTCCloud#updatePublishMediaStream}) 开始向 TRTC 后台服务更新媒体流时，SDK 会立刻将这一指令同步给云端服务器，随后 SDK 会收到来自云端服务器的处理结果，并将指令的执行结果通过本事件回调通知给您。
+     * @event TRTCCallback#onUpdatePublishMediaStream
+     * @param taskId {String} - 您调用媒体流发布接口 ([updatePublishMediaStream]{@link TRTCCloud#updatePublishMediaStream}) 时传入的 taskId，会通过此回调再带回给您，用于标识该回调属于哪一次更新请求。
+     * @param code {Number} - 回调结果，0 表示成功，其余值表示失败。
+     * @param message {String} - 具体回调信息。
+     */
+    private handleOnUpdatePublishMediaStream;
+    /**
+     * 停止媒体流的事件回调
+     *
+     * 当您调用停止发布媒体流 ([stopPublishMediaStream]{@link TRTCCloud#stopPublishMediaStream}) 开始向 TRTC 后台服务停止媒体流时，SDK 会立刻将这一指令同步给云端服务器，随后 SDK 会收到来自云端服务器的处理结果，并将指令的执行结果通过本事件回调通知给您。
+     * @event TRTCCallback#onStopPublishMediaStream
+     * @param taskId {String} - 您调用停止发布媒体流 ([stopPublishMediaStream]{@link TRTCCloud#stopPublishMediaStream}) 时传入的 taskId，会通过此回调再带回给您，用于标识该回调属于哪一次停止请求。
+     * @param code {Number} - 回调结果，0 表示成功，其余值表示失败。
+     * @param message {String} - 具体回调信息。
+     */
+    private handleOnStopPublishMediaStream;
+    /**
+     * RTMP/RTMPS 推流状态发生改变回调
+     *
+     * 当您调用 [startPublishMediaStream]{@link TRTCCloud#startPublishMediaStream} 开始向 TRTC 后台服务发布媒体流时，SDK 会立刻将这一指令同步给云端服务。
+     * 若您在目标推流配置 ([TRTCPublishTarget]{@link TRTCPublishTarget}) 设置了向腾讯或者第三方 CDN 上发布音视频流的 URL 配置，则具体 RTMP 或者 RTMPS 推流状态将通过此回调同步给您。
+     *
+     * @event TRTCCallback#onCdnStreamStateChanged
+     * @param cdnUrl {String} - 您调用 [startPublishMediaStream]{@link TRTCCloud#startPublishMediaStream} 时通过目标推流配置 ([TRTCPublishTarget]{@link TRTCPublishTarget}) 传入的 url，在推流状态变更时，会通过此回调同步给您。
+     * @param status {Number} - 推流状态。
+     * - 0：推流未开始或者已结束。在您调用 [stopPublishMediaStream]{@link TRTCCloud#stopPublishMediaStream} 时会返回该状态。
+     * - 1：正在连接 TRTC 服务器和 CDN 服务器。若无法立刻成功，TRTC 后台服务会多次重试尝试推流，并返回该状态（5s回调一次）。如成功进行推流，则进入状态 2；如服务器出错或 60 秒内未成功推流，则进入状态 4。
+     * - 2：CDN 推流正在进行。在成功推流后，会返回该状态。
+     * - 3：TRTC 服务器和 CDN 服务器推流中断，正在恢复。当 CDN 出现异常，或推流短暂中断时，TRTC 后台服务会自动尝试恢复推流，并返回该状态（5s回调一次）。如成功恢复推流，则进入状态 2；如服务器出错或 60 秒内未成功恢复，则进入状态 4。
+     * - 4：TRTC 服务器和 CDN 服务器推流中断，且恢复或连接超时。即此时推流失败，你可以再次调用 [updatePublishMediaStream]{@link TRTCCloud#updatePublishMediaStream} 尝试推流。
+     * - 5：正在断开 TRTC 服务器和 CDN 服务器。在您调用 [stopPublishMediaStream]{@link TRTCCloud#stopPublishMediaStream} 时，TRTC 后台服务会依次同步状态 5 和状态 0。
+     * @param code {Number} - 回调结果，0 表示成功，其余值表示失败。
+     * @param msg {String} - 具体回调信息。
+     */
+    private handleOnCdnStreamStateChanged;
     /**
      * 废弃事件： 播放音效结束回调
      *
@@ -797,6 +856,50 @@ declare class TRTCCloud extends EventEmitter {
      *
      */
     setDefaultStreamRecvMode(autoRecvAudio: boolean, autoRecvVideo: boolean): void;
+    /**
+     * 开始发布媒体流
+     *
+     * 该接口会向 TRTC 服务器发送指令，要求其将当前用户的音视频流转推/转码到直播 CDN 或者回推到 TRTC 房间中，您可以通过 [TRTCPublishTarget]{@link TRTCPublishTarget} 配置中的 [TRTCPublishMode]{@link TRTCPublishMode} 指定具体的发布模式。
+     *
+     * 注意：
+     * 1. SDK 会通过回调 [onStartPublishMediaStream]{@link TRTCCallback#event:onStartPublishMediaStream} 带给您后台启动的任务标识（即 taskId）。
+     * 2. 同一个任务（TRTCPublishMode 与 TRTCPublishCdnUrl 均相同）仅支持启动一次。若您后续需要更新或者停止该项任务，需要记录并使用返回的 taskId，通过 [updatePublishMediaStream]{@link TRTCCloud#updatePublishMediaStream} 或者 [stopPublishMediaStream]{@link TRTCCloud#stopPublishMediaStream} 来操作。
+     * 3. target 支持同时配置多个 CDN URL（最多同时 10 个）。若您的同一个转推/转码任务需要发布至多路 CDN，则仅需要在 target 中配置多个 CDN URL 即可。同一个转码任务即使有多个转推地址，对应的转码计费仍只收取一份。
+     * 4. 使用时需要注意不要多个任务同时往相同的 URL 地址推送，以免引起异常推流状态。一种推荐的方案是 URL 中使用 “sdkappid_roomid_userid_main” 作为区分标识，这种命名方式容易辨认且不会在您的多个应用中发生冲突。
+     *
+     * @param target {TRTCPublishTarget} - 媒体流发布的目标地址，支持转推/转码到腾讯或者第三方 CDN，也支持转码回推到 TRTC 房间中。
+     * @param params {TRTCStreamEncoderParam|null} - 媒体流编码输出参数，转码和回推到 TRTC 房间中时为必填项，您需要指定您预期的转码输出参数。在转推时，为了更好的转推稳定性和 CDN 兼容性，也建议您进行配置。
+     * @param config {TRTCStreamMixingConfig|null} - 媒体流转码配置参数，转码和回推到 TRTC 房间中时为必填项，您需要指定您预期的转码配置参数。转推模式下则无效。
+     */
+    startPublishMediaStream(target: TRTCPublishTarget, params: TRTCStreamEncoderParam | null, config: TRTCStreamMixingConfig | null): void;
+    /**
+     * 更新发布媒体流
+     *
+     * 该接口会向 TRTC 服务器发送指令，更新通过 [startPublishMediaStream]{@link TRTCCloud#startPublishMediaStream} 启动的媒体流
+     *
+     * 注意：
+     * 1. 您可以通过本接口来更新发布的 CDN URL（支持增删，最多同时 10 个），但您使用时需要注意不要多个任务同时往相同的 URL 地址推送，以免引起异常推流状态。
+     * 2. 您可以通过 taskId 来更新调整转推/转码任务。例如在 pk 业务中，您可以先通过 [startPublishMediaStream]{@link startPublishMediaStream} 发起转推，接着在主播发起 pk 时，通过 taskId 和本接口将转推更新为转码任务。此时，CDN 播放将连续并且不会发生断流（您需要保持媒体流编码输出参数 `param` 一致）。
+     * 3. 同一个任务不支持纯音频、音视频、纯视频之间的切换。
+     *
+     * @param taskId {String} - 通过回调 [onStartPublishMediaStream]{@link TRTCCallback#event:onStartPublishMediaStream} 带给您后台启动的任务标识（即 taskId）
+     * @param target {TRTCPublishTarget|null} - 媒体流发布的目标地址，支持转推/转码到腾讯或者第三方 CDN，也支持转码回推到 TRTC 房间中。
+     * @param params {TRTCStreamEncoderParam|null} - 媒体流编码输出参数，转码和回推到 TRTC 房间中时为必填项，您需要指定您预期的转码输出参数。在转推时，为了更好的转推稳定性和 CDN 兼容性，也建议您进行配置。
+     * @param config {TRTCStreamMixingConfig|null} - 媒体流转码配置参数，转码和回推到 TRTC 房间中时为必填项，您需要指定您预期的转码配置参数。转推模式下则无效。
+     */
+    updatePublishMediaStream(taskId: string, target: TRTCPublishTarget | null, params: TRTCStreamEncoderParam | null, config: TRTCStreamMixingConfig | null): void;
+    /**
+     * 停止发布媒体流
+     *
+     * 该接口会向 TRTC 服务器发送指令，停止通过 [startPublishMediaStream]{@link TRTCCloud#startPublishMediaStream} 启动的媒体流
+     *
+     * 注意：
+     * 1. 若您的业务后台并没有保存该 taskId，在您的主播异常退房重进后，如果您需要重新获取 taskId，您可以再次调用 [startPublishMediaStream]{@link TRTCCloud#startPublishMediaStream} 启动任务。此时 TRTC 后台会返回任务启动失败，同时带给您上一次启动的 taskId
+     * 2. 若 taskId 填空字符串，将会停止该用户所有通过 [startPublishMediaStream]{@link TRTCCloud#startPublishMediaStream} 启动的媒体流，如果您只启动了一个媒体流或者想停止所有通过您启动的媒体流，推荐使用这种方式。
+     *
+     * @param taskId {String} - 通过回调 [onStartPublishMediaStream]{@link TRTCCallback#event:onStartPublishMediaStream} 带给您后台启动的任务标识（即 taskId）
+     */
+    stopPublishMediaStream(taskId: string): void;
     /**
      * 开始向腾讯云的直播 CDN 推流
      *
@@ -820,10 +923,12 @@ declare class TRTCCloud extends EventEmitter {
      *
      * @param {String} streamId - 自定义流 ID。
      * @param {TRTCVideoStreamType} type - 仅支持 TRTCVideoStreamTypeBig 和 TRTCVideoStreamTypeSub。
+     * @deprecated
      */
     startPublishing(streamId: string, type: TRTCVideoStreamType): void;
     /**
      * 停止向腾讯云的直播 CDN 推流
+     * @deprecated
      */
     stopPublishing(): void;
     /**
@@ -840,10 +945,12 @@ declare class TRTCCloud extends EventEmitter {
      * @param {Number} param.bizId - 腾讯云直播服务的 bizid
      * @param {String} param.url   - 指定该路音视频流在第三方直播服务商的推流地址，推流 URL 必须为 RTMP 格式，必须符合您的目标直播服务商的规范要求，否则目标服务商会拒绝来自 TRTC 后台服务的推流请求。
      * @param {String} param.streamId - 需要转推的 streamId，默认值：空值。如果不填写，则默认转推调用者的旁路流。
+     * @deprecated
      */
     startPublishCDNStream(param: any): void;
     /**
      * 停止向非腾讯云的直播 CDN 推流
+     * @deprecated
      */
     stopPublishCDNStream(): void;
     /**
@@ -912,8 +1019,9 @@ declare class TRTCCloud extends EventEmitter {
      * @param {Number}  config.mixUsersArray[].renderMode  - 该画面在输出时的显示模式。视频流默认为0。0为裁剪，1为缩放，2为缩放并显示黑底。
      * @param {Number}  config.mixUsersArray[].soundLevel  - 该路音频参与混音时的音量等级（取值范围：0 - 100）,默认值：100。
      * @param {String}  config.mixUsersArray[].image       - 占位图是指当对应 userId 混流内容为纯音频时，混合后的画面中显示的是占位图片。水印图是指一张贴在混合后画面中的半透明图片，这张图片会一直覆盖于混合后的画面上。当指定 inputType 为 TRTCMixInputTypePureAudio 时，image 为占位图，此时需要您指定 userId。当指定 inputType 为 TRTCMixInputTypeWatermark 时，image 为水印图，此时不需要您指定 userId。
+     * @deprecated
      */
-    setMixTranscodingConfig(config: any): void;
+    setMixTranscodingConfig(config: Record<string, any>): void;
     private _startLocalPreview;
     /**
      * 启动本地摄像头采集和预览
@@ -2606,13 +2714,13 @@ declare class TRTCCloud extends EventEmitter {
     private _setRemoteVideoBuffer;
     /**
      * 获取设备管理器
-     *
+     * @private
      * @returns {TRTCDeviceManager}
      */
     private getDeviceManager;
     /**
      * 获取音效管理器
-     *
+     * @private
      * @returns {TRTCAudioEffectManager}
      */
     private getAudioEffectManager;
@@ -2624,7 +2732,7 @@ declare class TRTCCloud extends EventEmitter {
     getMediaMixingManager(): TRTCMediaMixingManager | null;
     /**
      * 获取插件管理器
-     *
+     * @private
      * @returns {TRTCPluginManager}
      */
     private getPluginManager;