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

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

Hierarchy

  • Stream

Index

Methods

addTrack

  • 添加音视频轨道

    该方法将音视频轨道添加到 Stream。

    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(): void
  • 禁用音频轨道

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

    Returns void

disableVideo

  • disableVideo(): void
  • 禁用视频轨道

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

    Returns void

enableAudio

  • enableAudio(): void
  • 启用音频轨道

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

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

    Returns void

enableVideo

  • enableVideo(): void
  • 启用视频轨道

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

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

    Returns void

getAudioLevel

  • getAudioLevel(): number
  • 获取当前音量

    该方法获取的是当前时刻的音量。如果你想表示本地或远端音量的变化,我们建议你使用 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

getAudioMixingCurrentPosition

  • getAudioMixingCurrentPosition(): number | void
  • 获取伴奏播放进度

    该方法获取伴奏播放进度,单位为 ms。

    Returns number | void

    方法调用成功返回伴奏播放进度。

getAudioMixingDuration

  • getAudioMixingDuration(): number | void
  • 获取伴奏时长

    Returns number | void

    方法调用成功返回伴奏时长(ms)。

getAudioTrack

  • 获取音频轨道

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

    Returns MediaStreamTrack | void

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

getId

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

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

    example

    stream.getId()

    Returns number

getStats

  • getStats(callback: function): void

getVideoTrack

  • 获取视频轨道

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

    Returns MediaStreamTrack | void

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

hasAudio

  • hasAudio(): boolean
  • 获取音频 flag

    Returns boolean

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

hasVideo

  • hasVideo(): boolean
  • 获取视频 flag

    Returns boolean

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

init

  • init(onSuccess: function, onFailure: function): void
  • 初始化音视频对象

    该方法初始化音视频流对象。如果调用失败,回调函数会返回错误信息,例如:{type: "error", msg: "MEDIA_OPTION_INVALID"}

    可能出现的错误码信息如下:

    • MEDIA_OPTION_INVALID: 摄像头被占用或者分辨率不支持(早期浏览器)
    • DEVICES_NOT_FOUND: 没有找到设备
    • NOT_SUPPORTED: 浏览器不支持获取获取摄像头和麦克风
    • PERMISSION_DENIED: 浏览器禁用设备或者用户拒绝打开设备
    • CONSTRAINT_NOT_SATISFIED: 配置参数不合法(早期浏览器)
    • UNDEFINED: 未定义错误
    example

    示例代码

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

    Parameters

    • onSuccess: function

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

        • (): void
        • Returns void

    • onFailure: function

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

        • (err: any): void
        • Parameters

          • err: any

          Returns void

    Returns void

on

  • on(event: "accessAllowed", callback: function): void
  • on(event: "accessDenied", callback: function): void
  • on(event: "stopScreenSharing", 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

pauseAudioMixing

  • pauseAudioMixing(): void
  • 暂停播放伴奏

    Returns void

play

  • play(HTMLElementID: string, option: object): void
  • 播放音视频流

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

    Note:

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

    example

    示例代码

    stream.play("agora_remote", {fit: 'contain'}); // stream will be played in the element with the ID agora_remote

    Parameters

    • HTMLElementID: string

      HTML element ID。

    • option: object

      用于流播放的选项

      • fit: string

        设置视频播放时的显示模式,有 'cover''contain' 可以选择:

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

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

    Returns void

removeTrack

  • 移除音视频轨道

    该方法将音视频轨道从 Stream 中移除。

    Note

    • 如需同时更改音频和视频轨道,Agora 建议使用 replaceTrack 方法。
    • 该方法不支持 Firefox 和 Safari。
    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

      新的音视频轨道。

    • onSuccess: function

      方法调用成功的回调。

        • (): void
        • Returns void

    • onFailure: function

      方法调用失败的回调。

        • (err: string): void
        • Parameters

          • err: string

          Returns void

    Returns void

resumeAudioMixing

  • resumeAudioMixing(): void
  • 恢复播放伴奏

    Returns void

setAudioMixingPosition

  • setAudioMixingPosition(position: number): void
  • 设置伴奏音频文件的播放位置

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

    Parameters

    • position: number

      整数,进度条位置,单位为 ms。

    Returns void

setAudioOutput

  • setAudioOutput(deviceId: string, onSuccess: function, onFailure: function): void
  • 设置音频输出

    该方法可以在语音场景下设置音频输出设备,在通话时切换麦克风和扬声器。

    Note:

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

    Parameters

    • deviceId: string

      设备 ID,可以通过 getDevices 获得,设备的 kind 属性应该为 "audiooutput"

    • onSuccess: function
        • (): void
        • Returns void

    • 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

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

setVideoProfile

  • setVideoProfile(profile: string): void
  • 设置视频属性

    该方法设置视频属性,为可选项,且须在 Stream.init 之前调用。默认值为 "480p_1"

    example

    setVideoProfile("480p");

    Parameters

    • profile: string

      视频属性。详见下表的定义及不同场景支持的属性。

      Video Profile Definition

      视频属性 分辨率(宽×高) 帧率(fps) 码率(Kbps) Chrome Firefox/Opera 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 648 × 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 分辨率而设备性能跟不上,则有可能出现帧率过低的情况。声网将继续在后续版本中为较低端设备进行视频优化。

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

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

    Returns void

startAudioMixing

  • startAudioMixing(options: object, callback: function): void
  • 开始播放伴奏

    指定在线音频文件和麦克风采集的音频流进行混音或替换(用音频文件替换麦克风采集的音频流)。 可以通过参数指定音频文件播放的次数和时长。

    Note:

    • 该方法支持以下浏览器:
      • Safari 12+
      • Chrome 65+
      • 最新版 Firefox
    • 请在频道内调用该方法,如果在频道外调用该方法可能会出现问题。
    • 受浏览器策略影响,在 Chrome 70+ 和 Safari 浏览器上,该方法必须由用户手势触发,详见 Autoplay Policy Changes

    Parameters

    • options: object

      混音设置。

      • Optional cycle?: number

        指定音频文件循环播放的次数(仅支持 Chrome 65+),正整数。

      • filePath: string

        指定需要混音的在线音频文件。支持以下音频格式: mp3,aac 以及浏览器支持的其他音频格式。

      • Optional loop?: boolean

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

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

        设置音频文件开始播放的时间位置,单位为 ms。如需从头开始播放,设置为 0 即可。

      • Optional replace?: boolean

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

        • true:音频文件内容将会替换本地录音的音频流
        • false:音频文件内容将会和麦克风采集的音频流进行混音

        Note:

        Safari 不支持此设置。

    • callback: function

      方法的回调:

      • null:方法调用成功
      • err:方法调用失败
        • (err: string | null): void
        • Parameters

          • err: string | null

          Returns void

    Returns void

stop

  • stop(): void
  • 停止音视频流

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

    Returns void

stopAudioMixing

  • stopAudioMixing(): void
  • 停止播放伴奏

    Returns void

switchDevice

  • switchDevice(type: string, deviceId: string, onSuccess: function, onFailure: function): void
  • 切换媒体输入设备

    该方法可以切换媒体输入设备:

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

    可以通过 getDevices 方法获取设备的 deviceId 再进行切换。 已经发布的流,切换后不用重新发流。

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

    • 开启双流模式
    • stream 不是本地流
    • 使用自采集属性(audioSourcevideoSource)创建的流
    • Firefox 浏览器

    Parameters

    • type: string

      设备的类型

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

      设备的Id

    • onSuccess: function

      切换成功的回调

        • (): void
        • Returns void

    • onFailure: function

      切换失败的回调

        • (err: string): void
        • Parameters

          • err: string

          Returns void

    Returns void