文档中心
极速直播 (Legacy)
Console 官网 社区 技术支持
简体中文
search-icon

Agora Web API Reference

概览 AgoraRTC Client Stream Error Codes Warning Codes

Stream 接口提供的方法用于定义音视频流对象的行为，例如流的播放控制、音视频的编码配置等。

你可以通过 createStream 创建 Stream 对象。一个 Stream 对象指通话中发布的本地音视频流或订阅的远端音视频流。

Stream 方法如无特别说明，本地和远端音视频流均可调用。

Hierarchy

  • Stream

Index

Methods

Methods

addTrack

  • 添加音视频轨道

    该方法将音视频轨道添加到 Stream。添加成功后，远端会触发 Client.on("stream-updated") 回调。

    example

    示例代码

    var localStream = AgoraRTC.createStream({audio: true, video: false});
localStream.addTrack(anotherStream.getVideoTrack());

    Note

    • 该方法不支持 Firefox 和 Safari。
    • 一个 Stream 对象最多只能包含一个音频轨道和一个视频轨道。

    Parameters

    • track: MediaStreamTrack

      可以通过 mediaStream 方法获取音视频轨道。

    Returns void

adjustAudioMixingVolume

  • adjustAudioMixingVolume(level: number): void

  • 调节音乐文件音量

    Parameters

    • level: number

      音乐文件音量范围为 [0,100]。默认 100 为原始文件音量。

    Returns void

close

  • close(): void

  • 关闭音视频流

    该方法关闭当前的流。调用该方法会取消摄像头和麦克风的访问权限。

    Returns void

disableAudio

  • disableAudio(): boolean

  • 禁用音频轨道

    DEPRECATED

    自 2.5.1 起废弃，请使用 muteAudio。

    该方法禁用音频轨道。在 createStream 时将 audio 设置为 true 才可使用该方法。

    Returns boolean

    • true：禁用音频轨道成功。
    • false：禁用音频轨道失败，可能的原因包括没有音频、流未初始化、音频轨道已经禁用等。

disableVideo

  • disableVideo(): boolean

  • 禁用视频轨道

    DEPRECATED

    自 2.5.1 起废弃，请使用 muteVideo。

    该方法禁用视频轨道。在 createStream 时将 video 设置为 true 才可使用该方法。

    Returns boolean

    • true：禁用视频轨道成功。
    • false：禁用视频轨道失败，可能的原因包括没有视频、流未初始化、视频轨道已经禁用等。

enableAudio

  • enableAudio(): boolean

  • 启用音频轨道

    DEPRECATED

    自 2.5.1 起废弃，请使用 unmuteAudio。

    该方法启用音频轨道。在 createStream 时将 audio 设置为 true 才可使用该方法。

    音频轨道默认为开启状态。如果你调用了 disableAudio，可调用本方法启用音频。

    Returns boolean

    • true：启用音频轨道成功。
    • false：启用音频轨道失败，可能的原因包括没有音频、流未初始化、音频轨道已经启用等。

enableVideo

  • enableVideo(): boolean

  • 启用视频轨道

    DEPRECATED

    自 2.5.1 起废弃，请使用 unmuteVideo。

    该方法启用视频轨道。在 createStream 时将 video 设置为 true 才可使用该方法。

    视频轨道默认为开启状态。如果你调用了 disableVideo，可调用本方法启用视频。

    Returns boolean

    • true：启用视频轨道成功。
    • false：启用视频轨道失败，可能的原因包括没有视频、流未初始化、视频轨道已经启用等。

getAudioLevel

  • getAudioLevel(): number | undefined

  • 获取当前音量

    该方法获取的是当前时刻的音量。如果你想表示本地或远端音量的变化，我们建议你使用 setTimeout 或者 setInterval 方法实时获取。

    example

    示例代码

    setInterval(function() {
  var audioLevel = stream.getAudioLevel();
  // Use audioLevel to render the UI
}, 100)

    该方法对没有音频数据的流是无效的，并且会产生警告。

    Note

    受浏览器策略影响，在 Chrome 70+ 和 Safari 浏览器上，该方法必须由用户手势触发，详见处理浏览器的自动播放策略。

    Returns number | undefined

    获取的音量值，取值范围 [0,1]。

getAudioMixingCurrentPosition

  • getAudioMixingCurrentPosition(): number | void

  • 获取音乐文件播放进度

    该方法获取音乐文件播放进度，单位为 ms。

    Returns number | void

    方法调用成功返回音乐文件播放进度。

getAudioMixingDuration

  • getAudioMixingDuration(): number | void

  • 获取音乐文件时长

    Returns number | void

    方法调用成功返回音乐文件时长（ms）。

getAudioTrack

  • 获取音频轨道

    该方法获取音视频流中的音频轨道，可与 replaceTrack 搭配使用。

    Returns MediaStreamTrack | undefined

    如果音视频流中包含音频轨道，会以 MediaStreamTrack 对象返回。

getEffectsVolume

  • getEffectsVolume(): Array<object>

  • 获取所有音效文件播放音量

    example

    示例代码

    var volumes = stream.getEffectsVolume();
volumes.forEach(function({soundId, volume}){
    console.log("SoundId", soundId, "Volume", volume);
});

    Returns Array<object>

    返回一个包含 soundId 和 volume 的数组。每个 soundId 对应一个 volume。

    • soundId 为音效的 ID，正整数，取值范围为 [1,10000]。
    • volume 为音量值，整数，范围为 [0,100]。

getId

  • getId(): number | string

  • 获取音视频流 ID

    该方法可以获取音视频流 ID。

    example

    stream.getId()

    Returns number | string

getStats

  • getStats(callback: function): void

  • 获取连接数据

    该方法获取音视频流的连接数据。

    Note

    部分统计数据可能存在延时。

    example

    示例代码

    localStream.getStats((stats) => {
    console.log(`Local Stream accessDelay: ${stats.accessDelay}`);
    console.log(`Local Stream audioSendBytes: ${stats.audioSendBytes}`);
    console.log(`Local Stream audioSendPackets: ${stats.audioSendPackets}`);
    console.log(`Local Stream audioSendPacketsLost: ${stats.audioSendPacketsLost}`);
    console.log(`Local Stream videoSendBytes: ${stats.videoSendBytes}`);
    console.log(`Local Stream videoSendFrameRate: ${stats.videoSendFrameRate}`);
    console.log(`Local Stream videoSendPackets: ${stats.videoSendPackets}`);
    console.log(`Local Stream videoSendPacketsLost: ${stats.videoSendPacketsLost}`);
    console.log(`Local Stream videoSendResolutionHeight: ${stats.videoSendResolutionHeight}`);
    console.log(`Local Stream videoSendResolutionWidth: ${stats.videoSendResolutionWidth}`);
});


remoteStream.getStats((stats) => {
    console.log(`Remote Stream accessDelay: ${stats.accessDelay}`);
    console.log(`Remote Stream audioReceiveBytes: ${stats.audioReceiveBytes}`);
    console.log(`Remote Stream audioReceiveDelay: ${stats.audioReceiveDelay}`);
    console.log(`Remote Stream audioReceivePackets: ${stats.audioReceivePackets}`);
    console.log(`Remote Stream audioReceivePacketsLost: ${stats.audioReceivePacketsLost}`);
    console.log(`Remote Stream endToEndDelay: ${stats.endToEndDelay}`);
    console.log(`Remote Stream videoReceiveBytes: ${stats.videoReceiveBytes}`);
    console.log(`Remote Stream videoReceiveDecodeFrameRate: ${stats.videoReceiveDecodeFrameRate}`);
    console.log(`Remote Stream videoReceiveDelay: ${stats.videoReceiveDelay}`);
    console.log(`Remote Stream videoReceiveFrameRate: ${stats.videoReceiveFrameRate}`);
    console.log(`Remote Stream videoReceivePackets: ${stats.videoReceivePackets}`);
    console.log(`Remote Stream videoReceivePacketsLost: ${stats.videoReceivePacketsLost}`);
    console.log(`Remote Stream videoReceiveResolutionHeight: ${stats.videoReceiveResolutionHeight}`);
    console.log(`Remote Stream videoReceiveResolutionWidth: ${stats.videoReceiveResolutionWidth}`);
});

    Parameters

    Returns void

getVideoTrack

  • 获取视频轨道

    该方法获取音视频流中的视频轨道，可与 replaceTrack 搭配使用。

    Returns MediaStreamTrack | undefined

    如果音视频流中包含视频轨道，会以 MediaStreamTrack 对象返回。

hasAudio

  • hasAudio(): boolean

  • 获取音频 flag

    该方法仅对本地流有效。

    Returns boolean

    • true: 该音视频流对象中包含音频资源。
    • false: 该音视频流对象中不包含音频资源。

hasVideo

  • hasVideo(): boolean

  • 获取视频 flag

    该方法仅对本地流有效。

    Returns boolean

    • true: 该音视频流对象中包含视频资源。
    • false: 该音视频流对象中不包含视频资源。

init

  • init(onSuccess?: function, onFailure?: function): void

  • 初始化音视频对象

    该方法初始化本地创建的音视频流对象。

    如果调用失败，错误信息请参考 getUserMedia 异常。

    部分错误信息可能会在调用失败的回调函数中出现，例如：{type: "error", msg: "NotAllowedError", info: "Permission denied"}。

    msg 字段可能出现以下值：

    • NotAllowedError: 用户拒绝授予对应的摄像头或麦克风权限。
    • MEDIA_OPTION_INVALID: 摄像头被占用或者分辨率不支持（早期浏览器）
    • DEVICES_NOT_FOUND: 没有找到设备
    • NOT_SUPPORTED: 浏览器不支持获取获取摄像头和麦克风
    • PERMISSION_DENIED: 浏览器禁用设备或者用户拒绝打开设备
    • CONSTRAINT_NOT_SATISFIED: 配置参数不合法（早期浏览器）
    • PluginNotInstalledProperly: 用户尝试在 Chrome 上进行屏幕共享，但未安装屏幕共享插件，或使用了错误的 extensionId
    • UNDEFINED: 未定义错误
    example

    示例代码

    init(function() {
    console.log("local stream initialized");
    // publish the stream
    //……
}, function(err) {
    console.error("local stream init failed ", err);
    //error handling
});

    Parameters

    • Optional onSuccess: function

      方法调用成功时执行的回调函数

        • (): void

        • Returns void

    • Optional onFailure: function

      方法调用失败时执行的回调函数

        • (err: object): void

        • Parameters

          • err: object
            • Optional info?: string
            • msg: string
            • type: "warning" | "error"

          Returns void

    Returns void

isPlaying

  • isPlaying(): boolean

  • 返回音视频流当前是否在播放状态

    Returns boolean

    • true：该音视频流正在渲染或播放。
    • false：该音视频流没有渲染。

muteAudio

  • muteAudio(): boolean

  • 禁用音频轨道

    该方法禁用音频轨道。

    • 对于本地流，调用该方法会停止发送音频，远端会触发 Client.on("mute-audio") 回调。
    • 对于远端流，调用该方法仍然会接收音频，但是会停止播放。

    Note

    对于本地流，在 createStream 时将 audio 设置为 true 才可使用该方法。

    Returns boolean

    • true：禁用音频轨道成功。
    • false：禁用音频轨道失败，可能的原因包括没有音频、流未初始化、音频轨道已经禁用等。

muteVideo

  • muteVideo(): boolean

  • 禁用视频轨道

    该方法禁用视频轨道。

    • 对于本地流，调用该方法会停止发送视频，远端会触发 Client.on("mute-video") 回调。
    • 对于远端流，调用该方法仍然会接收视频，但是会停止播放。

    Note

    对于本地创建的流，在 createStream 时将 video 设置为 true 才可使用该方法。

    Returns boolean

    • true：禁用视频轨道成功。
    • false：禁用视频轨道失败，可能的原因包括没有视频、流未初始化、视频轨道已经禁用等。

on

  • on(event: "accessAllowed", callback: function): void
  • on(event: "accessDenied", callback: function): void
  • on(event: "stopScreenSharing", callback: function): void
  • on(event: "videoTrackEnded", callback: function): void
  • on(event: "audioTrackEnded", callback: function): void
  • on(event: "audioMixingPlayed", callback: function): void
  • on(event: "audioMixingFinished", callback: function): void
  • on(event: "player-status-change", callback: function): void

  • 该回调通知应用已获取本地摄像头／麦克风使用权限。

    Parameters

    • event: "accessAllowed"
    • callback: function
        • (evt: any): void

        • Parameters

          • evt: any

          Returns void

    Returns void

  • 该回调通知应用已禁止本地摄像头／麦克风使用权限。

    Parameters

    • event: "accessDenied"
    • callback: function
        • (evt: any): void

        • Parameters

          • evt: any

          Returns void

    Returns void

  • 该回调通知应用屏幕共享已停止。

    Parameters

    • event: "stopScreenSharing"
    • callback: function
        • (evt: any): void

        • Parameters

          • evt: any

          Returns void

    Returns void

  • 该回调通知视频轨道已停止。

    停止的原因可能是设备拔出、取消授权等。详见 Media​Stream​Track​.onended。

    Parameters

    • event: "videoTrackEnded"
    • callback: function
        • (evt: any): void

        • Parameters

          • evt: any

          Returns void

    Returns void

  • 该回调通知音频轨道已停止。

    停止的原因可能是设备拔出、取消授权等。详见 Media​Stream​Track​.onended。

    Parameters

    • event: "audioTrackEnded"
    • callback: function
        • (evt: any): void

        • Parameters

          • evt: any

          Returns void

    Returns void

  • 该回调通知混音音乐文件播放已开始。

    Note

    该事件会在音乐文件加载完成并开始播放以及音乐文件暂停后恢复播放这两种情况下被触发。

    Parameters

    • event: "audioMixingPlayed"
    • callback: function
        • (evt: any): void

        • Parameters

          • evt: any

          Returns void

    Returns void

  • 该回调通知混音音乐文件播放完毕。

    Parameters

    • event: "audioMixingFinished"
    • callback: function
        • (evt: any): void

        • Parameters

          • evt: any

          Returns void

    Returns void

  • 该回调通知音视频播放状态变化。

    在 Windows 上，频繁的 DOM 操作可能会导致 Chrome 播放器被浏览器暂停。为了避免这种情况，需要侦听该回调，并尝试调用 Stream.resume 恢复播放。

    该回调有以下属性。

    • isErrorState: 播放状态是否出错
      • true: 播放状态出错
      • false: 播放状态正常
    • mediaType: 播放器类型
      • "audio": 音频播放器
      • "video": 视频播放器
    • status: 播放状态
      • "play": 正常播放
      • "aborted": 播放器在开始播放之前就被移除
      • "paused": 播放器处于停止状态
    • reason: 播放状态改变的原因。该值一般为触发播放失败的事件名。常见的的取值为：
      • "playing": 开始播放。详见 HTMLMedia​Element: playing event。
      • "stalled": 可能与浏览器播放策略相关。详见 stalled event。
      • "pause": 可能由于用户点按了暂停键。详见 pause event。
      • "suspend": 可能与浏览器播放策略相关。详见 suspend event。
      • "canplay": 某些浏览器会自动停止被遮挡的播放器播放。详见 canplay event。
      • "timer": 未知原因触发播放失败，播放失败由内置定时器捕获。
    example

    示例代码

     stream.on("player-status-change", function(evt){
     if (evt.isErrorState && evt.status === "paused"){
         console.error(`Stream is paused unexpectedly. Trying to resume...`);
         stream.resume().then(function(){
             console.log(`Stream is resumed successfully`);
         }).catch(function(e){
             console.error(`Failed to resume stream. Error ${e.name} Reason ${e.message}`);
         });
     }
 });

    Parameters

    • event: "player-status-change"
    • callback: function
        • (evt: any): void

        • Parameters

          • evt: any

          Returns void

    Returns void

pauseAllEffects

  • pauseAllEffects(callback?: function): void

  • 暂停播放所有音效文件

    example

    示例代码

    stream.pauseAllEffects(function(err){
    if (err){
        console.error("Failed to pause effects, reason: ", err);
    }else{
        console.log("Effects are paused successfully");
    }
});

    Parameters

    • Optional callback: function
        • (err: string | null): void

        • Parameters

          • err: string | null

          Returns void

    Returns void

pauseAudioMixing

  • pauseAudioMixing(callback?: function): void

  • 暂停播放音乐文件

    Parameters

    • Optional callback: function
        • (err: string | null): void

        • Parameters

          • err: string | null

          Returns void

    Returns void

pauseEffect

  • pauseEffect(soundId: number, callback?: function): void

  • 暂停播放指定音效文件

    example

    示例代码

    // 在音效1播放时
stream.pauseEffect(1, function(err){
    if (err){
        console.error("Failed to pause Effect, reason: ", err);
    }else{
        console.log("Effect is paused successfully");
    }
});

    Parameters

    • soundId: number

      指定音效的 ID。每个音效均有唯一的 ID。正整数，取值范围为 [1,10000]。

    • Optional callback: function
        • (err: string | null): void

        • Parameters

          • err: string | null

          Returns void

    Returns void

play

  • play(HTMLElementID: string, option?: object, callback?: function): void

  • 播放音视频流

    该方法播放视频流或音频流。

    Note

    受浏览器策略影响，在 Chrome 70+ 和 Safari 浏览器上，该方法必须由用户手势触发，详见处理浏览器的自动播放策略。

    example

    示例代码

    stream.play("agora_remote", {fit: "contain"}, function(errState){
    if (errState && errState.status !== "aborted"){
        // 播放失败，一般为浏览器策略阻止。引导用户用手势触发恢复播放。
    }
}); // stream will be played in the element with the ID agora_remote

    Parameters

    • HTMLElementID: string

      HTML element ID。ASCII 字符集中的字母和数字，以及 “_”、“-"、"."，字符串长度大于 0 小于 256 字节。

    • Optional option: object

      用于流播放的选项

      • Optional fit?: "cover" | "contain"

        设置视频播放时的显示模式，有 "cover" 和 "contain" 可以选择：

        • cover 模式：优先保证视窗被填满。视频尺寸等比缩放，直至整个视窗被视频填满。如果视频长宽与显示窗口不同，则视频流会按照显示视窗的比例进行周边裁剪或图像拉伸后填满视窗。可以参考 CSS 属性中 object-fit 的 cover 选项。
        • contain 模式：优先保证视频内容全部显示。视频尺寸等比缩放，直至视频窗口的一边与视窗边框对齐。如果视频尺寸与显示视窗尺寸不一致，在保持长宽比的前提下，将视频进行缩放后填满视窗，缩放后的视频四周会有一圈黑边。可以参考 CSS 属性中 object-fit 的 contain 选项。

        对于本地流来说，播放视频流默认使用 cover 模式，屏幕共享默认使用 contain 模式；对于远端流来说，因为不知道流的类型，默认使用 cover 模式。

      • Optional muted?: boolean

        设置播放的流是否静音

        muted 通常用于规避浏览器的自动播放策略。

        一般情况下，播放带声音的视频时，浏览器会要求该行为由手势触发。 如果你不希望以手势触发，也可以选择将 muted 设为 true，这样可以绕过自动播放策略，详见处理浏览器的自动播放策略。

    • Optional callback: function

      播放是否成功的回调

      • err
        • 如果播放成功该参数为 null
        • 如果播放失败可以通过 StreamPlayError 了解可能的原因

    Returns void

playEffect

  • playEffect(options: object, callback?: function): void

  • 播放指定音效文件

    与 startAudioMixing 方法的区别是，该方法更适合播放较小的音效文件，且支持同时播放多个音效。

    Note

    • 受浏览器策略影响，在 Chrome 70 及以上和 Safari 浏览器上，该方法必须由用户手势触发，详见处理浏览器的自动播放策略。
    • 该方法支持以下浏览器：
      • Safari 12 及以上
      • Chrome 65 及以上
      • 最新版 Firefox
    • 请在频道内调用该方法，如果在频道外调用该方法可能会出现问题。
    example

    示例代码

    stream.playEffect({
     soundId: 1,
    filePath: "biu.mp3"
}, function(error) {
    if (error) {
        // 错误处理
        return;
    }
    // 播放成功后的流程
});

    Parameters

    • options: object

      音效设置。

      • Optional cycle?: number

        指定音效文件循环播放的次数

        Note

        仅支持 Chrome 65 及以上。

        正整数，取值范围为 [1,10000]。默认值为 1，即播放 1 次。

      • filePath: string

        指定在线音效文件的绝对路径。

        ASCII 字符，字符串长度大于 0 小于 256 字节。

        支持以下音频格式：MP3，AAC 以及浏览器支持的其他音频格式。

      • soundId: number

        指定音效的 ID。每个音效均有唯一的 ID。

        正整数，取值范围为 [1,10000]。如果你已通过 preloadEffect 将音效加载至内存，确保这里的 soundID 与 preloadEffect 设置的 soundID 相同。

    • Optional callback: function

      方法的回调：

      • null：方法调用成功
      • err：方法调用失败

      Note

      音效播放的其他方法的回调参数与此相同，使用 Node.js 回调风格。

        • (err: string | null): void

        • Parameters

          • err: string | null

          Returns void

    Returns void

preloadEffect

  • preloadEffect(soundId: number, filePath: string, callback?: function): void

  • 预加载指定音效文件

    该方法缓存音效文件，以供快速播放。为保证通信畅通，请注意控制预加载音效文件的大小。

    example

    示例代码

    stream.preloadEffect(1, "https://web-demos-static.agora.io/agora/smlt.flac", function(err){
    if (err){
        console.error("Failed to preload effect, reason: ", err);
    }else{
        console.log("Effect is preloaded successfully");
    }
});

    Parameters

    • soundId: number

      指定音效的 ID。每个音效均有唯一的 ID。正整数，取值范围为 [1,10000]。

    • filePath: string

      指定在线音效文件的绝对路径。支持以下音频格式：MP3，AAC 以及浏览器支持的其他音频格式。

    • Optional callback: function
        • (err: string | null): void

        • Parameters

          • err: string | null

          Returns void

    Returns void

removeTrack

  • 移除音视频轨道

    该方法将音视频轨道从 Stream 中移除。移除成功后，远端会触发 Client.on("stream-updated") 回调。

    Note

    • 该方法不支持 Firefox 和 Safari。
    • 如需同时更改音频和视频轨道，Agora 建议使用 replaceTrack 方法。
    example

    示例代码

    var localStream = AgoraRTC.createStream({audio: true, video: true});
localStream.removeTrack(localStream.getAudioTrack());

    Parameters

    • track: MediaStreamTrack

      可以通过 mediaStream 方法获取音视频轨道。

    Returns void

replaceTrack

  • replaceTrack(MediaStreamTrack: MediaStreamTrack, onSuccess?: function, onFailure?: function): void

  • 替换音视频轨道

    该方法可以替换本地音视频流中的音视频轨道。

    本地流发布后，可以通过该方法切换摄像头或者切换麦克风和播放的 mp3 等。

    新的音视频轨道可以通过 getUserMedia，MediaElement.captureStream 等方法获取。

    被替换的音视频轨道会被强制停止。

    Note

    • 支持 Chrome 65+，Safari 以及最新版 Firefox 浏览器。
    • 部分移动设备上该方法可能不生效。
    • Firefox 不支持在不同的麦克风之间切换音频轨道，可以支持切换麦克风和播放的音乐文件。
    • Safari 部分外接音频设备不支持此方法。
    • 订阅端无法知悉音视频轨道被替换。
    • Agora 推荐使用 switchDevice 方法来切换媒体输入设备。
    example

    示例代码

    // 假设已有 localStream1
localStream2 = AgoraRTC.createStream({video: true, cameraId: "XXX"});
localStream2.setVideoProfile("<与 localStream1 相同>")
localStream2.init(function(){
    var newVideoTrack = localStream2.getVideoTrack();
    localStream1.replaceTrack(newVideoTrack);
});

    Parameters

    • MediaStreamTrack: MediaStreamTrack

      新的音视频轨道。

    • Optional onSuccess: function

      方法调用成功的回调。

        • (): void

        • Returns void

    • Optional onFailure: function

      方法调用失败的回调。常见的错误如下：

      • "INVALID_TRACK" 和 "INVALID_TRACK_TYPE": 新传入的 MediaStreamTrack 对象无法识别，请检查传入对象。
      • "MEDIASTREAM_TRACK_NOT_FOUND": 找不到替换对象，比如在纯音频流上尝试替换一个视频的 Track。
      • "NO_STREAM_FOUND": 找不到本地流对象，无法替换。
        • (err: string): void

        • Parameters

          • err: string

          Returns void

    Returns void

resume

  • resume(): Promise<any>

  • 恢复音视频流播放

    该方法一般在调用 Stream.play 之后，播放失败时调用。通常播放失败是由于浏览器策略阻止导致的。

    该方法需用手势触发。详见处理浏览器的自动播放策略。

    Returns Promise<any>

resumeAllEffects

  • resumeAllEffects(callback?: function): void

  • 恢复播放所有音效文件

    example

    示例代码

    stream.resumeAllEffects(function(err){
    if (err){
        console.error("Failed to resume effects, reason: ", err);
    }else{
        console.log("Effects are resumed successfully");
    }
});

    Parameters

    • Optional callback: function
        • (err: string | null): void

        • Parameters

          • err: string | null

          Returns void

    Returns void

resumeAudioMixing

  • resumeAudioMixing(callback?: function): void

  • 恢复播放音乐文件

    混音音乐文件恢复播放后，本地会触发 Stream.on("audioMixingPlayed") 回调。

    Parameters

    • Optional callback: function
        • (err: string | null): void

        • Parameters

          • err: string | null

          Returns void

    Returns void

resumeEffect

  • resumeEffect(soundId: number, callback?: function): void

  • 恢复播放指定音效文件

    example

    示例代码

    // 在音效1暂停时
stream.resumeEffect(1, function(err){
    if (err){
        console.error("Failed to resume Effect, reason: ", err);
    }else{
        console.log("Effect is resumed successfully");
    }
});

    Parameters

    • soundId: number

      指定音效的 ID。每个音效均有唯一的 ID。正整数，取值范围为 [1,10000]。

    • Optional callback: function
        • (err: string | null): void

        • Parameters

          • err: string | null

          Returns void

    Returns void

setAudioMixingPosition

  • setAudioMixingPosition(position: number, callback?: function): void

  • 设置音乐文件音频文件的播放位置

    该方法可以设置音频文件的播放位置，这样你可以根据实际情况播放文件，而不是非得从头到尾播放一个文件。

    Parameters

    • position: number

      整数，进度条位置，单位为 ms。取值范围为 [0,100000000]。

    • Optional callback: function
        • (err: string | null): void

        • Parameters

          • err: string | null

          Returns void

    Returns void

setAudioOutput

  • setAudioOutput(deviceId: string, onSuccess?: function, onFailure?: function): void

  • 设置音频输出

    该方法可以在语音场景下设置订阅流的音频输出设备，在通话时切换扬声器。在播放订阅流之前或之后都可以调用该方法。

    Note

    目前只有 Chrome 49 以上的浏览器支持该方法。

    Parameters

    • deviceId: string

      设备 ID，可以通过 getDevices 获得，设备的 kind 属性应该为 "audiooutput"。获取的 ID 为 ASCII 字符，字符串长度大于 0 小于 256 字节。

    • Optional onSuccess: function

      设置成功的回调

        • (): void

        • Returns void

    • Optional onFailure: function

      设置失败的回调

        • (err: string): void

        • Parameters

          • err: string

          Returns void

    Returns void

setAudioProfile

  • setAudioProfile(profile: "speech_low_quality" | "speech_standard" | "music_standard" | "standard_stereo" | "high_quality" | "high_quality_stereo"): void

  • 设置音频属性

    该方法设置本地流的音频属性，为可选项，且需在 Stream.init 之前调用。默认值为 "music_standard"。

    Note

    由于各浏览器的限制，部分浏览器对设置的音频属性不一定能全部适配：

    • Firefox 不支持设置音频编码码率。
    • Safari 不支持双声道功能。
    • Chrome 上如果将本地音频设为双声道，audioProcessing 中的 AEC、AGC 和 ANS 选项会自动关闭。

    Parameters

    • profile: "speech_low_quality" | "speech_standard" | "music_standard" | "standard_stereo" | "high_quality" | "high_quality_stereo"

      音频属性，包含以下选项：

      • "speech_low_quality": 16 kHz 采样率，单声道，编码码率约 24 Kbps
      • "speech_standard": 32 kHz 采样率，单声道，编码码率约 24 Kbps
      • "music_standard": 48 kHz 采样率，单声道，编码码率约 40 Kbps
      • "standard_stereo": 48 kHz 采样率，双声道，编码码率约 64 Kbps
      • "high_quality": 48 kHz 采样率，单声道， 编码码率约 128 Kbps
      • "high_quality_stereo": 48 kHz 采样率，双声道，编码码率约 192 Kbps

    Returns void

setAudioVolume

  • setAudioVolume(volume: number): void

  • 调节音量大小

    该方法可以调节订阅流的音量大小。

    Parameters

    • volume: number

      音量，范围为 0（静音） 到 100（声音最大）。默认值为 100。

    Returns void

setBeautyEffectOptions

  • setBeautyEffectOptions(enabled: boolean, options: object): Promise<void>

  • 开启本地美颜功能，并设置美颜效果选项。

    自从
       3.0.0

    该 API 为异步方法，需使用 Promise 或 async/await 关键字进行调用。

    美颜处理属于实时计算密集型操作，虽然基于硬件加速机制实现，但处理过程仍然会有较大的 GPU 和 CPU 开销。 美颜功能的开启会对低端机的性能造成影响，以至于无法达到预期的要求。对于低端机，视频编码设置为 360p 30 fps，720p 15 fps 或更高分辨率时， 我们不建议开启美颜。

    该方法支持以下浏览器：

    • Safari 12 及以上版本
    • Chrome 65 及以上版本
    • Firefox 70.0.1 及以上版本

    Note

    • 美颜功能不支持移动端设备。
    • 如果开启了双流模式（enableDualStream），美颜选项仅对大流生效。
    • 如果要为通过 replaceTrack 或 addTrack 创建的视频流开启美颜，必须在 replaceTrack 或 addTrack 完成之后调用 setBeautyEffectOptions。
    • 开启美颜后如需调用以下方法，必须先调用本方法关闭美颜功能。
    • 如果需要在创建视频流后立即开启美颜，可以在 Client.on("stream-published") 回调中调用本方法。
    example

    示例代码

    var streamPublishedHandler = async function() {
    await localStream.setBeautyEffectOptions(true, {
        lighteningContrastLevel: 1,
        lighteningLevel: 0.7,
        smoothnessLevel: 0.5,
        rednessLevel: 0.1
    });
    client.off("stream-published", streamPublishedHandler);
}
client.on("stream-published", streamPublishedHandler);

    Parameters

    • enabled: boolean

      是否开启美颜功能。

      • true：开启
      • false：（默认）关闭
    • options: object

      美颜选项。

      • Optional lighteningContrastLevel?: number

        亮度明暗对比度，与 lighteningLevel 参数搭配使用。

        取值范围为 0、1 或 2。默认值为 1（原始对比度）。取值越大，明暗对比越强烈。

      • Optional lighteningLevel?: number

        亮度

        取值范围为 [0.0,1.0]，其中 0.0 表示原始亮度，默认值为 0.7。可用来实现美白等视觉效果。

      • Optional rednessLevel?: number

        红色度

        取值范围为 [0.0,1.0]，其中 0.0 表示原始红色度，默认值为 0.1。可用来实现红润肤色等视觉效果。

      • Optional smoothnessLevel?: number

        平滑度

        取值范围为 [0.0,1.0]，其中 0.0 表示原始平滑等级，默认值为 0.5。可用来实现祛痘、磨皮等视觉效果。

    Returns Promise<void>

    一个 promise 对象，在该方法调用成功后 resolve。

setEffectsVolume

  • setEffectsVolume(volume: number, callback?: function): void

  • 设置所有音效文件播放音量

    example

    示例代码

    stream.setEffectsVolume(0, function(err){
    if (err){
        console.error("Failed to set effects volume, reason: ", err);
    }else{
        console.log("Effects volume is set successfully");
    }
});

    Parameters

    • volume: number

      音效音量。整数，范围为 [0,100]。默认 100 为原始文件音量。

    • Optional callback: function
        • (err: string | null): void

        • Parameters

          • err: string | null

          Returns void

    Returns void

setScreenProfile

  • setScreenProfile(profile: string): void

  • 设置屏幕属性

    该方法设置屏幕共享时屏幕的显示属性，必须在 Stream.init 之前调用。

    Note

    该方法仅可对本地流调用。

    Parameters

    • profile: string

      屏幕属性，下表列出可设置的屏幕属性。

      Screen Profile Definition

      屏幕属性 分辨率 帧率
      480p_1 640 × 480 5
      480p_2 640 × 480 30
      720p_1 1280 × 720 5
      720p_2 1280 × 720 30
      1080p_1 1920 × 1080 5
      1080p_2 1920 × 1080 30

      Note:

      由于设备和浏览器的限制，部分浏览器对设置的屏幕属性不一定能全部适配。这种情况下浏览器会自动调整分辨率，计费也将按照实际分辨率计算。

    Returns void

setVideoEncoderConfiguration

  • 自定义视频编码配置

    该方法可以根据需要灵活设置本地流的视频分辨率、帧率和码率，支持动态修改。

    Note

    • 该方法仅可对本地流调用。
    • 请不要在 publish 方法正在执行时调用该方法。
    • 开启双流模式（enableDualStream）后，调用该方法设置的是大流的视频属性。如果想设置小流的视频属性，你可以在发布之前调用 setLowStreamParameter。
    • 该方法支持 Chrome 63 及以上版本，其他浏览器对该方法的支持不完整。已知问题如下：
      • Safari 13 及以下版本对帧率的设置不生效。
      • Safari 11 及以下版本只支持特定分辨率。
      • iOS Safari 无法在 H.264 编码下使用较低的分辨率。
      • Firefox 只支持视频帧率为 30 fps。
    • 在部分 iOS 设备上动态修改视频编码配置可能会导致视频出现黑边。
    • 实际的视频分辨率宽高、帧率及码率的取值范围与使用的设备有关，更多信息请参考 Media​Stream​Track​.apply​Constraints()。
    • 对于自采集流（通过设置 audioSource 和 videoSource 属性创建的音视频流），该方法设置的分辨率和帧率都不生效。
    example

    示例代码

    stream.setVideoEncoderConfiguration({
    // 视频分辨率
    resolution: {
        width: 640,
        height: 480
    },
    // 视频编码帧率。通常建议是 15 帧，不超过 30 帧
    frameRate: {
        min: 15,
        max: 30
    },
    // 码率。一般情况下推荐使用标准码率
    bitrate: {
        min: 1000,
        max: 5000
    }
});

    Parameters

    Returns void

setVideoProfile

  • setVideoProfile(profile: string): void

  • 设置视频属性

    该方法设置本地流的视频编码属性。每个属性对应一套视频参数，如分辨率、帧率、码率等。

    该方法一般在 Stream.init 之前调用，从 2.7.0 开始，也可在 Stream.init 成功后调用本方法动态修改视频属性。

    Note

    • 该方法仅可对本地流调用。
    • 动态修改视频属性仅支持 Chrome 63 及以上版本和 Safari 11 及以上版本。
    • 在部分 iOS 设备上动态修改视频属性可能会导致视频出现黑边。
    • 请避免在发布流时调用该方法。
    • 开启双流模式（enableDualStream）后，无法向上调整视频分辨率。该问题为 Chromium 已知问题。
    • 对于自采集流（通过设置 audioSource 和 videoSource 属性创建的音视频流），该方法设置的分辨率和帧率都不生效。
    example

    setVideoProfile("480p");

    Parameters

    • profile: string

      视频属性，默认值为 "480p_1"。下表列出可设置的视频属性。

      视频分辨率表格

      视频属性 分辨率（宽×高） 帧率（fps） 码率（Kbps） Chrome Firefox Safari
      120p_1 160 × 120 15 65 ✓  
      120p_3 120 × 120 15 50 ✓  
      180p_1 320 × 180 15 140 ✓  
      180p_3 180 × 180 15 100 ✓  
      180p_4 240 × 180 15 120 ✓  
      240p_1 320 × 240 15 200 ✓  
      240p_3 240 × 240 15 140 ✓  
      240p_4 424 × 240 15 220 ✓  
      360p_1 640 × 360 15 400 ✓  
      360p_3 360 × 360 15 260 ✓  
      360p_4 640 × 360 30 600 ✓  
      360p_6 360 × 360 30 400 ✓  
      360p_7 480 × 360 15 320 ✓  
      360p_8 480 × 360 30 490 ✓  
      360p_9 640 × 360 15 800 ✓  
      360p_10 640 × 360 24 800 ✓  
      360p_11 640 × 360 24 1000 ✓  
      480p_1 640 × 480 15 500 ✓ ✓ ✓
      480p_2 640 × 480 30 1000 ✓ ✓ ✓
      480p_3 480 × 480 15 400 ✓ ✓ ✓
      480p_4 640 × 480 30 750 ✓ ✓ ✓
      480p_6 480 × 480 30 600 ✓ ✓ ✓
      480p_8 848 × 480 15 610 ✓ ✓ ✓
      480p_9 848 × 480 30 930 ✓ ✓ ✓
      480p_10 640 × 480 10 400 ✓ ✓ ✓
      720p_1 1280 × 720 15 1130 ✓ ✓ ✓
      720p_2 1280 × 720 30 2000 ✓ ✓ ✓
      720p_3 1280 × 720 30 1710 ✓ ✓ ✓
      720p_5 960 × 720 15 910 ✓ ✓ ✓
      720p_6 960 × 720 30 1380 ✓ ✓ ✓
      1080p_1 1920 × 1080 15 2080 ✓   ✓
      1080p_2 1920 × 1080 30 3000 ✓   ✓
      1080p_3 1920 × 1080 30 3150 ✓   ✓
      1080p_5 1920 × 1080 60 4780 ✓   ✓

      Note:

      • 视频能否达到 1080p 以上的分辨率取决于设备的性能，在性能配备较低的设备上有可能无法实现。如果采用 720p 分辨率而设备性能跟不上，则有可能出现帧率过低的情况。

      • 随着浏览器的升级，上表中列出的浏览器的分辨率支持可能并不完整，具体支持以实际情况为准。

      • 部分浏览器的某些版本可能不完全支持上表中列出的分辨率，在这种情况下建议使用主流分辨率（即上表中 _1 后缀的分辨率）。

      • Safari 浏览器不支持自定义视频帧率（默认为 30 fps）。如果你设置的视频帧率不是 30 fps，Safari 浏览器可能会修改或者拒绝你的设置。

      • 由于设备和浏览器的限制，部分浏览器对设置的 Video Profile 不一定能全部适配。这种情况下浏览器会自动调整分辨率，计费也将按照实际分辨率计算。

    Returns void

setVolumeOfEffect

  • setVolumeOfEffect(soundId: number, volume: number, callback?: function): void

  • 实时调整播放音效文件音量

    example

    示例代码

    // 在音效1存在时
stream.setVolumeOfEffect(1, 50, function(err){
    if (err){
        console.error("Failed to set volume of Effect, reason: ", err);
    }else{
        console.log("Effect volume is set to", 50);
    }
});

    Parameters

    • soundId: number

      指定音效的 ID。每个音效均有唯一的 ID。正整数，取值范围为 [1,10000]。

    • volume: number

      音效音量。整数，范围为 [0,100]。默认 100 为原始文件音量。

    • Optional callback: function
        • (err: string | null): void

        • Parameters

          • err: string | null

          Returns void

    Returns void

startAudioMixing

  • startAudioMixing(options: object, callback?: function): void

  • 开始播放音乐文件

    指定在线音频文件和麦克风采集的音频流进行混音或替换（用音频文件替换麦克风采集的音频流）。

    可以通过参数指定音频文件播放的次数和时长。

    混音音乐文件开始播放后，本地会触发 Stream.on("audioMixingPlayed") 回调。播放结束后，会触发 Stream.on("audioMixingFinished") 回调。

    Note

    • 受浏览器策略影响，在 Chrome 70+ 和 Safari 浏览器上，该方法必须由用户手势触发，详见处理浏览器的自动播放策略
    • 该方法支持以下浏览器：
      • Safari 12 及以上版本
      • Chrome 65 及以上版本
      • 最新版 Firefox
    • 请在频道内调用该方法，如果在频道外调用该方法可能会出现问题。
    example

    示例代码

    stream.startAudioMixing({
    filePath: "example.mp3"
}, function(error) {
    if (error) {
        // 错误处理
        return;
    }
    // 播放成功后的流程
});

    Parameters

    • options: object

      混音设置。

      • Optional cacheResource?: boolean

        是否缓存混音文件。

        • true：（默认值）将混音文件缓存在内存中，提升下次使用同一文件混音的速度。
        • false：不缓存混音文件，节省内存。
      • Optional cycle?: number

        指定音频文件循环播放的次数。

        Note

        仅支持 Chrome 65 及以上。

        正整数，取值范围为 [1,10000]。默认值为 1。

      • filePath: string

        指定需要混音的在线音频文件。

        ASCII 字符，字符串长度大于 0 小于 256 字节。

        支持以下音频格式： MP3，AAC 以及浏览器支持的其他音频格式。

      • Optional loop?: boolean

        是否要无限循环播放音频文件

        • true：无限循环播放音频文件。请不要和 cycle 同时设置。
        • false：（默认值）关闭无限循环播放。
      • playTime: number

        设置音频文件开始播放的时间位置，单位为 ms。整数，取值范围为 [0,100000000]。

        如需从头开始播放，设置为 0 即可。

      • Optional replace?: boolean

        是否要用音频文件替换本地音频流

        • true：音频文件内容将会替换本地录音的音频流
        • false：（默认值）音频文件内容将会和麦克风采集的音频流进行混音

        Note

        Safari 不支持此设置。

    • Optional callback: function

      方法的回调：

      • null：方法调用成功

      • err：方法调用失败，可能的错误如下：

        • "BROWSER_NOT_SUPPORT"：不支持当前浏览器。
        • "LOAD_AUDIO_FAILED"：加载在线音频资源失败。
        • "CREATE_BUFFERSOURCE_FAILED": 混音 Buffer 创建失败。

      Note

      混音其他方法的回调参数与此相同，使用 Node.js 回调风格。

        • (err: string | null): void

        • Parameters

          • err: string | null

          Returns void

    Returns void

stop

  • stop(): void

  • 停止音视频流

    调用该方法停止播放 Stream.play 播放的音视频流。

    Returns void

stopAllEffects

  • stopAllEffects(callback?: function): void

  • 停止播放所有音效文件

    example

    示例代码

    stream.stopAllEffects(function(err){
    if (err){
        console.error("Failed to stop effects, reason: ", err);
    }else{
        console.log("Effects are stopped successfully");
    }
});

    Parameters

    • Optional callback: function
        • (err: string | null): void

        • Parameters

          • err: string | null

          Returns void

    Returns void

stopAudioMixing

  • stopAudioMixing(callback?: function): void

  • 停止播放音乐文件

    Parameters

    • Optional callback: function
        • (err: string | null): void

        • Parameters

          • err: string | null

          Returns void

    Returns void

stopEffect

  • stopEffect(soundId: number, callback?: function): void

  • 停止播放指定音效文件

    example

    示例代码

    // 在音效1播放时
stream.stopEffect(1, function(err){
    if (err){
        console.error("Failed to stop Effect, reason: ", err);
    }else{
        console.log("Effect is stopped successfully");
    }
});

    Parameters

    • soundId: number

      指定音效的 ID。每个音效均有唯一的 ID。正整数，取值范围为 [1,10000]。

    • Optional callback: function
        • (err: string | null): void

        • Parameters

          • err: string | null

          Returns void

    Returns void

switchDevice

  • switchDevice(type: "audio" | "video", deviceId: string, onSuccess?: function, onFailure?: function): void

  • 切换媒体输入设备

    该方法可以切换本地流的媒体输入设备：

    • 音频输入设备，如麦克风
    • 视频输入设备，如摄像头

    已经发布的流，切换后不用重新发流。

    下列情况无法使用本方法：

    • 开启双流模式
    • 混音时
    • stream 不是本地流
    • 使用自采集属性（audioSource 和 videoSource）创建的流
    • Firefox 浏览器

    Note

    • 部分移动设备上该方法可能不生效。
    • Chrome 计划弃用和删除 WebRTC 中的 Plan B 语义，详见官方说明。该变动导致调用 publish 后再调用 switchDevice 方法可能出现视频卡顿或无声的问题。

    Parameters

    • type: "audio" | "video"

      设备的类型

      • "audio": 音频输入设备
      • "video": 视频输入设备
    • deviceId: string

      设备的 ID,可以通过 getDevices 方法获取。获取的 ID 为 ASCII 字符，字符串长度大于 0 小于 256 字节。

    • Optional onSuccess: function

      切换成功的回调

        • (): void

        • Returns void

    • Optional onFailure: function

      切换失败的回调

      • "Device switch is in process.": 已经有一个切换设备的操作正在进行中
      • "Only the local stream can switch the device.": 只有本地流才支持切换设备
      • "The device cannot be switched during screen-sharing.": 屏幕共享时无法切换设备
      • "The device cannot be switched when using videoSource or audioSource.": 如果在 initStream 时指定了音视频流，就不支持切换设备
      • "The device cannot be switched when using lowstream.": 在使用小流时无法切换设备
      • "The device cannot be switched when using audio Mixing.": 在使用音频混音时无法切换设备
      • "Invalid type." 传入的设备类型无效
      • "The device does not exist." 指定的设备不存在
        • (err: string): void

        • Parameters

          • err: string

          Returns void

    Returns void

unloadEffect

  • unloadEffect(soundId: number, callback?: function): void

  • 释放指定音效文件

    该方法从内存释放某个预加载的音效文件，以节省内存占用。

    example

    示例代码

    // 在音效1存在时
stream.unloadEffect(1, function(err){
    if (err){
        console.error("Failed to unload effect, reason: ", err);
    }else{
        console.log("Effect is unloaded successfully");
    }
});

    Parameters

    • soundId: number

      指定音效的 ID。每个音效均有唯一的 ID。正整数，取值范围为 [1,10000]。

    • Optional callback: function
        • (err: string | null): void

        • Parameters

          • err: string | null

          Returns void

    Returns void

unmuteAudio

  • unmuteAudio(): boolean

  • 启用音频轨道

    该方法启用音频轨道。对本地流启用音频轨道后远端会触发 Client.on("unmute-audio") 回调。

    Note

    对于本地流，在 createStream 时将 audio 设置为 true 才可使用该方法。

    音频轨道默认为开启状态。如果你调用了 muteAudio，可调用本方法启用音频。

    Returns boolean

    • true：启用音频轨道成功。
    • false：启用音频轨道失败，可能的原因包括没有音频、流未初始化、音频轨道已经启用等。

unmuteVideo

  • unmuteVideo(): boolean

  • 启用视频轨道

    该方法启用视频轨道。对本地流启用视频轨道后远端会触发 Client.on("unmute-video") 回调。

    Note

    对于本地创建的流，在 createStream 时将 video 设置为 true 才可使用该方法。

    视频轨道默认为开启状态。如果你调用了 muteVideo，可调用本方法启用视频。

    Returns boolean

    • true：启用视频轨道成功。
    • false：启用视频轨道失败，可能的原因包括没有视频、流未初始化、视频轨道已经启用等。