## RTCVideo 类型: `class` - **API** | 方法 | 描述 | | :-- | :-- | | [createRTCVideo](#rtcvideo-creatertcvideo) | 创建引擎对象 | | [createRTCRoom](#rtcvideo-creatertcroom) | 创建房间 | | [destroyRTCVideo](#rtcvideo-destroyrtcvideo) | 销毁引擎实例对象 | | [feedback](#rtcvideo-feedback) | 将用户反馈的问题上报到 RTC | | [setBusinessId](#rtcvideo-setbusinessid) | 设置业务标识参数 | | [setEncryptInfo](#rtcvideo-setencryptinfo) | 设置传输时使用内置加密的方式 | | [initializePluginManager](#rtcvideo-initializepluginmanager) | 初始化插件管理器 | | [releasePluginManager](#rtcvideo-releasepluginmanager) | 释放插件管理器 | | [registerPlugin](#rtcvideo-registerplugin) | 注册插件 | | [getPlugin](#rtcvideo-getplugin) | 获取插件实例 | | [unregisterPlugin](#rtcvideo-unregisterplugin) | 卸载插件 | | [muteAudioCapture](#rtcvideo-muteaudiocapture) | 设置是否将录音信号静音（不改变本端硬件）。 | | [startAudioCapture](#rtcvideo-startaudiocapture) | 开启内部音频采集。默认为关闭状态。 | | [stopAudioCapture](#rtcvideo-stopaudiocapture) | 关闭内部音频采集。默认为关闭状态。 | | [enumerateAudioPlaybackDevices](#rtcvideo-enumerateaudioplaybackdevices) | 获取当前系统内音频播放设备列表。如果后续设备有变更，你会收到 [`onAudioDeviceStateChanged`](85533#rtcvideocallback-onaudiodevicestatechanged) 回调通知，然后需要重新调用本接口以获得新的设备列表。 | | [enumerateAudioCaptureDevices](#rtcvideo-enumerateaudiocapturedevices) | 获取当前系统内音频采集设备列表。如果后续设备有变更，你需要重新调用本接口以获得新的设备列表。 | | [setAudioPlaybackDevice](#rtcvideo-setaudioplaybackdevice) | 设置音频播放设备。 | | [setAudioCaptureDevice](#rtcvideo-setaudiocapturedevice) | 设置音频采集设备。 | | [getAudioPlaybackDevice](#rtcvideo-getaudioplaybackdevice) | 获取当前音频播放设备 ID。 | | [getAudioCaptureDevice](#rtcvideo-getaudiocapturedevice) | 获取当前音频采集设备 ID。 | | [setAudioPlaybackDeviceVolume](#rtcvideo-setaudioplaybackdevicevolume) | 设置当前音频播放设备音量 | | [getAudioPlaybackDeviceVolume](#rtcvideo-getaudioplaybackdevicevolume) | 获取当前音频播放设备音量 | | [setAudioCaptureDeviceVolume](#rtcvideo-setaudiocapturedevicevolume) | 设置当前音频采集设备音量 | | [getAudioCaptureDeviceVolume](#rtcvideo-getaudiocapturedevicevolume) | 获取当前音频采集设备音量 | | [setAudioPlaybackDeviceMute](#rtcvideo-setaudioplaybackdevicemute) | 设置当前音频播放设备静音状态，默认为非静音。 | | [getAudioPlaybackDeviceMute](#rtcvideo-getaudioplaybackdevicemute) | 获取当前音频播放设备是否静音的信息。 | | [setAudioCaptureDeviceMute](#rtcvideo-setaudiocapturedevicemute) | 设置当前音频采集设备静音状态，默认为非静音。 | | [getAudioCaptureDeviceMute](#rtcvideo-getaudiocapturedevicemute) | 获取当前音频采集设备是否静音的信息。 | | [setCaptureVolume](#rtcvideo-setcapturevolume) | 调节音频采集音量 | | [setPlaybackVolume](#rtcvideo-setplaybackvolume) | 调节本地播放的所有远端用户音频混音后的音量，混音内容包括远端人声、音乐、音效等。播放音频前或播放音频时，你都可以使用此接口设定播放音量。 | | [setRemoteAudioPlaybackVolume](#rtcvideo-setremoteaudioplaybackvolume) | 调节来自远端用户的音频播放音量 | | [stopAudioPlaybackDeviceTest](#rtcvideo-stopaudioplaybackdevicetest) | 停止音频播放设备测试。 | | [setVoiceChangerType](#rtcvideo-setvoicechangertype) | 设置变声特效类型 | | [setVoiceReverbType](#rtcvideo-setvoicereverbtype) | 设置混响特效类型 | | [setAudioProfile](#rtcvideo-setaudioprofile) | 设置音质档位。 | | [startAudioPlaybackDeviceTest](#rtcvideo-startaudioplaybackdevicetest) | 启动音频播放设备测试。该方法测试播放设备是否能正常工作。SDK 播放指定的音频文件，测试者如果能听到声音，说明播放设备能正常工作。 | | [startEchoTest](#rtcvideo-startechotest) | 开始音频设备回路测试。 | | [stopEchoTest](#rtcvideo-stopechotest) | 停止音频设备回路测试。 | | [initAudioPlaybackDeviceForTest](#rtcvideo-initaudioplaybackdevicefortest) | 尝试初始化音频播放设备，可检测出设备不存在、权限被拒绝/禁用等异常问题。 | | [initAudioCaptureDeviceForTest](#rtcvideo-initaudiocapturedevicefortest) | 尝试初始化音频播放设备，可检测出设备不存在、权限被拒绝/禁用等异常问题。 | | [enableAudioPropertiesReport](#rtcvideo-enableaudiopropertiesreport) | 启用音频信息提示。 | | [enableVocalInstrumentBalance](#rtcvideo-enablevocalinstrumentbalance) | 开启/关闭音量均衡功能。 | | [setDummyCaptureImagePath](#rtcvideo-setdummycaptureimagepath) | 摄像头处于关闭状态时，使用静态图片填充本地推送的视频流。可重复调用该接口来更新图片。若要停止发送图片，可传入空字符串或启用内部摄像头采集。 | | [startVideoCapture](#rtcvideo-startvideocapture) | 开启内部视频采集。默认为关闭状态。 | | [stopVideoCapture](#rtcvideo-stopvideocapture) | 关闭内部视频采集。默认为关闭状态。 | | [enumerateVideoCaptureDevices](#rtcvideo-enumeratevideocapturedevices) | 获取当前系统内视频采集设备列表。 | | [followSystemPlaybackDevice](#rtcvideo-followsystemplaybackdevice) | 设置音频播放路由是否跟随系统。 | | [followSystemCaptureDevice](#rtcvideo-followsystemcapturedevice) | 设置音频采集路由是否跟随系统。 | | [setVideoCaptureDevice](#rtcvideo-setvideocapturedevice) | 设置当前视频采集设备 | | [getVideoCaptureDevice](#rtcvideo-getvideocapturedevice) | 获取当前 SDK 正在使用的视频采集设备 ID | | [setVideoEncoderConfig](#rtcvideo-setvideoencoderconfig) | 视频发布端设置推送多路流时各路流的参数，包括最大分辨率、帧率、码率、网络不佳时的回退策略等。 | | [setMaxVideoEncoderConfig](#rtcvideo-setmaxvideoencoderconfig) | 视频发布端设置期望发布的最大分辨率视频流参数，包括分辨率、帧率、码率、缩放模式、网络不佳时的回退策略等。 | | [enableAlphaChannelVideoEncode](#rtcvideo-enablealphachannelvideoencode) | 开启带有Alpha通道的视频帧编码支持。 | | [disableAlphaChannelVideoEncode](#rtcvideo-disablealphachannelvideoencode) | 关闭带有Alpha通道的视频帧编码支持。 | | [setLocalVideoMirrorType](#rtcvideo-setlocalvideomirrortype) | 为采集到的视频流开启镜像 | | [enableSimulcastMode](#rtcvideo-enablesimulcastmode) | 该方法设置视频流发布端是否开启发布多路编码参数不同的视频流的模式。 | | [initCVResource](#rtcvideo-initcvresource) | 视频特效许可证检查 | | [getAuthMessage](#rtcvideo-getauthmessage) | 从 CV SDK 获取授权消息，用于获取在线许可证。 | | [enableVideoEffect](#rtcvideo-enablevideoeffect) | 开启高级美颜、滤镜等视频特效。 | | [disableVideoEffect](#rtcvideo-disablevideoeffect) | 关闭视频特效。 | | [enableEffectBeauty](#rtcvideo-enableeffectbeauty) | 开启/关闭基础美颜 | | [setBeautyIntensity](#rtcvideo-setbeautyintensity) | 调整基础美颜强度 | | [setEffectNodes](#rtcvideo-seteffectnodes) | 设置视频特效素材包，支持同时设置多个素材包 | | [updateEffectNode](#rtcvideo-updateeffectnode) | 设置特效强度 | | [setColorFilter](#rtcvideo-setcolorfilter) | 设置颜色滤镜 | | [setColorFilterIntensity](#rtcvideo-setcolorfilterintensity) | 设置已启用颜色滤镜的强度 | | [setVideoSourceType](#rtcvideo-setvideosourcetype) | 设置向 SDK 输入的视频源，包括屏幕流。默认使用内部采集。内部采集指：使用 RTC SDK 内置的视频采集机制进行视频采集。 | | [pushExternalVideoFrame](#rtcvideo-pushexternalvideoframe) | 推送外部视频帧。 | | [setAudioSourceType](#rtcvideo-setaudiosourcetype) | 切换音频采集方式 | | [pushExternalAudioFrame](#rtcvideo-pushexternalaudioframe) | 推送自定义采集的音频数据到 RTC SDK。 | | [startPushSingleStreamToCDN](#rtcvideo-startpushsinglestreamtocdn) | 新增单流转推直播任务。 | | [stopPushStreamToCDN](#rtcvideo-stoppushstreamtocdn) | 停止转推直播。 | | [setAnsMode](#rtcvideo-setansmode) | 支持根据业务场景，设置通话中的音频降噪模式。 | | [takeLocalSnapshot](#rtcvideo-takelocalsnapshot) | 截取本地视频画面 | | [takeRemoteSnapshot](#rtcvideo-takeremotesnapshot) | 截取远端视频画面 | | [getNetworkTimeInfo](#rtcvideo-getnetworktimeinfo) | 通过 NTP 协议，获取网络时间。 | | [sendStreamSyncInfo](#rtcvideo-sendstreamsyncinfo) | 发送音频流同步信息。将消息通过音频流发送到远端，并实现与音频流同步。 | | [startCloudProxy](#rtcvideo-startcloudproxy) | 开启云代理 | | [stopCloudProxy](#rtcvideo-stopcloudproxy) | 关闭云代理 | | [startPushPublicStream](#rtcvideo-startpushpublicstream) | 发布一路公共流。 | | [stopPushPublicStream](#rtcvideo-stoppushpublicstream) | 停止发布当前用户发布的公共流 | | [updatePublicStreamParam](#rtcvideo-updatepublicstreamparam) | 更新公共流参数 | | [startPlayPublicStream](#rtcvideo-startplaypublicstream) | 订阅指定公共流。无论用户是否在房间内，都可以调用本接口获取和播放指定的公共流。 | | [stopPlayPublicStream](#rtcvideo-stopplaypublicstream) | 取消订阅指定公共流 | | [setupPublicStreamVideo](#rtcvideo-setuppublicstreamvideo) | 为公共流绑定本地视图 | | [removePublicStreamVideo](#rtcvideo-removepublicstreamvideo) | 为公共流解绑本地视图 | | [setPublicStreamVideoSink](#rtcvideo-setpublicstreamvideosink) | 为指定公共流绑定自定义渲染器。 | | [unsetPublicStreamVideoSink](#rtcvideo-unsetpublicstreamvideosink) | 为指定公共解绑自定义渲染器。 | | [startScreenAudioCapture](#rtcvideo-startscreenaudiocapture) | 在屏幕共享时，开始使用 RTC SDK 内部采集方式，采集屏幕音频 | | [startScreenVideoCapture](#rtcvideo-startscreenvideocapture) | 采集屏幕视频流，用于共享。屏幕视频流包括：屏幕上显示的内容，应用窗口中显示的内容，或虚拟屏幕中显示的内容。其中，虚拟屏幕中显示的内容仅在 Windows 平台上支持。 | | [stopScreenAudioCapture](#rtcvideo-stopscreenaudiocapture) | 在屏幕共享时，停止使用 RTC SDK 内部采集方式，采集屏幕音频。 | | [stopScreenVideoCapture](#rtcvideo-stopscreenvideocapture) | 停止屏幕视频流采集。 | | [updateScreenCaptureRegion](#rtcvideo-updatescreencaptureregion) | 更新屏幕共享区域。 | | [updateScreenCaptureHighlightConfig](#rtcvideo-updatescreencapturehighlightconfig) | 通过 RTC SDK 提供的采集模块采集屏幕视频流时，更新边框高亮设置。默认展示表框。 | | [updateScreenCaptureMouseCursor](#rtcvideo-updatescreencapturemousecursor) | 通过 RTC SDK 提供的采集模块采集屏幕视频流时，更新对鼠标的处理设置。默认采集鼠标。 | | [updateScreenCaptureFilterConfig](#rtcvideo-updatescreencapturefilterconfig) | 通过 RTC SDK 提供的采集模块采集屏幕视频流时，设置需要过滤的窗口。 | | [setScreenAudioChannel](#rtcvideo-setscreenaudiochannel) | 在屏幕共享时，设置屏幕音频流的声道数 | | [getScreenCaptureSourceList](#rtcvideo-getscreencapturesourcelist) | 获取屏幕采集对象列表。 | | [getThumbnail](#rtcvideo-getthumbnail) | 获取共享对象缩略图 | | [getWindowAppIcon](#rtcvideo-getwindowappicon) | 获取应用窗体所属应用的图标。 | | [setScreenAudioStreamIndex](#rtcvideo-setscreenaudiostreamindex) | 在屏幕共享时，设置屏幕音频流和麦克风采集到的音频流的混流方式 | | [setScreenVideoEncoderConfig](#rtcvideo-setscreenvideoencoderconfig) | 为发布的屏幕共享视频流设置期望的编码参数，包括分辨率、帧率、码率、网络不佳时的回退策略等。 | | [login](#rtcvideo-login) | 登录 RTS 服务器。必须先登录，才能发送房间外点对点消息和向应用服务器发送消息 | | [logout](#rtcvideo-logout) | 登出 RTS 服务器。调用本接口登出后，无法调用房间外消息以及端到服务器消息相关的方法或收到相关回调。 | | [updateLoginToken](#rtcvideo-updatelogintoken) | 更新用户用于登录的 Token。 | | [setServerParams](#rtcvideo-setserverparams) | 设置业务服务器参数。 | | [getPeerOnlineStatus](#rtcvideo-getpeeronlinestatus) | 查询对端用户或本端用户的登录状态 | | [sendUserMessageOutsideRoom](#rtcvideo-sendusermessageoutsideroom) | 给房间外指定的用户发送文本消息（P2P） | | [sendUserBinaryMessageOutsideRoom](#rtcvideo-senduserbinarymessageoutsideroom) | 给房间外指定的用户发送二进制消息（P2P） | | [sendServerMessage](#rtcvideo-sendservermessage) | 客户端给业务服务器发送文本消息（P2Server） | | [sendServerBinaryMessage](#rtcvideo-sendserverbinarymessage) | 客户端给业务服务器发送二进制消息（P2Server） | | [sendSEIMessage](#rtcvideo-sendseimessage) | 通过视频帧发送 SEI 数据。 | | [setVideoCaptureConfig](#rtcvideo-setvideocaptureconfig) | 设置 RTC SDK 内部采集时的视频采集参数。指定视频采集参数包括模式、分辨率、帧率。 | | [startAudioMixing](#rtcvideo-startaudiomixing) | 开始播放音乐文件及混音 | | [stopAudioMixing](#rtcvideo-stopaudiomixing) | 停止播放音乐文件及混音 | | [pauseAudioMixing](#rtcvideo-pauseaudiomixing) | 暂停播放音乐文件及混音 | | [resumeAudioMixing](#rtcvideo-resumeaudiomixing) | 恢复播放音乐文件及混音 | | [preloadAudioMixing](#rtcvideo-preloadaudiomixing) | 预加载指定音乐文件到内存中，以避免频繁播放同一文件时的重复加载，减少 CPU 占用。 | | [unloadAudioMixing](#rtcvideo-unloadaudiomixing) | 卸载指定音乐文件 | | [setAudioMixingVolume](#rtcvideo-setaudiomixingvolume) | 调节音乐文件在本地和远端播放的音量大小 | | [getAudioMixingDuration](#rtcvideo-getaudiomixingduration) | 获取音乐文件时长 | | [getAudioMixingCurrentPosition](#rtcvideo-getaudiomixingcurrentposition) | 获取音乐文件播放进度 | | [setAudioMixingPosition](#rtcvideo-setaudiomixingposition) | 设置音乐文件的播放位置 | | [getAudioMixingPlaybackDuration](#rtcvideo-getaudiomixingplaybackduration) | 获取混音音频文件的实际播放时长（单位：毫秒）。 | | [setAudioMixingDualMonoMode](#rtcvideo-setaudiomixingdualmonomode) | 设置当前音频文件的声道模式 | | [setAudioMixingPitch](#rtcvideo-setaudiomixingpitch) | 开启本地播放音乐文件变调功能，多用于 K 歌场景。 | | [setAudioMixingPlaybackSpeed](#rtcvideo-setaudiomixingplaybackspeed) | 设置混音时音频文件的播放速度 | | [setAudioMixingLoudness](#rtcvideo-setaudiomixingloudness) | 如果你需要使用 enableVocalInstrumentBalance 对混音使音频文件/PCM 音频数据进行音量调整，你必须通过此接口传入其原始响度。 | | [setAudioMixingProgressInterval](#rtcvideo-setaudiomixingprogressinterval) | 设置混音时音频文件播放进度回调的间隔 | | [getAudioTrackCount](#rtcvideo-getaudiotrackcount) | 获取当前音频文件的音轨索引 | | [selectAudioTrack](#rtcvideo-selectaudiotrack) | 指定当前音频文件的播放音轨 | | [setLocalVoicePitch](#rtcvideo-setlocalvoicepitch) | 开启本地语音变调功能，多用于 K 歌场景。使用该方法，你可以对本地语音的音调进行升调或降调等调整。 | | [startFileRecording](#rtcvideo-startfilerecording) | 该方法将通话过程中的音视频数据录制到本地的文件中。 | | [stopFileRecording](#rtcvideo-stopfilerecording) | 停止本地录制 | | [setPublishFallbackOption](#rtcvideo-setpublishfallbackoption) | 设置发布的音视频流回退选项。你可以调用这个接口来设置网络情况不佳或设备性能不足时只发送小流，以保证通话质量。 | | [setSubscribeFallbackOption](#rtcvideo-setsubscribefallbackoption) | 设置订阅的音视频流回退选项。你可以通过调用该接口来设置网络情况不佳或性能不足时只订阅小流或音频流，以保证通话质量。 | | [setRemoteUserPriority](#rtcvideo-setremoteuserpriority) | 设置用户优先级 | | [startNetworkDetection](#rtcvideo-startnetworkdetection) | 开启通话前网络探测 | | [stopNetworkDetection](#rtcvideo-stopnetworkdetection) | 停止通话前网络探测 | | [enableVirtualBackground](#rtcvideo-enablevirtualbackground) | 将摄像头采集画面中的人像背景替换为指定图片或纯色背景。 | | [disableVirtualBackground](#rtcvideo-disablevirtualbackground) | 关闭虚拟背景。 | | [enableFaceDetection](#rtcvideo-enablefacedetection) | 开启人脸识别功能，并设置人脸检测结果回调观察者。 | | [disableFaceDetection](#rtcvideo-disablefacedetection) | 关闭人脸识别功能。 | | [setVideoWatermark](#rtcvideo-setvideowatermark) | 在指定视频流上添加水印。 | | [clearVideoWatermark](#rtcvideo-clearvideowatermark) | 移除指定视频流的水印。 | | [setupLocalVideo](#rtcvideo-setuplocalvideo) | 设置本地视频渲染时使用的视图，并设置渲染模式。 | | [removeLocalVideo](#rtcvideo-removelocalvideo) | 解绑本地视频流已绑定的渲染视图 | | [setupRemoteVideo](#rtcvideo-setupremotevideo) | 为远端视频流绑定本地渲染视图，并设置渲染模式。 | | [removeRemoteVideo](#rtcvideo-removeremotevideo) | 解绑指定远端视频流已绑定的本地视图 | | [removeAllRemoteVideo](#rtcvideo-removeallremotevideo) | 解绑所有已绑定本地视图的指定远端视频流 | | [setupLocalScreen](#rtcvideo-setuplocalscreen) | 为本地屏幕共享流绑定视图，实现预览 | | [removeLocalScreen](#rtcvideo-removelocalscreen) | 解绑屏幕共享流已绑定的视图 | | [setupRemoteScreen](#rtcvideo-setupremotescreen) | 为远端屏幕共享流绑定本地视图 | | [removeRemoteScreen](#rtcvideo-removeremotescreen) | 解绑远端屏幕共享流已绑定的本地视图 | | [setLocalVideoSink](#rtcvideo-setlocalvideosink) | 获取本地视频流。 | | [unsetLocalVideoSink](#rtcvideo-unsetlocalvideosink) | 停止获取本地视频流。 | | [setRemoteVideoSink](#rtcvideo-setremotevideosink) | 获取远端视频流。 | | [unsetRemoteVideoSink](#rtcvideo-unsetremotevideosink) | 停止获取远端视频流。 | | [playMusic](#rtcvideo-playmusic) | 播放歌曲。 | | [pauseMusic](#rtcvideo-pausemusic) | 暂停播放歌曲。 | | [resumeMusic](#rtcvideo-resumemusic) | 继续播放歌曲。 | | [stopMusic](#rtcvideo-stopmusic) | 停止播放歌曲。 | | [seekMusic](#rtcvideo-seekmusic) | 设置音乐文件的起始播放位置。 | | [setMusicVolume](#rtcvideo-setmusicvolume) | 设置歌曲播放音量，只能在开始播放后进行设置。 | | [switchAudioTrackType](#rtcvideo-switchaudiotracktype) | 切换歌曲原唱伴唱。 | | [setMusicPitch](#rtcvideo-setmusicpitch) | 对播放中的音乐设置升降调信息。 | | [setMaxCacheSize](#rtcvideo-setmaxcachesize) | 设置歌曲文件最大占用的本地缓存。 | | [getMusicList](#rtcvideo-getmusiclist) | 获取歌曲列表。 | | [searchMusic](#rtcvideo-searchmusic) | 根据关键词搜索歌曲。 | | [getHotMusic](#rtcvideo-gethotmusic) | 根据热榜类别获取每个榜单的歌曲列表。 | | [getMusicDetail](#rtcvideo-getmusicdetail) | 获取音乐详细信息。 | | [downloadMusic](#rtcvideo-downloadmusic) | 下载音乐。 | | [downloadLyric](#rtcvideo-downloadlyric) | 下载歌词。 | | [downloadMidi](#rtcvideo-downloadmidi) | 下载 MIDI 文件。 | | [cancelDownload](#rtcvideo-canceldownload) | 取消下载任务。 | | [clearCache](#rtcvideo-clearcache) | 清除当前音乐缓存文件，包括音乐音频和歌词。 | | [initSingScoring](#rtcvideo-initsingscoring) | 初始化 K 歌评分。 | | [setSingScoringConfig](#rtcvideo-setsingscoringconfig) | 设置 K 歌评分参数。 | | [getStandardPitchCount](#rtcvideo-getstandardpitchcount) | 获取当前系统内音视频设备数量 | | [getStandardPitchInfo](#rtcvideo-getstandardpitchinfo) | 获取每句歌词的标准音高信息 | | [startSingScoring](#rtcvideo-startsingscoring) | 开始 K 歌评分。 | | [stopSingScoring](#rtcvideo-stopsingscoring) | 停止 K 歌评分。 | | [getLastSentenceScore](#rtcvideo-getlastsentencescore) | 获取上一句的演唱评分。 | | [getTotalScore](#rtcvideo-gettotalscore) | 获取当前演唱总分。 | | [getAverageScore](#rtcvideo-getaveragescore) | 获取当前演唱歌曲的平均分。 | | [setLocalVoiceEqualization](#rtcvideo-setlocalvoiceequalization) | 设置本地采集语音的均衡效果。包含内部采集和外部采集，但不包含混音音频文件。 | | [setLocalVoiceReverbParam](#rtcvideo-setlocalvoicereverbparam) | 设置本地采集音频的混响效果。包含内部采集和外部采集，但不包含混音音频文件。 | | [enableLocalVoiceReverb](#rtcvideo-enablelocalvoicereverb) | 开启本地音效混响效果 | | [startAudioRecording](#rtcvideo-startaudiorecording) | 开启录制语音通话，生成本地文件。 | | [stopAudioRecording](#rtcvideo-stopaudiorecording) | 停止音频文件录制 | | [enableFilterSilentDevice](#rtcvideo-enablefiltersilentdevice) | 开启/关闭过滤无声设备功能。 | | [stopAllAudioMixing](#rtcvideo-stopallaudiomixing) | 停止播放所有音频文件及混音。 | | [pauseAllAudioMixing](#rtcvideo-pauseallaudiomixing) | 暂停播放所有音频文件及混音。 | | [resumeAllAudioMixing](#rtcvideo-resumeallaudiomixing) | 恢复播放所有音频文件及混音。 | | [enableAGC](#rtcvideo-enableagc) | 打开/关闭 AGC(Automatic Gain Control) 自动增益控制功能。开启该功能后，SDK 会自动调节麦克风的采集音量，确保音量稳定。 | | [setVideoCaptureRotation](#rtcvideo-setvideocapturerotation) | 设置本端采集的视频帧的旋转角度。当外接摄像头倒置或者倾斜安装时，调用本接口进行调整。 | | [setVideoDigitalZoomConfig](#rtcvideo-setvideodigitalzoomconfig) | 设置本地摄像头数码变焦参数，包括缩放倍数，移动步长。 | | [setVideoDigitalZoomControl](#rtcvideo-setvideodigitalzoomcontrol) | 控制本地摄像头数码变焦，缩放或移动一次。设置对本地预览画面和发布到远端的视频都生效。 | | [startVideoDigitalZoomControl](#rtcvideo-startvideodigitalzoomcontrol) | 开启本地摄像头持续数码变焦，缩放或移动。设置对本地预览画面和发布到远端的视频都生效。 | | [stopVideoDigitalZoomControl](#rtcvideo-stopvideodigitalzoomcontrol) | 停止本地摄像头持续数码变焦。 | | [startPushMixedStreamToCDN](#rtcvideo-startpushmixedstreamtocdn) | 新增转推直播任务(新)，并设置合流的图片、视频视图布局和音频属性。 | | [updatePushMixedStreamToCDN](#rtcvideo-updatepushmixedstreamtocdn) | 更新转推直播参数。 | | [setupMixingVideo](#rtcvideo-setupmixingvideo) | 为客户端合流绑定本地视图 | | [removeMixingVideo](#rtcvideo-removemixingvideo) | 为合流转推解绑本地视图 | | [setPublicStreamAudioPlaybackVolume](#rtcvideo-setpublicstreamaudioplaybackvolume) | 调节公共流的音频播放音量。 | | [startHardwareEchoDetection](#rtcvideo-starthardwareechodetection) | 开启通话前回声检测 | | [stopHardwareEchoDetection](#rtcvideo-stophardwareechodetection) | 停止通话前回声检测 | | [setLocalProxy](#rtcvideo-setlocalproxy) | 设置本地代理。 | | [setEarMonitorMode](#rtcvideo-setearmonitormode) | 开启/关闭耳返功能 | | [setEarMonitorVolume](#rtcvideo-setearmonitorvolume) | 设置耳返的音量 | | [getAudioEffectPlayer](#rtcvideo-getaudioeffectplayer) | 创建音效播放器实例。 | | [getMediaPlayer](#rtcvideo-getmediaplayer) | 创建音乐播放器实例。 | | [enableExternalSoundCard](#rtcvideo-enableexternalsoundcard) | 启用匹配外置声卡的音频处理模式 | | [enableAudioFrameCallback](#rtcvideo-enableaudioframecallback) | 设置并开启指定的音频数据帧回调。 | | [disableAudioFrameCallback](#rtcvideo-disableaudioframecallback) | 关闭音频回调 | | [setAudioAlignmentProperty](#rtcvideo-setaudioalignmentproperty) | 在听众端，设置订阅的所有远端音频流精准对齐后播放。 | | [enablePlaybackDucking](#rtcvideo-enableplaybackducking) | 打开/关闭音量闪避功能，适用于在 RTC 通话过程中会同时播放短视频或音乐的场景，如“一起看”、“在线 KTV”等。开启该功能后，当检测到远端人声时，RTC 的本地的媒体播放音量会自动减弱，从而保证远端人声的清晰可辨；当远端人声消失时，RTC 的本地媒体音量会恢复到闪避前的音量水平。 | | [startAudioDeviceRecordTest](#rtcvideo-startaudiodevicerecordtest) | 开始音频采集设备和音频播放设备测试。 | | [stopAudioDeviceRecordAndPlayTest](#rtcvideo-stopaudiodevicerecordandplaytest) | 停止采集本地音频，并开始播放采集到的声音。录音播放完毕后，设备测试流程结束。 | | [stopAudioDevicePlayTest](#rtcvideo-stopaudiodeviceplaytest) | 停止由调用 [startAudioDeviceRecordTest](85532#rtcvideo-startaudiodevicerecordtest) 开始的音频播放设备测试。 | | [setLowLightAdjusted](#rtcvideo-setlowlightadjusted) | 设置视频暗光增强模式。对于光线不足、照明不均匀或背光等场景下推荐开启，可有效改善画面质量。 | | `static` [getSDKVersion](#static-rtcvideo-getsdkversion) | 获取当前 SDK 版本信息 | | `static` [setLogConfig](#static-rtcvideo-setlogconfig) | 设置日志文件 | | `static` [getErrorDescription](#static-rtcvideo-geterrordescription) | 获取错误码的描述 | | `static` [getCurrentProcessId](#static-rtcvideo-getcurrentprocessid) | 获取加载引擎进程的 ID 方便调试 | | `static` [setRenderType](#static-rtcvideo-setrendertype) | 设置渲染类型 | | `static` [getTimestampMs](#static-rtcvideo-gettimestampms) | 获取时间戳, 单位毫秒 | | `static` [getTimestampUs](#static-rtcvideo-gettimestampus) | 获取时间戳, 单位微秒 | ### createRTCVideo 创建引擎对象 - **类型** ```ts (app_id: string, parameters: string) => number ``` - **注意** + 你应注意保持 handler 的生命周期必须大于 `RTCVideo` 的生命周期，即 handler 必须在调用 [createRTCVideo](#creatertcvideo) 之前创建，在调用 [destroyRTCVideo](#destroyrtcvideo) 之后销毁。 + 通常不建议在移动端设备上创建多于 2 个引擎实例。 + 如果当前线程中未创建引擎实例，那么你必须先使用此方法，以使用 RTC 提供的各种音视频能力。 + 如果当前线程中已创建了引擎实例，再次调用此方法时，会返回已创建的引擎实例。 - **参数** - **app_id** 类型: string 每个应用的唯一标识符，由 RTC 控制台随机生成的。不同的 AppId 生成的实例在 RTC 中进行音视频通话完全独立，无法互通。获取到当前应用的目录路径。 - **parameters** 类型: string 私有参数。如需使用请联系技术支持人员。 - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### createRTCRoom 创建房间 - **类型** ```ts (room_id: string) => veRTCRoom ``` - **注意** 多次调用此方法以创建多个 `veRTCRoom` 实例。分别调用各实例中的 joinRoom 方法，同时加入多个房间。多房间模式下，用户可以同时订阅各房间的音视频流。 - **参数** - **room_id** 类型: string 标识通话房间的房间 ID，最大长度为 128 字节的非空字符串。支持的字符集范围为: • 26个大写字母 A ~ Z • 26个小写字母 a ~ z • 10个数字 0 ~ 9 • 下划线 "_", at 符 "@", 减号 "-" 请勿使用同样的 roomId 创建多个房间，否则后创建的房间实例会替换先创建的房间实例。 - **返回值** 类型: veRTCRoom + `0`: 成功 + `-1`: 失败 ### destroyRTCVideo 销毁引擎实例对象 - **类型** ```ts () => number ``` - **注意** + 请确保和需要销毁的 `RTCVideo` 实例相关的业务场景全部结束后，才调用此方法 + 该方法在调用之后，会销毁所有和此 `RTCVideo` 实例相关的内存，并且停止与媒体服务器的任何交互 + 调用本方法会启动 SDK 退出逻辑。引擎线程会保留，直到退出逻辑完成。因此，不要在回调线程中直接调用此 API，会导致死锁。同时此方法是耗时操作，不建议在主线程调用本方法，避免主线程阻塞。 - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### feedback 将用户反馈的问题上报到 RTC - **类型** ```ts (type: ProblemFeedbackOption, info: ProblemFeedbackInfo) => number ``` - **注意** + 你可以在 [RTC 控制台](https://console.volcengine.com/rtc/callQualityRTC/feedback?from=doc)上查看用户通过此接口提交的反馈详情和整体趋势。 + 如果用户上报时在房间内，那么问题会定位到用户当前所在的一个或多个房间；如果用户上报时不在房间内，那么问题会定位到引擎此前退出的房间。 - **参数** - **type** 类型: [ProblemFeedbackOption](85535#problemfeedbackoption) 反馈问题类型。 - **info** 类型: [ProblemFeedbackInfo](85535#problemfeedbackinfo) 预设问题以外的其他问题的具体描述，房间信息。 - **返回值** 类型: number - 0: 上报成功。 - -3: 上报失败。 ### setBusinessId 设置业务标识参数 - **类型** ```ts (business_id: string) => number ``` - **注意** 可通过 businessId 区分不同的业务场景。businessId 由客户自定义，相当于一个“标签”，可以分担和细化现在 AppId 的逻辑划分的功能，但不需要鉴权。 - **参数** - **business_id** 类型: string 用户设置的自己的 business_id 值。business_id 相当于一个 sub AppId，可以分担和细化现在 AppId 的逻辑划分的功能，但不需要鉴权。business_id 只是一个标签，颗粒度需要用户自定义。 - **返回值** 类型: number + 0：成功。 + <0：失败 + -2：参数非法。 ### setEncryptInfo 设置传输时使用内置加密的方式 - **类型** ```ts (encrypt_type: number, key: string) => number ``` - **注意** 该方法必须在进房之前调用，可重复调用，以最后调用的参数作为生效参数。 - **参数** - **encrypt_type** 类型: number 加密算法

`0`: 不使用内置加密

`1`:AES-128-CBC 加密算法

`2`:AES-256-CBC 加密算法

`3`:AES-128-ECB 加密算法

`4`:AES-256-ECB 加密算法

- **key** 类型: string 加密密钥，长度限制为 36 位，超出部分将会被截断 - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### initializePluginManager 初始化插件管理器 - **类型** ```ts () => number ``` - **注意** 该方法必须在创建引擎之后，进房之前调用。 - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### releasePluginManager 释放插件管理器 - **类型** ```ts () => number ``` - **注意** 该方法必须在初始化插件管理器之后，销毁引擎之前调用。 - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### registerPlugin 注册插件 - **类型** ```ts (info: RTCPluginInfo) => number ``` - **注意** 该方法必须在初始化插件管理器之后调用。 - **参数** - **info** 类型: [RTCPluginInfo](85535#rtcplugininfo) #RTCPluginInfo类型：id是插件的唯一标识，path是插件库的路径 - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### getPlugin 获取插件实例 - **类型** ```ts (plugin_id: string) => RTCPlugin | undefined ``` - **注意** 该方法必须在注册插件之后调用。 - **参数** - **plugin_id** 类型: string 是插件的唯一标识 - **返回值** 类型: [RTCPlugin](85535#rtcplugin) | undefined #RTCPlugin类型，如果插件不存在返回undefined ### unregisterPlugin 卸载插件 - **类型** ```ts (plugin_id: string) => number ``` - **注意** 该方法必须在注册插件之后调用。 - **参数** - **plugin_id** 类型: string 是插件的唯一标识 - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### muteAudioCapture 设置是否将录音信号静音（不改变本端硬件）。 - **类型** ```ts (index: number, mute: boolean) => number ``` - **注意** + 该方法支持选择静音或取消静音麦克风采集，而不影响 SDK 音频流发布状态。 + 静音后通过 [`setCaptureVolume`](85532#rtcvideo-setcapturevolume) 调整音量不会取消静音状态，音量状态会保存至取消静音。 + 调用 [`startAudioCapture`](85532#rtcvideo-startaudiocapture) 开启音频采集前后，都可以使用此接口设置采集音量。 - **参数** - **index** 类型: number 流索引，指定调节主流/屏幕流音量。 + `0`: 主流。由麦克风通过内部采集机制，采集到的音频; + `1`: 屏幕流。来自声卡的本地播放音频流。 - **mute** 类型: boolean 是否静音音频采集。 + true：静音（关闭麦克风） + false：（默认）开启麦克风 - **返回值** 类型: number + 0: 调用成功。 + < 0 : 调用失败。 ### startAudioCapture 开启内部音频采集。默认为关闭状态。 - **类型** ```ts () => number ``` - **注意** + 进房前调用该方法，本地用户会收到 [onAudioDeviceStateChanged](85533#onaudiodevicestatechanged) 的回调。 + 若未取得当前设备的麦克风权限，调用该方法后会触发 [onAudioDeviceStateChanged](85533#onaudiodevicestatechanged) 回调，对应的 `device_error` 为 1。 + 调用 stopAudioCapture 可以关闭音频采集设备，否则，SDK 只会在销毁引擎的时候自动关闭设备。 + 由于不同硬件设备初始化响应时间不同，频繁调用 stopAudioCapture 和本接口闭麦/开麦可能出现短暂无声问题，建议使用 publishStream/unpublishStream 实现临时闭麦和重新开麦。 + 创建引擎后，无论是否发布音频数据，你都可以调用该方法开启音频采集，并且调用后方可发布音频。 - **返回值** 类型: number + 0：成功 + !0：失败 ### stopAudioCapture 关闭内部音频采集。默认为关闭状态。 - **类型** ```ts () => number ``` - **注意** + 进房前调用该方法，本地用户会收到 [onAudioDeviceStateChanged](85533#onaudiodevicestatechanged) 的回调。 + 可见用户进房后调用该方法后，房间中的其他用户会收到 [onUserStopAudioCapture](85533#onuserstopaudiocapture) 的回调。 + 调用 [startAudioCapture](85532#startaudiocapture) 可以开启音频采集设备。 + 如果不调用本方法停止内部视频采集，则只有当销毁引擎实例时，内部音频采集才会停止。 - **返回值** 类型: number + 0：成功 + !0：失败 ### enumerateAudioPlaybackDevices 获取当前系统内音频播放设备列表。如果后续设备有变更，你会收到 [`onAudioDeviceStateChanged`](85533#rtcvideocallback-onaudiodevicestatechanged) 回调通知，然后需要重新调用本接口以获得新的设备列表。 - **类型** ```ts () => { device_name: string; device_id: string;}[] ``` - **返回值** 类型: { device_name: string; device_id: string; }[] 包含系统中所有音频播放设备的列表和相关信息 ### enumerateAudioCaptureDevices 获取当前系统内音频采集设备列表。如果后续设备有变更，你需要重新调用本接口以获得新的设备列表。 - **类型** ```ts () => { device_name: string; device_id: string;}[] ``` - **返回值** 类型: { device_name: string; device_id: string; }[] 包含系统中所有音频采集设备列表和相关信息 ### setAudioPlaybackDevice 设置音频播放设备。 - **类型** ```ts (device_id: string) => number ``` - **注意** 当你调用 followSystemPlaybackDevice 设置音频播放设备跟随系统后，将无法调用此接口设置音频播放设备。 - **参数** - **device_id** 类型: string 音频播放设备 ID，可通过 [enumerateAudioPlaybackDevices](#enumerateaudioplaybackdevices) 获取。 - **返回值** 类型: number 方法调用结果 + 0：方法调用成功 + <0：方法调用失败 ### setAudioCaptureDevice 设置音频采集设备。 - **类型** ```ts (device_id: string) => number ``` - **注意** 当你调用 followSystemCaptureDevice 设置音频采集设备跟随系统后，将无法调用此接口设置音频采集设备。 - **参数** - **device_id** 类型: string 音频采集设备 ID，可通过 [enumerateAudioPlaybackDevices](#enumerateaudioplaybackdevices) 获取。 - **返回值** 类型: number 方法调用结果 + 0：方法调用成功 + <0：方法调用失败 ### getAudioPlaybackDevice 获取当前音频播放设备 ID。 - **类型** ```ts () => string ``` - **返回值** 类型: string 当前音频播放设备 ID ### getAudioCaptureDevice 获取当前音频采集设备 ID。 - **类型** ```ts () => string ``` - **返回值** 类型: string 当前音频采集设备 ID ### setAudioPlaybackDeviceVolume 设置当前音频播放设备音量 - **类型** ```ts (volume: number) => number ``` - **参数** - **volume** 类型: number 音频播放设备音量，取值范围为 [0,255], 超出此范围设置无效。 + [0,25] 接近无声； + [25,75] 为低音量； + [76,204] 为中音量； + [205,255] 为高音量。 - **返回值** 类型: number 方法调用结果 + 0：方法调用成功 + <0：方法调用失败 ### getAudioPlaybackDeviceVolume 获取当前音频播放设备音量 - **类型** ```ts () => number ``` - **返回值** 类型: number 音频播放设备音量，范围应在 [0,255] 内。 + [0,25] 接近无声； + [25,75] 为低音量； + [76,204] 为中音量； + [205,255] 为高音量。 ### setAudioCaptureDeviceVolume 设置当前音频采集设备音量 - **类型** ```ts (volume: number) => number ``` - **注意** 如果音频采集设备通过 [`setAudioCaptureDeviceMute`](85532#rtcvideo-setaudiocapturedevicemute) 被静音，则音量调节会在取消静音后生效。 - **参数** - **volume** 类型: number 音频采集设备音量，取值范围为 [0,255], 超出此范围设置无效。 + [0,25] 接近无声； + [25,75] 为低音量； + [76,204] 为中音量； + [205,255] 为高音量。 - **返回值** 类型: number 方法调用结果 + 0：方法调用成功 + <0：方法调用失败 ### getAudioCaptureDeviceVolume 获取当前音频采集设备音量 - **类型** ```ts () => number ``` - **返回值** 类型: number 范围应在 [0,255] 内。 + [0,25] 接近无声； + [25,75] 为低音量； + [76,204] 为中音量； + [205,255] 为高音量。 ### setAudioPlaybackDeviceMute 设置当前音频播放设备静音状态，默认为非静音。 - **类型** ```ts (mute: boolean) => number ``` - **参数** - **mute** 类型: boolean

true：静音

false：非静音

- **返回值** 类型: number 方法调用结果 + 0：方法调用成功 + <0：方法调用失败 ### getAudioPlaybackDeviceMute 获取当前音频播放设备是否静音的信息。 - **类型** ```ts () => boolean ``` - **返回值** 类型: boolean

true：静音

false：非静音

### setAudioCaptureDeviceMute 设置当前音频采集设备静音状态，默认为非静音。 - **类型** ```ts (mute: boolean) => number ``` - **注意** + 该方法用于静音整个系统的音频采集。 + 设该方法为 `true` 静音后仍可通过 [`setAudioCaptureDeviceVolume`](85532#rtcvideo-setaudiocapturedevicevolume) 调整采集音量，调整后的音量会在取消静音后生效。 - **参数** - **mute** 类型: boolean

true：静音

false：非静音

- **返回值** 类型: number 方法调用结果 + 0：方法调用成功 + <0：方法调用失败 ### getAudioCaptureDeviceMute 获取当前音频采集设备是否静音的信息。 - **类型** ```ts () => boolean ``` - **返回值** 类型: boolean + true：静音 + false：非静音 ### setCaptureVolume 调节音频采集音量 - **类型** ```ts (index: number, volume: number) => number ``` - **注意** 在开启音频采集前后，你都可以使用此接口设定采集音量。 - **参数** - **index** 类型: number 流索引，指定调节主流还是调节屏幕流的音量

主流。包括：由摄像头/麦克风通过内部采集机制，采集到的视频/音频。

屏幕流。屏幕共享时共享的视频流，或来自声卡的本地播放音频流。

- **volume** 类型: number 采集的音量值和原始音量的比值，范围是 [0, 400]，单位为 %，自带溢出保护。只改变音频数据的音量信息，不涉及本端硬件的音量调节。为保证更好的通话质量，建议将 volume 值设为 [0,100]。 + 0：静音 + 100：原始音量 + 400: 最大可为原始音量的 4 倍(自带溢出保护) - **返回值** 类型: number + 0：成功 + !0：失败 ### setPlaybackVolume 调节本地播放的所有远端用户音频混音后的音量，混音内容包括远端人声、音乐、音效等。播放音频前或播放音频时，你都可以使用此接口设定播放音量。 - **类型** ```ts (volume: number) => number ``` - **参数** - **volume** 类型: number 音频播放音量，取值范围： [0,400]。只改变音频数据的音量信息，不涉及本端硬件的音量调节。为保证更好的通话质量，建议将 volume 值设为 [0,100]。 + 0: 静音 + 100: 原始音量 + 400: 最大可为原始音量的 4 倍(自带溢出保护) - **返回值** 类型: number + 0：成功 + !0：失败 ### setRemoteAudioPlaybackVolume 调节来自远端用户的音频播放音量 - **类型** ```ts (room_id: string, user_id: string, volume: number) => number ``` - **参数** - **room_id** 类型: string 音频来源用户所在的房间 ID - **user_id** 类型: string 音频来源的远端用户 ID - **volume** 类型: number 播放音量只改变音频数据的音量信息，不涉及本端硬件的音量调节。取值范围： [0,400]

0: 静音

100: 原始音量，默认值

400: 最大可为原始音量的 4 倍(自带溢出保护) - **返回值** 类型: number + 0：成功 + !0：失败 ### stopAudioPlaybackDeviceTest 停止音频播放设备测试。 - **类型** ```ts () => number ``` - **注意** 调用 [startAudioPlaybackDeviceTest](#startaudioplaybackdevicetest) 后，需调用本方法停止测试。 - **返回值** 类型: number 方法调用结果 + `0`：成功 + `< 0`：失败 ### setVoiceChangerType 设置变声特效类型 - **类型** ```ts (change_type: number) => number ``` - **注意** + 在进房前后都可设置。 + 对 RTC SDK 内部采集的音频和自定义采集的音频都生效。 + 只对单声道音频生效。 + 只在包含美声特效能力的 SDK 中有效。 + 与 [setVoiceReverbType](#setvoicereverbtype) 互斥，后设置的特效会覆盖先设置的特效。 - **参数** - **change_type** 类型: number 变声特效类型。 + `0`: 原声，不含特效 + `1`: 巨人 + `2`: 花栗鼠 + `3`: 小黄人 + `4`: 颤音 + `5`: 机器人 - **返回值** 类型: number + 0：成功 + !0：失败。查看 [ReturnStatus](85535#returnstatus) 获得错误说明。 ### setVoiceReverbType 设置混响特效类型 - **类型** ```ts (voice_reverb_type: number) => number ``` - **注意** + 在进房前后都可设置。 + 只对单声道音频生效。 + 只在包含美声特效能力的 SDK 中有效。 + 与 [setVoiceChangerType](#setvoicechangertype) 互斥，后设置的特效会覆盖先设置的特效。 - **参数** - **voice_reverb_type** 类型: number 混响特效类型 + `0`: 原声，不含特效 + `1`: 回声 + `2`: 演唱会 + `3`: 空灵 + `4`: KTV + `5`: 录音棚 - **返回值** 类型: number + 0：成功 + !0：失败。查看 [ReturnStatus](85535#returnstatus) 获得错误说明。 ### setAudioProfile 设置音质档位。 - **类型** ```ts (audio_profile: number) => number ``` - **注意** + 设置音质档位。当所选的 audioProfile 中的音频参数无法满足你的场景需求时，调用本接口切换的音质档位。 + 该方法在进房前后均可调用； + 支持通话过程中动态切换音质档位。 - **参数** - **audio_profile** 类型: number 音质档位 + `0`: 默认音质，服务器下发或客户端已设置的 RoomProfileType 的音质配置 + `1`: 流畅音质，单声道，采样率为 16 kHz，编码码率为 32 Kbps。流畅优先、低功耗、低流量消耗，适用于大部分游戏场景，如小队语音、组队语音、国战语音等。 + `2`: 单声道标准音质。采样率为 24 kHz，编码码率为 48 kbps。适用于对音质有一定要求的场景，同时延时、功耗和流量消耗相对适中，适合教育场景和狼人杀等游戏。 + `3`: 双声道音乐音质。采样率为 48kHz，编码码率为 128 kbps。超高音质，同时延时、功耗和流量消耗相对较大，适用于连麦 PK 等音乐场景。游戏场景不建议使用。 + `4`: 双声道标准音质。采样率为 48 KHz，编码码率最大值为 80 Kbps。 + `5`: 单声道音乐音质。采样率为 48 kHz，编码码率最大值为 64 Kbps - **返回值** 类型: number + `0`：成功 + `!0`：失败 ### startAudioPlaybackDeviceTest 启动音频播放设备测试。该方法测试播放设备是否能正常工作。SDK 播放指定的音频文件，测试者如果能听到声音，说明播放设备能正常工作。 - **类型** ```ts (test_audio_file_path: string, indication_interval: number) => number ``` - **注意** + 该方法必须在 [joinRoom](#joinroom) 前调用，且不可与其它音频设备测试功能同时应用。 + 你需调用 [stopAudioPlaybackDeviceTest](#stopaudioplaybackdevicetest) 停止测试。 - **参数** - **test_audio_file_path** 类型: string 音频文件的绝对路径，路径字符串使用 UTF-8 编码格式，支持以下音频格式: mp3，aac，m4a，3gp，wav。 - **indication_interval** 类型: number 设置 onAudioPlaybackDeviceTestVolume 音量回调的时间间隔，推荐设置为 200 毫秒或以上。单位为毫秒。最小值为 10 毫秒。 - **返回值** 类型: number 方法调用结果 + 0：方法调用成功 + <0：方法调用失败 ### startEchoTest 开始音频设备回路测试。 - **类型** ```ts (echo_test_config: EchoTestConfig, play_delay_time: number) => number ``` - **注意** + 在进房前，用户可调用该接口对音视频通话全链路进行检测，包括对音视频设备以及用户上下行网络的检测，从而帮助用户判断是否可以正常发布和接收音视频流。 + 开始检测后，SDK 会录制你声音或视频。如果你在设置的延时范围内收到了回放，则视为音视频回路测试正常。 + 调用该方法开始音视频回路检测后，你可以调用 [stopEchoTest](#stopechotest) 立即结束测试，也可等待测试 60s 后自动结束，以更换设备进行下一次测试，或进房。 + 在该方法之前调用的所有跟设备控制、流控制相关的方法均在开始检测时失效，在结束检测后恢复生效。 + 在调用 [startEchoTest](#startechotest) 和 [stopEchoTest](#stopechotest) 之间调用的所有跟设备采集、流控制、进房相关的方法均不生效，并会收到 [onWarning](85533#onwarning) 回调，提示警告码为 `kWarningCodeInEchoTestMode`。 + 音视频回路检测的结果会通过 [onEchoTestResult](85533#onechotestresult) 回调通知。 - **参数** - **echo_test_config** 类型: [EchoTestConfig](85535#echotestconfig) 回路测试参数设置 - **play_delay_time** 类型: number 音视频延迟播放的时间间隔，用于指定在开始检测多长时间后期望收到回放。取值范围为 [2,10]，单位为秒，默认为 2 秒。 - **返回值** 类型: number 方法调用结果： + 0：成功 + -2：失败，参数异常 + -4：失败，用户已进房 + -6：失败，当前用户已经在检测中 + -7：失败，音视频均不检测 + -8：失败，已经存在相同 roomId 的房间 ### stopEchoTest 停止音频设备回路测试。 - **类型** ```ts () => number ``` - **注意** + 调用 [startEchoTest](#startechotest) 后，需调用本方法停止测试。 + 音视频回路检测结束后，所有对系统设备及音视频流的控制均会恢复到开始检测前的状态。 - **返回值** 类型: number 方法调用结果 + 0：成功。 + -3：失败，未开启回路检测 ### initAudioPlaybackDeviceForTest 尝试初始化音频播放设备，可检测出设备不存在、权限被拒绝/禁用等异常问题。 - **类型** ```ts (device_id: string) => number ``` - **注意** 1. 该接口需在进房前调用； 2. 检测成功不代表设备一定可以启动成功，还可能因设备被其他应用进程独占，或 CPU/内存不足等原因导致启动失败。 - **参数** - **device_id** 类型: string 设备索引号 - **返回值** 类型: number 设备状态错误码 + 0: 设备检测结果正常 + -1: 接口状态不正确，例如在正常启动采集后再调用该接口进行检测 + -2: 采集设备无麦克风权限，尝试初始化设备失败 + -3: 设备不存在，当前没有设备或设备被移除时返回 + -4: 设备音频格式不支持 + -5: 其它原因错误 ### initAudioCaptureDeviceForTest 尝试初始化音频播放设备，可检测出设备不存在、权限被拒绝/禁用等异常问题。 - **类型** ```ts (device_id: string) => number ``` - **注意** 1. 该接口需在进房前调用； 2. 检测成功不代表设备一定可以启动成功，还可能因设备被其他应用进程独占，或 CPU/内存不足等原因导致启动失败。 - **参数** - **device_id** 类型: string 设备索引号 - **返回值** 类型: number 设备状态错误码 + 0: 设备检测结果正常 + -1: 接口状态不正确，例如在正常启动采集后再调用该接口进行检测 + -2: 采集设备无麦克风权限，尝试初始化设备失败 + -3: 设备不存在，当前没有设备或设备被移除时返回 + -4: 设备音频格式不支持 + -5: 其它原因错误 ### enableAudioPropertiesReport 启用音频信息提示。 - **类型** ```ts (config: AudioPropertiesConfig) => number ``` - **注意** 开启提示后，你可以： + 通过 [onLocalAudioPropertiesReport](85533#onlocalaudiopropertiesreport) 回调获取本地麦克风和屏幕音频流采集的音频信息。 + 通过 [onRemoteAudioPropertiesReport](85533#onremoteaudiopropertiesreport) 回调获取订阅的远端用户的音频信息。 + 通过 [onActiveSpeaker](85533#onactivespeaker) 回调获取房间内的最活跃用户信息。 - **参数** - **config** 类型: [AudioPropertiesConfig](85535#audiopropertiesconfig) 音频属性信息提示的相关配置。 - **返回值** 类型: number ### enableVocalInstrumentBalance 开启/关闭音量均衡功能。 - **类型** ```ts (enable: boolean) => number ``` - **注意** 开启音量均衡功能后，人声的响度会调整为 -16lufs。如果已调用 setAudioMixingLoudness 传入了混音音乐的原始响度，此音乐播放时，响度会调整为 -20lufs。（Linux 不支持） - **参数** - **enable** 类型: boolean 是否开启音量均衡功能： - **返回值** 类型: number + 0: 调用成功 + <0: 调用失败 ### setDummyCaptureImagePath 摄像头处于关闭状态时，使用静态图片填充本地推送的视频流。可重复调用该接口来更新图片。若要停止发送图片，可传入空字符串或启用内部摄像头采集。 - **类型** ```ts (file_path: string) => number ``` - **注意** + 该接口只适用于 SDK 内部摄像头采集，不适用于自定义视频采集。 + 本地预览无法看到静态图片。 + 进入房间前后均可调用此方法。在多房间场景中，静态图片仅在发布的房间中生效。 + 针对该静态图片，滤镜和镜像效果不生效，水印效果生效。 + 只有主流能设置静态图片，屏幕流不支持设置。 + 开启大小流后，静态图片对大小流均生效，且针对小流进行等比例缩小。 - **参数** - **file_path** 类型: string 设置静态图片的路径。支持本地文件绝对路径，不支持网络链接，长度限制为 512 字节。静态图片支持类型为 JPEG/JPG、PNG、BMP。若图片宽高比与设置的编码宽高比不一致，图片会被等比缩放，黑边填充空白区域。推流帧率与码率与设置的编码参数一致。 - **返回值** 类型: number + 0: 成功。 + -2: 失败。确保传入的 file_path 为有效路径。 + -12: 本方法不支持在 Audio SDK 中使用。 ### startVideoCapture 开启内部视频采集。默认为关闭状态。 - **类型** ```ts () => number ``` - **注意** + 内部视频采集指：使用 RTC SDK 内置视频采集模块，进行采集。 + 调用该方法后，本地用户会收到 [onVideoDeviceStateChanged](85533#onvideodevicestatechanged) 的回调。 + 本地用户在不可见状态下调用该方法后，房间中的其他用户会收到 [onUserStartVideoCapture](85533#onuserstartvideocapture) 的回调。 + 调用 stopVideoCapture 可以停止内部视频采集。否则，只有当销毁引擎实例时，内部视频采集才会停止。 + 创建引擎后，无论是否发布视频数据，你都可以调用该方法开启内部视频采集。 - **返回值** 类型: number + `0`：成功 + `!0`：失败 ### stopVideoCapture 关闭内部视频采集。默认为关闭状态。 - **类型** ```ts () => number ``` - **注意** + 内部视频采集指：使用 RTC SDK 内置视频采集模块，进行采集。 + 调用该方法后，本地用户会收到 onVideoDeviceStateChanged 的回调。 + 可见用户进房后调用该方法，房间中的其他用户会收到 onUserStopVideoCapture 的回调。 + 调用 startVideoCapture 可以开启内部视频采集。 + 如果不调用本方法停止内部视频采集，则只有当销毁引擎实例时，内部视频采集才会停止。 - **返回值** 类型: number + 0：成功 + !0：失败 ### enumerateVideoCaptureDevices 获取当前系统内视频采集设备列表。 - **类型** ```ts () => { device_name: string; device_id: string;}[] ``` - **返回值** 类型: { device_name: string; device_id: string; }[] 包含系统中所有视频采集设备的列表和相关信息 ### followSystemPlaybackDevice 设置音频播放路由是否跟随系统。 - **类型** ```ts (followed: boolean) => number ``` - **参数** - **followed** 类型: boolean 音频播放路由是否跟随系统 + true: 跟随。默认值。此时，调用 [setAudioPlaybackDevice](#setaudioplaybackdevice) 会失败。 + false: 不跟随系统。此时，可以调用 [setAudioPlaybackDevice](#setaudioplaybackdevice) 进行设置。 - **返回值** 类型: number + 0：成功 + !0：失败 ### followSystemCaptureDevice 设置音频采集路由是否跟随系统。 - **类型** ```ts (followed: boolean) => number ``` - **参数** - **followed** 类型: boolean 音频采集路由是否跟随系统 + true: 跟随。默认值。此时，调用 [setAudioCaptureDevice](#setaudiocapturedevice) 会失败。 + false: 不跟随系统。此时，可以调用 [setAudioCaptureDevice](#setaudiocapturedevice) 进行设置。 - **返回值** 类型: number + 0：成功 + !0：失败 ### setVideoCaptureDevice 设置当前视频采集设备 - **类型** ```ts (device_id: string) => number ``` - **参数** - **device_id** 类型: string 视频设备 ID，可以通过 [EnumerateVideoCaptureDevices](#enumeratevideocapturedevices) 获取 - **返回值** 类型: number + 0：方法调用成功 + !0：方法调用失败 ### getVideoCaptureDevice 获取当前 SDK 正在使用的视频采集设备 ID - **类型** ```ts () => string ``` - **返回值** 类型: string 当前 SDK 正在使用的视频采集设备 ID ### setVideoEncoderConfig 视频发布端设置推送多路流时各路流的参数，包括最大分辨率、帧率、码率、网络不佳时的回退策略等。 - **类型** ```ts (solutions: VideoEncoderConfig[]) => number ``` - **注意** + 该方法是否生效取决于是否同时调用了 [enableSimulcastMode](#enablesimulcastmode) 开启发布多路参数不同的视频流模式。若未开启推送多路流模式，但调用本方法设置了多个分辨率，SDK 默认发布分辨率最大的一条流，多个分辨率的设置会在开启推送多路流模式之后生效。 + 调用该方法设置多路视频流参数前，SDK 默认仅发布一条分辨率为 640px × 360px，帧率为 15fps 的视频流。 + 调用该方法设置分辨率不同的多条流后，SDK 会根据订阅端设置的期望订阅参数自动匹配发送的流，具体规则参看[推送多路流](https://www.volcengine.com/docs/6348/70139)文档。 + 该方法适用于摄像头采集的视频流，设置屏幕共享视频流参数参看 [setScreenVideoEncoderConfig](#setscreenvideoencoderconfig) - **参数** - **solutions** 类型: [VideoEncoderConfig](85535#videoencoderconfig)[] 视频参数数组首地址。要推送的多路视频流的参数。最多支持 3 路参数。当设置了多路参数时，分辨率和帧率必须是依次减小，从大到小排列的。最大分辨率没有限制。但是如果设置的分辨率无法编码，就会导致编码推流失败。注意，所设置的分辨率是各路流的最大分辨率。 - **返回值** 类型: number + 0：成功。 + !0：失败。查看 [ReturnStatus](85535#returnstatus) 获得错误说明。 ### setMaxVideoEncoderConfig 视频发布端设置期望发布的最大分辨率视频流参数，包括分辨率、帧率、码率、缩放模式、网络不佳时的回退策略等。 - **类型** ```ts (max_solution: VideoEncoderConfig) => any ``` - **注意** + 若调用该方法设置了期望发布的最大分辨率的流参数之前，已调用 [enableSimulcastMode](#enablesimulcastmode) 开启发布多路视频流的模式，SDK 会根据订阅端的设置自动调整发布的流数以及各路流的参数，其中最大分辨率为设置的分辨率，流数最多 4 条，具体参看[推送多路流](https://www.volcengine.com/docs/6348/70139)文档；否则仅发布该条最大分辨率的视频流。 + 调用该方法设置多路视频流参数前，SDK 默认仅发布一条分辨率为 640px × 360px，帧率为 15fps 的视频流。 + 该方法适用于摄像头采集的视频流，设置屏幕共享视频流参数参看 [setScreenVideoEncoderConfig](#setscreenvideoencoderconfig) - **参数** - **max_solution** 类型: [VideoEncoderConfig](85535#videoencoderconfig) 期望发布的最大分辨率视频流参数。 - **返回值** + 0：成功 + !0：失败 ### enableAlphaChannelVideoEncode 开启带有Alpha通道的视频帧编码支持。 - **类型** ```ts (index: StreamIndex, layout: AlphaLayout) => any ``` - **注意** + 适用于需要分离推流端视频主体与背景，且在拉流端可自定义渲染背景的场景。 + 需要在发布视频流之前调用此接口，否则会调用失败。 + 开启此接口后，需要配合自定义视频采集 [`pushExternalVideoFrame`](85532#rtcvideo-pushexternalvideoframe)，选择 `kVideoPixelFormatRGBA`，把 RGBA 格式视频帧推送至 SDK。 - **参数** - **index** 类型: [StreamIndex](85535#streamindex) 视频流属性，当前仅支持 `0`，代表主流。 - **layout** 类型: [AlphaLayout](85535#alphalayout) 设置 Alpha 通道数据的布局位置。当前仅支持 `kAlphaLayoutTop`，即置于 RGB 通道信息上方。 - **返回值** + 0: 成功。 + < 0 : 失败。查看 [ReturnStatus](85535#returnstatus) 获得错误说明。 ### disableAlphaChannelVideoEncode 关闭带有Alpha通道的视频帧编码支持。 - **类型** ```ts (index: StreamIndex) => any ``` - **注意** 需要在停止发布视频流之后调用此接口，否则会调用失败。 - **参数** - **index** 类型: [StreamIndex](85535#streamindex) 视频流属性，当前仅支持 `0`，代表主流。 - **返回值** + 0: 成功。 + < 0 : 失败。查看 [ReturnStatus](85535#returnstatus) 获得错误说明。 ### setLocalVideoMirrorType 为采集到的视频流开启镜像 - **类型** ```ts (mirror_type: MirrorType) => number ``` - **注意** + 必须先调用 [setupLocalVideo](85532#rtcvideo-setuplocalvideo) 设置本地视图后再调用本接口。 + 切换视频源不影响镜像设置。 + 屏幕视频流始终不受镜像设置影响。 + 该接口调用前，各视频源的初始状态如下：

	前置摄像头	后置摄像头	自定义采集视频源	桌面端摄像头
移动端	本地预览镜像，编码传输不镜像	本地预览不镜像，编码传输不镜像	本地预览不镜像，编码传输不镜像	/
桌面端	/	/	本地预览不镜像，编码传输不镜像	本地预览镜像，编码传输不镜像

- **参数** - **mirror_type** 类型: [MirrorType](85535#mirrortype) 镜像类型 - **返回值** 类型: number + 0：成功 + !0：失败 ### enableSimulcastMode 该方法设置视频流发布端是否开启发布多路编码参数不同的视频流的模式。 - **类型** ```ts (enabled: boolean) => number ``` - **注意** + 你应在进房前或进房后但未发布流时，调用此方法。 + 开启推送多路视频流模式后，你可以调用 [`setVideoEncoderConfig`](85532#rtcvideo-setvideoencoderconfig) 为多路视频流分别设置编码参数。 + 该功能关闭时，或该功能开启但未设置多路流参数时，默认只发一路视频流，该流的编码参数为：分辨率 640px × 360px，帧率 15fps。 - **参数** - **enabled** 类型: boolean 是否开启推送多路视频流模式： + true：开启 + false：关闭（默认） - **返回值** 类型: number + 0: 成功。 + <0: 失败。查看 [ReturnStatus](85535#returnstatus) 获得错误说明。 ### initCVResource 视频特效许可证检查 - **类型** ```ts (license_path: string, algo_model_dir: string) => number ``` - **注意** 开始使用视频特效前，你必须先调用这个方法进行许可证验证 - **参数** - **license_path** 类型: string 许可证文件绝对路径 - **algo_model_dir** 类型: string 算法模型绝对路径，即存放特效 SDK 所有算法模型的目录。 - **返回值** 类型: number + `0`: 调用成功 + `1000`: 未集成 CV SDK + `1001`: 本版本不支持 CV 功能 + `<0`: 调用失败，具体错误码请参考 [错误码表](https://www.volcengine.com/docs/6705/102042)。 ### getAuthMessage 从 CV SDK 获取授权消息，用于获取在线许可证。 - **类型** ```ts () => string ``` - **注意** + 使用视频特效的功能前，你必须获取特效 SDK 的在线许可证。 + 使用背景分割或视频特效的功能前，你必须自行实现获取智能美化特效产品在线许可证的业务逻辑，参考 [在线授权说明](https://www.volcengine.com/docs/6705/102012)。 + 获取许可证后，建议调用 [initCVResource](#initcvresource) 确认许可证有效，再开始使用背景分割或视频特效功能。 - **返回值** 类型: string 授权消息字符串 ### enableVideoEffect 开启高级美颜、滤镜等视频特效。 - **类型** ```ts () => number ``` - **注意** + 调用本方法前，必须先调用 [initCVResource](#initcvresource) 进行初始化。 + 调用该方法后，特效不直接生效，你还需调用 [setEffectNodes](#seteffectnodes) 设置视频特效素材包或调用调用 [setColorFilter](#setcolorfilter) 设置滤镜。 + 调用 [disableVideoEffect](#disablevideoeffect) 关闭视频特效。 - **返回值** 类型: number + 0: 调用成功。 + –1000: 未集成特效 SDK。 + –1001: 特效 SDK 不支持该功能。 + –1002: 特效 SDK 版本不兼容。 + < 0: 调用失败，错误码对应具体描述参看 [错误码表](https://www.volcengine.com/docs/6705/102042)。 ### disableVideoEffect 关闭视频特效。 - **类型** ```ts () => number ``` - **注意** 调用 [enableVideoEffect](#enablevideoeffect) 开启视频特效。 - **返回值** 类型: number + 0: 调用成功。 + –1000: 未集成特效 SDK。 + –1001: 特效 SDK 不支持该功能。 + –1002: 特效 SDK 版本不兼容。 + < 0: 调用失败，错误码对应具体描述参看 [错误码表](https://www.volcengine.com/docs/6705/102042)。 ### enableEffectBeauty 开启/关闭基础美颜 - **类型** ```ts (enabled: boolean) => number ``` - **注意** + 本方法不能与高级视频特效接口共用。如已购买高级视频特效，建议调用 [enableVideoEffect](#enablevideoeffect) 使用高级特效、贴纸功能等。 + 使用此功能需要集成特效 SDK，建议使用特效 SDK V4.4.2+ 版本。 + 调用 [setBeautyIntensity](#setbeautyintensity) 设置基础美颜强度。若在调用本方法前没有设置美颜强度，则初始美白、磨皮、锐化强度均为 0.5。 + 本方法仅适用于视频源，不适用于屏幕源 - **参数** - **enabled** 类型: boolean 是否开启基础美颜强度，true: 开启，false: 关闭 - **返回值** 类型: number + 0: 调用成功。 + –1001: RTC SDK 版本不支持此功能。 + -12: 本方法不支持在 Audio SDK 中使用。 + <0: 调用失败，特效 SDK 内部错误，具体错误码请参考[错误码表](https://www.volcengine.com/docs/6705/102042)。 ### setBeautyIntensity 调整基础美颜强度 - **类型** ```ts (beauty_mode: EffectBeautyMode, intensity: number) => number ``` - **注意** + 获取许可证后，建议调用 [initCVResource](#initcvresource) 确认许可证有效，再开始使用背景分割或视频特效功能。 + 若在调用 [enableEffectBeauty](#enableeffectbeauty) 前设置美颜强度，则对应美颜功能的强度初始值会根据设置更新。 + 销毁引擎后，美颜功能强度恢复默认值。 - **参数** - **beauty_mode** 类型: [EffectBeautyMode](85535#effectbeautymode) 基础美颜模式 - **intensity** 类型: number 美颜强度，取值范围为 [0,1]。强度为 0 表示关闭，默认强度为 0.5。 - **返回值** 类型: number + 0: 调用成功。 + -2: `intensity` 取值范围应为 [0,1]。 + –1001: RTC SDK 版本不支持此功能。 + <0: 调用失败，特效 SDK 内部错误，具体错误码请参考[错误码表](https://www.volcengine.com/docs/6705/102042)。 ### setEffectNodes 设置视频特效素材包，支持同时设置多个素材包 - **类型** ```ts (effect_node_paths: string[] | null) => number ``` - **参数** - **effect_node_paths** 类型: string[] | null 特效素材包路径数组。取消当前视频特效，将此参数设置为 null。 - **返回值** 类型: number + 0: 调用成功 + 1000: 未集成 CV SDK + 1001: 本 RTC 版本不支持 CV 功能 + <0: 调用失败，具体错误码，请参考 [错误码表](https://www.volcengine.com/docs/6705/102042)。 ### updateEffectNode 设置特效强度 - **类型** ```ts (effect_node_path: string, node_key: string, node_value: number) => number ``` - **参数** - **effect_node_path** 类型: string 特效素材包路径 - **node_key** 类型: string 需要设置的素材 key 名称，取值请参考 [素材 key 对应说明](https://www.volcengine.com/docs/6705/102040)。 - **node_value** 类型: number 需要设置的强度值取值范围 [0,1]，超出范围时设置无效。 - **返回值** 类型: number + 0: 调用成功。 + –1000: 未集成特效 SDK。 + –1001: 特效 SDK 不支持该功能。 + –1002: 特效 SDK 版本不兼容。 + < 0: 调用失败，错误码对应具体描述参看 [错误码表](https://www.volcengine.com/docs/6705/102042)。 ### setColorFilter 设置颜色滤镜 - **类型** ```ts (res_path: string) => number ``` - **参数** - **res_path** 类型: string 滤镜资源包绝对路径。 - **返回值** 类型: number + 0: 调用成功 + 1000: 未集成 CV SDK + 1001: 本 RTC 版本不支持 CV 功能 + <0: 调用失败，具体错误码，请参考 [错误码表](https://www.volcengine.com/docs/6705/102042)。 ### setColorFilterIntensity 设置已启用颜色滤镜的强度 - **类型** ```ts (intensity: number) => number ``` - **参数** - **intensity** 类型: number 滤镜强度。取值范围 [0,1]，超出范围时设置无效。 - **返回值** 类型: number + 0: 调用成功 + 1000: 未集成 CV SDK + 1001: 本 RTC 版本不支持 CV 功能 + <0: 调用失败，具体错误码，请参考 [错误码表](https://www.volcengine.com/docs/6705/102042)。 ### setVideoSourceType 设置向 SDK 输入的视频源，包括屏幕流。默认使用内部采集。内部采集指：使用 RTC SDK 内置的视频采集机制进行视频采集。 - **类型** ```ts (stream_index: StreamIndex, type: VideoSourceType) => any ``` - **注意** + 该方法进房前后均可调用。 + 当你已调用 [`startVideoCapture`](85532#rtcvideo-startvideocapture) 开启内部采集后，再调用此方法切换至自定义采集时，SDK 会自动关闭内部采集。 + 当你调用此方法开启自定义采集后，想要切换至内部采集，你必须先调用此方法关闭自定义采集，然后调用 [`startVideoCapture`](85532#rtcvideo-startvideocapture) 手动开启内部采集。 - **参数** - **stream_index** 类型: [StreamIndex](85535#streamindex) 视频流的属性 - **type** 类型: [VideoSourceType](85535#videosourcetype) 视频输入源类型 - **返回值** + 0: 调用成功。 + < 0 : 调用失败。 ### pushExternalVideoFrame 推送外部视频帧。 - **类型** ```ts (frame: ExternalVideoFrame) => any ``` - **注意** + 支持格式：I420, NV12, RGBA, BGRA, ARGB + 该函数运行在用户调用线程内 + 推送外部视频帧前，必须调用 [`setVideoSourceType`](85532#rtcvideo-setvideosourcetype) 开启外部视频源采集。 - **参数** - **frame** 类型: [ExternalVideoFrame](85535#externalvideoframe) 设置视频帧 - **返回值** 方法调用结果： + 0：成功； + <0：失败。 ### setAudioSourceType 切换音频采集方式 - **类型** ```ts (type: AudioSourceType) => any ``` - **注意** + 进房前后调用此方法均有效。 + 如果你调用此方法由内部采集切换至自定义采集，SDK 会自动关闭内部采集。然后，调用 [`pushExternalAudioFrame`](85532#rtcvideo-pushexternalaudioframe) 推送自定义采集的音频数据到 RTC SDK 用于传输。 + 如果你调用此方法由自定义采集切换至内部采集，你必须再调用 [`startAudioCapture`](85532#rtcvideo-startaudiocapture) 手动开启内部采集。 - **参数** - **type** 类型: [AudioSourceType](85535#audiosourcetype) 音频数据源。默认使用内部音频采集。音频采集和渲染方式无需对应。 - **返回值** 方法调用结果： + ≥0: 切换成功。 + -1：切换失败。 ### pushExternalAudioFrame 推送自定义采集的音频数据到 RTC SDK。 - **类型** ```ts (frame: ExternalAudioFrame) => any ``` - **注意** + 推送自定义采集的音频数据前，必须先调用 [`startAudioCapture`](85532#rtcvideo-startaudiocapture) 开启自定义采集。 + 你必须每 10 ms 推送一次数据。 - **参数** - **audio_frame** 类型: [ExternalAudioFrame](85535#externalaudioframe) 10 ms 对应的音频数据。 - **返回值** 方法调用结果 + 0：成功。 + < 0：失败。查看 [ReturnStatus](85535#returnstatus) 获得错误说明。 ### startPushSingleStreamToCDN 新增单流转推直播任务。 - **类型** ```ts (task_id: string, param: PushSingleStreamParam) => number ``` - **注意** + 调用该方法后，关于启动结果和推流过程中的错误，会收到 [`onStreamPushEvent`](85533#onstreampushevent) 回调。 + 调用 [`stopPushStreamToCDN`](85532#stoppushstreamtocdn) 停止任务。 - **参数** - **task_id** 类型: string 任务 ID。你可以发起多个转推直播任务，并用不同的任务 ID 加以区分。当你需要发起多个转推直播任务时，应使用多个 ID；当你仅需发起一个转推直播任务时，建议使用空字符串。 - **param** 类型: [PushSingleStreamParam](85535#pushsinglestreamparam) 转推直播配置参数 - **返回值** 类型: number + 0：成功 + !0：失败 ### stopPushStreamToCDN 停止转推直播。 - **类型** ```ts (task_id: string) => number ``` - **注意** 关于启动转推直播，参看 [`startPushStreamToCDN`](85532#rtcvideo-startpushsinglestreamtocdn) 和 [`startPushSingleStreamToCDN`](85532#rtcvideo-startpushsinglestreamtocdn)。 - **参数** - **task_id** 类型: string 转推直播任务 ID。指定想要停止的转推直播任务。 - **返回值** 类型: number + 0：成功 + !0：失败 ### setAnsMode > Available since 3.52 支持根据业务场景，设置通话中的音频降噪模式。 - **类型** ```ts (ans_mode: AnsMode) => number ``` - **注意** + 该接口可重复调用，仅最后一次调用生效。 + 降噪算法包含传统降噪和 AI 降噪。传统降噪主要是抑制平稳噪声，比如空调声、风扇声等。而 AI 降噪主要是抑制非平稳噪声，比如键盘敲击声、桌椅碰撞声等。 + 只有在以下 [RoomProfileType](85535#roomprofiletype) 场景下，调用本接口可以开启 AI 降噪。其余场景的 AI 降噪不会生效。 + 游戏语音模式：kRoomProfileTypeGame + 高音质游戏模式：kRoomProfileTypeGameHD + 云游戏模式：kRoomProfileTypeCloudGame + 1 vs 1 音视频通话：kRoomProfileTypeChat + 多端同步播放音视频：kRoomProfileTypeLwTogether + 云端会议中的个人设备：kRoomProfileTypeMeeting + 课堂互动模式：kRoomProfileTypeClassroom + 云端会议中的会议室终端：kRoomProfileTypeMeetingRoom - **参数** - **ans_Mode** 类型: [AnsMode](85535#ansmode) 降噪模式。 - **返回值** 类型: number ### takeLocalSnapshot 截取本地视频画面 - **类型** ```ts (stream_index: StreamIndex) => number ``` - **注意** + 对截取的画面，包含本地视频处理的全部效果，包含旋转，镜像，美颜等。 + 不管采用 SDK 内部采集，还是自定义采集，都可以进行截图。 - **参数** - **stream_index** 类型: [StreamIndex](85535#streamindex) 截图的视频流的属性，为主流还是屏幕流。 - **返回值** 类型: number 本地截图任务的编号，从 `1` 开始递增。调用成功后通过 [onTakeLocalSnapshotResult](85533#ontakelocalsnapshotresult) 回调快照文件。 ### takeRemoteSnapshot 截取远端视频画面 - **类型** ```ts (stream_key: RemoteStreamKey) => number ``` - **注意** + 对截取的画面，包含本地视频处理的全部效果，包含旋转，镜像，美颜等。 + 不管采用 SDK 内部采集，还是自定义采集，都可以进行截图。 - **参数** - **stream_key** 类型: [RemoteStreamKey](85535#remotestreamkey) 截图的视频流 - **返回值** 类型: number 本地截图任务的编号，从 `1` 开始递增。调用成功后通过 [onTakeLocalSnapshotResult](85533#ontakelocalsnapshotresult) 回调快照文件。 ### getNetworkTimeInfo 通过 NTP 协议，获取网络时间。 - **类型** ```ts () => number ``` - **注意** + 第一次调用此接口会启动网络时间同步功能，并返回 `0`。同步完成后，会收到 [onNetworkTimeSynchronized](85533#onnetworktimesynchronized)，此后，再次调用此 API，即可获取准确的网络时间。 + 在合唱场景下，合唱参与者应在相同的网络时间播放背景音乐。 - **返回值** 类型: number ### sendStreamSyncInfo 发送音频流同步信息。将消息通过音频流发送到远端，并实现与音频流同步。 - **类型** ```ts (data: Uint8Array, config: StreamSycnInfoConfig) => number ``` - **注意** + 调用本接口的频率建议不超过 50 次每秒。 + 如果本地用户未说话，此消息不一定会送达。 + 该接口调用成功后，远端用户会收到 [onStreamSyncInfoReceived](85533#onstreamsyncinforeceived) 回调。 - **参数** - **data** 类型: Uint8Array 消息内容。 - **config** 类型: [StreamSycnInfoConfig](85535#streamsycninfoconfig) 音频流同步信息的相关配置。 - **返回值** 类型: number + `>= 0`: 消息发送成功。返回成功发送的次数。 + `-1`: 消息发送失败。消息长度大于 255 字节。 + `-2`: 消息发送失败。传入的消息内容为空。 + `-3`: 消息发送失败。通过屏幕流进行消息同步时，此屏幕流还未发布。 + `-4`: 消息发送失败。通过用麦克风或自定义设备采集到的音频流进行消息同步时，此音频流还未发布，详见错误码 ErrorCode。 ### startCloudProxy 开启云代理 - **类型** ```ts (cloud_proxies?: CloudProxyInfo[]) => number ``` - **注意** + 在加入房间前调用此接口 + 在开启云代理后，进行通话前网络探测 + 开启云代理后，并成功链接云代理服务器后，会收到 [onCloudProxyConnected](85533#oncloudproxyconnected)。 + 要关闭云代理，调用 [stopCloudProxy](#stopcloudproxy)。 - **参数** - **cloud_proxies** 类型: [CloudProxyInfo](85535#cloudproxyinfo)[] 默认值: `' []'` 云代理服务器信息列表。 - **返回值** 类型: number ### stopCloudProxy 关闭云代理 - **类型** ```ts () => number ``` - **注意** 要开启云代理，调用 [startCloudProxy](#startcloudproxy)。 - **返回值** 类型: number ### startPushPublicStream 发布一路公共流。 - **类型** ```ts (public_stream_id: string, param: IPublicStreamParam) => number ``` - **注意** + 用户可以指定房间内多个用户发布的媒体流合成一路公共流。使用同一 `appID` 的用户，可以调用 [`startPlayPublicStream`](#startplaypublicstream) 获取和播放指定的公共流。 + 同一用户使用同一公共流 ID 多次调用本接口无效。如果你希望更新公共流参数，调用 [`updatePublicStreamParam`](#updatepublicstreamparam) 接口。 + 不同用户使用同一公共流 ID 多次调用本接口时，RTC 将使用最后一次调用时传入的参数更新公共流。 + 使用不同的 ID 多次调用本接口可以发布多路公共流。 + 调用 [`stopPushPublicStream`](#stoppushpublicstream) 停止发布公共流。 + 关于公共流功能的介绍，详见[发布和订阅公共流](https://www.volcengine.com/docs/6348/108930) - **参数** - **public_stream_id** 类型: string 公共流 ID。 - **param** 类型: [IPublicStreamParam](85535#ipublicstreamparam) 公共流参数。一路公共流可以包含多路房间内的媒体流，按照指定的布局方式进行聚合。如果指定的媒体流还未发布，则公共流将在指定流开始发布后实时更新。 - **返回值** 类型: number + 0: 成功。同时将收到 [`onPushPublicStreamResult`](85533#onpushpublicstreamresult) 回调。 + !0: 失败。当参数不合法或参数为空，调用失败。 ### stopPushPublicStream 停止发布当前用户发布的公共流 - **类型** ```ts (public_stream_id: string) => number ``` - **注意** 关于发布公共流，查看 [`startPushPublicStream`](#startpushpublicstream)。 - **参数** - **public_stream_id** 类型: string 公共流 ID 指定的流必须为当前用户所发布。 - **返回值** 类型: number + 0: 成功 + !0: 失败 ### updatePublicStreamParam 更新公共流参数 - **类型** ```ts (public_stream_id: string, param: IPublicStreamParam) => number ``` - **注意** + 关于发布公共流，查看 [`startPushPublicStream`](#startpushpublicstream)。 + 调用本接口前需要通过 [`onPushPublicStreamResult`](85533#rtcvideocallback-onpushpublicstreamresult) 确认公共流是否已经成功启动。 - **参数** - **public_stream_id** 类型: string 公共流 ID - **param** 类型: [IPublicStreamParam](85535#ipublicstreamparam) 公共流参数。指定的流必须为当前用户所发布的。 - **返回值** 类型: number + 0: 成功 + !0: 失败 ### startPlayPublicStream 订阅指定公共流。无论用户是否在房间内，都可以调用本接口获取和播放指定的公共流。 - **类型** ```ts (public_stream_id: string) => number ``` - **注意** + 一个客户端最多同时播放 5 路公共流，请及时调用 [`stopPlayPublicStream`](#stopplaypublicstream) 取消订阅公共流，避免订阅的公共流数量超限。 + 在调用本接口之前，建议先绑定渲染视图。 - 调用 [`setupPublicStreamVideo`](#setuppublicstreamvideo) 绑定内部渲染视图： - 调用 [`setPublicStreamVideoSink`](#setpublicstreamvideosink) 绑定自定义渲染视图： + 调用本接口后，可以通过 [`onFirstPublicStreamVideoFrameDecoded`](85533#onfirstpublicstreamvideoframedecoded) 和 [`onFirstPublicStreamAudioFrame`](85533#onfirstpublicstreamaudioframe) 回调公共流的视频和音频首帧解码情况。 + 调用本接口后，可以通过 [`onPublicStreamSEIMessageReceived`](85533#onpublicstreamseimessagereceived) 回调公共流中包含的 SEI 信息。 - **参数** - **public_stream_id** 类型: string 公共流 ID，如果指定流暂未发布，则本地客户端将在其开始发布后接收到流数据。 - **返回值** 类型: number + 0: 成功。同时将收到 [`onPlayPublicStreamResult`](85533#onplaypublicstreamresult) 回调。 + !0: 失败。当参数不合法或参数为空，调用失败。 ### stopPlayPublicStream 取消订阅指定公共流 - **类型** ```ts (public_stream_id: string) => number ``` - **注意** 关于订阅公共流，查看 [`startPlayPublicStream`](#startplaypublicstream)。 - **参数** - **public_stream_id** 类型: string 公共流 ID - **返回值** 类型: number + 0：成功 + !0：失败 ### setupPublicStreamVideo 为公共流绑定本地视图 - **类型** ```ts (public_stream_id: string, view: HTMLDivElement, renderOptions?: RenderOptions) => number ``` - **注意** + 监听到 [onFirstPublicStreamVideoFrameDecoded](85533#onfirstpublicstreamvideoframedecoded) 后，调用本 API 绑定公共流。 + 如果需要解除绑定，调用 [`removePublicStreamVideo`](#removepublicstreamvideo)。 - **参数** - **public_stream_id** 类型: string 公共流 ID - **view** 类型: HTMLDivElement 视图 - **renderOptions** 类型: [RenderOptions](85535#renderoptions) 默认值: `' { render_mode: RenderMode.FIT, mirror: false, }'` 渲染选项 - **返回值** 类型: number + `0`：成功 + `-1`: 失败 ### removePublicStreamVideo 为公共流解绑本地视图 - **类型** ```ts (public_stream_id: string) => number ``` - **注意** 停止接收公共流时解绑视图。 - **参数** - **public_stream_id** 类型: string 公共流 ID - **返回值** 类型: number + `0`：成功 + `-1`: 失败 ### setPublicStreamVideoSink 为指定公共流绑定自定义渲染器。 - **类型** ```ts (public_stream_id: string, required_format: PixelFormat) => number ``` - **注意** 详见[自定义视频渲染](https://www.volcengine.com/docs/6348/81201)。 - **参数** - **public_stream_id** 类型: string 公共流 ID - **required_format** 类型: [PixelFormat](85535#pixelformat) 适用的视频帧编码格式 - **返回值** 类型: number + 0：成功 + !0：失败 ### unsetPublicStreamVideoSink 为指定公共解绑自定义渲染器。 - **类型** ```ts (public_stream_id: string) => number ``` - **注意** 详见[自定义视频渲染](https://www.volcengine.com/docs/6348/81201)。 - **参数** - **public_stream_id** 类型: string 公共流 ID - **返回值** 类型: number + 0：成功 + !0：失败 ### startScreenAudioCapture 在屏幕共享时，开始使用 RTC SDK 内部采集方式，采集屏幕音频 - **类型** ```ts (device_id?: string) => number ``` - **注意** + 采集后，你还需要调用 [publishScreen](#publishscreen) 将采集到的屏幕音频推送到远端。 + 要关闭屏幕音频内部采集，调用 [stopScreenAudioCapture](#stopscreenaudiocapture)。 - **参数** - **device_id** 类型: string | undefined 设备 ID。Mac下需要传入虚拟的声卡id，windows 下不用传入 - **返回值** 类型: number + `0`：成功 + `!0`：失败 ### startScreenVideoCapture 采集屏幕视频流，用于共享。屏幕视频流包括：屏幕上显示的内容，应用窗口中显示的内容，或虚拟屏幕中显示的内容。其中，虚拟屏幕中显示的内容仅在 Windows 平台上支持。 - **类型** ```ts (source_info: ScreenCaptureSourceInfo, capture_params: ScreenCaptureParameters) => number ``` - **注意** + 调用此方法仅开启屏幕流视频采集，不会发布采集到的视频。发布屏幕流视频需要调用 [publishScreen](#publishscreen) 。 + 要关闭屏幕视频源采集，调用 [stopScreenVideoCapture](#stopscreenvideocapture)。 + 本地用户通过 [onVideoDeviceStateChanged](85533#onvideodevicestatechanged) 的回调获取屏幕采集状态，包括开始、暂停、恢复、错误等。 + 调用成功后，本端会收到 [onFirstLocalVideoFrameCaptured](85533#onfirstlocalvideoframecaptured) 回调。然后通过调用 [setupLocalScreen](#setuplocalscreen) 设置本地屏幕共享视图。 + 调用此接口前，你可以调用 [setVideoEncoderConfig](#setvideoencoderconfig) 设置屏幕视频流的采集帧率和编码分辨率。 + 监听 [`onLocalScreenFrame`](85533#onlocalscreenframe) 本地屏幕视频回调事件。 - **参数** - **source_info** 类型: [ScreenCaptureSourceInfo](85535#screencapturesourceinfo) 待共享的屏幕源，你可以调用 [getScreenCaptureSourceList](#getscreencapturesourcelist) 获得所有可以共享的屏幕源。 - **capture_params** 类型: [ScreenCaptureParameters](85535#screencaptureparameters) 共享参数 - **返回值** 类型: number + 0：成功 + !0：失败 ### stopScreenAudioCapture 在屏幕共享时，停止使用 RTC SDK 内部采集方式，采集屏幕音频。 - **类型** ```ts () => number ``` - **注意** 要开始屏幕音频内部采集，调用 [startScreenAudioCapture](#startscreenaudiocapture)。 - **返回值** 类型: number + 0：成功 + !0：失败 ### stopScreenVideoCapture 停止屏幕视频流采集。 - **类型** ```ts () => number ``` - **注意** + 要开始屏幕音频内部采集，调用 [startScreenAudioCapture](#startscreenaudiocapture)。 + 调用后，本地用户会收到 [onVideoDeviceStateChanged](85533#onvideodevicestatechanged) 的回调。 + 调用此接口不影响屏幕视频流发布。 - **返回值** 类型: number + 0：成功 + !0：失败 ### updateScreenCaptureRegion 更新屏幕共享区域。 - **类型** ```ts (region_rect?: Rectangle) => number ``` - **注意** 调用此接口前，必须已通过调用 [startScreenVideoCapture](#startscreenvideocapture) 开启了内部屏幕流采集。 - **参数** - **region_rect** 类型: [Rectangle](85535#rectangle) 默认值: `' { x: 0, y: 0, width: 0, height: 0 }'`

当共享屏幕时，指定待共享区域相对于虚拟屏幕的位置

当共享窗口时，指定待共享区域相对于整个窗口的位置

此参数描述了调用此接口后的采集区域，和 [startScreenVideoCapture](#startscreenvideocapture) 中 `source_info` 设定区域的相对关系。 - **返回值** 类型: number + 0：成功 + !0：失败 ### updateScreenCaptureHighlightConfig 通过 RTC SDK 提供的采集模块采集屏幕视频流时，更新边框高亮设置。默认展示表框。 - **类型** ```ts (highlight_config?: HighlightConfig) => number ``` - **注意** 调用此接口前，必须已通过调用 [startScreenVideoCapture](#startscreenvideocapture) 开启了内部屏幕流采集。 - **参数** - **highlight_config** 类型: [HighlightConfig](85535#highlightconfig) 默认值: `' { enable_highlight: true, border_color: 0xff29cca3, border_width: 4, }'` 边框高亮设置 - **返回值** 类型: number + 0：成功 + !0：失败 ### updateScreenCaptureMouseCursor 通过 RTC SDK 提供的采集模块采集屏幕视频流时，更新对鼠标的处理设置。默认采集鼠标。 - **类型** ```ts (capture_mouse_cursor?: MouseCursorCaptureState) => number ``` - **注意** 调用此接口前，必须已通过调用 [startScreenVideoCapture](#startscreenvideocapture) 开启了内部屏幕流采集。 - **参数** - **capture_mouse_cursor** 类型: [MouseCursorCaptureState](85535#mousecursorcapturestate) 默认值: `' MouseCursorCaptureState.kMouseCursorCaptureStateOn'` 内部采集屏幕视频流时，是否采集鼠标信息 - **返回值** 类型: number + 0：成功 + !0：失败 ### updateScreenCaptureFilterConfig 通过 RTC SDK 提供的采集模块采集屏幕视频流时，设置需要过滤的窗口。 - **类型** ```ts (filter_config?: number[]) => number ``` - **注意** + 调用此接口前，必须已通过调用 [startScreenVideoCapture](#startscreenvideocapture) 开启了内部屏幕流采集。 + 本函数在屏幕源类别是屏幕而非应用窗体时才起作用。 - **参数** - **filter_config** 类型: number[] 默认值: `' []'` 窗口过滤设置 - **返回值** 类型: number + 0：成功 + !0：失败 ### setScreenAudioChannel 在屏幕共享时，设置屏幕音频流的声道数 - **类型** ```ts (channel: AudioChannel) => number ``` - **注意** 当你调用 [setScreenAudioStreamIndex](#setscreenaudiostreamindex) 并设置屏幕音频流和麦克风音频流混流时，此接口不生效，音频通道数由 [setAudioProfile](#setaudioprofile) 控制。 - **参数** - **channel** 类型: [AudioChannel](85535#audiochannel) 声道数 - **返回值** 类型: number ### getScreenCaptureSourceList 获取屏幕采集对象列表。 - **类型** ```ts () => ScreenCaptureSourceInfo[] ``` - **注意** 不同的平台上，对最小化的窗口的处理方式不同：在 Windows 平台上，最小化的窗口也会包含在返回列表中；在 macOS 和 Linux 平台上，最小化的窗口不会包含在返回列表中。 - **返回值** 类型: [ScreenCaptureSourceInfo](85535#screencapturesourceinfo)[] 屏幕采集对象列表，包括应用窗口和屏幕。由用户选择其中一个共享对象，并在调用 [startScreenVideoCapture](#startscreenvideocapture) 时作为参数传给 RTC SDK。 ### getThumbnail 获取共享对象缩略图 - **类型** ```ts (type: ScreenCaptureSourceType, source_id: number, max_width: number, max_height: number) => ThumbnailInfo ``` - **参数** - **type** 类型: [ScreenCaptureSourceType](85535#screencapturesourcetype) 屏幕采集对象的类型 - **source_id** 类型: number 屏幕共享对象的 ID，可通过 [getScreenCaptureSourceList](#getscreencapturesourcelist) 枚举共享对象列表中获取。 - **max_width** 类型: number 最大宽度。保持采集对象本身的宽高比不变，将缩略图缩放到指定范围内的最大宽高。如果给出的尺寸与共享对象比例不同，得到的缩略图会有黑边。 - **max_height** 类型: number 最大高度。参见 `maxWidth` 的说明。 - **返回值** 类型: [ThumbnailInfo](85535#thumbnailinfo) 共享对象缩略图 ### getWindowAppIcon 获取应用窗体所属应用的图标。 - **类型** ```ts (source_id: number, max_width: number, max_height: number) => AppIconInfo ``` - **参数** - **source_id** 类型: number 屏幕共享对象的 ID，可通过 [getScreenCaptureSourceList](#getscreencapturesourcelist) 枚举共享对象列表中获取。 - **max_width** 类型: number 最大宽度。返回的图标将是宽高相等的，输入宽高不等时，取二者较小值。宽高范围为 [32,256]，超出该范围将返回 nullptr，默认输出 100 x 100 的图像。 - **max_height** 类型: number 最大高度。参见 `maxWidth` 的说明。 - **返回值** 类型: [AppIconInfo](85535#appiconinfo) 应用窗体所属应用的图标。当屏幕共享对象为应用窗体时有效，否则返回 nullptr。 ### setScreenAudioStreamIndex 在屏幕共享时，设置屏幕音频流和麦克风采集到的音频流的混流方式 - **类型** ```ts (index: number) => number ``` - **注意** 你应该在 [publishScreen](#publishscreen) 之前，调用此方法。否则，你将收到 [onWarning](85533#onwarning) 的报错：kWarningCodeSetScreenAudioStreamIndexFailed` - **参数** - **index** 类型: number 混流方式

`0`: 将屏幕音频流和麦克风采集到的音频流混流

`1`: 将屏幕音频流和麦克风采集到的音频流分为两路音频流

- **返回值** 类型: number + 0：成功 + !0：失败 ### setScreenVideoEncoderConfig 为发布的屏幕共享视频流设置期望的编码参数，包括分辨率、帧率、码率、网络不佳时的回退策略等。 - **类型** ```ts (screen_solution: ScreenVideoEncoderConfig) => number ``` - **注意** 调用该方法之前，屏幕共享视频流默认的编码参数为：分辨率 1920px × 1080px，帧率 15fps。 - **参数** - **screen_solution** 类型: [ScreenVideoEncoderConfig](85535#screenvideoencoderconfig) 屏幕共享视频流参数。 - **返回值** 类型: number + 0：成功 + !0：失败 ### login 登录 RTS 服务器。必须先登录，才能发送房间外点对点消息和向应用服务器发送消息 - **类型** ```ts (token: string, uid: string) => number ``` - **注意** + 在调用本接口登录后，如果想要登出，需要调用 [Logout](#logout)。 + 本地用户调用此方法登录后，会收到 [onLoginResult](85533#onloginresult) 回调通知登录结果，远端用户不会收到通知。 - **参数** - **token** 类型: string 动态密钥。用户登录必须携带的 Token，用于鉴权验证。本 Token 与加入房间时必须携带的 Token 不同。测试时可使用控制台生成临时 Token，正式上线需要使用密钥 SDK 在你的服务端生成并下发 Token。 - **uid** 类型: string 用户 ID 用户 ID 在 appid 的维度下是唯一的。 - **返回值** 类型: number + `0`：成功 + `-1`：失败。无效参数 + `-2`：无效调用。用户已经登录。成功登录后再次调用本接口将收到此返回值 ### logout 登出 RTS 服务器。调用本接口登出后，无法调用房间外消息以及端到服务器消息相关的方法或收到相关回调。 - **类型** ```ts () => number ``` - **注意** + 调用本接口登出前，必须先调用 [login](85532#login) 登录。 + 本地用户调用此方法登出后，会收到 [onLogout](85533#onlogout) 回调通知结果，远端用户不会收到通知。 - **返回值** 类型: number + 0: 方法调用成功 + <0: 方法调用失败 ### updateLoginToken 更新用户用于登录的 Token。 - **类型** ```ts (token: string) => number ``` - **注意** + 调用 [login](85532#login) 方法登录时，如果使用了过期的 Token 将导致登录失败，并会收到 [onLoginResult](85533#onloginresult) 回调通知，错误码为 kLoginErrorCodeInvalidToken。此时需要重新获取 Token，并调用此方法更新 Token。 + 如果 Token 无效导致登录失败，则调用此方法更新 Token 后，SDK 会自动重新登录，而用户不需要自己调用 [login](85532#login) 方法。 + Token 过期时，如果已经成功登录，则不会受到影响。Token 过期的错误会在下一次使用过期 Token 登录时，或因本地网络状况不佳导致断网重新登录时通知给用户。 - **参数** - **token** 类型: string Token 有一定的有效期，当 Token 过期时，需调用此方法更新登录的 Token 信息。 - **返回值** 类型: number + 0: 方法调用成功 + <0: 方法调用失败 ### setServerParams 设置业务服务器参数。 - **类型** ```ts (signature: string, url: string) => number ``` - **注意** + 客户端调用 [sendServerMessage](#sendservermessage) 或 [sendServerBinaryMessage](#sendserverbinarymessage) 发送消息给业务服务器之前，必须设置有效签名和业务服务器地址。 + 用户必须调用 [login](85532#login) 登录后，才能调用本接口。 + 调用本接口后，SDK 会使用 [onServerParamsSetResult](85533#onserverparamssetresult) 返回相应结果。 - **参数** - **signature** 类型: string 动态签名，应用服务器可使用该签名验证消息来源。签名需自行定义，可传入任意非空字符串，建议将 uid 等信息编码为签名。设置的签名会以 post 形式发送至通过本方法中 url 参数设置的应用服务器地址。 - **url** 类型: string 业务服务器的地址 - **返回值** 类型: number + 0: 方法调用成功 + <0: 方法调用失败 ### getPeerOnlineStatus 查询对端用户或本端用户的登录状态 - **类型** ```ts (peer_user_id: string) => number ``` - **注意** + 必须调用 [login](85532#login) 登录后，才能调用本接口。 + 调用本接口后，SDK 会使用 [onGetPeerOnlineStatus](85533#ongetpeeronlinestatus) 回调通知查询结果。 + 在发送房间外消息之前，用户可以通过本接口了解对端用户是否登录，从而决定是否发送消息。也可以通过本接口查询自己查看自己的登录状态。 - **参数** - **peer_user_id** 类型: string 需要查询的用户 ID - **返回值** 类型: number + 0: 方法调用成功 + <0: 方法调用失败 ### sendUserMessageOutsideRoom 给房间外指定的用户发送文本消息（P2P） - **类型** ```ts (uid: string, message: string, config: MessageConfig) => number ``` - **注意** + 在发送房间外文本消息前，必须先调用 [login](85532#login) 完成登录。 + 用户调用本接口发送文本信息后，会收到一次 [onUserMessageSendResultOutsideRoom](85533#onusermessagesendresultoutsideroom) 回调，得知消息是否成功发送。 + 若文本消息发送成功，则 uid 所指定的用户会通过 [onUserMessageReceivedOutsideRoom](85533#onusermessagereceivedoutsideroom) 回调收到该消息。 - **参数** - **uid** 类型: string 消息接收用户的 ID - **message** 类型: string 发送的文本消息内容，消息不超过 64 KB。 - **config** 类型: [MessageConfig](85535#messageconfig) 消息类型 - **返回值** 类型: number + `>0`：发送成功，返回这次发送消息的编号，从 1 开始递增。 ### sendUserBinaryMessageOutsideRoom 给房间外指定的用户发送二进制消息（P2P） - **类型** ```ts (uid: string, length: number, message: Uint8Array, config: MessageConfig) => number ``` - **注意** + 在发送房间外二进制消息前，必须先调用 [login](85532#login) 完成登录。 + 用户调用本接口发送二进制消息后，会收到一次 [onUserMessageSendResultOutsideRoom](85533#onusermessagesendresultoutsideroom) 回调，通知消息是否发送成功。 + 若二进制消息发送成功，则 uid 所指定的用户会通过 [onUserMessageReceivedOutsideRoom](85533#onusermessagereceivedoutsideroom) 回调收到该条消息。 - **参数** - **uid** 类型: string 消息接收用户的 ID - **length** 类型: number 二进制字符串的长度 - **message** 类型: Uint8Array 发送的二进制消息内容，每条消息不超过 64 KB。 - **config** 类型: [MessageConfig](85535#messageconfig) 消息类型 - **返回值** 类型: number + `>0`：发送成功，返回这次发送消息的编号，从 1 开始递增。 + `-1`：发送失败，消息为空。 ### sendServerMessage 客户端给业务服务器发送文本消息（P2Server） - **类型** ```ts (message: string) => number ``` - **注意** + 在向业务服务器发送文本消息前，必须先调用 [login](85532#login) 完成登录，随后调用 [setServerParams](85532#setserverparams) 设置业务服务器。 + 调用本接口后，会收到一次 [onServerMessageSendResult](85533#onservermessagesendresult) 回调，通知消息发送方是否发送成功。 + 若文本消息发送成功，则之前调用 [setServerParams](85532#setserverparams) 设置的业务服务器会收到该条消息。 - **参数** - **message** 类型: string 发送的文本消息内容，消息不超过 64 KB。 - **返回值** 类型: number + `>0`：发送成功，返回这次发送消息的编号，从 1 开始递增。 ### sendServerBinaryMessage 客户端给业务服务器发送二进制消息（P2Server） - **类型** ```ts (length: number, message: Uint8Array) => number ``` - **注意** + 在向业务服务器发送二进制消息前，必须先调用 [login](85532#login) 完成登录，随后调用 [setServerParams](85532#setserverparams) 设置业务服务器。 + 调用本接口后，会收到一次 [onServerMessageSendResult](85533#onservermessagesendresult) 回调，通知消息发送方发送成功或失败。 + 若二进制消息发送成功，则之前调用 [setServerParams](85532#setserverparams) 设置的业务服务器会收到该条消息。 - **参数** - **length** 类型: number 二进制字符串的长度 - **message** 类型: Uint8Array 发送的二进制消息内容，消息不超过 46KB。 - **返回值** 类型: number + `>0`：发送成功，返回这次发送消息的编号，从 1 开始递增。 + `-1`：发送失败。消息为空。 ### sendSEIMessage 通过视频帧发送 SEI 数据。 - **类型** ```ts (stream_index: number, message: Uint8Array, repeat_count: number, mode: SEICountPerFrame) => number ``` - **注意** + SEI 数据会随视频帧发送。每秒发送的 SEI 消息数量建议不超过当前的视频帧率。在语音通话场景下，SDK 会自动生成一路 16px × 16px 的黑帧视频流用来发送 SEI 数据，帧率为 15 fps。 + 如果调用此接口之后的 2s 内，没有可带 SEI 的视频帧（比如没有开启视频采集和传输），那么，SEI 数据不会被加进视频帧中。 + 消息发送成功后，远端会收到 [onSEIMessageReceived](85533#onseimessagereceived) 回调。 + 语音通话切换至视频通话时，会停止 SEI 数据发送，你需再次调用该接口方可恢复发送。 + SEI PayLoadType 需为 `5` 或 `100`。 - **参数** - **stream_index** 类型: number 媒体流类型

主流。包括：由摄像头/麦克风通过内部采集机制，采集到的视频/音频。

屏幕流。屏幕共享时共享的视频流，或来自声卡的本地播放音频流。

- **message** 类型: Uint8Array SEI 消息。超过 4KB 的消息会被丢弃。 - **repeat_count** 类型: number 消息发送重复次数。取值范围是 [0, max{29, %{视频帧率}-1}]。推荐范围 [2,4]。调用此接口后，这些 SEI 数据会添加到从当前视频帧开始的连续 `%{repeat_count}` 个视频帧中。 - **mode** 类型: [SEICountPerFrame](85535#seicountperframe) - **返回值** 类型: number + \>=0: 将被添加到视频帧中的 SEI 的数量 + < 0: 发送失败。查看 [ReturnStatus](85535#returnstatus) 获得错误说明。 ### setVideoCaptureConfig 设置 RTC SDK 内部采集时的视频采集参数。指定视频采集参数包括模式、分辨率、帧率。 - **类型** ```ts (video_capture_config?: VideoCaptureConfig) => number ``` - **注意** + 本接口在引擎创建后即可调用，建议在调用 [startVideoCapture](85532#startvideocapture) 前调用本接口。 + 建议同一设备上的不同 Engine 使用相同的视频采集参数。 + 如果调用本接口前使用内部模块开始视频采集，采集参数默认为 Auto 模式。 - **参数** - **video_capture_config** 类型: [VideoCaptureConfig](85535#videocaptureconfig) | undefined 视频采集参数 - **返回值** 类型: number 方法调用结果： + 0：成功。 + !0：失败。查看 [ReturnStatus](85535#returnstatus) 获得错误说明。 ### startAudioMixing 开始播放音乐文件及混音 - **已弃用** since 325.1, use RTCMediaPlayer and RTCAudioEffectPlayer instead. - **类型** ```ts (mix_id: number, file_path: string, config: AudioMixingConfig) => number ``` - **注意** + 调用本方法成功播放音乐文件后，SDK 会向本地回调当前的混音状态，见 [onAudioMixingStateChanged](85533#onaudiomixingstatechanged)。 + 开始播放音乐文件及混音后，可以调用 [stopAudioMixing](#stopaudiomixing) 方法停止播放音乐文件。 + 可以通过传入不同的 ID 和 file_path 多次调用本方法，以实现同时播放多个音乐文件，实现混音叠加。 - **参数** - **mix_id** 类型: number 混音 ID，用于标识混音，请保证混音 ID 唯一性。如果已经通过 [preloadAudioMixing](#preloadaudiomixing) 将音效加载至内存，确保此处的 ID 与 [preloadAudioMixing](#preloadaudiomixing) 设置的 ID 相同。如果使用相同的 ID 重复调用本方法，前一次混音会停止，后一次混音开始，且 SDK 会使用 [onAudioMixingStateChanged](85533#onaudiomixingstatechanged) 回调通知前一次混音已停止。 - **file_path** 类型: string 用于混音文件路径。支持在线文件的 URL、和本地文件的绝对路径。对于在线文件的 URL，仅支持 https 协议。推荐的音频文件采样率：8KHz、16KHz、22.05KHz、44.1KHz、48KHz。不同平台支持的本地音频文件格式:

	mp3	mp4	aac	m4a	3gp	wav	ts	wma
macOS	Y	Y	Y	Y	Y	Y
Windows	Y	Y	Y	Y	Y	Y	Y	Y
Linux						Y

不同平台支持的在线音频文件格式:

	mp3	mp4	aac	m4a	3gp	wav	ogg	ts	wma
macOS	Y		Y	Y		Y
Windows	Y		Y	Y	Y	Y		Y	Y

- **config** 类型: [AudioMixingConfig](85535#audiomixingconfig) 混音配置，设置混音的播放次数、是否本地播放混音、以及是否将混音发送至远端 - **返回值** 类型: number + 0：成功 + !0：失败 ### stopAudioMixing 停止播放音乐文件及混音 - **已弃用** since 325.1, use RTCMediaPlayer and RTCAudioEffectPlayer instead. - **类型** ```ts (mix_id: number) => number ``` - **注意** + 调用 [startAudioMixing](#startaudiomixing) 方法开始播放音乐文件及混音后，可以调用本方法停止播放音乐文件及混音。 + 调用本方法停止播放音乐文件后，SDK 会向本地回调通知已停止混音，见 [onAudioMixingStateChanged](85533#onaudiomixingstatechanged)。 + 调用本方法停止播放音乐文件后，该音乐文件会被自动卸载。 - **参数** - **mix_id** 类型: number 混音 ID - **返回值** 类型: number + 0：成功 + !0：失败 ### pauseAudioMixing 暂停播放音乐文件及混音 - **已弃用** since 325.1, use RTCMediaPlayer and RTCAudioEffectPlayer instead. - **类型** ```ts (mix_id: number) => number ``` - **注意** + 调用 [startAudioMixing](#startaudiomixing) 方法开始播放音乐文件及混音后，可以通过调用本方法暂停播放音乐文件及混音。 + 调用本方法暂停播放音乐文件及混音后，可调用 [resumeAudioMixing](#resumeaudiomixing) 方法恢复播放及混音。 + 调用本方法暂停播放音乐文件后，SDK 会向本地回调通知已暂停混音，见 [onAudioMixingStateChanged](85533#onaudiomixingstatechanged)。 - **参数** - **mix_id** 类型: number 混音 ID - **返回值** 类型: number + 0：成功 + !0：失败 ### resumeAudioMixing 恢复播放音乐文件及混音 - **已弃用** since 325.1, use RTCMediaPlayer and RTCAudioEffectPlayer instead. - **类型** ```ts (mix_id: number) => number ``` - **注意** + 调用 [pauseAudioMixing](#pauseaudiomixing) 方法暂停播放音乐文件及混音后，可以通过调用本方法恢复播放及混音。 + 调用本方法恢复播放音乐文件及混音后，SDK 会向本地回调通知音乐文件正在播放中，见 [onAudioMixingStateChanged](85533#onaudiomixingstatechanged)。 - **参数** - **mix_id** 类型: number 混音 ID - **返回值** 类型: number + 0：成功 + !0：失败 ### preloadAudioMixing 预加载指定音乐文件到内存中，以避免频繁播放同一文件时的重复加载，减少 CPU 占用。 - **已弃用** since 325.1, use RTCMediaPlayer and RTCAudioEffectPlayer instead. - **类型** ```ts (mix_id: number, file_path: string) => number ``` - **注意** + 需要频繁播放某个音乐文件的时候，调用本方法预加载该文件，在播放的时候可以只加载一次该文件，减少 CPU 占用。 + 本方法只是预加载指定音乐文件，只有调用 [startAudioMixing](#startaudiomixing) 方法才开始播放指定音乐文件。 + 调用本方法预加载音乐文件后，SDK 会回调通知音乐文件已加载，见 [onAudioMixingStateChanged](85533#onaudiomixingstatechanged)。 + 调用本方法预加载的指定音乐文件可以通过 [unloadAudioMixing](#unloadaudiomixing) 卸载。 - **参数** - **mix_id** 类型: number 混音 ID 应用调用者维护，请保证唯一性。如果使用相同的 ID 调用本方法，后一次会覆盖前一次。如果先调用 [startAudioMixing](#startaudiomixing) ，再使用相同的 ID 调用本方法，会先回调 [onAudioMixingStateChanged](85533#onaudiomixingstatechanged) 上一个混音停止，然后加载后一个混音。使用一个 ID 调用本方法预加载 A.mp3 后，如果需要使用相同的 ID 调用 [startAudioMixing](#startaudiomixing) 播放 B.mp3，请先调用 [unloadAudioMixing](#unloadaudiomixing) 卸载 A.mp3 ，否则会报错 kAudioMixingErrorLoadConflict。 - **file_path** 类型: string 指定需要混音的本地文件的绝对路径，支持音频文件格式有: mp3，aac，m4a，3gp，wav。预加载的文件长度不得超过 20s。 - **返回值** 类型: number + 0：成功 + !0：失败 ### unloadAudioMixing 卸载指定音乐文件 - **已弃用** since 325.1, use RTCMediaPlayer and RTCAudioEffectPlayer instead. - **类型** ```ts (mix_id: number) => number ``` - **注意** 不论音乐文件是否播放，调用本方法卸载该文件后，SDK 会回调通知混音已停止，见 [onAudioMixingStateChanged](85533#onaudiomixingstatechanged)。 - **参数** - **mix_id** 类型: number 混音 ID - **返回值** 类型: number + 0：成功 + !0：失败 ### setAudioMixingVolume 调节音乐文件在本地和远端播放的音量大小 - **已弃用** since 325.1, use RTCMediaPlayer and RTCAudioEffectPlayer instead. - **类型** ```ts (mix_id: number, volume: number, type: number) => number ``` - **注意** + 调用本方法设置音量前，请先调用 [preloadAudioMixing](#preloadaudiomixing) 或 [startAudioMixing](#startaudiomixing)。 + 为保证更好的音质，建议将 volume 值设为 [0,100]。 - **参数** - **mix_id** 类型: number 混音 ID - **volume** 类型: number 音乐文件播放音量范围为 0~400。

0：静音

（默认值）100：原始音量

400: 最大可调音量 (自带溢出保护)

- **type** 类型: number 混音播放类型设置音乐文件是否本地播放、以及是否发送到远端，由此控制音乐文件本地或远端播放的音量 + `0`: 仅本地播放 + `1`: 仅发送到远端 + `2`: 在本地播放并发送到远端 - **返回值** 类型: number + 0：成功 + !0：失败 ### getAudioMixingDuration 获取音乐文件时长 - **已弃用** since 325.1, use RTCMediaPlayer and RTCAudioEffectPlayer instead. - **类型** ```ts (mix_id: number) => number ``` - **注意** 调用本方法获取音乐文件时长前，需要先调用 [preloadAudioMixing](#preloadaudiomixing) 或 [startAudioMixing](#startaudiomixing)。 - **参数** - **mix_id** 类型: number 混音 ID - **返回值** 类型: number + `>0`: 成功, 音乐文件时长，单位为毫秒。 + `<0`: 失败 ### getAudioMixingCurrentPosition 获取音乐文件播放进度 - **已弃用** since 325.1, use RTCMediaPlayer and RTCAudioEffectPlayer instead. - **类型** ```ts (mix_id: number) => number ``` - **注意** 调用本方法获取音乐文件播放进度前，需要先调用 [startAudioMixing](#startaudiomixing) 开始播放音乐文件。 - **参数** - **mix_id** 类型: number 混音 ID - **返回值** 类型: number + `>0`: 成功, 音乐文件播放进度，单位为毫秒。 + `<0`: 失败 ### setAudioMixingPosition 设置音乐文件的播放位置 - **已弃用** since 325.1, use RTCMediaPlayer and RTCAudioEffectPlayer instead. - **类型** ```ts (mix_id: number, position: number) => number ``` - **注意** 在播放在线文件时，调用此接口可能造成播放延迟的现象。 - **参数** - **mix_id** 类型: number 混音 ID - **position** 类型: number 音频文件起始播放位置，单位为毫秒。你可以通过 [getAudioMixingDuration](#getaudiomixingduration) 获取音频文件总时长，position 的值应小于音频文件总时长。 - **返回值** 类型: number + 0：成功 + !0：失败 ### getAudioMixingPlaybackDuration 获取混音音频文件的实际播放时长（单位：毫秒）。 - **已弃用** since 325.1, use RTCMediaPlayer and RTCAudioEffectPlayer instead. - **类型** ```ts (mix_id: number) => any ``` - **注意** + 实际播放时长指的是歌曲不受停止、跳转、倍速、卡顿影响的播放时长。例如，若歌曲正常播放到 1:30 时停止播放 30s 或跳转进度到 2:00, 随后继续正常播放 2分钟，则实际播放时长为 3分30秒。 + 调用本接口前，需要先调用 startAudioMixing 开始播放指定音频文件。 - **参数** - **mix_id** 类型: number 混音 ID - **返回值** + `> 0`: 实际播放时长。 + `< 0`: 失败 ### setAudioMixingDualMonoMode 设置当前音频文件的声道模式 - **已弃用** since 325.1, use RTCMediaPlayer and RTCAudioEffectPlayer instead. - **类型** ```ts (mix_id: number, mode: AudioMixingDualMonoMode) => number ``` - **注意** 调用本方法设置音频文件的声道模式前，需要先调用 startAudioMixing 开始播放音频文件。 - **参数** - **mix_id** 类型: number 混音 ID - **mode** 类型: [AudioMixingDualMonoMode](85535#audiomixingdualmonomode) 声道模式。默认的声道模式和源文件一致，详见 AudioMixingDualMonoMode。 - **返回值** 类型: number + 0：成功 + !0：失败 ### setAudioMixingPitch 开启本地播放音乐文件变调功能，多用于 K 歌场景。 - **已弃用** since 325.1, use RTCMediaPlayer and RTCAudioEffectPlayer instead. - **类型** ```ts (mix_id: number, pitch: number) => number ``` - **注意** 本方法需要在调用 [`startAudioMixing`](#startaudiomixing) 开始播放音频文件后、调用 [`stopAudioMixing`](#stopaudiomixing) 停止播放音频文件前使用，否则会触发 [`onAudioMixingStateChanged`](85533#onaudiomixingstatechanged) 回调报错 - **参数** - **mix_id** 类型: number 混音 ID - **pitch** 类型: number 相对于音乐文件原始音调的升高/降低值，取值范围[-12，12]，默认值为 0，即不做调整。取值范围内每相邻两个值的音高距离相差半音，正值表示升调，负值表示降调，设置的绝对值越大表示音调升高或降低越多。超出取值范围则设置失败，并且会触发 onAudioMixingStateChanged 回调，提示 AudioMixingState 状态为 AUDIO_MIXING_STATE_FAILED 混音播放失败，AudioMixingError 错误码为 AUDIO_MIXING_ERROR_ID_TYPE_INVALID_PITCH 设置混音文件音调不合法 - **返回值** 类型: number + 0：成功 + !0：失败 ### setAudioMixingPlaybackSpeed 设置混音时音频文件的播放速度 - **已弃用** since 325.1, use RTCMediaPlayer and RTCAudioEffectPlayer instead. - **类型** ```ts (mix_id: number, speed: number) => number ``` - **注意** + 你需要在调用 startAudioMixing 开始混音，并且收到onAudioMixingStateChanged 回调提示 AudioMixingState 状态为 kAudioMixingStatePlaying，AudioMixingError 错误码为 kAudioMixingErrorOk 之后调用该方法。 + 在 [stopAudioMixing](#stopaudiomixing) 停止混音或 [unloadAudioMixing](#unloadaudiomixing) 卸载音频文件后调用该 API，会收到状态为 kAudioMixingStateFailed 错误码为 kAudioMixingErrorIdNotFound 的 onAudioMixingStateChanged 回调。 - **参数** - **mix_id** 类型: number 混音 ID - **speed** 类型: number 播放速度与原始文件速度的比例，单位：%，取值范围为 [50,200]，默认值为 100。超出取值范围则设置失败，你会收到 onAudioMixingStateChanged 回调，提示 AudioMixingState 状态为 kAudioMixingStateFailed 混音播放失败，AudioMixingError 错误码为 kAudioMixingErrorInValidPlaybackSpeed 设置混音文件的播放速度不合法。 - **返回值** 类型: number + 0：成功 + !0：失败 ### setAudioMixingLoudness 如果你需要使用 enableVocalInstrumentBalance 对混音使音频文件/PCM 音频数据进行音量调整，你必须通过此接口传入其原始响度。 - **已弃用** since 325.1, use RTCMediaPlayer and RTCAudioEffectPlayer instead. - **类型** ```ts (mix_id: number, loudness: number) => number ``` - **注意** 建议在 startAudioMixing 开始播放音频文件之前调用该接口，以免播放过程中的音量突变导致听感体验下降。 - **参数** - **mix_id** 类型: number 混音 ID - **loudness** 类型: number 原始响度，单位：lufs，取值范围为 [-70.0, 0.0]。当设置的值小于 -70.0lufs 时，则默认调整为 -70.0lufs，大于 0.0lufs 时，则不对该响度做音均衡处理。默认值为 1.0lufs，即不做处理。 - **返回值** 类型: number + 0：成功 + !0：失败 ### setAudioMixingProgressInterval 设置混音时音频文件播放进度回调的间隔 - **已弃用** since 325.1, use RTCMediaPlayer and RTCAudioEffectPlayer instead. - **类型** ```ts (mix_id: number, interval: number) => number ``` - **注意** 本方法需要在调用 [startAudioMixing](#startaudiomixing) 开始播放音频文件后、调用 [stopAudioMixing](#stopaudiomixing) 停止播放音频文件前使用，否则会触发 onAudioMixingStateChanged 回调报错。若想在音乐文件开始播放前设置播放进度回调间隔，你需调用 startAudioMixing 在 AudioMixingConfig 中设置时间间隔，开始播放后可以通过此接口更新回调间隔。 - **参数** - **mix_id** 类型: number 混音 ID。可以通过多次调用本接口传入不同的 ID 对多个 ID 进行间隔设置。 - **interval** 类型: number 音频文件播放进度回调的时间间隔，单位毫秒。 • interval 的值为大于 0 的 10 的倍数，当设置的值不能被 10 整除时，则默认向上取整 10，如设为 52ms 时会默认调整为 60ms。设置完成后 SDK 将会按照设置的时间间隔触发 onAudioMixingPlayingProgress 回调。 • interval 的值小于等于 0 时，不会触发进度回调。 - **返回值** 类型: number + 0：成功 + !0：失败 ### getAudioTrackCount 获取当前音频文件的音轨索引 - **已弃用** since 325.1, use RTCMediaPlayer and RTCAudioEffectPlayer instead. - **类型** ```ts (mix_id: number) => number ``` - **注意** 调用本方法获取音频文件的音轨前，需要先调用 [startAudioMixing](#startaudiomixing) 开始播放音频文件。 - **参数** - **mix_id** 类型: number 混音 ID - **返回值** 类型: number + ≥ 0：成功，返回当前音频文件的音轨索引 + < 0：方法调用失败 ### selectAudioTrack 指定当前音频文件的播放音轨 - **已弃用** since 325.1, use RTCMediaPlayer and RTCAudioEffectPlayer instead. - **类型** ```ts (mix_id: number, audio_track_index: number) => number ``` - **注意** 调用本方法设置音频文件的音轨前，需要先调用 [startAudioMixing](#startaudiomixing) 开始播放音频文件。 - **参数** - **mix_id** 类型: number 混音 ID - **audio_track_index** 类型: number 指定的播放音轨设置的参数值需要小于或等于 [getAudioTrackCount](#getaudiotrackcount) 的返回值 - **返回值** 类型: number + 0：成功 + !0：失败 ### setLocalVoicePitch 开启本地语音变调功能，多用于 K 歌场景。使用该方法，你可以对本地语音的音调进行升调或降调等调整。 - **已弃用** since 325.1, use RTCMediaPlayer and RTCAudioEffectPlayer instead. - **类型** ```ts (pitch: number) => number ``` - **参数** - **pitch** 类型: number 相对于语音原始音调的升高/降低值，取值范围[-12，12]，默认值为 0，即不做调整。取值范围内每相邻两个值的音高距离相差半音，正值表示升调，负值表示降调，设置的绝对值越大表示音调升高或降低越多。超出取值范围则设置失败，并且会触发 [onWarning](85533#onwarning) 回调，提示码为 `WARNING_CODE_SET_SCREEN_STREAM_INVALID_VOICE_PITCH` 设置语音音调不合法 - **返回值** 类型: number + 0：成功 + !0：失败 ### startFileRecording 该方法将通话过程中的音视频数据录制到本地的文件中。 - **类型** ```ts (type: StreamIndex, config: RecordingConfig, recording_type: RecordingType) => number ``` - **注意** 该方法需在本端用户进房并发布媒体流后调用。 - **参数** - **type** 类型: [StreamIndex](85535#streamindex) 流属性，指定录制主流还是屏幕流

主流。包括：由摄像头/麦克风通过内部采集机制，采集到的视频/音频。

屏幕流。屏幕共享时共享的视频流，或来自声卡的本地播放音频流。

- **config** 类型: [RecordingConfig](85535#recordingconfig) 本地录制参数配置 - **recording_type** 类型: [RecordingType](85535#recordingtype) 录制存储文件格式 - **返回值** 类型: number + 0: 方法调用成功。录制开始后，你可以通过每秒一次的 [onRecordingProgressUpdate](85533#onrecordingprogressupdate) 回调获取录制进度。 + <0: 方法调用失败。查看 [ReturnStatus](85535#returnstatus) 获得错误说明。你还可以通过 [onRecordingStateUpdate](85533#onrecordingstateupdate) 回调感知和处理录制错误。 ### stopFileRecording 停止本地录制 - **类型** ```ts (type: number) => number ``` - **注意** + 调用 [startFileRecording](#startfilerecording) 开启本地录制后，你必须调用该方法停止录制。 + 调用该方法后，你会收到 [onRecordingStateUpdate](85533#onrecordingstateupdate) 回调提示录制结果。 - **参数** - **type** 类型: number 流属性，指定停止主流或者屏幕流录制

主流。包括：由摄像头/麦克风通过内部采集机制，采集到的视频/音频。

屏幕流。屏幕共享时共享的视频流，或来自声卡的本地播放音频流。

- **返回值** 类型: number + 0: 方法调用成功 + <0: 方法调用失败。查看 [ReturnStatus](85535#returnstatus) 获得错误说明。 ### setPublishFallbackOption 设置发布的音视频流回退选项。你可以调用这个接口来设置网络情况不佳或设备性能不足时只发送小流，以保证通话质量。 - **类型** ```ts (option: number) => number ``` - **注意** + 该方法仅在调用 [enableSimulcastMode](#enablesimulcastmode) 开启了发送多路视频流的情况下生效。 + 你必须在进房前设置，进房后设置或更改设置无效。 + 调用该方法后，如因性能或网络不佳产生发布性能回退或恢复，本端会提前收到 [onPerformanceAlarms](85533#rtcvideocallback-onperformancealarms) 回调发出的告警，以便采集设备配合调整。 + 设置回退选项后，本端发布的音视频流发生回退或从回退中恢复时，订阅该音视频流的客户端会收到 [onSimulcastSubscribeFallback](85533#onsimulcastsubscribefallback) 回调，通知该情况。 + 你可以调用 API 或者在服务端下发策略设置回退。当使用服务端下发配置实现时，下发配置优先级高于在客户端使用 API 设定的配置。 - **参数** - **option** 类型: number 本地发布的音视频流回退选项

0：（默认）上行网络较弱或性能不佳时，不对音视频流作回退处理。

>1：上行网络较弱或性能不佳时，只发送视频小流。 - **返回值** 类型: number + 0: 方法调用成功 + <0: 方法调用失败 ### setSubscribeFallbackOption 设置订阅的音视频流回退选项。你可以通过调用该接口来设置网络情况不佳或性能不足时只订阅小流或音频流，以保证通话质量。 - **类型** ```ts (option: number) => number ``` - **注意** + 你必须在进房前设置，进房后设置或更改设置无效。 + 设置回退选项后，本端订阅的音视频流发生回退或从回退中恢复时,会收到 [onSimulcastSubscribeFallback](85533#onsimulcastsubscribefallback) 回调通知。 + 设置回退选项后，本端订阅的视频流因为回退分辨率发生变化时,会收到 [onRemoteVideoSizeChanged](85533#onremotevideosizechanged) 回调通知。 + 你可以调用 API 或者在服务端下发策略设置回退。当使用服务端下发配置实现时，下发配置优先级高于在客户端使用 API 设定的配置。 - **参数** - **option** 类型: number 远端订阅流回退处理选项

`0`: 关闭订阅音视频流时的性能回退功能

`1`: 只接收视频小流

`2`: 先尝试只接收视频小流；如果网络环境无法显示视频，则再回退到只接收远端订阅的音频流

- **返回值** 类型: number 方法调用结果 + 0：成功。 + <0：失败。查看 [ReturnStatus](85535#returnstatus) 获得错误说明。 ### setRemoteUserPriority 设置用户优先级 - **类型** ```ts (room_id: string, user_id: string, priority: RemoteUserPriority) => number ``` - **注意** + 1. 该方法与 [setSubscribeFallbackOption](#setsubscribefallbackoption) 搭配使用。 + 2. 如果开启了订阅流回退选项，弱网或性能不足时会优先保证收到的高优先级用户的流的质量。 + 3. 该方法在进房前后都可以使用，可以修改远端用户的优先级。 - **参数** - **room_id** 类型: string 房间 ID - **user_id** 类型: string 远端用户的 ID - **priority** 类型: [RemoteUserPriority](85535#remoteuserpriority) 远端用户的需求优先级 - **返回值** 类型: number + 0：成功。 + <0：失败。查看 [ReturnStatus](85535#returnstatus) 获得错误说明。 ### startNetworkDetection 开启通话前网络探测 - **类型** ```ts (is_test_uplink: boolean, expected_uplink_bitrate: number, is_test_downlink: boolean, expected_downlink_biterate: number) => number ``` - **注意** + 若探测停止，则会收到一次 [onNetworkDetectionStopped](85533#onnetworkdetectionstopped) 通知探测停止。 - **参数** - **is_test_uplink** 类型: boolean 是否探测上行带宽 - **expected_uplink_bitrate** 类型: number 期望上行带宽，单位：kbps范围为 {0, [100-10000]}，其中， 0 表示由 SDK 指定最高码率。 - **is_test_downlink** 类型: boolean 是否探测下行带宽 - **expected_downlink_biterate** 类型: number 期望下行带宽，单位：kbps范围为 {0, [100-10000]}，其中， 0 表示由 SDK 指定最高码率。 - **返回值** 类型: number + 0: 成功开启网络探测。探测结果将通过 [onNetworkDetectionResult](85533#onnetworkdetectionresult) 周期性回调。 + `-1`: 开始探测失败。 + `-2`: 开始探测失败。参数错误，上下行探测均为 `false`，或期望带宽超过了范围 [100,10000]。 + `-3`: 开始探测失败。失败原因为，本地已经开始推拉流。 + `-11`: 已经开始探测，无需重复开启。 + `-10`: 不支持该功能。 ### stopNetworkDetection 停止通话前网络探测 - **类型** ```ts () => number ``` - **注意** 调用本接口后，会收到一次 [onNetworkDetectionStopped](85533#onnetworkdetectionstopped) 回调通知探测停止。 - **返回值** 类型: number + 0：成功 + !0：失败 ### enableVirtualBackground 将摄像头采集画面中的人像背景替换为指定图片或纯色背景。 - **类型** ```ts (background_sticker_path: string, source: VirtualBackgroundSource) => number ``` - **注意** + 调用本方法前，必须先调用 [initCVResource](#initcvresource)。 + 调用 [disableVirtualBackground](#disablevirtualbackground) 关闭虚拟背景。 - **参数** - **background_sticker_path** 类型: string 背景贴纸特效素材绝对路径。 - **source** 类型: [VirtualBackgroundSource](85535#virtualbackgroundsource) 背景贴纸对象。 - **返回值** 类型: number + `0`: 调用成功 + `-1000`: 未集成 CV SDK + `-1001`: 本版本不支持 CV 功能 + `–1002`: 特效 SDK 版本不兼容 + `<0`: 调用失败，具体错误码请参考 [错误码表](https://www.volcengine.com/docs/6705/102042)。 ### disableVirtualBackground 关闭虚拟背景。 - **类型** ```ts () => number ``` - **注意** 调用 [enableVirtualBackground](#enablevirtualbackground) 开启虚拟背景后，可以调用此接口关闭虚拟背景。 - **返回值** 类型: number + `0`: 调用成功。 + `–1000`: 未集成特效 SDK。 + `–1001`: 特效 SDK 不支持该功能。 + `–1002`: 特效 SDK 版本不兼容。 + `< 0`: 调用失败，错误码对应具体描述参看 [错误码表](https://www.volcengine.com/docs/6705/102042)。 ### enableFaceDetection 开启人脸识别功能，并设置人脸检测结果回调观察者。 - **类型** ```ts (interval_ms: number, face_model_path: string) => number ``` - **注意** 此观察者后，你会周期性收到 [onFaceDetectResult](85533#onfacedetectresult) 回调。 - **参数** - **interval_ms** 类型: number 两次回调之间的最小时间间隔，必须大于 0，单位为毫秒。实际收到回调的时间间隔大于 `interval_ms`，小于 `interval_ms+视频采集帧间隔`。 - **face_model_path** 类型: string 人脸检测算法模型文件路径，一般为 ttfacemodel 文件夹中 tt_face_vXXX.model 文件的绝对路径。 - **返回值** 类型: number + `0`: 调用成功。 + `–1000`: 未集成特效 SDK。 + `–1001`: 特效 SDK 不支持该功能。 + `–1002`: 特效 SDK 版本不兼容。 + `-1004`: 初始化中，初始化完成后启动此功能。 + `<0`: 调用失败，错误码对应具体描述参看 [错误码表](https://www.volcengine.com/docs/6705/102042)。 ### disableFaceDetection 关闭人脸识别功能。 - **类型** ```ts () => number ``` - **返回值** 类型: number + `0`: 调用成功。 + `–1000`: 未集成特效 SDK。 + `–1001`: 特效 SDK 不支持该功能。 + `–1002`: 特效 SDK 版本不兼容。 + `<0`: 调用失败，错误码对应具体描述参看 [错误码表](https://www.volcengine.com/docs/6705/102042)。 ### setVideoWatermark 在指定视频流上添加水印。 - **类型** ```ts (stream_index: number, image_path: string, config: RTCWatermarkConfig) => number ``` - **注意** + 调用 [clearVideoWatermark](#clearvideowatermark) 移除指定视频流的水印。 + 同一路流只能设置一个水印，新设置的水印会代替上一次的设置。你可以多次调用本方法来设置不同流的水印。 + 进入房间前后均可调用此方法。 + 若开启本地预览镜像，或开启本地预览和编码传输镜像，则远端水印均不镜像；在开启本地预览水印时，本端水印会镜像。 + 开启大小流后，水印对大小流均生效，且针对小流进行等比例缩小。 - **参数** - **stream_index** 类型: number 需要添加水印的视频流属性。 - **image_path** 类型: string 水印图片路径，支持本地文件绝对路径和Asset 资源路径（/assets/xx.png），长度限制为 512 字节。水印图片为 PNG 或 JPG 格式。 - **config** 类型: [RTCWatermarkConfig](85535#rtcwatermarkconfig) 水印参数 - **返回值** 类型: number + 0: 调用成功 + 1000: 未集成 CV SDK + 1001: 本版本不支持 CV 功能 + <0: 调用失败，具体错误码请参考 [错误码表](https://www.volcengine.com/docs/6705/102042)。 ### clearVideoWatermark 移除指定视频流的水印。 - **类型** ```ts (stream_index: number) => any ``` - **参数** - **stream_index** 类型: number 需要移除水印的视频流属性，参看 StreamIndex。 - **返回值** + 0: 调用成功 + 1000: 未集成 CV SDK + 1001: 本版本不支持 CV 功能 + <0: 调用失败，具体错误码请参考 [错误码表](https://www.volcengine.com/docs/6705/102042)。 ### setupLocalVideo 设置本地视频渲染时使用的视图，并设置渲染模式。 - **类型** ```ts (view: HTMLDivElement, render_options?: RenderOptions) => number ``` - **注意** 如果需要解除绑定，调用 [`removeLocalVideo`](#removelocalvideo)。 - **参数** - **view** 类型: HTMLDivElement 视图 - **render_options** 类型: [RenderOptions](85535#renderoptions) 默认值: `' { render_mode: RenderMode.FIT, mirror: false, }'` 渲染选项 - **返回值** 类型: number + `0`：成功 + `-1`: 失败 ### removeLocalVideo 解绑本地视频流已绑定的渲染视图 - **类型** ```ts () => number ``` - **返回值** 类型: number + `0`：成功 + `-1`: 失败 ### setupRemoteVideo 为远端视频流绑定本地渲染视图，并设置渲染模式。 - **类型** ```ts (user_id: string, room_id: string, view: HTMLDivElement, render_options?: RenderOptions) => number ``` - **注意** + 监听到 [onUserPublishStream](85533#onuserpublishstream) 后，调用本 API 绑定远端流。 + 如果需要解除绑定，调用 [`removeRemoteVideo`](#removeremotevideo) 或 [`removeAllRemoteVideo`](#removeallremotevideo)。 + 本地用户离开房间时，会解除调用此 API 建立的绑定关系；远端用户离开房间则不会影响。 - **参数** - **user_id** 类型: string 远端用户 ID - **room_id** 类型: string 房间 ID - **view** 类型: HTMLDivElement 视图 - **render_options** 类型: [RenderOptions](85535#renderoptions) 默认值: `' { render_mode: RenderMode.FIT, mirror: false, }'` 渲染选项 - **返回值** 类型: number + `0`：成功 + `-1`: 失败 ### removeRemoteVideo 解绑指定远端视频流已绑定的本地视图 - **类型** ```ts (user_id: string, room_id: string) => number ``` - **注意** 停止接收远端视频流时应解绑视图 - **参数** - **user_id** 类型: string 远端用户 ID - **room_id** 类型: string 房间 ID - **返回值** 类型: number + `0`：成功 + `-1`: 失败 ### removeAllRemoteVideo 解绑所有已绑定本地视图的指定远端视频流 - **类型** ```ts (room_id: string) => number ``` - **注意** 停止接收远端视频流时应解绑视图 - **参数** - **room_id** 类型: string 房间 ID - **返回值** 类型: number + `0`：成功 + `-1`: 失败 ### setupLocalScreen 为本地屏幕共享流绑定视图，实现预览 - **类型** ```ts (view: HTMLDivElement, render_options?: RenderOptions) => number ``` - **注意** + 本地发起屏幕共享需要先绑定视图 + 如果需要解除绑定，调用 [`removeLocalScreen`](#removelocalscreen)。 - **参数** - **view** 类型: HTMLDivElement 视图 - **render_options** 类型: [RenderOptions](85535#renderoptions) 默认值: `' { render_mode: RenderMode.FIT, mirror: false, }'` 渲染选项 - **返回值** 类型: number + `0`：成功 + `-1`: 失败 ### removeLocalScreen 解绑屏幕共享流已绑定的视图 - **类型** ```ts () => number ``` - **注意** 本地停止屏幕共享时解绑视图 - **返回值** 类型: number 0：成功 !0: 失败 ### setupRemoteScreen 为远端屏幕共享流绑定本地视图 - **类型** ```ts (user_id: string, room_id: string, view: HTMLDivElement, render_options?: RenderOptions) => number ``` - **注意** + 监听到 [onUserPublishScreen](85533#onuserpublishscreen) 后，调用本 API 绑定远端屏幕共享流。 + 如果需要解除绑定，调用 [`removeRemoteScreen`](#removeremotescreen)。 - **参数** - **user_id** 类型: string 远端用户 ID - **room_id** 类型: string 房间 ID - **view** 类型: HTMLDivElement 视图 - **render_options** 类型: [RenderOptions](85535#renderoptions) 默认值: `' { render_mode: RenderMode.FIT, mirror: false, }'` 渲染选项 - **返回值** 类型: number 0：成功 -1: 失败 ### removeRemoteScreen 解绑远端屏幕共享流已绑定的本地视图 - **类型** ```ts (user_id: string, room_id: string) => number ``` - **注意** 停止接收屏幕共享流时应解绑视图 - **参数** - **user_id** 类型: string 远端用户 ID - **room_id** 类型: string 房间 ID - **返回值** 类型: number + `0`：成功 + `-1`: 失败 ### setLocalVideoSink 获取本地视频流。 - **类型** ```ts (index: StreamIndex, required_format: PixelFormat) => number ``` - **参数** - **index** 类型: [StreamIndex](85535#streamindex) 视频流属性。采集的视频流/屏幕视频流 - **required_format** 类型: [PixelFormat](85535#pixelformat) 适用的视频帧编码格式 - **返回值** 类型: number + `0`：成功 + `-1`: 失败 ### unsetLocalVideoSink 停止获取本地视频流。 - **类型** ```ts (stream_index: StreamIndex) => number ``` - **参数** - **stream_index** 类型: [StreamIndex](85535#streamindex) 视频流属性。采集的视频流/屏幕视频流 - **返回值** 类型: number + `0`：成功 + `-1`: 失败 ### setRemoteVideoSink 获取远端视频流。 - **类型** ```ts (stream_key: RemoteStreamKey, required_format: PixelFormat) => number ``` - **参数** - **stream_key** 类型: [RemoteStreamKey](85535#remotestreamkey) 远端流信息，用于指定需要设置的视频流来源及属性。 - **required_format** 类型: [PixelFormat](85535#pixelformat) 适用的视频帧编码格式 - **返回值** 类型: number + `0`：成功 + `-1`: 失败 ### unsetRemoteVideoSink 停止获取远端视频流。 - **类型** ```ts (stream_key: RemoteStreamKey) => number ``` - **参数** - **stream_key** 类型: [RemoteStreamKey](85535#remotestreamkey) 远端流信息，用于指定需要设置的视频流来源及属性。 - **返回值** 类型: number + `0`：成功 + `-1`: 失败 ### playMusic 播放歌曲。 - **类型** ```ts (music_id: string, track_type: AudioTrackType, play_type: AudioPlayType) => number ``` - **注意** + 调用接口后，你会收到 [`onPlayStateChanged`](85533#onplaystatechanged) 回调歌曲播放状态。 + 若音乐 ID 错误，会触发 [`onPlayStateChanged`](85533#onplaystatechanged) 回调，error_code 为 –3023，play_state 为 4。 + 若未进房，会触发 [`onPlayStateChanged`](85533#onplaystatechanged) 回调，error_code 为 –3022，play_state 为 4。 + 若音乐文件不存在，会触发 [`onPlayStateChanged`](85533#onplaystatechanged) 回调，error_code 为 –3020，play_state 为 4。 - **参数** - **music_id** 类型: string 音乐 ID。若同一 music_id 的歌曲正在播放，再次调用接口会从开始位置重新播放。若 music_id 对应的音频文件不存在会触发报错。 - **track_type** 类型: [AudioTrackType](85535#audiotracktype) 原唱伴唱类型。 - **play_type** 类型: [AudioPlayType](85535#audioplaytype) 音乐播放类型。 - **返回值** 类型: number + `0`：成功 + `-1`: 失败 ### pauseMusic 暂停播放歌曲。 - **类型** ```ts (music_id: string) => number ``` - **注意** + 调用接口后，你会收到 [`onPlayStateChanged`](85533#onplaystatechanged) 回调歌曲播放状态。 + 若音乐 ID 错误，会触发 [`onPlayStateChanged`](85533#onplaystatechanged) 回调，error_code 为 –3023，play_state 为 4。 + 若未进房，会触发 [`onPlayStateChanged`](85533#onplaystatechanged) 回调，error_code 为 –3022，play_state 为 4。 - **参数** - **music_id** 类型: string 音乐 ID。 - **返回值** 类型: number + `0`：成功 + `<0`: 失败 ### resumeMusic 继续播放歌曲。 - **类型** ```ts (music_id: string) => number ``` - **注意** + 调用接口后，你会收到 [`onPlayStateChanged`](85533#onplaystatechanged) 回调歌曲播放状态。 + 若音乐 ID 错误，会触发 [`onPlayStateChanged`](85533#onplaystatechanged) 回调，error_code 为 –3023，play_state 为 4。 + 若未进房，会触发 [`onPlayStateChanged`](85533#onplaystatechanged) 回调，error_code 为 –3022，play_state 为 4。 - **参数** - **music_id** 类型: string 音乐 ID。 - **返回值** 类型: number + `0`：成功 + `<0`: 失败 ### stopMusic 停止播放歌曲。 - **类型** ```ts (music_id: string) => number ``` - **注意** + 调用接口后，你会收到 [`onPlayStateChanged`](85533#onplaystatechanged) 回调歌曲播放状态。 + 若音乐 ID 错误，会触发 [`onPlayStateChanged`](85533#onplaystatechanged) 回调，error_code 为 –3023，play_state 为 4。 + 若未进房，会触发 [`onPlayStateChanged`](85533#onplaystatechanged) 回调，error_code 为 –3022，play_state 为 4。 - **参数** - **music_id** 类型: string 音乐 ID。 - **返回值** 类型: number + `0`：成功 + `<0`: 失败 ### seekMusic 设置音乐文件的起始播放位置。 - **类型** ```ts (music_id: string, position: number) => number ``` - **注意** + 调用本接口时音乐必须处于播放中状态。 + 调用接口后，你会收到 [`onPlayStateChanged`](85533#onplaystatechanged) 回调歌曲播放状态。 + 若音乐 ID 错误，会触发 [`onPlayStateChanged`](85533#onplaystatechanged) 回调，error_code 为 –3023，play_state 为 4。 + 若未进房，会触发 [`onPlayStateChanged`](85533#onplaystatechanged) 回调，error_code 为 –3022，play_state 为 4。 - **参数** - **music_id** 类型: string 音乐 ID。 - **position** 类型: number 音乐起始位置，单位为毫秒，取值小于音乐文件总时长。 - **返回值** 类型: number + `0`：成功 + `<0`: 失败 ### setMusicVolume 设置歌曲播放音量，只能在开始播放后进行设置。 - **类型** ```ts (music_id: string, volume: number) => number ``` - **注意** + 调用本接口时音乐必须处于播放中状态。 + 若设置的音量大于 400，则按最大值 400 进行调整；若设置的音量小于 0，则按最小值 0 进行调整。 + 若音乐 ID 错误，会触发 [`onPlayStateChanged`](85533#onplaystatechanged) 回调，error_code 为 –3023，play_state 为 4。 + 若未进房，会触发 [`onPlayStateChanged`](85533#onplaystatechanged) 回调，error_code 为 –3022，play_state 为 4。 - **参数** - **music_id** 类型: string 音乐 ID。 - **volume** 类型: number 歌曲播放音量，调节范围：[0,400]。 + `0`：静音。 + `100`：原始音量。 + `400`: 原始音量的 4 倍(自带溢出保护)。 - **返回值** 类型: number + `0`：成功 + `<0`: 失败 ### switchAudioTrackType 切换歌曲原唱伴唱。 - **类型** ```ts (music_id: string) => number ``` - **注意** 调用本接口时音乐必须处于播放中状态。 - **参数** - **music_id** 类型: string 音乐 ID。 - **返回值** 类型: number + `0`：成功 + `<0`: 失败 ### setMusicPitch 对播放中的音乐设置升降调信息。 - **类型** ```ts (music_id: string, pitch: number) => number ``` - **注意** + 调用本接口时音乐必须处于播放中状态。 + 若设置的 pitch 大于 12，则按最大值 12 进行调整；若设置的 pitch 小于 –12，，则按最小值 –12 进行调整。 + 若音乐 ID 错误，会触发 [`onPlayStateChanged`](85533#onplaystatechanged) 回调，error_code 为 –3023，play_state 为 4。 + 若未进房，会触发 [`onPlayStateChanged`](85533#onplaystatechanged) 回调，error_code 为 –3022，play_state 为 4。 - **参数** - **music_id** 类型: string 音乐 ID。 - **pitch** 类型: number 相对于音乐文件原始音调的升高/降低值，取值范围 [-12，12]，默认值为 0，即不做调整。取值范围内每相邻两个值的音高距离相差半音，正值表示升调，负值表示降调，设置的绝对值越大表示音调升高或降低越多。 - **返回值** 类型: number + `0`：成功 + `<0`: 失败 ### setMaxCacheSize 设置歌曲文件最大占用的本地缓存。 - **类型** ```ts (max_cache_size_MB: number) => number ``` - **参数** - **max_cache_size_MB** 类型: number 本地缓存，单位 MB。设置值小于等于 0 时，使用默认值 1024 MB。 - **返回值** 类型: number + `0`：成功 + `<0`: 失败 ### getMusicList 获取歌曲列表。 - **类型** ```ts (page_num: number, page_size: number, filters: number) => number ``` - **注意** 调用接口后，你会收到 [onMusicListResult](85533#onmusiclistresult) 回调歌曲列表。 - **参数** - **page_num** 类型: number 页码，默认从 1 开始。 - **page_size** 类型: number 每页显示歌曲的最大数量，取值范围 [1,99]。 - **filters** 类型: number 歌曲过滤方式。多个过滤方式可以按位或组合。 + `0`: 不过滤。 + `1<<0`: 过滤没有歌词的歌曲。 + `1<<1`: 过滤不支持打分的歌曲。 + `1<<2`: 过滤不支持伴唱切换的歌曲。 + `1<<3`: 过滤没有高潮片段的歌曲。 - **返回值** 类型: number + `0`：成功 + `<0`: 失败 ### searchMusic 根据关键词搜索歌曲。 - **类型** ```ts (key_word: string, page_num: number, page_size: number, filters: number) => number ``` - **注意** 调用接口后，你会收到 [onSearchMusicResult](85533#onsearchmusicresult) 回调歌曲列表。 - **参数** - **key_word** 类型: string 关键词，字符串长度最大为 20 个字符。 - **page_num** 类型: number 页码，默认从 1 开始。 - **page_size** 类型: number 每页显示歌曲的最大数量，取值范围 [1,99]。 - **filters** 类型: number 歌曲过滤方式。多个过滤方式可以按位或组合。 + `0`: 不过滤。 + `1<<0`: 过滤没有歌词的歌曲。 + `1<<1`: 过滤不支持打分的歌曲。 + `1<<2`: 过滤不支持伴唱切换的歌曲。 + `1<<3`: 过滤没有高潮片段的歌曲。 - **返回值** 类型: number + `0`：成功 + `<0`: 失败 ### getHotMusic 根据热榜类别获取每个榜单的歌曲列表。 - **类型** ```ts (hot_types: number, filters: number) => number ``` - **注意** 调用接口后，你会收到 [onHotMusicResult](85533#onhotmusicresult) 回调歌曲列表。 - **参数** - **hot_types** 类型: number 热榜类别。多个热榜类别可以按位或组合。 + `1<<0`: 火山内容中心热歌榜。 + `1<<1`: 项目热歌榜。 - **filters** 类型: number 歌曲过滤方式。多个过滤方式可以按位或组合。 + `0`: 不过滤。 + `1<<0`: 过滤没有歌词的歌曲。 + `1<<1`: 过滤不支持打分的歌曲。 + `1<<2`: 过滤不支持伴唱切换的歌曲。 + `1<<3`: 过滤没有高潮片段的歌曲。 - **返回值** 类型: number + `0`：成功 + `<0`: 失败 ### getMusicDetail 获取音乐详细信息。 - **类型** ```ts (music_id: string) => number ``` - **注意** 调用接口后，你会收到 [onMusicDetailResult](85533#onmusicdetailresult) 回调。 - **参数** - **music_id** 类型: string 音乐 ID。 - **返回值** 类型: number + `0`：成功 + `<0`: 失败 ### downloadMusic 下载音乐。 - **类型** ```ts (music_id: string) => number ``` - **注意** + 若音乐下载成功，你会收到 [onDownloadSuccess](85533#ondownloadsuccess) 回调。 + 若音乐下载失败，你会收到 [onDownloadFailed](85533#ondownloadfailed) 回调。 + 音乐下载进度更新时，你会收到 onDownloadMusicProgress(85533#onDownloadMusicProgress) 回调。 - **参数** - **music_id** 类型: string 音乐 ID。 - **返回值** 类型: number 下载任务 ID。 ### downloadLyric 下载歌词。 - **类型** ```ts (music_id: string, type: DownloadLyricType) => number ``` - **注意** + 若歌词下载成功，你会收到 [onDownloadSuccess](85533#ondownloadsuccess) 回调。 + 若歌词下载失败，你会收到 [onDownloadFailed](85533#ondownloadfailed) 回调。 - **参数** - **music_id** 类型: string 音乐 ID。 - **type** 类型: [DownloadLyricType](85535#downloadlyrictype) 歌词文件类型。 - **返回值** 类型: number 下载任务 ID。 ### downloadMidi 下载 MIDI 文件。 - **类型** ```ts (music_id: string) => number ``` - **注意** + 若文件下载成功，你会收到 [onDownloadSuccess](85533#ondownloadsuccess) 回调。 + 若文件下载失败，你会收到 [onDownloadFailed](85533#ondownloadfailed) 回调。 - **参数** - **music_id** 类型: string 音乐 ID。 - **返回值** 类型: number 下载任务 ID。 ### cancelDownload 取消下载任务。 - **类型** ```ts (download_id: number) => number ``` - **参数** - **download_id** 类型: number 下载任务 ID。 - **返回值** 类型: number + `0`：成功 + `<0`: 失败 ### clearCache 清除当前音乐缓存文件，包括音乐音频和歌词。 - **类型** ```ts () => number ``` - **返回值** 类型: number + `0`: Success + `<0`: Failure. ### initSingScoring 初始化 K 歌评分。 - **类型** ```ts (sing_scoring_appkey: string, sing_scoring_token: string) => number ``` - **注意** 输入正确的鉴权信息才可以使用 K 歌评分相关的功能，鉴权方式为离线鉴权，根据包名（bundleID）绑定 Appkey 及 Token，K 歌评分密钥请联系技术支持同学申请。 - **参数** - **sing_scoring_appkey** 类型: string K 歌评分密钥，用于鉴权验证 K 歌功能是否开通。 - **sing_scoring_token** 类型: string K 歌评分密钥，用于鉴权验证 K 歌功能是否开通。 - **返回值** 类型: number + `0`: 成功。 + `<0`: 失败。 ### setSingScoringConfig 设置 K 歌评分参数。 - **类型** ```ts (config: SingScoringConfig) => number ``` - **参数** - **config** 类型: [SingScoringConfig](85535#singscoringconfig) K 歌评分的各项参数 - **返回值** 类型: number + `0`：配置成功。 + `-1`：接口调用失败。 + `-2`：未集成 K 歌评分模块。 ### getStandardPitchCount 获取当前系统内音视频设备数量 - **类型** ```ts () => any ``` - **返回值** 音视频设备数量 ### getStandardPitchInfo 获取每句歌词的标准音高信息 - **类型** ```ts (index: number) => StandardPitchInfo ``` - **参数** - **index** 类型: number 歌词句子数，取值范围为 0 到调用 [getStandardPitchCount](85532#rtcvideo-getstandardpitchcount) 获取到的句子总数减 1。 - **返回值** 类型: [StandardPitchInfo](85535#standardpitchinfo) 标准音高数据 ### startSingScoring 开始 K 歌评分。 - **类型** ```ts (position: number, scoring_info_interval: number) => any ``` - **注意** + 在调用 [initSingScoring](#initsingscoring) 初始化 K 歌评分功能后调用该接口。 + 调用该接口后，将会根据设置的回调时间间隔，收到评分结果 [onCurrentScoringInfo](85533#oncurrentscoringinfo) 回调。 + 如果调用 [startAudioMixing](#startaudiomixing) 接口播放音频文件，请在收到 [onAudioMixingStateChanged](85533#onaudiomixingstatechanged)(AUDIO_MIXING_STATE_PLAYING(1)) 之后调用此接口。 - **参数** - **position** 类型: number 开始评分时，音乐的播放进度，单位：ms。 - **scoring_info_interval** 类型: number 实时回调的时间间隔，单位：ms；默认 50 ms。最低间隔为 20 ms。 - **返回值** + `0`: 成功。 + `<0`: 失败。 ### stopSingScoring 停止 K 歌评分。 - **类型** ```ts () => number ``` - **返回值** 类型: number + `0`: 成功。 + `<0`: 失败。 ### getLastSentenceScore 获取上一句的演唱评分。 - **类型** ```ts () => number ``` - **注意** 调用 [startSingScoring](#startsingscoring) 开始评分后可以调用该接口。 - **返回值** 类型: number + `<0`：获取评分失败。 + `>=0`：上一句歌词的演唱评分。 ### getTotalScore 获取当前演唱总分。 - **类型** ```ts () => number ``` - **注意** 调用 [startSingScoring](#startsingscoring) 开始评分后可以调用该接口。 - **返回值** 类型: number + `<0`：获取总分失败。 + `>=0`：当前演唱总分。 ### getAverageScore 获取当前演唱歌曲的平均分。 - **类型** ```ts () => number ``` - **返回值** 类型: number + `<0`：获取平均分失败。 + `>=0`：当前演唱平均分。 ### setLocalVoiceEqualization 设置本地采集语音的均衡效果。包含内部采集和外部采集，但不包含混音音频文件。 - **类型** ```ts (config: VoiceEqualizationConfig) => number ``` - **注意** 根据奈奎斯特采样率，音频采样率必须大于等于设置的中心频率的两倍，否则，设置不生效。 - **参数** - **config** 类型: [VoiceEqualizationConfig](85535#voiceequalizationconfig) 语音均衡效果 - **返回值** 类型: number + `0`: 成功。 + `<0`: 失败。 ### setLocalVoiceReverbParam 设置本地采集音频的混响效果。包含内部采集和外部采集，但不包含混音音频文件。 - **类型** ```ts (param?: VoiceReverbConfig) => number ``` - **注意** 根据奈奎斯特采样率，音频采样率必须大于等于设置的中心频率的两倍，否则，设置不生效。 - **参数** - **param** 类型: [VoiceReverbConfig](85535#voicereverbconfig) | undefined 混响效果 - **返回值** 类型: number + `0`：成功。 + `<0`：失败。查看 [ReturnStatus](85535#returnstatus) 获得错误说明。 ### enableLocalVoiceReverb 开启本地音效混响效果 - **类型** ```ts (enable: boolean) => number ``` - **注意** 调用 [setLocalVoiceReverbParam](#setlocalvoicereverbparam) 设置混响效果。 - **参数** - **enable** 类型: boolean 是否开启 - **返回值** 类型: number + `0`：成功。 + `<0`：失败。查看 [ReturnStatus](85535#returnstatus) 获得错误说明。 ### startAudioRecording 开启录制语音通话，生成本地文件。 - **类型** ```ts (config: AudioRecordingConfig) => number ``` - **注意** + 录制包含各种音频效果。但不包含背景音乐。 + 调用 [stopAudioRecording](#stopaudiorecording) 关闭录制。 + 加入房间后才可调用。如果加入了多个房间，录制的文件中会包含各个房间的音频。离开最后一个房间后，录制任务自动停止。 + 调用该方法后，你会收到 onAudioRecordingStateUpdate(85533#onaudiorecordingstateupdate) 回调。 - **参数** - **config** 类型: [AudioRecordingConfig](85535#audiorecordingconfig) 录制参数 - **返回值** 类型: number + `0`: 正常 + `-2`: 参数设置异常 + `-3`: 当前版本 SDK 不支持该特性，请联系技术支持人员 ### stopAudioRecording 停止音频文件录制 - **类型** ```ts () => number ``` - **注意** 调用 [startAudioRecording](#startaudiorecording) 开启本地录制。 - **返回值** 类型: number + 0: 正常 + -3: 当前版本 SDK 不支持该特性，请联系技术支持人员 ### enableFilterSilentDevice 开启/关闭过滤无声设备功能。 - **类型** ```ts (enable: boolean) => number ``` - **参数** - **enable** 类型: boolean 是否开启过滤无声设备功能: + 1: 是 + 0: 否 - **返回值** 类型: number + `0`: 成功。 + `<0`: 失败。 ### stopAllAudioMixing 停止播放所有音频文件及混音。 - **已弃用** since 325.1, use RTCMediaPlayer and RTCAudioEffectPlayer instead. - **类型** ```ts () => any ``` - **注意** + 调用 [startAudioMixing](#startaudiomixing) 方法开始播放音频文件及混音后，可以调用本方法停止播放所有音频文件及混音。 + 调用本方法停止播放所有音频文件及混音后，会收到 `onAudioMixingStateChanged` 回调，通知已停止播放和混音。 + 调用本方法停止播放所有音频文件及混音后，该音频文件会被自动卸载。 - **返回值** + `0`: 成功。 + `<0`: 失败。 ### pauseAllAudioMixing 暂停播放所有音频文件及混音。 - **已弃用** since 325.1, use RTCMediaPlayer and RTCAudioEffectPlayer instead. - **类型** ```ts () => any ``` - **注意** + 调用 [startAudioMixing](#startaudiomixing) 方法开始播放音频文件及混音后，可以通过调用本方法暂停播放所有音频文件及混音。 + 调用本方法暂停播放所有音频文件及混音后，可调用 [resumeAllAudioMixing](#resumeallaudiomixing) 方法恢复所有播放及混音。 + 调用本方法暂停播放所有音频文件及混音后，会收到 `onAudioMixingStateChanged` 回调，通知已暂停播放和混音。 - **返回值** + `0`: 成功。 + `<0`: 失败。 ### resumeAllAudioMixing 恢复播放所有音频文件及混音。 - **已弃用** since 325.1, use RTCMediaPlayer and RTCAudioEffectPlayer instead. - **类型** ```ts () => any ``` - **注意** + 调用 [pauseAllAudioMixing](#pauseallaudiomixing) 方法暂停所有正在播放音频文件及混音后，可以通过调用本方法恢复播放及混音。 + 调用本方法恢复播放所有音频文件及混音后，会收到 `onAudioMixingStateChanged` 回调，通知已恢复播放和混音。 - **返回值** + `0`: 成功。 + `<0`: 失败。 ### enableAGC 打开/关闭 AGC(Automatic Gain Control) 自动增益控制功能。开启该功能后，SDK 会自动调节麦克风的采集音量，确保音量稳定。 - **类型** ```ts (enable: boolean) => number ``` - **注意** + 该方法在进房前后均可调用。如果你需要在进房前使用 AGC 功能，请联系技术支持获得私有参数，传入对应 [`RoomProfileType`](85535#roomprofiletype)。 + 要想在进房后开启 AGC 功能，你需要把 [`RoomProfileType`](85535#roomprofiletype) 设置为 `kRoomProfileTypeMeeting` 、`kRoomProfileTypeMeetingRoom` 或 `kRoomProfileTypeClassroom` 。 + AGC 功能生效后，不建议再调用 [`setAudioCaptureDeviceVolume`](85532#rtcvideo-setaudiocapturedevicevolume) 来调节设备麦克风的采集音量。 - **参数** - **enable** 类型: boolean 是否打开 AGC 功能: + true: 打开 AGC 功能。 + false: 关闭 AGC 功能。 - **返回值** 类型: number + 0: 调用成功。 + -1: 调用失败。 ### setVideoCaptureRotation 设置本端采集的视频帧的旋转角度。当外接摄像头倒置或者倾斜安装时，调用本接口进行调整。 - **类型** ```ts (rotation: VideoRotation) => number ``` - **注意** + 调用本接口也将对自定义采集视频画面生效，在原有的旋转角度基础上叠加本次设置。 + 通过 [enableVirtualBackground](85532#rtcvideo-enablevirtualbackground) 增加的虚拟背景，不会跟随本接口的设置进行旋转。 + 通过本接口设置的旋转角度不会应用到转推直播中。 - **参数** - **rotation** 类型: [VideoRotation](85535#videorotation) 相机朝向角度，默认为 `VIDEO_ROTATION_0(0)`，无旋转角度。 - **返回值** 类型: number ### setVideoDigitalZoomConfig 设置本地摄像头数码变焦参数，包括缩放倍数，移动步长。 - **类型** ```ts (type: ZoomConfigType, size: number) => number ``` - **注意** + 每次调用本接口只能设置一种参数。如果缩放系数和移动步长都需要设置，分别调用本接口传入相应参数。 + 由于移动步长的默认值为 `0` ，在调用 [setVideoDigitalZoomControl](85532#rtcvideo-setvideodigitalzoomcontrol) 或 [startVideoDigitalZoomControl](85532#rtcvideo-startvideodigitalzoomcontrol) 进行数码变焦操作前，应先调用本接口。 - **参数** - **type** 类型: [ZoomConfigType](85535#zoomconfigtype) 数码变焦参数类型，缩放系数或移动步长。必填。 - **size** 类型: number 缩放系数或移动步长，保留到小数点后三位。默认值为 0。必填。选择不同 `type` 时有不同的取值范围。当计算后的结果超过缩放和移动边界时，取临界值。 + `kZoomFocusOffset`：缩放系数增量，范围为 [0, 7]。例如，设置为 0.5 时，如果调用 [setVideoDigitalZoomControl](85532#rtcvideo-setvideodigitalzoomcontrol) 选择 Zoom in，则缩放系数增加 0.5。缩放系数范围 [1，8]，默认为 `1`，原始大小。 + `kZoomMoveOffset`：移动百分比，范围为 [0, 0.5]，默认为 0，不移动。如果调用 [setVideoDigitalZoomControl](85532#rtcvideo-setvideodigitalzoomcontrol) 选择的是左右移动，则移动距离为 size x 原始视频宽度；如果选择的是上下移动，则移动距离为 size x 原始视频高度。例如，视频帧边长为 1080 px，设置为 0.5 时，实际移动距离为 0.5 x 1080 px = 540 px。 - **返回值** 类型: number ### setVideoDigitalZoomControl 控制本地摄像头数码变焦，缩放或移动一次。设置对本地预览画面和发布到远端的视频都生效。 - **类型** ```ts (direction: ZoomDirectionType) => number ``` - **注意** + 由于默认步长为 `0`，调用该方法前需通过 [setVideoDigitalZoomControl](85532#rtcvideo-setvideodigitalzoomcontrol) 设置参数。 + 调用该方法进行移动前，应先使用本方法或 [startVideoDigitalZoomControl](85532#rtcvideo-startvideodigitalzoomcontrol) 进行放大，否则无法移动。 + 当数码变焦操作超出范围时，将置为临界值。例如，移动到了图片边界、放大到了 8 倍、缩小到原图大小。 + 如果你希望实现持续数码变焦操作，调用 [startVideoDigitalZoomControl](85532#rtcvideo-startvideodigitalzoomcontrol)。 - **参数** - **direction** 类型: [ZoomDirectionType](85535#zoomdirectiontype) 数码变焦操作类型。 - **返回值** 类型: number ### startVideoDigitalZoomControl 开启本地摄像头持续数码变焦，缩放或移动。设置对本地预览画面和发布到远端的视频都生效。 - **类型** ```ts (direction: ZoomDirectionType) => number ``` - **注意** + 由于默认步长为 `0`，调用该方法前需通过 [setVideoDigitalZoomControl](85532#rtcvideo-setvideodigitalzoomcontrol) 设置参数。 + 调用该方法进行移动前，应先使用本方法或 [setVideoDigitalZoomControl](85532#rtcvideo-setvideodigitalzoomcontrol) 进行放大，否则无法移动。 + 当数码变焦操作超出范围时，将置为临界值并停止操作。例如，移动到了图片边界、放大到了 8 倍、缩小到原图大小。 + 你也可以调用 [stopVideoDigitalZoomControl](85532#rtcvideo-stopvideodigitalzoomcontrol) 手动停止控制。 + 如果你希望实现单次数码变焦操作，调用 [setVideoDigitalZoomControl](85532#rtcvideo-setvideodigitalzoomcontrol)。 - **参数** - **direction** 类型: [ZoomDirectionType](85535#zoomdirectiontype) 数码变焦操作类型。 - **返回值** 类型: number ### stopVideoDigitalZoomControl 停止本地摄像头持续数码变焦。 - **类型** ```ts () => number ``` - **注意** 关于开始数码变焦，参看 [startVideoDigitalZoomControl](85532#rtcvideo-startvideodigitalzoomcontrol)。 - **返回值** 类型: number ### startPushMixedStreamToCDN 新增转推直播任务(新)，并设置合流的图片、视频视图布局和音频属性。 - **类型** ```ts (task_id: string, config: IMixedStreamConfig) => number ``` - **注意** + 同一个任务中转推多路直播流时，SDK 会先将多路流合成一路流，然后再进行转推。 + 调用该方法后，关于启动结果和推流过程中的错误，会收到 [onSetRoomExtraInfoResult](85533#rtcroomcallback-onsetroomextrainforesult) 回调。 + 如果你在[控制台](https://console.volcengine.com/rtc/cloudRTC?tab=callback&from=doc)配置了转推直播回调，调用本接口会收到 [TranscodeStarted](https://www.volcengine.com/docs/6348/75125#transcodestarted) 服务端的回调通知。重复调用该接口时，第二次调用会同时触发 [TranscodeStarted](https://www.volcengine.com/docs/6348/75125#transcodestarted) 和 [TranscodeUpdated](https://www.volcengine.com/docs/6348/75125#transcodeupdated) ，如果第二次调用的参数不同，还会触发 [TranscodeStateChanged](https://www.volcengine.com/docs/6348/75125#transcodestatechanged)。 + 调用 [stopPushStreamToCDN](85532#rtcvideo-stoppushstreamtocdn) 停止转推直播。 - **参数** - **task_id** 类型: string 转推直播任务 ID，长度不超过 126 字节。你可以在同一房间内发起多个转推直播任务，并用不同的任务 ID 加以区分。当你需要发起多个转推直播任务时，应使用多个 ID；当你仅需发起一个转推直播任务时，建议使用空字符串。 - **config** 类型: [IMixedStreamConfig](85535#imixedstreamconfig) 转推直播配置参数。 - **返回值** 类型: number + 0: 成功 + !0: 失败 ### updatePushMixedStreamToCDN 更新转推直播参数。 - **类型** ```ts (task_id: string, config: IMixedStreamConfig) => number ``` - **注意** + 会收到 [`onSetRoomExtraInfoResult`](85533#rtcroomcallback-onsetroomextrainforesult) 回调。 + 使用 [`startPushMixedStreamToCDN`](85532#rtcvideo-startpushmixedstreamtocdn) 启用转推直播功能后，使用此方法更新功能配置参数。 - **参数** - **task_id** 类型: string 转推直播任务 ID。指定想要更新参数设置的转推直播任务。 - **config** 类型: [IMixedStreamConfig](85535#imixedstreamconfig) 转推直播配置参数。除特殊说明外，均支持过程中更新。 - **返回值** 类型: number + 0: 成功 + !0: 失败 ### setupMixingVideo 为客户端合流绑定本地视图 - **类型** ```ts (task_id: string, view: HTMLDivElement, renderOptions?: RenderOptions) => number ``` - **注意** + 使用客户端合流功能时，调用 [`startPushMixedStreamToCDN`](#rtcvideo-startpushmixedstreamtocdn) 后，调用本 API 绑定。 + 如果需要解除绑定，调用 [`removeMixingVideo`](#removemixingvideo)。 - **参数** - **task_id** 类型: string task ID - **view** 类型: HTMLDivElement 视图 - **renderOptions** 类型: [RenderOptions](85535#renderoptions) 默认值: `' { render_mode: RenderMode.FIT, mirror: false, }'` 渲染选项 - **返回值** 类型: number + `0`：成功 + `-1`: 失败 ### removeMixingVideo 为合流转推解绑本地视图 - **类型** ```ts (task_id: string) => number ``` - **注意** 停止接收合流转推时解绑视图。 - **参数** - **task_id** 类型: string task ID - **返回值** 类型: number + `0`：成功 + `-1`: 失败 ### setPublicStreamAudioPlaybackVolume 调节公共流的音频播放音量。 - **类型** ```ts (public_stream_id: string, volume: number) => number ``` - **参数** - **public_stream_id** 类型: string 公共流 ID - **volume** 类型: number 音频播放音量值和原始音量值的比值，该比值的范围是 `[0, 400]`，单位为 %，且自带溢出保护。为保证更好的音频质量，建议设定在 `[0, 100]` 之间，其中 100 为系统默认值。 - **返回值** 类型: number + 0: 成功调用。 + -2: 参数错误。 ### startHardwareEchoDetection 开启通话前回声检测 - **类型** ```ts (test_audio_file_path: string) => number ``` - **注意** + 只有当 `RoomProfileType` 为 `kRoomProfileTypeMeeting` 和 `kRoomProfileTypeMeetingRoom` 时支持开启本功能。 + 开启检测前，你需要向用户获取音频设备的使用权限。 + 开启检测前，请确保音频设备没有被静音，采集和播放音量正常。 + 调用本接口后监听 [`onHardwareEchoDetectionResult`](85533#rtcvideocallback-onhardwareechodetectionresult) 获取检测结果。 + 检测期间，进程将独占音频设备，无法使用其他音频设备测试接口： [`startEchoTest`](85532#rtcvideo-startechotest) 或 [`startAudioPlaybackDeviceTest`](85532#rtcvideo-startaudioplaybackdevicetest)。 + 调用 [`stopHardwareEchoDetection`](85532#rtcvideo-stophardwareechodetection) 停止检测，释放对音频设备的占用。 - **参数** - **test_audio_file_path** 类型: string 用于回声检测的音频文件的绝对路径，路径字符串使用 UTF-8 编码格式，支持以下音频格式: mp3，aac，m4a，3gp，wav。音频文件不为静音文件，推荐时长为 10 ～ 20 秒。 - **返回值** 类型: number 方法调用结果： + 0: 成功。 + -1：失败。上一次检测未结束，请先调用 [stopHardwareEchoDetection](85532#rtcvideo-stophardwareechodetection) 停止检测后重新调用本接口。 + -2：失败。路径不合法或音频文件格式不支持。 ### stopHardwareEchoDetection 停止通话前回声检测 - **类型** ```ts () => number ``` - **注意** + 关于开启通话前回声检测，参看 [startHardwareEchoDetection](85532#rtcvideo-starthardwareechodetection) 。 + 建议在收到 [onHardwareEchoDetectionResult](85533#rtcvideocallback-onhardwareechodetectionresult) 通知的检测结果后，调用本接口停止检测。 + 在用户进入房间前结束回声检测，释放对音频设备的占用，以免影响正常通话。 - **返回值** 类型: number 方法调用结果： + 0: 成功。 + -1：失败。 ### setLocalProxy 设置本地代理。 - **类型** ```ts (configurations: LocalProxyConfiguration[]) => number ``` - **注意** + 该方法需要在进房前调用。 + 调用该方法设置本地代理后，SDK 会触发 [onLocalProxyStateChanged](85533#rtcvideocallback-onlocalproxystatechanged) ，返回代理连接的状态。 - **参数** - **configurations** 类型: [LocalProxyConfiguration](85535#localproxyconfiguration)[] 本地代理配置参数。你可以根据自己的需要选择同时设置 Http 隧道和 Socks5 两类代理，或者单独设置其中一类代理。如果你同时设置了 Http 隧道和 Socks5 两类代理，此时，媒体和信令采用 Socks5 代理， Http 请求采用 Http 隧道代理；如果只设置 Http 隧道或 Socks5 一类代理，媒体、信令和 Http 请求均采用已设置的代理。调用此接口设置本地代理后，若想清空当前已有的代理设置，可再次调用此接口，选择不设置任何代理即可清空。 - **返回值** 类型: number ### setEarMonitorMode 开启/关闭耳返功能 - **类型** ```ts (mode: EarMonitorMode) => number ``` - **注意** - 耳返功能仅适用于由 RTC SDK 内部采集的音频。 - 耳返功能仅支持设备通过 3.5mm 接口、USB 接口、或蓝牙方式直连耳机时可以使用。对于通过 HDMI 或 USB-C 接口连接显示器，再连接，或通过连接 OTG 外接声卡再连接的耳机，不支持耳返功能。 - **参数** - **mode** 类型: [EarMonitorMode](85535#earmonitormode) 是否开启耳返功能 - **返回值** 类型: number + 0: 调用成功。 + < 0 : 调用失败。 ### setEarMonitorVolume 设置耳返的音量 - **类型** ```ts (volume: number) => number ``` - **注意** 设置耳返音量前，你必须先调用 [setEarMonitorMode](85532#rtcvideo-setearmonitormode) 打开耳返功能。 - **参数** - **volume** 类型: number 耳返的音量相对原始音量的比值，取值范围：[0,100]，单位：% - **返回值** 类型: number + 0: 调用成功。 + < 0 : 调用失败。 ### getAudioEffectPlayer 创建音效播放器实例。 - **类型** ```ts () => veRTCAudioEffectPlayer ``` - **返回值** 类型: veRTCAudioEffectPlayer 音效播放器。 ### getMediaPlayer 创建音乐播放器实例。 - **类型** ```ts (player_id: number) => veRTCMediaPlayer ``` - **参数** - **player_id** 类型: number 音乐播放器实例 id。取值范围为 `[0, 3]`。最多同时存在4个实例，超出取值范围时返回 nullptr。 - **返回值** 类型: veRTCMediaPlayer 音乐播放器实例 ### enableExternalSoundCard 启用匹配外置声卡的音频处理模式 - **类型** ```ts (enable: boolean) => number ``` - **注意** + 当采用外接声卡进行音频采集时，建议开启此模式，以获得更好的音质。 + 开启此模式时，仅支持耳机播放。如果需要使用扬声器或者外置音箱播放，关闭此模式。 - **参数** - **enable** 类型: boolean + true: 开启 + false: 不开启(默认) - **返回值** 类型: number + 0: 调用成功。 + < 0 : 调用失败。 ### enableAudioFrameCallback 设置并开启指定的音频数据帧回调。 - **类型** ```ts (method: AudioFrameCallbackMethod, format: AudioFormat) => number ``` - **参数** - **method** 类型: [AudioFrameCallbackMethod](85535#audioframecallbackmethod) 音频回调方法。方法对应的回调名称参见类型说明。每次调用本接口设置一种回调。 + 当音频回调方法设置为 `kAudioFrameCallbackRecord`、`kAudioFrameCallbackPlayback`、`kAudioFrameCallbackMixed`、`kAudioFrameCallbackRecordScreen`时，你需要在参数 `format` 中指定准确的采样率和声道，暂不支持设置为自动。 + 当音频回调方法设置为 `kAudioFrameCallbackRemoteUser`时，应将 `format` 的字段设置为默认值。 - **format** 类型: [AudioFormat](85535#audioformat) 音频参数格式 - **返回值** 类型: number + 0: 调用成功。 + < 0 : 调用失败 ### disableAudioFrameCallback 关闭音频回调 - **类型** ```ts (method: AudioFrameCallbackMethod) => number ``` - **注意** 该方法需要在调用 [enableAudioFrameCallback](85532#rtcvideo-enableaudioframecallback) 之后调用。 - **参数** - **method** 类型: [AudioFrameCallbackMethod](85535#audioframecallbackmethod) 音频回调方法 - **返回值** 类型: number + 0: 调用成功。 + < 0 : 调用失败。 ### setAudioAlignmentProperty 在听众端，设置订阅的所有远端音频流精准对齐后播放。 - **类型** ```ts (streamKey: RemoteStreamKey, mode: AudioAlignmentMode) => number ``` - **注意** + 你必须在实时合唱场景下使用此功能。在加入房间时，所有人应设置 [RoomProfileType](85535#roomprofiletype) 为 `kRoomProfileTypeChorus`。 + 订阅的所有远端流必须通过 [startAudioMixing](85532#rtcvideo-startaudiomixing) 开启了背景音乐混音，并将 [AudioMixingConfig](85535#audiomixingconfig) 中的 `sync_progress_to_record_frame` 设置为 `true`。 + 如果订阅的某个音频流延迟过大，可能无法实现精准对齐。 + 合唱的参与者不应调用此 API，因为调用此 API 会增加延迟。如果希望从听众变为合唱参与者，应关闭对齐功能。 - **参数** - **streamKey** 类型: [RemoteStreamKey](85535#remotestreamkey) 作为对齐基准的远端音频流。一般选择主唱的音频流。你必须在收到 [onUserPublishStream](85533#rtcroomcallback-onuserpublishstream)，确认此音频流已发布后，调用此 API。 - **mode** 类型: [AudioAlignmentMode](85535#audioalignmentmode) 是否对齐，默认不对齐。 - **返回值** 类型: number + 0: 调用成功。 + < 0 : 调用失败。 ### enablePlaybackDucking 打开/关闭音量闪避功能，适用于在 RTC 通话过程中会同时播放短视频或音乐的场景，如“一起看”、“在线 KTV”等。开启该功能后，当检测到远端人声时，RTC 的本地的媒体播放音量会自动减弱，从而保证远端人声的清晰可辨；当远端人声消失时，RTC 的本地媒体音量会恢复到闪避前的音量水平。 - **类型** ```ts (enable: boolean) => number ``` - **参数** - **enable** 类型: boolean 是否开启音量闪避： + true: 是 + false: 否 - **返回值** 类型: number + 0: 调用成功。 + < 0 : 调用失败。 ### startAudioDeviceRecordTest 开始音频采集设备和音频播放设备测试。 - **类型** ```ts (indication_interval: number) => number ``` - **注意** + 该方法在进房前后均可调用。且不可与其它音频设备测试功能同时应用。 + 调用本接口 30 s 后，采集自动停止，并开始播放采集到的声音。录音播放完毕后，设备测试流程自动结束。你也可以在 30 s 内调用 [stopAudioDeviceRecordAndPlayTest](85532#rtcvideo-stopaudiodevicerecordandplaytest) 来停止采集并开始播放此前采集到的声音。 + 调用 [stopAudioDevicePlayTest](85532#rtcvideo-stopaudiodeviceplaytest) 可以停止音频设备采集和播放测试。 + 你不应在测试过程中，调用 `enableAudioPropertiesReport` 注册音量提示回调。 + 该方法仅在本地进行音频设备测试，不涉及网络连接。 - **参数** - **indication_interval** 类型: number 测试中会收到 `onLocalAudioPropertiesReport` 回调，本参数指定了该周期回调的时间间隔，单位为毫秒。建议设置到大于 200 毫秒。最小不得少于 10 毫秒。 - **返回值** 类型: number 方法调用结果 + 0：方法调用成功 + < 0：方法调用失败 ### stopAudioDeviceRecordAndPlayTest 停止采集本地音频，并开始播放采集到的声音。录音播放完毕后，设备测试流程结束。 - **类型** ```ts () => number ``` - **注意** + 调用 [`startAudioDeviceRecordTest`](85532#rtcvideo-startaudiodevicerecordtest) 30 s 内调用本接口来停止采集并开始播放此前采集到的声音。 + 调用本接口开始播放录音后，可以在播放过程中调用 [`stopAudioDevicePlayTest`](85532#rtcvideo-stopaudiodeviceplaytest) 停止播放。 - **返回值** 类型: number 方法调用结果 + 0：方法调用成功 + < 0：方法调用失败 ### stopAudioDevicePlayTest 停止由调用 [startAudioDeviceRecordTest](85532#rtcvideo-startaudiodevicerecordtest) 开始的音频播放设备测试。 - **类型** ```ts () => number ``` - **注意** 在音频播放设备测试自动结束前，可调用本接口停止音频采集与播放测试。 - **返回值** 类型: number 方法调用结果 + 0：方法调用成功 + < 0：方法调用失败 ### setLowLightAdjusted 设置视频暗光增强模式。对于光线不足、照明不均匀或背光等场景下推荐开启，可有效改善画面质量。 - **类型** ```ts (mode: VideoEnhancementMode) => number ``` - **注意** + 开启后会影响设备性能，应根据实际需求和设备性能决定是否开启。 + 对 RTC SDK 内部采集的视频和自定义采集的视频都生效。 - **参数** - **mode** 类型: [VideoEnhancementMode](85535#videoenhancementmode) 默认不开启。 - **返回值** 类型: number + 0: API 调用成功。会立即生效，但需要等待下载和检测完成后才能看到增强后的效果。 + < 0: API 调用失败。 ### `static` getSDKVersion 获取当前 SDK 版本信息 - **类型** ```ts () => string ``` - **返回值** 类型: string 当前 SDK 版本信息 ### `static` setLogConfig 设置日志文件 - **类型** ```ts (log_config: LogConfig) => number ``` - **参数** - **log_config** 类型: [LogConfig](85535#logconfig) 日志文件配置 - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### `static` getErrorDescription 获取错误码的描述 - **类型** ```ts (code: number) => string ``` - **注意** 该接口是通用功能，调用时不需要依赖引擎对象。 - **参数** - **code** 类型: number 需要获取描述的错误码 - **返回值** 类型: string 错误码的描述 ### `static` getCurrentProcessId 获取加载引擎进程的 ID 方便调试 - **类型** ```ts () => string ``` - **返回值** 类型: string 进程的 ID ### `static` setRenderType 设置渲染类型 - **类型** ```ts (type: RenderType) => void ``` - **注意** + 默认渲染类型为 WebGL 渲染。 + 设置渲染类型之后，新创建的 canvas 渲染类型会以新的渲染方式生效 + 设置 WebGL 渲染，如果不支持 WebGL 渲染或者 WebGL渲染失败的情况下，会自动切换为 Software 渲染。 - **参数** - **type** 类型: [RenderType](85535#rendertype) 渲染类型 ### `static` getTimestampMs 获取时间戳, 单位毫秒 - **类型** ```ts () => number ``` - **返回值** 类型: number 时间戳, 单位毫秒 ### `static` getTimestampUs 获取时间戳, 单位微秒 - **类型** ```ts () => number ``` - **返回值** 类型: number 时间戳, 单位微秒 ## RTCRoom 类型: `class` - **API** | 方法 | 描述 | | :-- | :-- | | [createRTCRoom](#rtcroom-creatertcroom) | 创建房间实例 | | [getRoomId](#rtcroom-getroomid) | 获取房间 ID | | [destroy](#rtcroom-destroy) | 退出并销毁房间。 | | [joinRoom](#rtcroom-joinroom) | 加入房间。 | | [leaveRoom](#rtcroom-leaveroom) | 离开房间。 | | [setUserVisibility](#rtcroom-setuservisibility) | 设置用户可见性。未调用该接口前，本地用户默认对他人可见。 | | [setMultiDeviceAVSync](#rtcroom-setmultideviceavsync) | 设置发流端音画同步。 | | [updateToken](#rtcroom-updatetoken) | 更新 Token。Token 中同时包含进房、发布和订阅权限，各权限有一定的有效期，并且到期前 30 秒会触发回调，提示用户更新 Token 相关权限。此时需要重新获取 Token，并调用此方法更新 Token，以保证通话的正常进行。 | | [setRemoteVideoConfig](#rtcroom-setremotevideoconfig) | 设置期望订阅的远端视频流的参数。 | | [publishStream](#rtcroom-publishstream) | 在当前所在房间内发布本地通过摄像头/麦克风采集的媒体流 | | [unpublishStream](#rtcroom-unpublishstream) | 停止将本地摄像头/麦克风采集的媒体流发布到当前所在房间中 | | [publishScreen](#rtcroom-publishscreen) | 在当前所在房间内发布本地屏幕共享音视频流 | | [unpublishScreen](#rtcroom-unpublishscreen) | 停止将本地屏幕共享音视频流发布到当前所在房间中 | | [subscribeStream](#rtcroom-subscribestream) | 订阅房间内指定的通过摄像头/麦克风采集的媒体流，或更新对指定远端用户的订阅选项 | | [unsubscribeStream](#rtcroom-unsubscribestream) | 取消订阅房间内指定的通过摄像头/麦克风采集的媒体流。该方法对自动订阅和手动订阅模式均适用。 | | [subscribeAllStreams](#rtcroom-subscribeallstreams) | 订阅房间内所有通过摄像头/麦克风采集的媒体流，或更新订阅选项。 | | [unsubscribeAllStreams](#rtcroom-unsubscribeallstreams) | 取消订阅房间内所有的通过摄像头/麦克风采集的媒体流。 | | [subscribeScreen](#rtcroom-subscribescreen) | 订阅房间内指定的远端屏幕共享音视频流，或更新对指定远端用户的订阅选项 | | [unsubscribeScreen](#rtcroom-unsubscribescreen) | 取消订阅房间内指定的远端屏幕共享音视频流。 | | [pauseAllSubscribedStream](#rtcroom-pauseallsubscribedstream) | 暂停接收来自远端的媒体流。 | | [resumeAllSubscribedStream](#rtcroom-resumeallsubscribedstream) | 恢复接收来自远端的媒体流 | | [sendUserMessage](#rtcroom-sendusermessage) | 给房间内指定的用户发送点对点文本消息 | | [sendUserBinaryMessage](#rtcroom-senduserbinarymessage) | 给房间内指定的用户发送点对点二进制消息。 | | [sendRoomMessage](#rtcroom-sendroommessage) | 给房间内的所有其他用户群发文本消息。 | | [sendRoomBinaryMessage](#rtcroom-sendroombinarymessage) | 给房间内的所有其他用户群发二进制消息。 | | [startForwardStreamToRooms](#rtcroom-startforwardstreamtorooms) | 开始跨房间转发媒体流。 | | [updateForwardStreamToRooms](#rtcroom-updateforwardstreamtorooms) | 更新跨房间媒体流转发信息。 | | [stopForwardStreamToRooms](#rtcroom-stopforwardstreamtorooms) | 停止跨房间媒体流转发。 | | [pauseForwardStreamToAllRooms](#rtcroom-pauseforwardstreamtoallrooms) | 暂停跨房间媒体流转发。 | | [resumeForwardStreamToAllRooms](#rtcroom-resumeforwardstreamtoallrooms) | 恢复跨房间媒体流转发。 | | [enableRangeAudio](#rtcroom-enablerangeaudio) | 开启/关闭范围语音功能。 | | [updateReceiveRange](#rtcroom-updatereceiverange) | 更新本地用户的音频收听范围。 | | [updateRangePosition](#rtcroom-updaterangeposition) | 更新本地用户在房间内空间直角坐标系中的位置坐标。 | | [setAttenuationModel](#rtcroom-setattenuationmodel) | 设置范围语音的音量衰减模式。 | | [setNoAttenuationFlags](#rtcroom-setnoattenuationflags) | 添加标签组，用于标记相互之间通话不衰减的用户组。
在同一个 RTC 房间中，如果多个用户的标签组之间有交集，那么，他们之间互相通话时，通话不衰减。
比如，用户身处多个队伍，队伍成员间通话不衰减。那么，可以为每个队伍绑定专属标签，每个用户的标签组包含用户所属各个队伍的标签。 | | [enableSpatialAudio](#rtcroom-enablespatialaudio) | 开启/关闭空间音频功能。 | | [updateSpatialPosition](#rtcroom-updatespatialposition) | 更新本地用户在房间内空间直角坐标系中的位置坐标。 | | [updateSelfOrientation](#rtcroom-updateselforientation) | 更新本地用户在空间音频坐标系下的朝向。 | | [disableRemoteOrientation](#rtcroom-disableremoteorientation) | 参与通话的各端调用本接口后，将忽略远端用户的朝向，认为所有远端用户都面向本地用户。 | | [updateListenerPosition](#rtcroom-updatelistenerposition) | 更新在房间内收听音频时的位置。
通过此接口，你可以设定本地发声位置和收听位置不同。 | | [updateListenerOrientation](#rtcroom-updatelistenerorientation) | 更新在房间内收听音频时的朝向。
通过此接口，你可以设定本地用户的发声朝向和收听朝向不同。 | | [setRemoteRoomAudioPlaybackVolume](#rtcroom-setremoteroomaudioplaybackvolume) | 调节某个房间内所有远端用户的音频播放音量。 | | [setAudioSelectionConfig](#rtcroom-setaudioselectionconfig) | 设置本端发布流在音频选路中的优先级。 | | [setRoomExtraInfo](#rtcroom-setroomextrainfo) | 设置/更新房间附加信息，可用于标识房间状态或属性，或灵活实现各种业务逻辑。 | | [startSubtitle](#rtcroom-startsubtitle) | 识别或翻译房间内所有用户的语音，形成字幕。 | | [stopSubtitle](#rtcroom-stopsubtitle) | 关闭字幕。
调用该方法后，用户会收到 [onSubtitleStateChanged](85533#onsubtitlestatechanged) 回调，通知字幕是否关闭。 | | [updateSelfPosition](#rtcroom-updateselfposition) | 设置本地用户在自建空间直角坐标系中的收听坐标和收听朝向，以实现本地用户预期的空间音频收听效果。 | | [updateRemotePosition](#rtcroom-updateremoteposition) | 设置房间内某一远端用户在本地用户自建的空间音频坐标系中的发声位置和发声朝向，以实现本地用户预期的空间音频收听效果。 | | [removeRemotePosition](#rtcroom-removeremoteposition) | 移除调用 [updateRemotePosition](85532#updateremoteposition) 为某一远端用户设置的空间音频效果。 | | [removeAllRemotePosition](#rtcroom-removeallremoteposition) | 移除调用 [updateRemotePosition](85532#updateremoteposition) 为所有远端用户设置的空间音频效果。 | ### createRTCRoom 创建房间实例 - **类型** ```ts (room_id: string) => -1 | 0 ``` - **注意** + 调用此方法仅返回一个房间实例，你仍需调用 [joinRoom](#joinroom) 才能真正地创建/加入房间。 + 多次调用此方法以创建多个 RTCRoom 实例。分别调用各 RTCRoom 实例中的 [joinRoom](#joinroom) 方法，同时加入多个房间。 + 多房间模式下，用户可以同时订阅各房间的音视频流。 + 如果需要加入的房间已存在，你仍需先调用本方法来获取 RTCRoom 实例，再调用 [joinRoom](#joinroom) 加入房间。 + 多房间模式下，创建多个房间实例需要使用不同的 roomId，否则会导致创建房间失败。 + 如果你需要在多个房间发布音视频流，无须创建多房间，直接调用 [startForwardStreamToRooms](#startforwardstreamtorooms) 开始跨房间转发媒体流。 - **参数** - **room_id** 类型: string 标识通话房间的房间 ID，最大长度为 128 字节的非空字符串。支持的字符集范围为: • 26个大写字母 A ~ Z • 26个小写字母 a ~ z • 10个数字 0 ~ 9 • 下划线 "_", at 符 "@", 减号 "-" 多房间模式下，调用创建房间接口后，请勿调用同样的 roomID 创建房间，否则会导致创建房间失败。 - **返回值** + `0`: 成功 + `-1`: 失败 ### getRoomId 获取房间 ID - **类型** ```ts () => string ``` - **返回值** 类型: string 房间 ID ### destroy 退出并销毁房间。 - **类型** ```ts () => number ``` - **注意** 关于创建房间，参见 [createRTCRoom](#creatertcroom)。 - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### joinRoom 加入房间。 - **类型** ```ts (token: string, user_info: UserInfo, config?: RTCRoomConfig) => number ``` - **注意** + 调用 [`createRTCRoom`](#creatertcroom) 创建房间后，调用此方法加入房间，同房间内其他用户进行音视频通话。 + 同一个 App ID 的同一个房间内，每个用户的用户 ID 必须是唯一的。如果两个用户的用户 ID 相同，则后进房的用户会将先进房的用户踢出房间，并且先进房的用户会收到 [`onError`](85533#rtcvideocallback-onerror) 回调通知，错误类型详见 [`ErrorCode`](85534#errorcode) 中的 `kErrorCodeDuplicateLogin`。 + 本地用户调用此方法加入房间成功后，会收到 [`onRoomStateChanged`](85533#onroomstatechanged) 回调通知。若本地用户同时为可见用户，加入房间时远端用户会收到 [`onUserJoined`](85533#rtcroomcallback-onuserjoined) 回调通知。关于可见性设置参看 [`setUserVisibility`](#setuservisibility)。 + 房间内不可见用户的容量远远大于可见用户，而且用户默认可见，因此对于不参与互动的用户，你需要调用 [`setUserVisibility`](#setuservisibility)。更改为不可见用户。从而避免因房间内用户达到数量上限所导致的进房失败。默认情况下，一个 RTC 房间最多同时容纳 50 名可见用户，最多 30 人可同时上麦。更多信息参看[用户和媒体流上限](https://www.volcengine.com/docs/6348/257549)。 + 用户加入房间成功后，在本地网络状况不佳的情况下，SDK 可能会与服务器失去连接，并触发 [`onConnectionStateChanged`](85533#onconnectionstatechanged) 回调。此时 SDK 会自动重试，直到成功重连。重连成功后，本地会收到 [`onRoomStateChanged`](85533#rtcroomcallback-onroomstatechanged) 回调通知。 - **参数** - **token** 类型: string 动态密钥。用于对进房用户进行鉴权验证。进入房间需要携带 Token。测试时可使用控制台生成临时 Token，正式上线需要使用密钥 SDK 在你的服务端生成并下发 Token。Token 有效期及生成方式参看[使用 Token 完成鉴权](70121)。使用不同 AppID 的 App 是不能互通的。请务必保证生成 Token 使用的 AppID 和创建引擎时使用的 AppID 相同，否则会导致加入房间失败。 - **user_info** 类型: [UserInfo](85535#userinfo) 用户信息 - **config** 类型: [RTCRoomConfig](85535#rtcroomconfig) | undefined 房间参数配置，设置房间模式以及是否自动发布或订阅流。 - **返回值** 类型: number 方法调用结果。 - `0`: 调用成功。 - `-1`,`-2`,或 `-4`: 调用失败。查看 [ReturnStatus](85535#returnstatus) 获得错误说明。 ### leaveRoom 离开房间。 - **类型** ```ts () => number ``` - **注意** + 用户调用此方法离开房间，结束通话过程，释放所有通话相关的资源。 + 调用 [joinRoom](#joinroom) 方法加入房间后，必须调用此方法结束通话，否则无法开始下一次通话。无论当前是否在房间内，都可以调用此方法。重复调用此方法没有负面影响。 + 此方法是异步操作，调用返回时并没有真正退出房间。真正退出房间后，本地会收到 [`onLeaveRoom`](85533#onleaveroom) 回调通知。+ 调用 [`setUserVisibility`](#setuservisibility) 将自身设为可见的用户离开房间后，房间内其他用户会收到 [`onUserLeave`](85533#onuserleave) 回调通知。 + 如果调用此方法后立即销毁引擎，SDK 将无法触发 [`onLeaveRoom`](85533#onleaveroom) 回调。 - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### setUserVisibility 设置用户可见性。未调用该接口前，本地用户默认对他人可见。 - **类型** ```ts (enable: Boolean) => number ``` - **注意** + 在加入房间前后，用户均可调用此方法设置用户可见性。 + 默认情况下，一个 RTC 房间最多同时容纳 50 名可见用户，最多 30 人可同时上麦。更多信息参看[用户和媒体流上限](https://www.volcengine.com/docs/6348/257549)。 + 在房间内，调用此方法成功切换用户可见性后，房间内其他用户会收到相应的回调通知： - 从不可见换至可见时，房间内其他用户会收到 [onUserJoined](85533#onuserjoined)； - 从可见切换至不可见时，房间内其他用户会收到 [onLeaveRoom](85533#onleaveroom) 。 + 若调用该方法将可见性设为 false，此时尝试发布流会收到 `WARNING_CODE_PUBLISH_STREAM_FORBIDEN` 警告。 - **参数** - **enable** 类型: Boolean 设置用户是否对房间内其他用户可见： + true: 可以在房间内发布音视频流，房间中的其他用户将收到用户的行为通知，例如进房、开启视频采集和退房。 + false: 不可以在房间内发布音视频流，房间中的其他用户不会收到用户的行为通知，例如进房、开启视频采集和退房。 - **返回值** 类型: number + 0: 方法调用成功 + < 0: 方法调用失败 ### setMultiDeviceAVSync 设置发流端音画同步。 - **类型** ```ts (audio_user_id: string) => number ``` - **注意** + 当同一用户同时使用两个通话设备分别采集发送音频和视频时，有可能会因两个设备所处的网络环境不一致而导致发布的流不同步，此时你可以在视频发送端调用该接口，SDK 会根据音频流的时间戳自动校准视频流，以保证接收端听到音频和看到视频在时间上的同步性。 + 该方法在进房前后均可调用。 + 进行音画同步的音频发布用户 ID 和视频发布用户 ID 须在同一个 RTC 房间内。 + 调用该接口后音画同步状态发生改变时，你会收到 [onAVSyncStateChange](85533#onavsyncstatechange) 回调。 + 同一 RTC 房间内允许存在多个音视频同步关系，但需注意单个音频源不支持与多个视频源同时同步。 + 如需更换同步音频源，再次调用该接口传入新的 `audioUserId` 即可；如需更换同步视频源，需先解除当前的同步关系，后在新视频源端开启同步。 - **参数** - **audio_user_id** 类型: string 音频发送端的用户 ID，将该参数设为空则可解除当前音视频的同步关系。 - **返回值** 类型: number 方法调用结果： + 0：成功。 + !0：失败。查看 [ReturnStatus](85535#returnstatus) 获得错误说明。 ### updateToken 更新 Token。Token 中同时包含进房、发布和订阅权限，各权限有一定的有效期，并且到期前 30 秒会触发回调，提示用户更新 Token 相关权限。此时需要重新获取 Token，并调用此方法更新 Token，以保证通话的正常进行。 - **类型** ```ts (token: string) => number ``` - **参数** - **token** 类型: string 重新获取的有效 Token。如果传入的 Token 无效，回调错误码为 [ErrorCode](85534) 中的 `-1010` 提示传入的 Token 无效。 - **返回值** 类型: number ### setRemoteVideoConfig 设置期望订阅的远端视频流的参数。 - **类型** ```ts (user_id: string, remote_video_config: RemoteVideoConfig) => number ``` - **注意** + 若使用 1.5.0 及以前版本的 SDK，调用该方法前请联系技术支持人员开启按需订阅功能。 + 该方法仅在发布端调用 [enableSimulcastMode](#enablesimulcastmode) 开启了发送多路视频流的情况下生效，此时订阅端将收到来自发布端与期望设置的参数最相近的一路流；否则订阅端只会收到一路参数为分辨率 640px × 360px、帧率 15fps 的视频流。 + 若发布端开启了推送多路流功能，但订阅端不对流参数进行设置，则默认接受发送端设置的分辨率最大的一路视频流。 + 该方法需在进房后调用，若想进房前设置，你需调用 [joinRoom](#joinroom)，并对 `roomConfig` 中的 `remoteVideoConfig` 进行设置。 + SDK 会根据发布端和所有订阅端的设置灵活调整视频流的参数，具体调整策略详见[推送多路流](https://www.volcengine.com/docs/6348/70139)文档。 - **参数** - **user_id** 类型: string 期望配置订阅参数的远端视频流发布用户的 ID。 - **remote_video_config** 类型: [RemoteVideoConfig](85535#remotevideoconfig) 期望配置的远端视频流参数。 - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### publishStream 在当前所在房间内发布本地通过摄像头/麦克风采集的媒体流 - **类型** ```ts (type: MediaStreamType) => number ``` - **注意** + 如果你已经在用户进房时通过调用 [joinRoom](#joinroom) 成功选择了自动发布，则无需再调用本接口。 + 调用 [setUserVisibility](#setuservisibility) 方法将自身设置为不可见后无法调用该方法，需将自身切换至可见后方可调用该方法发布摄像头音视频流。 + 如果你需要发布屏幕共享流，调用 [publishScreen](#publishscreen)。 + 如果你需要向多个房间发布流，调用 [startForwardStreamToRooms](#startforwardstreamtorooms)。 + 调用此方法后，房间中的所有远端用户会收到 [onUserPublishStream](85533#onuserpublishstream) 回调通知，其中成功收到了音频流的远端用户会收到 [onFirstRemoteAudioFrame](85533#onfirstremoteaudioframe) 回调，订阅了视频流的远端用户会收到 [onFirstRemoteVideoFrameDecoded](85533#onfirstremotevideoframedecoded) 回调。 + 调用 [unpublishStream](#unpublishstream) 取消发布。 - **参数** - **type** 类型: [MediaStreamType](85535#mediastreamtype) 媒体流类型，用于指定发布音频/视频 - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### unpublishStream 停止将本地摄像头/麦克风采集的媒体流发布到当前所在房间中 - **类型** ```ts (type: MediaStreamType) => number ``` - **注意** + 调用 [publishStream](#publishstream) 手动发布摄像头音视频流后，你需调用此接口停止发布。 + 调用此方法停止发布音视频流后，房间中的其他用户将会收到 [onUserUnpublishStream](85533#onuserunpublishstream) 回调通知。 - **参数** - **type** 类型: [MediaStreamType](85535#mediastreamtype) 媒体流类型，用于指定停止发布音频/视频 - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### publishScreen 在当前所在房间内发布本地屏幕共享音视频流 - **类型** ```ts (type: MediaStreamType) => number ``` - **注意** + 即使你已经在用户进房时通过调用 [joinRoom](#joinroom) 成功选择了自动发布，也需要调用本接口发布屏幕流。 + 调用 [setUserVisibility](#setuservisibility) 方法将自身设置为不可见后无法调用该方法，需将自身切换至可见后方可调用该方法发布屏幕流。 + 调用该方法后，房间中的所有远端用户会收到 [onUserPublishScreen](85533#onuserpublishscreen) 回调，其中成功收到音频流的远端用户会收到 [onFirstRemoteAudioFrame](85533#onfirstremoteaudioframe) 回调，订阅了视频流的远端用户会收到 [onFirstRemoteVideoFrameDecoded](85533#onfirstremotevideoframedecoded) 回调。 + 调用该方法后，本端用户会收到 [onScreenVideoFrameSendStateChanged](85533#onscreenvideoframesendstatechanged) 回调。 + 如果你需要向多个房间发布流，调用 [startForwardStreamToRooms](#startforwardstreamtorooms)。 + 调用 [unpublishScreen](#unpublishscreen) 取消发布。 - **参数** - **type** 类型: [MediaStreamType](85535#mediastreamtype) 媒体流类型，用于指定发布屏幕音频/视频 - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### unpublishScreen 停止将本地屏幕共享音视频流发布到当前所在房间中 - **类型** ```ts (type: MediaStreamType) => number ``` - **注意** + 调用 [publishScreen](#publishscreen) 发布屏幕流后，你需调用此接口停止发布。 + 调用此方法停止发布屏幕音视频流后，房间中的其他用户将会收到 [onUserUnpublishScreen](85533#onuserunpublishscreen) 回调。 - **参数** - **type** 类型: [MediaStreamType](85535#mediastreamtype) 媒体流类型，用于指定停止发布屏幕音频/视频 - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### subscribeStream 订阅房间内指定的通过摄像头/麦克风采集的媒体流，或更新对指定远端用户的订阅选项 - **类型** ```ts (user_id: string, type: MediaStreamType) => number ``` - **注意** + 若当前用户在调用本接口时已经订阅该远端用户（手动订阅或自动订阅），则将根据本次传入的参数，更新订阅配置。 + 你必须先通过 [onUserPublishStream](85533#onuserpublishstream) 回调获取当前房间里的远端摄像头音视频流信息，然后调用本方法按需订阅。 + 调用该方法后，你会收到 [onStreamSubscribed](85533#onstreamsubscribed) 通知方法调用结果。 + 成功订阅远端用户的媒体流后，订阅关系将持续到调用 [unsubscribeStream](#unsubscribestream) 取消订阅或本端用户退房。 + 关于其他调用异常，你会收到 [onStreamStateChanged](85533#onstreamstatechanged) 回调通知，具体异常原因参看 [ErrorCode](85534#errorcode)。 - **参数** - **user_id** 类型: string 指定订阅的远端发布音视频流的用户 ID。 - **type** 类型: [MediaStreamType](85535#mediastreamtype) 媒体流类型，用于指定订阅音频/视频。 - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### unsubscribeStream 取消订阅房间内指定的通过摄像头/麦克风采集的媒体流。该方法对自动订阅和手动订阅模式均适用。 - **类型** ```ts (user_id: string, type: MediaStreamType) => number ``` - **注意** + 调用成功后，如果此时本端用户仍订阅了该远端用户的其他媒体流，将会触发 [onStreamSubscribed](85533#rtcroomcallback-onstreamsubscribed) 回调。否则不会收到此回调。比如，本端同时订阅了用户 A 的音频和视频流，通过本方法取消订阅 A 的视频流时，收到 [onStreamSubscribed](85533#rtcroomcallback-onstreamsubscribed) 回调。再次调用本方法，取消订阅 A 的音频流，则取消成功时不会收到该回调。 + 调用异常时，你会收到 [onStreamStateChanged](85533#rtcroomcallback-onstreamstatechanged) 回调通知，具体失败原因参看 [ErrorCode](85534#errorcode)。 - **参数** - **user_id** 类型: string 指定取消订阅的远端发布音视频流的用户 ID。 - **type** 类型: [MediaStreamType](85535#mediastreamtype) 媒体流类型，用于指定取消订阅音频/视频。 - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### subscribeAllStreams 订阅房间内所有通过摄像头/麦克风采集的媒体流，或更新订阅选项。 - **类型** ```ts (type: MediaStreamType) => number ``` - **注意** + 多次调用订阅接口时，将根据末次调用接口和传入的参数，更新订阅配置。 + 在控制台[开启音频选路](113547)后，如果房间内的媒体流超过上限，建议通过调用 [subscribeStream](#subscribestream) 逐一指定需要订阅的媒体流。 + 调用该方法后，你会收到 [onStreamSubscribed](85533#onstreamsubscribed) 通知方法调用结果。 + 成功订阅远端用户的媒体流后，订阅关系将持续到调用 [unsubscribeStream](#unsubscribestream) 取消订阅或本端用户退房。 + 关于其他调用异常，你会收到 onStreamStateChanged(85533#onstreamstatechanged) 回调通知，具体异常原因参看 [ErrorCode](85534)。 - **参数** - **type** 类型: [MediaStreamType](85535#mediastreamtype) 媒体流类型，用于指定订阅音频/视频。 - **返回值** 类型: number + 0：成功。 + <0：失败。查看 [ReturnStatus](85535#returnstatus) 获得错误说明。 ### unsubscribeAllStreams 取消订阅房间内所有的通过摄像头/麦克风采集的媒体流。 - **类型** ```ts (type: MediaStreamType) => number ``` - **注意** + 自动订阅和手动订阅的流都可以通过本方法取消订阅。 + 调用成功后，如果此时本端用户仍订阅了该远端用户的其他媒体流，将会触发 [onStreamSubscribed](85533#rtcroomcallback-onstreamsubscribed) 回调。否则不会收到此回调。比如，本端同时订阅了用户 A 的音频和视频流，通过本方法取消订阅 A 的视频流时，收到 [onStreamSubscribed](85533#rtcroomcallback-onstreamsubscribed) 回调。再次调用本方法，取消订阅 A 的音频流，则取消成功时不会收到该回调。 + 调用异常时，你会收到 [onStreamStateChanged](85533#rtcroomcallback-onstreamstatechanged) 回调通知，具体失败原因参看 [ErrorCode](85534#errorcode)。 - **参数** - **type** 类型: [MediaStreamType](85535#mediastreamtype) 媒体流类型，用于指定取消订阅音频/视频。 - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### subscribeScreen 订阅房间内指定的远端屏幕共享音视频流，或更新对指定远端用户的订阅选项 - **类型** ```ts (user_id: string, type: MediaStreamType) => number ``` - **注意** + 若当前用户在调用本接口时已经订阅该远端用户（手动订阅或自动订阅），则将根据本次传入的参数，更新订阅配置。 + 你必须先通过 [onUserPublishScreen](85533#onuserpublishscreen) 回调获取当前房间里的远端屏幕流信息，然后调用本方法按需订阅。 + 调用该方法后，你会收到 [onStreamSubscribed](85533#onstreamsubscribed) 通知流的订阅结果。 + 成功订阅远端用户的媒体流后，订阅关系将持续到调用 [unsubscribeScreen](#unsubscribescreen) 取消订阅或本端用户退房。 + 关于其他调用异常，你会收到 [onStreamStateChanged](85533#onstreamstatechanged) 回调通知，具体异常原因参看 [ErrorCode](85534#errorcode)。 - **参数** - **user_id** 类型: string 指定订阅的远端发布屏幕流的用户 ID。 - **type** 类型: [MediaStreamType](85535#mediastreamtype) 媒体流类型，用于指定订阅音频/视频。 - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### unsubscribeScreen 取消订阅房间内指定的远端屏幕共享音视频流。 - **类型** ```ts (user_id: string, type: MediaStreamType) => number ``` - **注意** + 该方法对自动订阅和手动订阅模式均适用。 + 调用成功后，如果此时本端用户仍订阅了该远端用户的其他媒体流，将会触发 [onStreamSubscribed](85533#rtcroomcallback-onstreamsubscribed) 回调。否则不会收到此回调。比如，本端同时订阅了用户 A 的音频和视频流，通过本方法取消订阅 A 的视频流时，收到 [onStreamSubscribed](85533#rtcroomcallback-onstreamsubscribed) 回调。再次调用本方法，取消订阅 A 的音频流，则取消成功时不会收到该回调。 + 调用异常时，你会收到 [onStreamStateChanged](85533#rtcroomcallback-onstreamstatechanged) 回调通知，具体失败原因参看 [ErrorCode](85534#errorcode)。 - **参数** - **user_id** 类型: string 指定取消订阅的远端发布屏幕流的用户 ID。 - **type** 类型: [MediaStreamType](85535#mediastreamtype) 媒体流类型，用于指定取消订阅音频/视频。 - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### pauseAllSubscribedStream 暂停接收来自远端的媒体流。 - **类型** ```ts (media_type: PauseResumeControlMediaType) => number ``` - **注意** + 该方法仅暂停远端流的接收，并不影响远端流的采集和发送； + 该方法不改变用户的订阅状态以及订阅流的属性。 + 若想恢复接收远端流，需调用 [resumeAllSubscribedStream](#resumeallsubscribedstream)。 + 多房间场景下，仅暂停接收发布在当前所在房间的流。 - **参数** - **media_type** 类型: [PauseResumeControlMediaType](85535#pauseresumecontrolmediatype) 媒体流类型，指定需要暂停接收音频还是视频流 - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### resumeAllSubscribedStream 恢复接收来自远端的媒体流 - **类型** ```ts (media_type: PauseResumeControlMediaType) => number ``` - **注意** + 该方法仅恢复远端流的接收，并不影响远端流的采集和发送； + 该方法不改变用户的订阅状态以及订阅流的属性。 - **参数** - **media_type** 类型: [PauseResumeControlMediaType](85535#pauseresumecontrolmediatype) 媒体流类型，指定需要恢复接收音频还是视频流 - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### sendUserMessage 给房间内指定的用户发送点对点文本消息 - **类型** ```ts (uid: string, message: string, config: MessageConfig) => number ``` - **注意** + 在发送房间内文本消息前，必须先调用 [joinRoom](#joinroom) 加入房间。 + 调用后，会收到 [onUserMessageSendResult](85533#onusermessagesendresult) 回调，通知消息发送成功或失败； + 若消息发送成功，则 userId 所指定的用户会收到 [onUserMessageReceived](85533#onusermessagereceived) 回调。 - **参数** - **uid** 类型: string 消息接收用户的 ID - **message** 类型: string 发送的文本消息内容消息不超过 64 KB。 - **config** 类型: [MessageConfig](85535#messageconfig) 消息发送的可靠/有序类型 - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### sendUserBinaryMessage 给房间内指定的用户发送点对点二进制消息。 - **类型** ```ts (uid: string, length: number, message: Uint8Array, config: MessageConfig) => number ``` - **注意** + 在发送房间内二进制消息前，必须先调用 [joinRoom](#joinroom) 加入房间。 + 调用后，会收到 [onUserMessageSendResult](85533#onusermessagesendresult) 回调，通知消息发送成功或失败； + 若消息发送成功，则 userId 所指定的用户会收到 [onUserBinaryMessageReceived](85533#onuserbinarymessagereceived) 回调。 - **参数** - **uid** 类型: string 消息接收用户的 ID - **length** 类型: number 二进制字符串的长度 - **message** 类型: Uint8Array 发送的二进制消息内容消息不超过 46KB。 - **config** 类型: [MessageConfig](85535#messageconfig) 消息类型 - **返回值** 类型: number + > `0`: 成功。这次发送消息的编号，从 1 开始递增。 + `-1`: 失败 ### sendRoomMessage 给房间内的所有其他用户群发文本消息。 - **类型** ```ts (message: string) => number ``` - **注意** + 在房间内广播文本消息前，必须先调用 [joinRoom](#joinroom) 加入房间。 + 调用后，会收到 [onRoomMessageSendResult](85533#onroommessagesendresult) 回调； + 同一房间内的其他用户会收到 [onRoomMessageReceived](85533#onroommessagereceived) 回调。 - **参数** - **message** 类型: string 发送的文本消息内容消息不超过 64 KB。 - **返回值** 类型: number + `0`: 成功。这次发送消息的编号，从 1 开始递增。 + `-1`: 失败 ### sendRoomBinaryMessage 给房间内的所有其他用户群发二进制消息。 - **类型** ```ts (size: number, message: Uint8Array) => number ``` - **注意** + 在房间内广播二进制消息前，必须先调用 [joinRoom](#joinroom) 加入房间。 + 调用后，会收到 [onRoomMessageSendResult](85533#onroommessagesendresult) 回调； + 同一房间内的其他用户会收到 [onRoomBinaryMessageReceived](85533#onroombinarymessagereceived) 回调。 - **参数** - **size** 类型: number 发送的二进制消息长度 - **message** 类型: Uint8Array 发送的二进制消息内容，消息不超过 46 KB。 - **返回值** 类型: number + `0`: 成功。这次发送消息的编号，从 1 开始递增。 + `-1`: 失败 ### startForwardStreamToRooms 开始跨房间转发媒体流。 - **类型** ```ts (configuration: ForwardStreamConfiguration) => number ``` - **注意** + 在调用 [joinRoom](#joinroom) 后，调用本接口，实现向多个房间转发媒体流，适用于跨房间连麦等场景。 + 调用本方法后，将在本端触发 [onForwardStreamStateChanged](85533#onforwardstreamstatechanged) 回调。 + 调用本方法后，你可以通过监听 [onForwardStreamEvent](85533#onforwardstreamevent) 回调来获取各个目标房间在转发媒体流过程中的相关事件。 + 开始转发后，目标房间中的用户将接收到本地用户进房 [onUserJoined](85533#onuserjoined) 和发流 [onUserPublishStream](85533#onuserpublishstream) / [onUserPublishScreen](85533#onuserpublishscreen) 的回调。 + 调用本方法后，可以调用 [updateForwardStreamToRooms](#updateforwardstreamtorooms) 更新目标房间信息，例如，增加或减少目标房间等。 + 调用本方法后，可以调用 [stopForwardStreamToRooms](#stopforwardstreamtorooms) 停止向所有房间转发媒体流。 + 调用本方法后，可以调用 [pauseForwardStreamToAllRooms](#pauseforwardstreamtoallrooms) 暂停向所有房间转发媒体流。 - **参数** - **configuration** 类型: [ForwardStreamConfiguration](85535#forwardstreamconfiguration) 跨房间媒体流转发指定房间的信息。 - **返回值** 类型: number + 0：成功。 + <0：失败。查看 [ReturnStatus](85535#returnstatus) 获得错误说明。 ### updateForwardStreamToRooms 更新跨房间媒体流转发信息。 - **类型** ```ts (configuration: ForwardStreamConfiguration) => number ``` - **注意** + 通过 [startForwardStreamToRooms](#startforwardstreamtorooms) 发起媒体流转发后，可调用本方法增加或者减少目标房间，或更新房间密钥。 + 调用本方法增加或删减房间后，将在本端触发 [onForwardStreamStateChanged](85533#onforwardstreamstatechanged) 回调，包含发生了变动的目标房间中媒体流转发状态。 + 增加目标房间后，新增目标房间中的用户将接收到本地用户进房 [onUserJoined](85533#onuserjoined) 和发布 [onUserPublishStream](85533#onuserpublishstream)/ [onUserPublishScreen](85533#onuserpublishscreen) 的回调。 + 删减目标房间后，原目标房间中的用户将接收到本地用户停止发布 [onUserUnpublishStream](85533#onuserunpublishstream) / [onUserUnpublishScreen](85533#onuserunpublishscreen) 和退房 [onUserLeave](85533#onuserleave) 的回调。 - **参数** - **configuration** 类型: [ForwardStreamConfiguration](85535#forwardstreamconfiguration) 跨房间媒体流转发目标房间信息。 - **返回值** 类型: number + 0：成功。 + <0：失败。查看 [ReturnStatus](85535#returnstatus) 获得错误说明。 ### stopForwardStreamToRooms 停止跨房间媒体流转发。 - **类型** ```ts () => number ``` - **注意** + 通过 [startForwardStreamToRooms](#startforwardstreamtorooms) 发起媒体流转发后，可调用本方法停止向所有目标房间转发媒体流。 + 调用本方法后，将在本端触发 [onForwardStreamStateChanged](85533#onforwardstreamstatechanged) 回调。 + 调用本方法后，原目标房间中的用户将接收到本地用户停止发布 [onUserUnpublishStream](85533#onuserunpublishstream) / [onUserUnpublishScreen](85533#onuserunpublishscreen) 和退房 [onUserLeave](85533#onuserleave) 的回调。 + 如果需要停止向指定的房间转发媒体流，请调用 [updateForwardStreamToRooms](#updateforwardstreamtorooms) 更新房间信息。 + 如果需要暂停转发，请调用 [pauseForwardStreamToAllRooms](#pauseforwardstreamtoallrooms)，并在之后随时调用 resumeForwardStreamToAllRooms(#resumeforwardstreamtoallrooms) 快速恢复转发。 - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### pauseForwardStreamToAllRooms 暂停跨房间媒体流转发。 - **类型** ```ts () => number ``` - **注意** + 通过 [startForwardStreamToRooms](#startforwardstreamtorooms) 发起媒体流转发后，可调用本方法暂停向所有目标房间转发媒体流。 + 调用本方法暂停向所有目标房间转发后，你可以随时调用 resumeForwardStreamToAllRooms(#resumeforwardstreamtoallrooms) 快速恢复转发。 + 调用本方法后，目标房间中的用户将接收到本地用户停止发布 [onUserUnpublishStream](85533#onuserunpublishstream)/[onUserUnpublishScreen](85533#onuserunpublishscreen) 和退房 [onUserLeave](85533#onuserleave) 的回调。 - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### resumeForwardStreamToAllRooms 恢复跨房间媒体流转发。 - **类型** ```ts () => number ``` - **注意** 目标房间中的用户将接收到本地用户进房 [onUserJoined](85533#onuserjoined) 和发布 [onUserPublishStream](85533#onuserpublishstream)/[onUserPublishScreen](85533#onuserpublishscreen) 的回调。 - **返回值** 类型: number + `0`: 成功 + `-1`: 失败调用 [pauseForwardStreamToAllRooms](#pauseforwardstreamtoallrooms) 暂停转发之后，调用本方法恢复向所有目标房间转发媒体流。 ### enableRangeAudio 开启/关闭范围语音功能。 - **类型** ```ts (enable: boolean) => number ``` - **注意** + 范围语音是指，在同一 RTC 房间中设定的音频接收距离范围内，本地用户收听到的远端用户音频音量会随着远端用户的靠近/远离而放大/衰减；若远端用户在房间内的位置超出设定范围，则本地用户无法接收其音频。音频接收范围设置参看 [updateReceiveRange](#updatereceiverange)。 + 如果开启区域语音，非队友之间在收发世界模式下语音会根据用户之间的距离衰减，超过收听范围就听不到，如果关闭区域语音，非队友之间在收发世界模式下，语音不会随距离衰减 + 该方法进房前后都可调用，为保证进房后范围语音效果的平滑切换，你需在该方法前先调用 [updateRangePosition](#updaterangeposition) 设置自身位置坐标，然后开启该方法收听范围语音效果。 - **参数** - **enable** 类型: boolean 是否开启范围语音功能： 1. true 表示开启， 2. （默认）false 表示关闭 - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### updateReceiveRange 更新本地用户的音频收听范围。 - **类型** ```ts (range: ReceiveRange) => number ``` - **参数** - **range** 类型: [ReceiveRange](85535#receiverange) 音频收听范围 - **返回值** 类型: number 方法调用结果： + `0`：成功； + `!0`: 失败。 ### updateRangePosition 更新本地用户在房间内空间直角坐标系中的位置坐标。 - **类型** ```ts (pos: Position) => number ``` - **注意** 调用该接口更新坐标后，你需调用 [enableRangeAudio](#enablerangeaudio) 开启范围语音功能以收听范围语音效果。 - **参数** - **pos** 类型: [Position](85535#position) 三维坐标的值，默认为 [0, 0, 0] - **返回值** 类型: number 方法调用结果： + 0：成功； + !0：失败。 ### setAttenuationModel 设置范围语音的音量衰减模式。 - **类型** ```ts (type: AttenuationType, coefficient: number) => number ``` - **注意** 音量衰减范围通过 [updateReceiveRange](#updatereceiverange) 进行设置。 - **参数** - **type** 类型: [AttenuationType](85535#attenuationtype) 音量衰减模式。默认为线性衰减。 - **coefficient** 类型: number 指数衰减模式下的音量衰减系数，默认值为 1。范围 [0.1,100]，推荐设置为 `50`。数值越大，音量的衰减速度越快。 - **返回值** 类型: number 调用是否成功 + `0`:调用成功 + `-1`:调用失败。原因为在调用 [enableRangeAudio](#enablerangeaudio) 开启范围语音前或进房前调用本接口 ### setNoAttenuationFlags 添加标签组，用于标记相互之间通话不衰减的用户组。在同一个 RTC 房间中，如果多个用户的标签组之间有交集，那么，他们之间互相通话时，通话不衰减。比如，用户身处多个队伍，队伍成员间通话不衰减。那么，可以为每个队伍绑定专属标签，每个用户的标签组包含用户所属各个队伍的标签。 - **类型** ```ts (flags?: string[]) => any ``` - **参数** - **flags** 类型: string[] 默认值: `' []'` 标签组 ### enableSpatialAudio 开启/关闭空间音频功能。 - **类型** ```ts (enable: boolean) => number ``` - **注意** 该方法仅开启空间音频功能，你须调用 [updateSpatialPosition](#updatespatialposition) 设置自身位置坐标后方可收听空间音频效果。空间音频相关 API 和调用时序详见[空间音频](https://www.volcengine.com/docs/6348/93903)。 - **参数** - **enable** 类型: boolean 是否开启空间音频功能： + true：开启 + false：关闭（默认） - **返回值** 类型: number 0：支持空间音频 -1:不支持 ### updateSpatialPosition 更新本地用户在房间内空间直角坐标系中的位置坐标。 - **类型** ```ts (pos: Position) => number ``` - **注意** 调用该接口更新坐标前，你需调用 [enableSpatialAudio](#enablespatialaudio) 开启空间音频功能。空间音频相关 API 和调用时序详见[空间音频](https://www.volcengine.com/docs/6348/93903)。 - **参数** - **pos** 类型: [Position](85535#position) 三维坐标的值，默认为 [0, 0, 0]。 - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### updateSelfOrientation 更新本地用户在空间音频坐标系下的朝向。 - **类型** ```ts (orientation: HumanOrientation) => number ``` - **注意** + 空间音频相关 API 和调用时序详见[空间音频](https://www.volcengine.com/docs/6348/93903)。 + 调用 [disableRemoteOrientation](#disableremoteorientation) 可忽略远端用户朝向。 - **参数** - **orientation** 类型: [HumanOrientation](85535#humanorientation) 自身朝向信息 - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### disableRemoteOrientation 参与通话的各端调用本接口后，将忽略远端用户的朝向，认为所有远端用户都面向本地用户。 - **类型** ```ts () => number ``` - **注意** + 如果此后调用 [updateSelfOrientation](#updateselforientation) 更新本地用户朝向，远端用户无法感知这些变化，但本地用户接收音频时可以感知自身朝向改变带来的音频效果变化。 + 进房前后都可以调用该接口。 + 调用本接口关闭朝向功能后，在当前的空间音频实例的生命周期内无法再次开启。 - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### updateListenerPosition 更新在房间内收听音频时的位置。通过此接口，你可以设定本地发声位置和收听位置不同。 - **类型** ```ts (pos: Position) => number ``` - **注意** + 调用此接口前，你需调用 [enableSpatialAudio](#enablespatialaudio) 开启空间音频功能。 + 空间音频相关 API 和调用时序详见[空间音频](https://www.volcengine.com/docs/6348/93903)。 - **参数** - **pos** 类型: [Position](85535#position) 空间直角坐标系下的坐标值。如果未调用此接口设定收听位置，那么默认值为通过 [updateSpatialPosition](#updatespatialposition) 设定的值。 - **返回值** 类型: number + `0`: 成功 + `!0`: 失败 ### updateListenerOrientation 更新在房间内收听音频时的朝向。通过此接口，你可以设定本地用户的发声朝向和收听朝向不同。 - **类型** ```ts (orientation: HumanOrientation) => number ``` - **注意** 空间音频相关 API 和调用时序详见[空间音频](https://www.volcengine.com/docs/6348/93903)。 - **参数** - **orientation** 类型: [HumanOrientation](85535#humanorientation) 自身朝向信息如果未调用此接口设定收听朝向，那么默认值为通过 [updateSelfOrientation](#updateselforientation) 设定的值。 - **返回值** 类型: number + `0`: 成功 + `!0`: 失败 ### setRemoteRoomAudioPlaybackVolume 调节某个房间内所有远端用户的音频播放音量。 - **类型** ```ts (volume: number) => number ``` - **注意** 如果某远端用户 A 始终在被调节的目标用户范围内， + 该方法与 [`setRemoteAudioPlaybackVolume`](#setremoteaudioplaybackvolume) 互斥，最新调用的任一方法设置的音量将覆盖此前已设置的音量，效果不叠加； + 当该方法与 [`setPlaybackVolume`](#setplaybackvolume) 方法共同使用时，本地收听用户 A 的音量将为两次设置的音量效果的叠加。 - **参数** - **volume** 类型: number 音频播放音量和原始音量的比值，范围是 [0, 400]，单位为 %，自带溢出保护。为保证更好的通话质量，建议将 volume 值设为 [0,100]。 + 0: 静音 + 100: 原始音量，默认值 + 400: 最大可为原始音量的 4 倍(自带溢出保护) - **返回值** 类型: number ### setAudioSelectionConfig 设置本端发布流在音频选路中的优先级。 - **类型** ```ts (audio_selection_priority: AudioSelectionPriority) => number ``` - **注意** + 在控制台上为本 appId 开启音频选路后，调用本接口才会生效。进房前后调用均可生效。更多信息参见[音频选路](https://www.volcengine.com/docs/6348/113547)。 + 如果本端用户同时加入不同房间，使用本接口进行的设置相互独立。 - **参数** - **audio_selection_priority** 类型: [AudioSelectionPriority](85535#audioselectionpriority) 本端发布流在音频选路中的优先级，默认正常参与音频选路。 - **返回值** 类型: number ### setRoomExtraInfo 设置/更新房间附加信息，可用于标识房间状态或属性，或灵活实现各种业务逻辑。 - **类型** ```ts (key: string, value: string) => any ``` - **注意** + 在设置房间附加信息前，必须先调用 [joinRoom](85532#rtcroom-joinroom) 加入房间。 + 调用该方法成功设置附加信息后，同一房间内的其他用户会收到关于该信息的回调 [onRoomExtraInfoUpdate](85533#rtcroomcallback-onroomextrainfoupdate)。 + 新进房的用户会收到进房前房间内已有的全部附加信息通知。 - **参数** - **key** 类型: string 房间附加信息键值，长度小于 10 字节。同一房间内最多可存在 5 个 key，超出则会从第一个 key 起进行替换。 - **value** 类型: string 房间附加信息内容，长度小于 128 字节。 - **返回值** + 0: 方法调用成功，返回本次调用的任务编号； + <0: 方法调用失败。你可以在 [onSetRoomExtraInfoResult](85533#rtcroomcallback-onsetroomextrainforesult) 回调中查看失败原因。调用该方法后，会收到一次上述回调。 ### startSubtitle 识别或翻译房间内所有用户的语音，形成字幕。 - **类型** ```ts (subtitle_config: SubtitleConfig) => number ``` - **注意** + 语音识别或翻译的结果会通过 [`onSubtitleMessageReceived`](85533#onsubtitlemessagereceived) 事件回调给你。 + 调用该方法后，你会收到 [`onSubtitleStateChanged`](85533#onsubtitlestatechanged) 回调，通知字幕是否开启。 + 此方法需要在进房后调用。 + 如需指定源语言，你需要在调用 `joinRoom` 接口进房时，通过 extraInfo 参数传入格式为`"语种英文名": "语种代号"` JSON 字符串，例如设置源语言为英文时，传入 `"source_language": "en"`。如未指定源语言，SDK 会将系统语种设定为源语言。如果你的系统语种不是中文、英文和日文，此时 SDK 会自动将中文设为源语言。 + 识别模式下，你可以传入 [RTC 控制台](https://console.volcengine.com/rtc/cloudRTC?tab=subtitle&from=doc)上预设或自定义的语种英文名和语种代号。识别模式下支持的语言参看[识别模式语种支持](https://www.volcengine.com/docs/6561/109880)。 + 翻译模式下，你需要传入机器翻译规定的语种英文名和语种代号。翻译模式下支持的语言及对应的代号参看[翻译模式语言支持](https://www.volcengine.com/docs/4640/35107)。 - **参数** - **subtitle_config** 类型: [SubtitleConfig](85535#subtitleconfig) 字幕配置信息。 - **返回值** 类型: number + `0`: 调用成功。 + `!0`: 调用失败。查看 [ReturnStatus](85535#returnstatus) 获得错误说明。 ### stopSubtitle 关闭字幕。调用该方法后，用户会收到 [onSubtitleStateChanged](85533#onsubtitlestatechanged) 回调，通知字幕是否关闭。 - **类型** ```ts () => number ``` - **返回值** 类型: number + `0`: 调用成功。 + `!0`: 调用失败。查看 [ReturnStatus](85535#returnstatus) 获得错误说明。 ### updateSelfPosition 设置本地用户在自建空间直角坐标系中的收听坐标和收听朝向，以实现本地用户预期的空间音频收听效果。 - **类型** ```ts (position_info: PositionInfo) => number ``` - **注意** 该方法需在进房后调用。调用该接口更新坐标前，你需调用 [enableSpatialAudio](#enablespatialaudio) 开启空间音频功能。空间音频相关 API 和调用时序详见[空间音频](https://www.volcengine.com/docs/6348/93903)。调用此接口在本地进行的设定对其他用户的空间音频收听效果不会产生任何影响。 - **参数** - **position_info** 类型: [PositionInfo](85535#positioninfo) 空间音频位置信息。 - **返回值** 类型: number + `0`：成功。 + `<0`：失败。 + `-2`: 失败，原因是校验本地用户的三维朝向信息时，三个向量没有两两垂直。 ### updateRemotePosition 设置房间内某一远端用户在本地用户自建的空间音频坐标系中的发声位置和发声朝向，以实现本地用户预期的空间音频收听效果。 - **类型** ```ts (uid: string, position_info: PositionInfo) => number ``` - **注意** 该方法需在创建房间后调用。调用此接口在本地进行的设定对其他用户的空间音频收听效果不会产生任何影响。 - **参数** - **uid** 类型: string 用户 ID - **position_info** 类型: [PositionInfo](85535#positioninfo) 远端用户的空间音频位置信息。 - **返回值** 类型: number + `0`：成功。 + `<0`：失败。 + `-2`: 失败，原因是校验远端用户的三维朝向信息时，三个向量没有两两垂直。 ### removeRemotePosition 移除调用 [updateRemotePosition](85532#updateremoteposition) 为某一远端用户设置的空间音频效果。 - **类型** ```ts (uid: string) => number ``` - **参数** - **uid** 类型: string 远端用户 ID。 - **返回值** 类型: number + `0`：成功。 + `<0`：失败。 ### removeAllRemotePosition 移除调用 [updateRemotePosition](85532#updateremoteposition) 为所有远端用户设置的空间音频效果。 - **类型** ```ts () => number ``` - **返回值** 类型: number + `0`：成功。 + `<0`：失败。 ## RTCAudioEffectPlayer 类型: `class` - **API** | 方法 | 描述 | | :-- | :-- | | [start](#rtcaudioeffectplayer-start) | 开始播放音效文件。
可以通过传入不同的 ID 和 filepath 多次调用本方法，以实现同时播放多个音效文件，实现音效叠加。 | | [stop](#rtcaudioeffectplayer-stop) | 停止播放音效文件。 | | [stopAll](#rtcaudioeffectplayer-stopall) | 停止播放所有音效文件。 | | [preload](#rtcaudioeffectplayer-preload) | 预加载指定音乐文件到内存中，以避免频繁播放同一文件时的重复加载，减少 CPU 占用。 | | [unload](#rtcaudioeffectplayer-unload) | 卸载指定音效文件。 | | [unloadAll](#rtcaudioeffectplayer-unloadall) | 卸载所有音效文件。 | | [pause](#rtcaudioeffectplayer-pause) | 暂停播放音效文件。 | | [pauseAll](#rtcaudioeffectplayer-pauseall) | 暂停播放所有音效文件。 | | [resume](#rtcaudioeffectplayer-resume) | 恢复播放音效文件。 | | [resumeAll](#rtcaudioeffectplayer-resumeall) | 恢复播放所有音效文件。 | | [setPosition](#rtcaudioeffectplayer-setposition) | 设置音效文件的起始播放位置。 | | [getPosition](#rtcaudioeffectplayer-getposition) | 获取音效文件播放进度。 | | [setVolume](#rtcaudioeffectplayer-setvolume) | 调节指定音效的音量大小，包括音效文件和 PCM 音频。 | | [setVolumeAll](#rtcaudioeffectplayer-setvolumeall) | 设置所有音效的音量大小，包括音效文件和 PCM 音效。 | | [getVolume](#rtcaudioeffectplayer-getvolume) | 获取当前音量。 | | [getDuration](#rtcaudioeffectplayer-getduration) | 获取音效文件时长。 | | [setEventHandler](#rtcaudioeffectplayer-seteventhandler) | 设置回调句柄。 | ### start 开始播放音效文件。可以通过传入不同的 ID 和 filepath 多次调用本方法，以实现同时播放多个音效文件，实现音效叠加。 - **类型** ```ts (effect_id: number, file_path: string, config: AudioEffectPlayerConfig) => number ``` - **注意** + 如果已经通过 [preload](85532#rtcaudioeffectplayer-preload) 将文件加载至内存，确保此处的 ID 与 [preload](85532#rtcaudioeffectplayer-preload) 设置的 ID 相同。 + 开始播放音效文件后，可以调用 [stop](85532#rtcaudioeffectplayer-stop) 方法停止播放音效文件。 - **参数** - **effect_id** 类型: number 音效 ID。用于标识音效，请保证音效 ID 唯一性。如果使用相同的 ID 重复调用本方法后，上一个音效会停止，下一个音效开始，并收到 [onAudioEffectPlayerStateChanged](85533#rtcaudioeffectplayercallback-onaudioeffectplayerstatechanged)。 - **file_path** 类型: string 音效文件路径。支持在线文件的 URL、本地文件的 URI、或本地文件的绝对路径。对于在线文件的 URL，仅支持 https 协议。推荐的音效文件采样率：8KHz、16KHz、22.05KHz、44.1KHz、48KHz。不同平台支持的本地音效文件格式:

	mp3	mp4	aac	m4a	3gp	wav	ogg	ts	wma
Android	Y	Y	Y	Y	Y	Y	Y
iOS/macOS	Y	Y	Y	Y	Y	Y
Windows	Y	Y	Y	Y	Y	Y		Y	Y

不同平台支持的在线音效文件格式:

	mp3	aac	m4a	3gp	wav	ts	wma
Android	Y	Y	Y	Y	Y
iOS/macOS	Y	Y	Y		Y
Windows	Y	Y	Y	Y	Y	Y	Y

- **config** 类型: [AudioEffectPlayerConfig](85535#audioeffectplayerconfig) 音效配置 - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### stop 停止播放音效文件。 - **类型** ```ts (effect_id: number) => number ``` - **注意** + 调用 [start](85532#rtcaudioeffectplayer-start) 方法开始播放音效文件后，可以调用本方法停止播放音效文件。 + 调用本方法停止播放音效文件后，该音效文件会被自动卸载。 - **参数** - **effect_id** 类型: number 音效 ID - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### stopAll 停止播放所有音效文件。 - **类型** ```ts () => number ``` - **注意** + 调用 [start](85532#rtcaudioeffectplayer-start) 方法开始播放音效文件后，可以调用本方法停止播放所有音效文件。 + 调用本方法停止播放所有音效文件后，该音效文件会被自动卸载。 - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### preload 预加载指定音乐文件到内存中，以避免频繁播放同一文件时的重复加载，减少 CPU 占用。 - **类型** ```ts (effect_id: number, file_path: string) => number ``` - **注意** + 本方法只是预加载指定音效文件，只有调用 [start](85532#rtcaudioeffectplayer-start) 方法才开始播放指定音效文件。 + 调用本方法预加载的指定音效文件可以通过 [unload](85532#rtcaudioeffectplayer-unload) 卸载。 - **参数** - **effect_id** 类型: number 音效 ID。用于标识音效，请保证音效 ID 唯一性。如果使用相同的 ID 重复调用本方法，后一次会覆盖前一次。如果先调用 [start](85532#rtcaudioeffectplayer-start)，再使用相同的 ID 调用本方法，会收到回调 [onAudioEffectPlayerStateChanged](85533#rtcaudioeffectplayercallback-onaudioeffectplayerstatechanged) ，通知前一个音效停止，然后加载下一个音效。调用本方法预加载 A.mp3 后，如果需要使用相同的 ID 调用 [start](85532#rtcaudioeffectplayer-start) 播放 B.mp3，请先调用 [unload](85532#rtcaudioeffectplayer-unload) 卸载 A.mp3 ，否则会报错 AUDIO_MIXING_ERROR_LOAD_CONFLICT。 - **file_path** 类型: string 音效文件路径。支持本地文件的 URI。预加载的文件长度不得超过 20s。不同平台支持的音效文件格式和 [start](85532#rtcaudioeffectplayer-start) 一致。 - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### unload 卸载指定音效文件。 - **类型** ```ts (effect_id: number) => number ``` - **注意** 仅在调用 [start](85532#rtcaudioeffectplayer-start) 或 [preload](85532#rtcaudioeffectplayer-preload) 后调用此接口。 - **参数** - **effect_id** 类型: number 音效 ID - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### unloadAll 卸载所有音效文件。 - **类型** ```ts () => number ``` - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### pause 暂停播放音效文件。 - **类型** ```ts (effect_id: number) => number ``` - **注意** + 调用 [start](85532#rtcaudioeffectplayer-start) 方法开始播放音效文件后，可以通过调用本方法暂停播放音效文件。 + 调用本方法暂停播放音效文件后，可调用 [resume](85532#rtcaudioeffectplayer-resume) 方法恢复播放。 - **参数** - **effect_id** 类型: number 音效 ID - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### pauseAll 暂停播放所有音效文件。 - **类型** ```ts () => number ``` - **注意** + 调用 [start](85532#rtcaudioeffectplayer-start) 方法开始播放音效文件后，可以通过调用本方法暂停播放所有音效文件。 + 调用本方法暂停播放所有音效文件后，可调用 [resumeAll](85532#rtcaudioeffectplayer-resumeall) 方法恢复所有播放。 - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### resume 恢复播放音效文件。 - **类型** ```ts (effect_id: number) => number ``` - **注意** 调用 [pause](85532#rtcaudioeffectplayer-pause) 方法暂停播放音效文件后，可以通过调用本方法恢复播放。 - **参数** - **effect_id** 类型: number 音效 ID - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### resumeAll 恢复播放所有音效文件。 - **类型** ```ts () => number ``` - **注意** 调用 [pauseAll](85532#rtcaudioeffectplayer-pauseall) 方法暂停所有正在播放音效文件后，可以通过调用本方法恢复播放。 - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### setPosition 设置音效文件的起始播放位置。 - **类型** ```ts (effect_id: number, pos: number) => number ``` - **注意** + 在播放在线文件时，调用此接口可能造成播放延迟的现象。 + 仅在调用 [start](85532#rtcaudioeffectplayer-start) 后调用此接口。 - **参数** - **effect_id** 类型: number 音效 ID - **pos** 类型: number 音效文件起始播放位置，单位为毫秒。你可以通过 [getDuration](85532#rtcaudioeffectplayer-getduration) 获取音效文件总时长，pos 的值应小于音效文件总时长。 - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### getPosition 获取音效文件播放进度。 - **类型** ```ts (effect_id: number) => number ``` - **注意** + 在播放在线文件时，调用此接口可能造成播放延迟的现象。 + 仅在调用 [start](85532#rtcaudioeffectplayer-start) 后调用此接口。 - **参数** - **effect_id** 类型: number 音效 ID - **返回值** 类型: number + >0: 成功, 音效文件播放进度，单位为毫秒。 + < 0: 失败 ### setVolume 调节指定音效的音量大小，包括音效文件和 PCM 音频。 - **类型** ```ts (effect_id: number, volume: number) => number ``` - **注意** 仅在调用 [start](85532#rtcaudioeffectplayer-start) 后调用此接口。 - **参数** - **effect_id** 类型: number 音效 ID - **volume** 类型: number 播放音量相对原音量的比值。单位为 %。范围为 `[0, 400]`，建议范围是 `[0, 100]`。带溢出保护。 - **返回值** 类型: number ### setVolumeAll 设置所有音效的音量大小，包括音效文件和 PCM 音效。 - **类型** ```ts (volume: number) => number ``` - **注意** 该接口的优先级低于 [setVolume](85532#rtcaudioeffectplayer-setvolume)，即通过 [setVolume](85532#rtcaudioeffectplayer-setvolume) 单独设置了音量的音效 ID，不受该接口设置的影响。 - **参数** - **volume** 类型: number 播放音量相对原音量的比值。单位为 %。范围为 `[0, 400]`，建议范围是 `[0, 100]`。带溢出保护。 - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### getVolume 获取当前音量。 - **类型** ```ts (effect_id: number) => number ``` - **注意** 仅在调用 [start](85532#rtcaudioeffectplayer-start) 后调用此接口。 - **参数** - **effect_id** 类型: number 音效 ID - **返回值** 类型: number + >0: 成功, 当前音量值。 + < 0: 失败 ### getDuration 获取音效文件时长。 - **类型** ```ts (effect_id: number) => number ``` - **注意** 仅在调用 [start](85532#rtcaudioeffectplayer-start) 后调用此接口。 - **参数** - **effect_id** 类型: number 音效 ID - **返回值** 类型: number + >0: 成功, 音效文件时长，单位为毫秒。 + < 0: 失败 ### setEventHandler 设置回调句柄。 - **类型** ```ts () => number ``` - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ## RTCMediaPlayer 类型: `class` - **API** | 方法 | 描述 | | :-- | :-- | | [open](#rtcmediaplayer-open) | 打开音乐文件。
一个播放器实例仅能够同时打开一个音乐文件。如果需要同时打开多个音乐文件，请创建多个音乐播放器实例。 | | [start](#rtcmediaplayer-start) | 播放音乐。你仅需要在调用 [open](85532#rtcmediaplayer-open)，且未开启自动播放时，调用此方法。 | | [stop](#rtcmediaplayer-stop) | 调用 [open](85532#rtcmediaplayer-open) 或 [start](85532#rtcmediaplayer-start) 开始播放后，可以调用本方法停止。 | | [pause](#rtcmediaplayer-pause) | 调用 [open](85532#rtcmediaplayer-open)，或 [start](85532#rtcmediaplayer-start) 开始播放音频文件后，调用本方法暂停播放。 | | [resume](#rtcmediaplayer-resume) | 调用 [pause](85532#rtcmediaplayer-pause) 暂停音频播放后，调用本方法恢复播放。 | | [setVolume](#rtcmediaplayer-setvolume) | 调节指定混音的音量大小，包括音乐文件混音和 PCM 混音。 | | [getVolume](#rtcmediaplayer-getvolume) | 获取当前音量 | | [getTotalDuration](#rtcmediaplayer-gettotalduration) | 获取音乐文件时长。 | | [getPlaybackDuration](#rtcmediaplayer-getplaybackduration) | 获取混音音乐文件的实际播放时长，单位为毫秒。 | | [getPosition](#rtcmediaplayer-getposition) | 获取音乐文件播放进度。 | | [setPosition](#rtcmediaplayer-setposition) | 设置音乐文件的起始播放位置。 | | [setAudioPitch](#rtcmediaplayer-setaudiopitch) | 开启变调功能，多用于 K 歌场景。 | | [setAudioDualMonoMode](#rtcmediaplayer-setaudiodualmonomode) | 设置当前音乐文件的声道模式 | | [getAudioTrackCount](#rtcmediaplayer-getaudiotrackcount) | 获取当前音乐文件的音轨数 | | [selectAudioTrack](#rtcmediaplayer-selectaudiotrack) | 指定当前音乐文件的播放音轨 | | [setPlaybackSpeed](#rtcmediaplayer-setplaybackspeed) | 设置播放速度 | | [setProgressInterval](#rtcmediaplayer-setprogressinterval) | 设置音频文件混音时，收到 [onMediaPlayerPlayingProgress](85533#rtcmediaplayercallback-onmediaplayerplayingprogress) 的间隔。 | | [setLoudness](#rtcmediaplayer-setloudness) | 如果你需要使用 [`enableVocalInstrumentBalance`](85532#rtcvideo-enablevocalinstrumentbalance) 对音频文件/PCM 音频数据设置音量均衡，你必须通过此接口传入其原始响度。 | | [setEventHandler](#rtcmediaplayer-seteventhandler) | 注册回调句柄以在本地音乐文件混音时，收到相关回调。 | | [openWithCustomSource](#rtcmediaplayer-openwithcustomsource) | 启动音频裸数据混音。 | | [pushExternalAudioFrame](#rtcmediaplayer-pushexternalaudioframe) | 推送用于混音的 PCM 音频帧数据 | ### open 打开音乐文件。一个播放器实例仅能够同时打开一个音乐文件。如果需要同时打开多个音乐文件，请创建多个音乐播放器实例。 - **类型** ```ts (file_path: string, config: MediaPlayerConfig) => number ``` - **参数** - **file_path** 类型: string 音乐文件路径。支持在线文件的 URL、本地文件的 URI、或本地文件的绝对路径。对于在线文件的 URL，仅支持 https 协议。推荐的采样率：8KHz、16KHz、22.05KHz、44.1KHz、48KHz。不同平台支持的本地文件格式:

	mp3	mp4	aac	m4a	3gp	wav	ogg	ts	wma
Android	Y	Y	Y	Y	Y	Y	Y
iOS/macOS	Y	Y	Y	Y	Y	Y
Windows	Y	Y	Y	Y	Y	Y		Y	Y

不同平台支持的在线文件格式:

	mp3	aac	m4a	3gp	wav	ts	wma
Android	Y	Y	Y	Y	Y
iOS/macOS	Y	Y	Y		Y
Windows	Y	Y	Y	Y	Y	Y	Y

- **config** 类型: [MediaPlayerConfig](85535#mediaplayerconfig) - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### start 播放音乐。你仅需要在调用 [open](85532#rtcmediaplayer-open)，且未开启自动播放时，调用此方法。 - **类型** ```ts () => number ``` - **注意** 调用本方法播放音频文件后，可调用 [`pause`](85532#rtcmediaplayer-pause) 方法暂停播放，或调用 [`stop`](85532#rtcmediaplayer-stop) 方法停止播放。 - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### stop 调用 [open](85532#rtcmediaplayer-open) 或 [start](85532#rtcmediaplayer-start) 开始播放后，可以调用本方法停止。 - **类型** ```ts () => number ``` - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### pause 调用 [open](85532#rtcmediaplayer-open)，或 [start](85532#rtcmediaplayer-start) 开始播放音频文件后，调用本方法暂停播放。 - **类型** ```ts () => number ``` - **注意** 调用本方法暂停播放后，可调用 [resume](85532#rtcmediaplayer-resume) 恢复播放。 - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### resume 调用 [pause](85532#rtcmediaplayer-pause) 暂停音频播放后，调用本方法恢复播放。 - **类型** ```ts () => number ``` - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### setVolume 调节指定混音的音量大小，包括音乐文件混音和 PCM 混音。 - **类型** ```ts (volume: number, type: AudioMixingType) => number ``` - **注意** 仅在音频播放进行状态时，调用此方法。 - **参数** - **volume** 类型: number 播放音量相对原音量的比值。单位为 %。范围为 `[0, 400]`，建议范围是 `[0, 100]`。带溢出保护。 - **type** 类型: [AudioMixingType](85535#audiomixingtype) - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### getVolume 获取当前音量 - **类型** ```ts (type: AudioMixingType) => number ``` - **注意** 仅在音频播放进行状态时，调用此方法。包括音乐文件混音和 PCM 混音。 - **参数** - **type** 类型: [AudioMixingType](85535#audiomixingtype) - **返回值** 类型: number + >0: 成功, 当前音量值。 + < 0: 失败 ### getTotalDuration 获取音乐文件时长。 - **类型** ```ts () => number ``` - **注意** + 仅在音频播放进行状态时，调用此方法。 + 此接口仅支持音频文件，不支持 PCM 数据。 - **返回值** 类型: number + >0: 成功, 音乐文件时长，单位为毫秒。 + < 0: 失败 ### getPlaybackDuration 获取混音音乐文件的实际播放时长，单位为毫秒。 - **类型** ```ts () => number ``` - **注意** + 实际播放时长指的是歌曲不受停止、跳转、倍速、卡顿影响的播放时长。例如，若歌曲正常播放到 1:30 时停止播放 30s 或跳转进度到 2:00, 随后继续正常播放 2分钟，则实际播放时长为 3分30秒。 + 仅在音频播放进行状态时，调用此方法。 + 此接口仅支持音频文件，不支持 PCM 数据。 - **返回值** 类型: number + >0: 实际播放时长。 + < 0: 失败。 ### getPosition 获取音乐文件播放进度。 - **类型** ```ts () => number ``` - **注意** + 仅在音频播放进行状态时，调用此方法。 + 此接口仅支持音频文件，不支持 PCM 数据。 - **返回值** 类型: number + >0: 成功, 音乐文件播放进度，单位为毫秒。 + < 0: 失败 ### setPosition 设置音乐文件的起始播放位置。 - **类型** ```ts (position: number) => number ``` - **注意** 在播放在线文件时，调用此接口可能造成播放延迟的现象。 - **参数** - **position** 类型: number 音乐文件起始播放位置，单位为毫秒。你可以通过 [getTotalDuration](85532#rtcmediaplayer-gettotalduration) 获取音乐文件总时长，position 的值应小于音乐文件总时长。 - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### setAudioPitch 开启变调功能，多用于 K 歌场景。 - **类型** ```ts (pitch: number) => number ``` - **注意** + 仅在音频播放进行状态时，调用此方法。 + 仅支持音乐文件混音，不支持 PCM 数据。 - **参数** - **pitch** 类型: number 与音乐文件原始音调相比的升高/降低值，取值范围为 `[-12，12]`，默认值为 0。每相邻两个值的音高距离相差半音，正值表示升调，负值表示降调。 - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### setAudioDualMonoMode 设置当前音乐文件的声道模式 - **类型** ```ts (mode: AudioMixingDualMonoMode) => number ``` - **注意** + 仅在音频播放进行状态时，调用此方法。 + 仅支持音频文件，不支持 PCM 数据。 - **参数** - **mode** 类型: [AudioMixingDualMonoMode](85535#audiomixingdualmonomode) 声道模式。默认的声道模式和源文件一致 - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### getAudioTrackCount 获取当前音乐文件的音轨数 - **类型** ```ts () => number ``` - **注意** + 仅在音频播放进行状态时，调用此方法。 + 此方法仅支持音乐文件，不支持 PCM 数据。 - **返回值** 类型: number + >= 0：成功，返回当前音乐文件的音轨数 + < 0：方法调用失败 ### selectAudioTrack 指定当前音乐文件的播放音轨 - **类型** ```ts (index: number) => number ``` - **注意** + 仅在音频播放进行状态时，调用此方法。 + 此方法仅支持音乐文件，不支持 PCM 数据。 - **参数** - **index** 类型: number 指定的播放音轨，从 0 开始，取值范围为 `[0, getAudioTrackCount()-1]`。设置的参数值需要小于 [getAudioTrackCount](85532#rtcmediaplayer-getaudiotrackcount) 的返回值 - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### setPlaybackSpeed 设置播放速度 - **类型** ```ts (speed: number) => number ``` - **注意** + 仅在音频播放进行状态时，调用此方法。 + 此方法对音频文件可用，不支持 PCM 数据。 - **参数** - **speed** 类型: number 播放速度与原始文件速度的比例，单位：%，取值范围为 `[50,200]`，默认值为 100。 - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### setProgressInterval 设置音频文件混音时，收到 [onMediaPlayerPlayingProgress](85533#rtcmediaplayercallback-onmediaplayerplayingprogress) 的间隔。 - **类型** ```ts (interval: string) => number ``` - **注意** + 仅在音频播放进行状态时，调用此方法。 + 此方法仅支持音频文件，不支持 PCM 数据。 - **参数** - **interval** 类型: string 时间间隔，单位毫秒。 + interval > 0 时，触发回调。实际间隔为 10 的倍数。如果输入数值不能被 10 整除，将自动向上取整。例如传入 `52`，实际间隔为 60 ms。 + interval <= 0 时，不会触发回调。 - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### setLoudness 如果你需要使用 [`enableVocalInstrumentBalance`](85532#rtcvideo-enablevocalinstrumentbalance) 对音频文件/PCM 音频数据设置音量均衡，你必须通过此接口传入其原始响度。 - **类型** ```ts (loudness: number) => number ``` - **注意** + 仅在音频播放进行状态时，调用此方法。 + 此方法对音频文件和音频裸数据播放都可用。 - **参数** - **loudness** 类型: number 原始响度，单位：lufs，取值范围为 `[-70.0, 0.0]`。当设置的值小于 -70.0lufs 时，则默认调整为 -70.0lufs，大于 0.0lufs 时，则不对该响度做音量均衡处理。默认值为 1.0lufs，即不做处理。 - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### setEventHandler 注册回调句柄以在本地音乐文件混音时，收到相关回调。 - **类型** ```ts () => number ``` - **注意** 触发回调 [onMediaPlayerStateChanged](85533#rtcmediaplayercallback-onmediaplayerstatechanged) 和 [onMediaPlayerPlayingProgress](85533#rtcmediaplayercallback-onmediaplayerplayingprogress)。 - **返回值** 类型: number + `0`: 成功 + `-1`: 失败 ### openWithCustomSource 启动音频裸数据混音。 - **类型** ```ts (source: MediaPlayerCustomSource, config: MediaPlayerConfig) => number ``` - **注意** + 要播放音乐文件，参看 [`open`](85532#rtcmediaplayer-open)。`open` 与此 API 互斥。 + 调用本方法启动后，再调用 [`pushExternalAudioFrame`](85532#rtcvideo-pushexternalaudioframe) 推送音频数据，才会开始混音。 + 如要结束 PCM 音频数据混音，调用 [`stop`](85532#rtcmediaplayer-stop)。 - **参数** - **source** 类型: [MediaPlayerCustomSource](85535#mediaplayercustomsource) 数据源 - **config** 类型: [MediaPlayerConfig](85535#mediaplayerconfig) 配置 - **返回值** 类型: number + 0: 调用成功。 + < 0 : 调用失败。 ### pushExternalAudioFrame 推送用于混音的 PCM 音频帧数据 - **类型** ```ts (frame: ExternalAudioFrame) => any ``` - **注意** + 调用该方法前，须通过 [`openWithCustomSource`](85532#rtcmediaplayer-openwithcustomsource) 启动外部音频流混音。 + 使用参考建议：首次推送数据，请在应用侧先缓存一定数据（如 200 毫秒），然后一次性推送过去；此后的推送操作定时 10 毫秒一次，并且每次的音频数据量为 10 毫秒数据量。 + 如果要暂停播放，暂停推送即可。 - **参数** - **audio_frame** 类型: [ExternalAudioFrame](85535#externalaudioframe) 音频帧 - **返回值** + 0: 成功 + < 0: 失败

云数据库 MySQL 版