API 参考

开发者中心





互动直播

Agora.io 社区





Agora Web SDK API Reference

概览 AgoraRTC Client Stream

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

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

Hierarchy

Stream

Index

Methods

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 及以上版本，受浏览器策略影响，首次调用此方法须由用户点击触发，详见https://goo.gl/7K7WLu.
Returns number

getId

getId(): number

获取音视频流 ID

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

example

stream.getId()

Returns number

getStats

getStats(callback: function): void

获取连接数据

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

Parameters
- callback: function
  回调包含音视频流的连接统计数据：
  - 如果是发布的流，统计数据为 LocalStreamStats。
  - 如果是订阅的流，统计数据为 RemoteStreamStats。
  - - (stats: LocalStreamStats | RemoteStreamStats): void
    - Parameters
      - stats: LocalStreamStats | RemoteStreamStats
      Returns void
Returns void

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

play

play(HTMLElementID: string): void

播放音视频流

该方法播放视频流或音频流。
example
示例代码
```
stream.play("agora_remote"); // stream will be played in the element with the ID agora_remote
```
Parameters
- HTMLElementID: string
Returns void

setAudioOutput

setAudioOutput(deviceId: string): void

设置音频输出

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

Note:

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

Parameters
- deviceId: string
  
  设备 ID，可以通过 getDevices 获得。
Returns void

setAudioProfile

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

设置音频属性

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

Note:

由于各浏览器的限制，部分浏览器对设置的音频属性不一定能全部适配：
- Firefox 不支持设置音频编码码率。
- Safari 不支持双声道功能。
- Chrome 当前版本不支持播放双声道音乐，可支持发送双声道音频流。
Parameters
- profile: "speech_standard" | "music_standard" | "standard_stereo" | "high_quality" | "high_quality_stereo"
  音频属性，包含以下选项：
  - "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分辨率而设备性能跟不上，则有可能出现帧率过低的情况。声网将继续在后续版本中为较低端设备进行视频优化。如设备有特别需求，请联系 support@agora.io。
Safari 浏览器视频帧率为 30 fps，不支持自定义视频帧率。
由于设备和浏览器的限制，部分浏览器对设置的 Video Profile 不一定能全部适配。这种情况下浏览器会自动调整分辨率，计费也将按照实际分辨率计算。

Returns void

stop

stop(): void

停止音视频流

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

Returns void

Hierarchy

Index

Methods

Methods

close

Returns void

disableAudio

Returns void

disableVideo

Returns void

enableAudio

Returns void

enableVideo

Returns void

getAudioLevel

Returns number

getId

Returns number

getStats

Parameters

callback: function

Parameters

stats: LocalStreamStats | RemoteStreamStats

Returns void

Returns void

hasAudio

Returns boolean

hasVideo

Returns boolean

init

Parameters

onSuccess: function

Returns void

onFailure: function

Parameters

err: any

Returns void

Returns void

on

Parameters

event: "accessAllowed"

callback: function

Parameters

evt: any

Returns void

Returns void

Parameters

event: "accessDenied"

callback: function

Parameters

evt: any

Returns void

Returns void

Parameters

event: "stopScreenSharing"

callback: function

Parameters

evt: any

Returns void

Returns void

play

Parameters

HTMLElementID: string

Returns void

setAudioOutput

Parameters

deviceId: string

Returns void

setAudioProfile

Parameters

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

Returns void

setAudioVolume

Parameters

volume: number

Returns void

setScreenProfile

Parameters

profile: string

Returns void

event: "accessAllowed"

event: "accessDenied"