通过 createStream 创建的音视频流对象。

一个音视频流对象指通话中的本地或远端音视频流。

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

Hierarchy

  • Stream

Index

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 | void
  • 获取当前音量

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

    example

    示例代码

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

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

    Note:

    受浏览器策略影响,在 Chrome 70+ 和 Safari 浏览器上,该方法必须由用户手势触发,详见 Autoplay Policy Changes

    Returns number | void

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

getAudioMixingCurrentPosition

  • getAudioMixingCurrentPosition(): number | void
  • 获取音乐文件播放进度

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

    Returns number | void

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

getAudioMixingDuration

  • getAudioMixingDuration(): number | void
  • 获取音乐文件时长

    Returns number | void

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

getAudioTrack

getEffectsVolume

  • getEffectsVolume(): Array<object>
  • 获取所有音效文件播放音量

    example

    示例代码

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

    Returns Array<object>

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

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

getId

  • getId(): number
  • 获取音视频流 ID

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

    example

    stream.getId()

    Returns number

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

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: any): void
        • Parameters

          • err: any

          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
  • 该回调通知 App 已获取本地摄像头/麦克风使用权限。

    Parameters

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

          • evt: any

          Returns void

    Returns void

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

    Parameters

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

          • evt: any

          Returns void

    Returns void

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

    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.state === "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 浏览器上,该方法必须由用户手势触发,详见 Autoplay Policy Changes

    example

    示例代码

    stream.play("agora_remote", {fit: "contain"}, function(errState){
        if (errState && errState !== "abort"){
            // 播放失败,一般为浏览器策略阻止。引导用户用手势触发恢复播放。
        }
    }); // 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-fitcover 选项。
        • contain 模式:优先保证视频内容全部显示。视频尺寸等比缩放,直至视频窗口的一边与视窗边框对齐。如果视频尺寸与显示视窗尺寸不一致,在保持长宽比的前提下,将视频进行缩放后填满视窗,缩放后的视频四周会有一圈黑边。可以参考 CSS 属性中 object-fit 的 contain 选项。

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

      • Optional muted?: boolean

        设置播放的流是否静音

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

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

        关于自动播放策略的更多信息,请参考 Autoplay Policy Changes

    • Optional callback: function

      播放是否成功的回调

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

    Returns void

playEffect

  • playEffect(options: object, callback?: function): void
  • 播放指定音效文件

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

    Note:

    • 受浏览器策略影响,在 Chrome 70 及以上和 Safari 浏览器上,该方法必须由用户手势触发,详见 Autoplay Policy Changes
    • 该方法支持以下浏览器:
      • 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 将音效加载至内存,确保这里的 soundIDpreloadEffect 设置的 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 等。

    新的音视频轨道可以通过 getUserMediaMediaElement.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

      方法调用失败的回调。

        • (err: string): void
        • Parameters

          • err: string

          Returns void

    Returns void

resume

  • resume(): Promise<any>
  • 恢复音视频流播放

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

    该方法需用手势触发。关于自动播放策略的更多信息,请参考 Autoplay Policy Changes

    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 当前版本不支持播放双声道音乐,可支持发送双声道音频流。

    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(声音最大)。

    Returns void

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
  • 设置屏幕属性

    该方法设置屏幕共享时屏幕的显示属性。

    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:

    • 请不要在发布流时调用该方法。
    • 该方法支持 Chrome 63 及以上版本,其他浏览器对该方法的支持不完整。已知问题包括 Safari 12 及以下版本对帧率的设置不生效、Safari 11 及以下版本只支持特定分辨率等。
    • 在部分 iOS 设备上动态修改视频编码配置可能会导致视频出现黑边。
    • 实际的视频分辨率宽高、帧率及码率的取值范围与使用的设备有关,更多信息请参考 Media​Stream​Track​.apply​Constraints()
    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 设备上动态修改视频属性可能会导致视频出现黑边。
    • 请避免在发布流时调用该方法。
    example

    setVideoProfile("480p");

    Parameters

    • profile: string

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

      Video Profile Definition

      视频属性 分辨率(宽×高) 帧率(fps) 码率(Kbps) Chrome Firefox Safari
      120p 160 × 120 15 65
      120p_1 160 × 120 15 65
      120p_3 120 × 120 15 50
      180p 320 × 180 15 140
      180p_1 320 × 180 15 140
      180p_3 180 × 180 15 100
      180p_4 240 × 180 15 120
      240p 320 × 240 15 200
      240p_1 320 × 240 15 200
      240p_3 240 × 240 15 140
      240p_4 424 × 240 15 220
      360p 640 × 360 15 400
      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 640 × 480 15 500
      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 1280 × 720 15 1130
      720p_1 1280 × 720 15 1130
      720p_2 1280 × 720 15 2080
      720p_3 1280 × 720 30 1710
      720p_5 960 × 720 15 910
      720p_6 960 × 720 30 1380
      1080p 1920 × 1080 15 2080
      1080p_1 1920 × 1080 15 2080
      1080p_2 1920 × 1080 30 3000
      1080p_3 1920 × 1080 30 3150
      1080p_5 1920 × 1080 60 4780
      1440p 2560 × 1440 30 4850
      1440p_1 2560 × 1440 30 4850
      1440p_2 2560 × 1440 60 7350
      4K 3840 × 2160 30 8910
      4K_1 3840 × 2160 30 8910
      4K_3 3840 × 2160 60 13500

      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 浏览器上,该方法必须由用户手势触发,详见 Autoplay Policy Changes
    • 该方法支持以下浏览器:
      • 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:方法调用失败

      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
  • 停止播放音乐文件

    停止播放混音音乐文件后,本地会触发 Stream.on("audioMixingFinished") 回调。

    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 不是本地流
    • 使用自采集属性(audioSourcevideoSource)创建的流
    • Firefox 浏览器

    Note:

    部分移动设备上该方法可能不生效。

    Parameters

    • type: "audio" | "video"

      设备的类型

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

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

    • Optional onSuccess: function

      切换成功的回调

        • (): void
        • Returns void

    • Optional onFailure: function

      切换失败的回调

        • (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:启用视频轨道失败,可能的原因包括没有视频、流未初始化、视频轨道已经启用等。