# Interface IAgoraRTC (/zh-CN/api-reference/rtc/web/interfaces/iagorartc)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

## Events [#events]

<a id="event_audio_context_state_changed"></a>

### audio-context-state-changed [#audio-context-state-changed]

<ApiSignature>

audio-context-state-changed(currState: AudioContextState | "interrupted", prevState: AudioContextState | "interrupted" | undefined): void

</ApiSignature>

:::info[自从]
*4.20.0*
:::

音频上下文 ([Audio Context](https://developer.mozilla.org/en-US/docs/Web/API/AudioContext)) 状态发生改变回调。该回调中的 `"interrupted"` 状态当前只会在 iOS 上触发。

<ParameterList title="Parameters">
<Parameter name="currState" type="AudioContextState | &quot;interrupted&quot;" required>

当前的状态，取值如下：

- `AudioContextState`：枚举值的含义详见 [BaseAudioContext.state](https://developer.mozilla.org/en-US/docs/Web/API/BaseAudioContext/state)。
- `"interrupted"`：App 的音视频播放被微信通话或系统电话打断。你可以调用 [resumeAudioContext](/zh-CN/api-reference/rtc/web/interfaces/iagorartc#resumeaudiocontext) 方法恢复音视频播放。

</Parameter>
<Parameter name="prevState" type="AudioContextState | &quot;interrupted&quot; | undefined" required>

之前的状态，取值如下：

- `AudioContextState`：枚举值的含义详见 [BaseAudioContext.state](https://developer.mozilla.org/en-US/docs/Web/API/BaseAudioContext/state)。
- `"interrupted"`：App 的音视频播放被微信通话或系统电话打断。
- `undefined`：无先前状态。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="event_autoplay_failed"></a>

### autoplay-failed [#autoplay-failed]

<ApiSignature>

autoplay-failed(): void

</ApiSignature>

:::info[自从]
*4.18.0*
:::

如果你需要更灵活地监听自动播放失败事件，推荐通过在 [IAgoraRTC.on](/zh-CN/api-reference/rtc/web/interfaces/iagorartc#on) 方法中传入该回调来代替 [onAutoplayFailed](/zh-CN/api-reference/rtc/web/interfaces/iagorartc#onautoplayfailed)。

```javascript
AgoraRTC.on("autoplay-failed", (info) => {
  console.log("Autoplay failed!", info.state, info.device);
});
```

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="event_camera_changed"></a>

### camera-changed [#camera-changed]

<ApiSignature>

camera-changed(deviceInfo: [DeviceInfo](/zh-CN/api-reference/rtc/web/interfaces/deviceinfo)): void

</ApiSignature>

:::info[自从]
*4.18.0*
:::

如果你需要更灵活地监听视频采集设备状态变化，推荐通过在 [IAgoraRTC.on](/zh-CN/api-reference/rtc/web/interfaces/iagorartc#on) 方法中传入该回调来代替 [onCameraChanged](/zh-CN/api-reference/rtc/web/interfaces/iagorartc#oncamerachanged)。

```javascript
AgoraRTC.on("camera-changed", (info) => {
  console.log("Camera changed!", info.state, info.device);
});
```

<ParameterList title="Parameters">
<Parameter name="deviceInfo" required>

<ParameterType>

[DeviceInfo](/zh-CN/api-reference/rtc/web/interfaces/deviceinfo)

</ParameterType>

设备信息，详见 [DeviceInfo](/zh-CN/api-reference/rtc/web/interfaces/deviceinfo)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="event_microphone_changed"></a>

### microphone-changed [#microphone-changed]

<ApiSignature>

microphone-changed(deviceInfo: [DeviceInfo](/zh-CN/api-reference/rtc/web/interfaces/deviceinfo)): void

</ApiSignature>

:::info[自从]
*4.18.0*
:::

如果你需要更灵活地监听麦克风设备变化，推荐通过在 [IAgoraRTC.on](/zh-CN/api-reference/rtc/web/interfaces/iagorartc#on) 方法中传入该回调来代替 [onMicrophoneChanged](/zh-CN/api-reference/rtc/web/interfaces/iagorartc#onmicrophonechanged)。

```javascript
AgoraRTC.on("microphone-changed", (info) => {
  console.log("Microphone changed!", info.state, info.device);
});
```

<ParameterList title="Parameters">
<Parameter name="deviceInfo" required>

<ParameterType>

[DeviceInfo](/zh-CN/api-reference/rtc/web/interfaces/deviceinfo)

</ParameterType>

设备信息，详见 [DeviceInfo](/zh-CN/api-reference/rtc/web/interfaces/deviceinfo)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="event_playback_device_changed"></a>

### playback-device-changed [#playback-device-changed]

<ApiSignature>

playback-device-changed(deviceInfo: [DeviceInfo](/zh-CN/api-reference/rtc/web/interfaces/deviceinfo)): void

</ApiSignature>

:::info[自从]
*4.18.0*
:::

如果你需要更灵活地监听音频播放设备变化，推荐通过在 [IAgoraRTC.on](/zh-CN/api-reference/rtc/web/interfaces/iagorartc#on) 方法中传入该回调来代替 [onPlaybackDeviceChanged](/zh-CN/api-reference/rtc/web/interfaces/iagorartc#onplaybackdevicechanged)。

```javascript
AgoraRTC.on("playback-device-changed", (info) => {
  console.log("Playback device changed!", info.state, info.device);
});
```

<ParameterList title="Parameters">
<Parameter name="deviceInfo" required>

<ParameterType>

[DeviceInfo](/zh-CN/api-reference/rtc/web/interfaces/deviceinfo)

</ParameterType>

设备信息，详见 [DeviceInfo](/zh-CN/api-reference/rtc/web/interfaces/deviceinfo)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="event_security_policy_violation"></a>

### security-policy-violation [#security-policy-violation]

<ApiSignature>

security-policy-violation(): void

</ApiSignature>

:::info[自从]
*4.18.0*
:::

如果你需要更灵活地监听触发 CSP 规则事件，推荐通过在 [IAgoraRTC.on](/zh-CN/api-reference/rtc/web/interfaces/iagorartc#on) 方法中传入该回调来代替 [onSecurityPolicyViolation](/zh-CN/api-reference/rtc/web/interfaces/iagorartc#onsecuritypolicyviolation)。

```javascript
AgoraRTC.on("security-policy-violation", (info) => {
  console.log("Security policy violation!", info.state, info.device);
});
```

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

## Global Callback Properties [#global-callback-properties]

<a id="onaudioautoplayfailed"></a>

<a id="optional-onaudioautoplayfailed"></a>

### onAudioAutoplayFailed [#onaudioautoplayfailed]

<ApiSignature labels="Optional">

onAudioAutoplayFailed: function

</ApiSignature>

音频轨道自动播放失败回调。

#### deprecated [#deprecated]

自 4.6.0 起废弃，请改用 [onAutoplayFailed](/zh-CN/api-reference/rtc/web/interfaces/iagorartc#onautoplayfailed)。

该回调在音频轨道自动播放失败的时候触发。如果短时间内有多个音频轨道对象都调用了 `play`，SDK 会触发多次 `onAudioAutoplayFailed`。

音频自动播放失败是浏览器的[自动播放策略](https://developer.mozilla.org/en-US/docs/Web/Media/Guides/Autoplay#autoplay_and_autoplay_blocking)导致的，视频轨道的播放不受此影响。

在 Agora Web SDK 中，只要用户和页面发生过一次点击交互，就会自动解锁浏览器音频自动播放的限制，所以针对音频自动播放有两种解决方案：

- 如果不希望收到 `onAudioAutoplayFailed` 回调，就确保在调用 `RemoteAudioTrack.play` 和 `LocalAudioTrack.play` 之前用户已经和页面发生了点击交互。
- 如果无法保证在调用 `RemoteAudioTrack.play` 和 `LocalAudioTrack.play` 之前用户已经和页面发生点击交互，就监听 `onAudioAutoplayFailed` 回调，通过回调在页面上显示一个按钮引导用户点击。

> 无论使用何种方案，只要浏览器启用了自动播放策略，都需要用户至少触发一次点击交互操作才能播放音频。随着用户使用某个页面的次数变多，浏览器会在这个页面上默认关闭自动播放策略，此时不需要任何交互也可以播放音频了，但是我们无法通过 JavaScript 去感知浏览器这个行为。

下面的示例代码演示了当检测到自动播放失败后的处理：在页面上动态显示一个按钮让用户点击。

```javascript
 let isAudioAutoplayFailed = false;
 AgoraRTC.onAudioAutoplayFailed = () => {
  if (isAudioAutoplayFailed) return;

  isAudioAutoplayFailed = true;
  const btn = document.createElement("button");
  btn.innerText = "Click me to resume the audio playback";
  btn.onClick = () => {
    isAudioAutoplayFailed = false;
    btn.remove();
  };
  document.body.append(btn);
};
```

> 需要注意的是，短时间内可能会有多个音频轨道对象都调用了 `play`，此时会触发多次 `onAudioAutoplayFailed`。示例代码中通过 `isAudioAutoplayFailed` 这个对象防止创建重复的按钮对象。

#### Type declaration [#type-declaration]

<ApiSignature>

(): void

</ApiSignature>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="onautoplayfailed"></a>

<a id="optional-onautoplayfailed"></a>

### onAutoplayFailed [#onautoplayfailed]

<ApiSignature labels="Optional">

onAutoplayFailed: function

</ApiSignature>

音频或视频轨道自动播放失败回调。

:::info[自从]
*4.6.0*
:::

SDK 在音频或视频轨道自动播放失败时触发该回调。

- 音频自动播放失败是由浏览器的[自动播放策略](https://developer.mozilla.org/en-US/docs/Web/Media/Guides/Autoplay#autoplay_and_autoplay_blocking)导致的。
- 在大部分浏览器中，纯视频不受到自动播放策略的限制，但是在低电量模式下的 iOS Safari 浏览器中以及开启自定义自动播放限制的 iOS `WKWebView` 中（如 iOS 微信浏览器），纯视频的自动播放也会受到限制。

在 Agora Web SDK 中，只要用户和页面发生过一次点击交互，就会自动解锁浏览器音频或视频的自动播放限制，所以针对自动播放有两种解决方案：

- 如果不希望收到 `onAutoplayFailed` 回调，就确保在调用 `RemoteTrack.play` 和 `LocalTrack.play` 之前用户已经和页面发生了点击交互。
- 如果无法保证在调用 `RemoteTrack.play` 和 `LocalTrack.play` 之前用户已经和页面发生点击交互，就监听 `onAutoplayFailed` 回调，通过回调在页面上显示一个按钮引导用户点击。

> 无论使用何种方案，只要浏览器启用了自动播放策略，都需要用户至少触发一次点击交互操作才能播放音频或视频。随着用户使用某个页面的次数变多，浏览器会在这个页面上默认关闭自动播放策略，此时不需要任何交互也可以播放音频和视频了，但是我们无法通过 JavaScript 去感知浏览器这个行为。

下面的示例代码演示了当检测到自动播放失败后的处理：在页面上动态显示一个按钮让用户点击。

```javascript
 AgoraRTC.onAutoplayFailed = () => {
  const btn = document.createElement("button");
  btn.innerText = "Click me to resume the audio/video playback";
  btn.onClick = () => {
    btn.remove();
  };
  document.body.append(btn);
```

> 由于自动播放失败后在用户通过手势点击恢复播放之前，`onAutoplayFailed` 只会触发一次，因此在业务代码中不需要像 `onAudioAutoplayFailed` 回调一样维护 `isAutoplayFailed` 状态。

#### Type declaration [#type-declaration-1]

<ApiSignature>

(): void

</ApiSignature>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="oncamerachanged"></a>

<a id="optional-oncamerachanged"></a>

### onCameraChanged [#oncamerachanged]

<ApiSignature labels="Optional">

onCameraChanged: function

</ApiSignature>

视频采集设备状态变化回调。

该回调提示有摄像头被添加或移除。

:::note[注意事项]
当该回调提示有设备被添加时，如果该设备是虚拟设备，可能无法采集到音频或视频。
:::

```javascript
AgoraRTC.onCameraChanged = (info) => {
  console.log("camera changed!", info.state, info.device);
};
```

**Parameters**

- **deviceInfo**：设备信息，详见 [DeviceInfo](/zh-CN/api-reference/rtc/web/interfaces/deviceinfo)。

#### Type declaration [#type-declaration-2]

<ApiSignature>

(deviceInfo: [DeviceInfo](/zh-CN/api-reference/rtc/web/interfaces/deviceinfo)): void

</ApiSignature>

<ParameterList title="Parameters">
<Parameter name="deviceInfo" required>

<ParameterType>

[DeviceInfo](/zh-CN/api-reference/rtc/web/interfaces/deviceinfo)

</ParameterType>

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="onmicrophonechanged"></a>

<a id="optional-onmicrophonechanged"></a>

### onMicrophoneChanged [#onmicrophonechanged]

<ApiSignature labels="Optional">

onMicrophoneChanged: function

</ApiSignature>

音频采集设备状态变化回调。

该回调提示有麦克风被添加或移除。

:::note[注意事项]
当该回调提示有设备被添加时，如果该设备是虚拟设备，可能无法采集到音频或视频。
:::

```javascript
AgoraRTC.onMicrophoneChanged = (info) => {
  console.log("microphone changed!", info.state, info.device);
};
```

**Parameters**

- **deviceInfo**：设备信息，详见 [DeviceInfo](/zh-CN/api-reference/rtc/web/interfaces/deviceinfo)。

#### Type declaration [#type-declaration-3]

<ApiSignature>

(deviceInfo: [DeviceInfo](/zh-CN/api-reference/rtc/web/interfaces/deviceinfo)): void

</ApiSignature>

<ParameterList title="Parameters">
<Parameter name="deviceInfo" required>

<ParameterType>

[DeviceInfo](/zh-CN/api-reference/rtc/web/interfaces/deviceinfo)

</ParameterType>

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="onplaybackdevicechanged"></a>

<a id="optional-onplaybackdevicechanged"></a>

### onPlaybackDeviceChanged [#onplaybackdevicechanged]

<ApiSignature labels="Optional">

onPlaybackDeviceChanged: function

</ApiSignature>

:::info[自从]
*4.1.0*
:::

音频播放设备状态变化回调。

该回调提示有音频播放设备被添加或移除。

```javascript
AgoraRTC.onPlaybackDeviceChanged = (info) => {
  console.log("speaker changed!", info.state, info.device);
};
```

**Parameters**

- **deviceInfo**：设备信息，详见 [DeviceInfo](/zh-CN/api-reference/rtc/web/interfaces/deviceinfo)。

#### Type declaration [#type-declaration-4]

<ApiSignature>

(deviceInfo: [DeviceInfo](/zh-CN/api-reference/rtc/web/interfaces/deviceinfo)): void

</ApiSignature>

<ParameterList title="Parameters">
<Parameter name="deviceInfo" required>

<ParameterType>

[DeviceInfo](/zh-CN/api-reference/rtc/web/interfaces/deviceinfo)

</ParameterType>

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="onsecuritypolicyviolation"></a>

<a id="optional-onsecuritypolicyviolation"></a>

### onSecurityPolicyViolation [#onsecuritypolicyviolation]

<ApiSignature labels="Optional">

onSecurityPolicyViolation: function

</ApiSignature>

:::info[自从]
*4.15.0*
:::

触发 CSP 规则回调。

当声网服务相关的资源加载或请求发送因为触发浏览器的 CSP（Content Security Policy，内容安全策略）规则而失败时，SDK 会触发该回调。
 收到该回调后，请及时调整你的 CSP 设置，确保能正常体验声网的服务。

#### Type declaration [#type-declaration-5]

<ApiSignature>

(event: SecurityPolicyViolationEvent): void

</ApiSignature>

<ParameterList title="Parameters">
<Parameter name="event" type="SecurityPolicyViolationEvent" required />
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

## Other Properties [#other-properties]

<a id="version"></a>

### VERSION [#version]

<ApiSignature>

VERSION: string

</ApiSignature>

Agora Web SDK 的版本信息。

## Agora Core Methods [#agora-core-methods]

<a id="createclient"></a>

### createClient [#createclient]

<ApiSignature>

createClient(config: [ClientConfig](/zh-CN/api-reference/rtc/web/interfaces/clientconfig)): [IAgoraRTCClient](/zh-CN/api-reference/rtc/web/interfaces/iagorartcclient)

</ApiSignature>

创建一个客户端对象用于通话/直播管理，通常来说这是使用 Agora Web SDK 的第一步。

<ParameterList title="Parameters">
<Parameter name="config" required>

<ParameterType>

[ClientConfig](/zh-CN/api-reference/rtc/web/interfaces/clientconfig)

</ParameterType>

客户端的配置，包括通话场景、编码格式等，默认使用 `vp8` 编码，`rtc` 通话场景。详见 [ClientConfig](/zh-CN/api-reference/rtc/web/interfaces/clientconfig)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

[IAgoraRTCClient](/zh-CN/api-reference/rtc/web/interfaces/iagorartcclient)

</ApiReturnType>

</ApiReturns>

## Local Track Methods [#local-track-methods]

<a id="createbuffersourceaudiotrack"></a>

### createBufferSourceAudioTrack [#createbuffersourceaudiotrack]

<ApiSignature>

createBufferSourceAudioTrack(config: [BufferSourceAudioTrackInitConfig](/zh-CN/api-reference/rtc/web/interfaces/buffersourceaudiotrackinitconfig)): Promise&lt;[IBufferSourceAudioTrack](/zh-CN/api-reference/rtc/web/interfaces/ibuffersourceaudiotrack)&gt;

</ApiSignature>

通过音频文件或者 [AudioBuffer](https://developer.mozilla.org/zh-CN/docs/Web/API/AudioBuffer) 对象创建一个音频轨道。

该方法支持本地和在线音频文件。音频文件支持以下音频格式：

- MP3
- AAC
- 浏览器支持的其他音频格式

<ParameterList title="Parameters">
<Parameter name="config" required>

<ParameterType>

[BufferSourceAudioTrackInitConfig](/zh-CN/api-reference/rtc/web/interfaces/buffersourceaudiotrackinitconfig)

</ParameterType>

通过该配置指定文件路径、缓存策略和编码配置。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

Promise&lt;[IBufferSourceAudioTrack](/zh-CN/api-reference/rtc/web/interfaces/ibuffersourceaudiotrack)&gt;

</ApiReturnType>

返回的音频轨道对象相对于普通的音频轨道对象增加了一些控制音频播放流程的方法。包括播放、暂停、跳转、实时播放状态获取等。

</ApiReturns>

<a id="createcameravideotrack"></a>

### createCameraVideoTrack [#createcameravideotrack]

<ApiSignature>

createCameraVideoTrack(config?: [CameraVideoTrackInitConfig](/zh-CN/api-reference/rtc/web/interfaces/cameravideotrackinitconfig)): Promise&lt;[ICameraVideoTrack](/zh-CN/api-reference/rtc/web/interfaces/icameravideotrack)&gt;

</ApiSignature>

通过摄像头采集的视频创建一个视频轨道。

<ParameterList title="Parameters">
<Parameter name="config" optional>

<ParameterType>

[CameraVideoTrackInitConfig](/zh-CN/api-reference/rtc/web/interfaces/cameravideotrackinitconfig)

</ParameterType>

采集视频的配置，包括采集设备、编码配置等。详见 [CameraVideoTrackInitConfig](/zh-CN/api-reference/rtc/web/interfaces/cameravideotrackinitconfig)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

Promise&lt;[ICameraVideoTrack](/zh-CN/api-reference/rtc/web/interfaces/icameravideotrack)&gt;

</ApiReturnType>

</ApiReturns>

<a id="createcustomaudiotrack"></a>

### createCustomAudioTrack [#createcustomaudiotrack]

<ApiSignature>

createCustomAudioTrack(config: [CustomAudioTrackInitConfig](/zh-CN/api-reference/rtc/web/interfaces/customaudiotrackinitconfig)): [ILocalAudioTrack](/zh-CN/api-reference/rtc/web/interfaces/ilocalaudiotrack)

</ApiSignature>

创建一个自定义的音频轨道。

你可以使用这个方法将自己维护的 [MediaStreamTrack](https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack) 转换成一个可以用于 SDK 的音频轨道。

<ParameterList title="Parameters">
<Parameter name="config" required>

<ParameterType>

[CustomAudioTrackInitConfig](/zh-CN/api-reference/rtc/web/interfaces/customaudiotrackinitconfig)

</ParameterType>

自定义音频的配置，详见 [CustomAudioTrackInitConfig](/zh-CN/api-reference/rtc/web/interfaces/customaudiotrackinitconfig)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

[ILocalAudioTrack](/zh-CN/api-reference/rtc/web/interfaces/ilocalaudiotrack)

</ApiReturnType>

</ApiReturns>

<a id="createcustomvideotrack"></a>

### createCustomVideoTrack [#createcustomvideotrack]

<ApiSignature>

createCustomVideoTrack(config: [CustomVideoTrackInitConfig](/zh-CN/api-reference/rtc/web/interfaces/customvideotrackinitconfig)): [ILocalVideoTrack](/zh-CN/api-reference/rtc/web/interfaces/ilocalvideotrack)

</ApiSignature>

创建一个自定义的视频轨道。

你可以使用这个方法将自己维护的 [MediaStreamTrack](https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack) 转换成一个可以用于 SDK 的视频轨道。

<ParameterList title="Parameters">
<Parameter name="config" required>

<ParameterType>

[CustomVideoTrackInitConfig](/zh-CN/api-reference/rtc/web/interfaces/customvideotrackinitconfig)

</ParameterType>

自定义视频轨道的配置，详见 [CustomVideoTrackInitConfig](/zh-CN/api-reference/rtc/web/interfaces/customvideotrackinitconfig)。

> 自 v4.17.1 起，自定义视频轨道配置 [config](/zh-CN/api-reference/rtc/web/interfaces/customvideotrackinitconfig) 除了支持设置码率，还支持设置分辨率和帧率。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

[ILocalVideoTrack](/zh-CN/api-reference/rtc/web/interfaces/ilocalvideotrack)

</ApiReturnType>

</ApiReturns>

<a id="createmicrophoneandcameratracks"></a>

### createMicrophoneAndCameraTracks [#createmicrophoneandcameratracks]

<ApiSignature>

createMicrophoneAndCameraTracks(audioConfig?: [MicrophoneAudioTrackInitConfig](/zh-CN/api-reference/rtc/web/interfaces/microphoneaudiotrackinitconfig), videoConfig?: [CameraVideoTrackInitConfig](/zh-CN/api-reference/rtc/web/interfaces/cameravideotrackinitconfig)): Promise&lt;[[IMicrophoneAudioTrack](/zh-CN/api-reference/rtc/web/interfaces/imicrophoneaudiotrack), [ICameraVideoTrack](/zh-CN/api-reference/rtc/web/interfaces/icameravideotrack)]&gt;

</ApiSignature>

同时创建麦克风音频轨道和摄像头视频轨道。

通过麦克风采集的音频创建一个音频轨道，同时通过摄像头采集的视频创建一个视频轨道。

> 调用该方法和分别调用 [createMicrophoneAudioTrack](/zh-CN/api-reference/rtc/web/interfaces/iagorartc#createmicrophoneaudiotrack) 以及 [createCameraVideoTrack](/zh-CN/api-reference/rtc/web/interfaces/iagorartc#createcameravideotrack) 的区别是：
>
> - 调用该方法会同时要求麦克风和摄像头的授权，用户只需授权一次。
> - 分别创建音频轨道和视频轨道需要用户分别对麦克风和摄像头进行授权，也就是说用户需要授权两次。

<ParameterList title="Parameters">
<Parameter name="audioConfig" optional>

<ParameterType>

[MicrophoneAudioTrackInitConfig](/zh-CN/api-reference/rtc/web/interfaces/microphoneaudiotrackinitconfig)

</ParameterType>

采集音频的配置，包括采集设备、编码配置等。

</Parameter>
<Parameter name="videoConfig" optional>

<ParameterType>

[CameraVideoTrackInitConfig](/zh-CN/api-reference/rtc/web/interfaces/cameravideotrackinitconfig)

</ParameterType>

采集视频的配置，包括采集设备、编码配置等。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

Promise&lt;[[IMicrophoneAudioTrack](/zh-CN/api-reference/rtc/web/interfaces/imicrophoneaudiotrack), [ICameraVideoTrack](/zh-CN/api-reference/rtc/web/interfaces/icameravideotrack)]&gt;

</ApiReturnType>

</ApiReturns>

<a id="createmicrophoneaudiotrackm"></a>

<a id="createmicrophoneaudiotrack"></a>

### createMicrophoneAudioTrack [#createmicrophoneaudiotrack]

<ApiSignature>

createMicrophoneAudioTrack(config?: [MicrophoneAudioTrackInitConfig](/zh-CN/api-reference/rtc/web/interfaces/microphoneaudiotrackinitconfig)): Promise&lt;[IMicrophoneAudioTrack](/zh-CN/api-reference/rtc/web/interfaces/imicrophoneaudiotrack)&gt;

</ApiSignature>

通过麦克风采集的音频创建一个音频轨道。

<ParameterList title="Parameters">
<Parameter name="config" optional>

<ParameterType>

[MicrophoneAudioTrackInitConfig](/zh-CN/api-reference/rtc/web/interfaces/microphoneaudiotrackinitconfig)

</ParameterType>

麦克风采集音频的配置，包括采集设备、音频编码配置等，详见 [MicrophoneAudioTrackInitConfig](/zh-CN/api-reference/rtc/web/interfaces/microphoneaudiotrackinitconfig)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

Promise&lt;[IMicrophoneAudioTrack](/zh-CN/api-reference/rtc/web/interfaces/imicrophoneaudiotrack)&gt;

</ApiReturnType>

</ApiReturns>

<a id="createscreenvideotrack"></a>

### createScreenVideoTrack [#createscreenvideotrack]

#### createScreenVideoTrack [1/3] [#createscreenvideotrack-13]

<ApiSignature>

createScreenVideoTrack(config: [ScreenVideoTrackInitConfig](/zh-CN/api-reference/rtc/web/interfaces/screenvideotrackinitconfig), withAudio: "enable"): Promise&lt;[[ILocalVideoTrack](/zh-CN/api-reference/rtc/web/interfaces/ilocalvideotrack), [ILocalAudioTrack](/zh-CN/api-reference/rtc/web/interfaces/ilocalaudiotrack)]&gt;

</ApiSignature>

创建用于屏幕共享的视频轨道。

<ParameterList title="Parameters">
<Parameter name="config" required>

<ParameterType>

[ScreenVideoTrackInitConfig](/zh-CN/api-reference/rtc/web/interfaces/screenvideotrackinitconfig)

</ParameterType>

屏幕共享的视频配置，包括编码配置、采集配置等。

</Parameter>
<Parameter name="withAudio" type="&quot;enable&quot;" required>

屏幕共享时是否同时分享**屏幕共享输入源**的音频。

- `enable`: 分享音频。
- `disable`: （默认）不分享音频。
- `auto`: 根据浏览器是否支持决定是否分享音频。
- [ScreenAudioTrackInitConfig](/zh-CN/api-reference/rtc/web/globals#screenaudiotrackinitconfig): 自定义音频共享的初始化配置，包含 3A 处理参数 (`AEC`、`AGC`、`ANS`）和本地音频播放设置。

  :::note[注意事项]
  - 该功能仅适用于支持 Web SDK 的浏览器桌面端，不支持移动端。具体支持列表详见[浏览器兼容性和已知问题](/zh-CN/realtime-media/rtc/reference/browser-compatibility)。
  - 关于各操作系统平台的浏览器版本及功能支持的补充说明如下：

    - 在 macOS 平台上，Chrome 74 及以上版本支持音视频共享，仅支持在共享 Chrome 标签页时分享音频。Firefox 和 Safari 14 及以上版本支持窗口和屏幕共享，不支持分享音频。
    - 在 Windows 平台上，Chrome 74 及以上版本和 Edge 支持在共享屏幕和浏览器标签页时分享音频，不支持在共享应用窗口时分享音频。Firefox 支持窗口和屏幕共享，不支持分享音频。
    - 在 ChromeOS 平台上，Chrome 支持在共享屏幕和共享浏览器标签页时分享音频，不支持在共享应用窗口时分享音频。
  - 设置了 `withAudio` 为 `enable` 后，还需要在屏幕共享的弹出框上，勾选**分享音频**才能真正生效。
  :::

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

Promise&lt;[[ILocalVideoTrack](/zh-CN/api-reference/rtc/web/interfaces/ilocalvideotrack), [ILocalAudioTrack](/zh-CN/api-reference/rtc/web/interfaces/ilocalaudiotrack)]&gt;

</ApiReturnType>

- 如果 `withAudio` 设为 `enable`，返回包含屏幕共享视频轨道和一个音频轨道的列表。如果用户没有勾选**分享音频**，SDK 会抛出错误。
- 如果 `withAudio` 设为 `disable`，返回屏幕共享的视频轨道。
- 如果 `withAudio` 设为 `auto` 或 `ScreenAudioTrackInitConfig`，在支持屏幕共享音频的浏览器上 SDK 会默认尝试分享音频。

  - 如果用户勾选了**分享音频**，会返回包含屏幕共享视频轨道和一个音频轨道的列表。
  - 如果用户没有勾选**分享音频**，只返回屏幕共享视频轨道。

</ApiReturns>

#### createScreenVideoTrack [2/3] [#createscreenvideotrack-23]

<ApiSignature>

createScreenVideoTrack(config: [ScreenVideoTrackInitConfig](/zh-CN/api-reference/rtc/web/interfaces/screenvideotrackinitconfig), withAudio: "disable"): Promise&lt;[ILocalVideoTrack](/zh-CN/api-reference/rtc/web/interfaces/ilocalvideotrack)&gt;

</ApiSignature>

创建用于屏幕共享的视频轨道。

<ParameterList title="Parameters">
<Parameter name="config" required>

<ParameterType>

[ScreenVideoTrackInitConfig](/zh-CN/api-reference/rtc/web/interfaces/screenvideotrackinitconfig)

</ParameterType>

屏幕共享的视频配置，包括编码配置、采集配置等。

</Parameter>
<Parameter name="withAudio" type="&quot;disable&quot;" required>

屏幕共享时是否同时分享**屏幕共享输入源**的音频。

- `enable`: 分享音频。
- `disable`: （默认）不分享音频。
- `auto`: 根据浏览器是否支持决定是否分享音频。
- [ScreenAudioTrackInitConfig](/zh-CN/api-reference/rtc/web/globals#screenaudiotrackinitconfig): 自定义音频共享的初始化配置，包含 3A 处理参数 (`AEC`、`AGC`、`ANS`）和本地音频播放设置。

  :::note[注意事项]
  - 该功能仅适用于支持 Web SDK 的浏览器桌面端，不支持移动端。具体支持列表详见[浏览器兼容性和已知问题](/zh-CN/realtime-media/rtc/reference/browser-compatibility)。
  - 关于各操作系统平台的浏览器版本及功能支持的补充说明如下：

    - 在 macOS 平台上，Chrome 74 及以上版本支持音视频共享，仅支持在共享 Chrome 标签页时分享音频。Firefox 和 Safari 14 及以上版本支持窗口和屏幕共享，不支持分享音频。
    - 在 Windows 平台上，Chrome 74 及以上版本和 Edge 支持在共享屏幕和浏览器标签页时分享音频，不支持在共享应用窗口时分享音频。Firefox 支持窗口和屏幕共享，不支持分享音频。
    - 在 ChromeOS 平台上，Chrome 支持在共享屏幕和共享浏览器标签页时分享音频，不支持在共享应用窗口时分享音频。
  - 设置了 `withAudio` 为 `enable` 后，还需要在屏幕共享的弹出框上，勾选**分享音频**才能真正生效。
  :::

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

Promise&lt;[ILocalVideoTrack](/zh-CN/api-reference/rtc/web/interfaces/ilocalvideotrack)&gt;

</ApiReturnType>

- 如果 `withAudio` 设为 `enable`，返回包含屏幕共享视频轨道和一个音频轨道的列表。如果用户没有勾选**分享音频**，SDK 会抛出错误。
- 如果 `withAudio` 设为 `disable`，返回屏幕共享的视频轨道。
- 如果 `withAudio` 设为 `auto` 或 `ScreenAudioTrackInitConfig`，在支持屏幕共享音频的浏览器上 SDK 会默认尝试分享音频。

  - 如果用户勾选了**分享音频**，会返回包含屏幕共享视频轨道和一个音频轨道的列表。
  - 如果用户没有勾选**分享音频**，只返回屏幕共享视频轨道。

</ApiReturns>

#### createScreenVideoTrack [3/3] [#createscreenvideotrack-33]

<ApiSignature>

createScreenVideoTrack(config: [ScreenVideoTrackInitConfig](/zh-CN/api-reference/rtc/web/interfaces/screenvideotrackinitconfig), withAudio?: "enable" | "disable" | "auto" | [ScreenAudioTrackInitConfig](/zh-CN/api-reference/rtc/web/globals#screenaudiotrackinitconfig)): Promise&lt;[[ILocalVideoTrack](/zh-CN/api-reference/rtc/web/interfaces/ilocalvideotrack), [ILocalAudioTrack](/zh-CN/api-reference/rtc/web/interfaces/ilocalaudiotrack)] | [ILocalVideoTrack](/zh-CN/api-reference/rtc/web/interfaces/ilocalvideotrack)&gt;

</ApiSignature>

创建用于屏幕共享的视频轨道。

<ParameterList title="Parameters">
<Parameter name="config" required>

<ParameterType>

[ScreenVideoTrackInitConfig](/zh-CN/api-reference/rtc/web/interfaces/screenvideotrackinitconfig)

</ParameterType>

屏幕共享的视频配置，包括编码配置、采集配置等。

</Parameter>
<Parameter name="withAudio" optional>

<ParameterType>

"enable" | "disable" | "auto" | [ScreenAudioTrackInitConfig](/zh-CN/api-reference/rtc/web/globals#screenaudiotrackinitconfig)

</ParameterType>

屏幕共享时是否同时分享**屏幕共享输入源**的音频。

- `enable`: 分享音频。
- `disable`: （默认）不分享音频。
- `auto`: 根据浏览器是否支持决定是否分享音频。
- [ScreenAudioTrackInitConfig](/zh-CN/api-reference/rtc/web/globals#screenaudiotrackinitconfig): 自定义音频共享的初始化配置，包含 3A 处理参数 (`AEC`、`AGC`、`ANS`) 和本地音频播放及采集设置。

  > - 该功能仅适用于支持 Web SDK 的浏览器桌面端，不支持移动端。具体支持列表详见[浏览器兼容性和已知问题](/zh-CN/realtime-media/rtc/reference/browser-compatibility)。
  > - 关于各操作系统平台的浏览器版本及功能支持的补充说明如下：
  >
  >   - 在 macOS 平台上，Chrome 74 及以上版本支持音视频共享，仅支持在共享 Chrome 标签页时分享音频。Firefox 和 Safari 14 及以上版本支持窗口和屏幕共享，不支持分享音频。
  >   - 在 Windows 平台上，Chrome 74 及以上版本和 Edge 支持在共享屏幕和浏览器标签页时分享音频，不支持在共享应用窗口时分享音频。Firefox 支持窗口和屏幕共享，不支持分享音频。
  >   - 在 ChromeOS 平台上，Chrome 支持在共享屏幕和共享浏览器标签页时分享音频，不支持在共享应用窗口时分享音频。
  > - 设置了 `withAudio` 为 `enable` 后，还需要在屏幕共享的弹出框上，勾选**分享音频**才能真正生效。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

Promise&lt;[[ILocalVideoTrack](/zh-CN/api-reference/rtc/web/interfaces/ilocalvideotrack), [ILocalAudioTrack](/zh-CN/api-reference/rtc/web/interfaces/ilocalaudiotrack)] | [ILocalVideoTrack](/zh-CN/api-reference/rtc/web/interfaces/ilocalvideotrack)&gt;

</ApiReturnType>

- 如果 `withAudio` 设为 `enable`，返回包含屏幕共享视频轨道和一个音频轨道的列表。如果用户没有勾选**分享音频**，SDK 会抛出错误。
- 如果 `withAudio` 设为 `disable`，返回屏幕共享的视频轨道。
- 如果 `withAudio` 设为 `auto` 或 `ScreenAudioTrackInitConfig`，在支持屏幕共享音频的浏览器上 SDK 会默认尝试分享音频。

  - 如果用户勾选了**分享音频**，会返回包含屏幕共享视频轨道和一个音频轨道的列表。
  - 如果用户没有勾选**分享音频**，只返回屏幕共享视频轨道。

</ApiReturns>

## Logger Methods [#logger-methods]

<a id="disablelogupload"></a>

### disableLogUpload [#disablelogupload]

<ApiSignature>

disableLogUpload(): void

</ApiSignature>

关闭日志上传。

日志上传默认是关闭状态，如果你调用了开启日志上传（[enableLogUpload](/zh-CN/api-reference/rtc/web/interfaces/iagorartc#enablelogupload))，可以通过本方法停止上传日志。

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="enablelogupload"></a>

### enableLogUpload [#enablelogupload]

<ApiSignature>

enableLogUpload(): void

</ApiSignature>

开启日志上传。开启后 SDK 的日志会上传到声网的服务器。

日志上传功能默认为关闭状态，如果你需要开启此功能，请确保在所有方法之前调用本方法。

> 如果没有成功加入频道，则服务器上无法查看日志信息。

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="setloglevel"></a>

### setLogLevel [#setloglevel]

<ApiSignature>

setLogLevel(level: number): void

</ApiSignature>

设置 SDK 的日志输出级别。

选择一个级别，你就可以看到在该级别及该级别以上所有级别的日志信息。

<ParameterList title="Parameters">
<Parameter name="level" type="number" required>

SDK 日志输出级别。按照输出日志最全到最少排列：

- 0: DEBUG。输出所有的 SDK 日志。
- 1: INFO。输出 INFO、WARNING 和 ERROR 级别的日志。
- 2: WARNING。输出 WARNING 和 ERROR 级别的日志。
- 3: ERROR。输出 ERROR 级别的日志。
- 4: NONE。不输出日志。

例如，如果你输入代码 `AgoraRTC.setLogLevel(1);`，就可以看到 INFO，WARNING 和 ERROR 级别的日志信息。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

## Media Devices Methods [#media-devices-methods]

<a id="getcameras"></a>

### getCameras [#getcameras]

<ApiSignature>

getCameras(skipPermissionCheck?: boolean): Promise&lt;MediaDeviceInfo[]&gt;

</ApiSignature>

该方法枚举可用的视频输入设备，比如摄像头。

调用成功后 SDK 会通过 [MediaDeviceInfo](https://developer.mozilla.org/en-US/docs/Web/API/MediaDeviceInfo) 对象返回可用的视频输入设备。

> 调用本方法会暂时打开摄像头以触发浏览器的媒体设备权限申请。在 Chrome 67+，Firefox 70+ 以及 Safari 12+ 等浏览器上没有媒体设备权限时，无法准确获取到设备信息。

<ParameterList title="Parameters">
<Parameter name="skipPermissionCheck" type="boolean" optional>

是否跳过权限检查。你可以通过将该参数设置成 `true` 来跳过媒体设备权限申请步骤，但是 SDK 无法保证可以通过本方法获取准确的媒体设备信息。

- `true`: 跳过权限检查。
- `false`:（默认）不跳过权限检查。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

Promise&lt;MediaDeviceInfo[]&gt;

</ApiReturnType>

</ApiReturns>

<a id="getdevices"></a>

### getDevices [#getdevices]

<ApiSignature>

getDevices(skipPermissionCheck?: boolean): Promise&lt;MediaDeviceInfo[]&gt;

</ApiSignature>

该方法枚举可用的媒体输入和输出设备，比如麦克风、摄像头、耳机等。
 调用成功后 SDK 会通过 [MediaDeviceInfo](https://developer.mozilla.org/en-US/docs/Web/API/MediaDeviceInfo) 对象返回可用的媒体设备。

:::note[注意事项]
- 调用本方法会暂时打开摄像头和麦克风以触发浏览器的媒体设备权限申请。在 Chrome 67+，Firefox 70+ 以及 Safari 12+ 等浏览器上没有媒体设备权限时，无法准确获取到设备信息。
- 即使是对于同一设备，SDK 返回的 [MediaDeviceInfo.deviceId](https://developer.mozilla.org/en-US/docs/Web/API/MediaDeviceInfo/deviceId) 也可能会发生变化，例如用户清除 Cookie 后，`deviceId` 就会被重置。因此，声网不建议基于 `deviceId` 开发业务逻辑。
:::

```javascript
getDevices().then(devices => {
  console.log("first device id", devices[0].deviceId);
}).catch(e => {
  console.log("get devices error!", e);
});
```

<ParameterList title="Parameters">
<Parameter name="skipPermissionCheck" type="boolean" optional>

是否跳过权限检查。你可以通过将该参数设置成 `true` 来跳过媒体设备权限申请步骤，但是 SDK 无法保证可以通过本方法获取准确的媒体设备信息。

- `true`: 跳过权限检查。
- `false`:（默认）不跳过权限检查。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

Promise&lt;MediaDeviceInfo[]&gt;

</ApiReturnType>

</ApiReturns>

<a id="getelectronscreensources"></a>

### getElectronScreenSources [#getelectronscreensources]

<ApiSignature>

getElectronScreenSources(type?: [ScreenSourceType](/zh-CN/api-reference/rtc/web/globals#screensourcetype)): Promise&lt;[ElectronDesktopCapturerSource](/zh-CN/api-reference/rtc/web/interfaces/electrondesktopcapturersource)[]&gt;

</ApiSignature>

在 Electron 环境下获取屏幕共享源。

调用成功后 SDK 会返回一组 [ElectronDesktopCapturerSource](/zh-CN/api-reference/rtc/web/interfaces/electrondesktopcapturersource) 对象。

> 如果你的 Electron 运行环境开启了 contextIsolation 配置，调用此方法会报错。你需要自己使用 contextBridge.exposeInMainWorld 来获取视频源 id。

```text
// preload.js

const {
  contextBridge, desktopCapturer
} = require("electron");

contextBridge.exposeInMainWorld(
  "electronDesktopCapturer", {
    getSources: async (...args) => {
      const sources = await desktopCapturer.getSources(...args);
      return sources;
    }
  }
);

// renderer.js
(async () => {
  sources = await window.electronDesktopCapturer.getSources(["window", "screen"]);
  const source = sources[0];   // just for example ,you shuould make an UI for user to select the exact source.
  const screenVideoTrack = await AgoraRTC.createScreenVideoTrack({ electronScreenSourceId: source.id });
})()
```

<ParameterList title="Parameters">
<Parameter name="type" optional>

<ParameterType>

[ScreenSourceType](/zh-CN/api-reference/rtc/web/globals#screensourcetype)

</ParameterType>

需要获取的共享源类型（窗口/应用/屏幕），详见 [ScreenSourceType](/zh-CN/api-reference/rtc/web/globals#screensourcetype)。如果为空则获取所有可以获取的共享源。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

Promise&lt;[ElectronDesktopCapturerSource](/zh-CN/api-reference/rtc/web/interfaces/electrondesktopcapturersource)[]&gt;

</ApiReturnType>

</ApiReturns>

<a id="getmicrophones"></a>

### getMicrophones [#getmicrophones]

<ApiSignature>

getMicrophones(skipPermissionCheck?: boolean): Promise&lt;MediaDeviceInfo[]&gt;

</ApiSignature>

该方法枚举可用的音频输入设备，比如麦克风。

调用成功后 SDK 会通过 [MediaDeviceInfo](https://developer.mozilla.org/en-US/docs/Web/API/MediaDeviceInfo) 对象返回可用的音频输入设备。

> 调用本方法会暂时打开麦克风以触发浏览器的媒体设备权限申请。在 Chrome 67+，Firefox 70+ 以及 Safari 12+ 等浏览器上没有媒体设备权限时，无法准确获取到设备信息。

<ParameterList title="Parameters">
<Parameter name="skipPermissionCheck" type="boolean" optional>

是否跳过权限检查。你可以通过将该参数设置成 `true` 来跳过媒体设备权限申请步骤，但是 SDK 无法保证可以通过本方法获取准确的媒体设备信息。

- `true`: 跳过权限检查。
- `false`:（默认）不跳过权限检查。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

Promise&lt;MediaDeviceInfo[]&gt;

</ApiReturnType>

</ApiReturns>

<a id="getplaybackdevices"></a>

### getPlaybackDevices [#getplaybackdevices]

<ApiSignature>

getPlaybackDevices(skipPermissionCheck?: boolean): Promise&lt;MediaDeviceInfo[]&gt;

</ApiSignature>

:::info[自从]
*4.1.0*
:::

该方法枚举可用的音频播放设备，比如扬声器。

调用成功后 SDK 会通过 [MediaDeviceInfo](https://developer.mozilla.org/en-US/docs/Web/API/MediaDeviceInfo) 对象返回可用的音频播放设备。

> - Chrome、Firefox、Edge 浏览器上支持该方法。Safari 支持情况如下：macOS 上的 Safari 18.4 及以上版本支持该方法；iOS 上的 Safari 26 及以上版本支持该方法。
> - 调用本方法会暂时打开麦克风以触发浏览器的媒体设备权限申请。在 Chrome 67+ 和 Firefox 70+ 浏览器上，没有媒体设备权限时无法获取到准确的设备信息。

<ParameterList title="Parameters">
<Parameter name="skipPermissionCheck" type="boolean" optional>

是否跳过权限检查。你可以通过将该参数设置成 `true` 来跳过媒体设备权限申请步骤，但是 SDK 无法保证可以通过本方法获取准确的媒体设备信息。

- `true`: 跳过权限检查。
- `false`:（默认）不跳过权限检查。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

Promise&lt;MediaDeviceInfo[]&gt;

</ApiReturnType>

</ApiReturns>

## Other Methods [#other-methods]

<a id="checkaudiotrackisactive"></a>

### checkAudioTrackIsActive [#checkaudiotrackisactive]

<ApiSignature>

checkAudioTrackIsActive(track: [ILocalAudioTrack](/zh-CN/api-reference/rtc/web/interfaces/ilocalaudiotrack) | [IRemoteAudioTrack](/zh-CN/api-reference/rtc/web/interfaces/iremoteaudiotrack), timeout?: number): Promise&lt;boolean&gt;

</ApiSignature>

检测音频轨道是否活跃。

SDK 通过检测指定时间范围内音量是否发生变化来判断音频轨道是否活跃。

声网建议通过此方法在开始通话前对音频输入设备进行可用性检测。你可以将麦克风采集到的音频轨道作为参数传入该方法，判断麦克风是否正常运行。

:::note[注意事项]
- 极为安静的环境下可能检测失败，所以声网建议你在使用此方法的时候提示用户发出声响。
- 当音频轨道被 mute 时，会返回 `false`。
- 不建议频繁调用此方法。
:::

```javascript
const audioTrack = await AgoraRTC.createMicrophoneAudioTrack({ microphoneId });
AgoraRTC.checkAudioTrackIsActive(audioTrack).then(result => {
  console.log(`${ microphoneLabel } is ${ result ? "available" : "unavailable" }`);
}).catch(e => {
  console.log("check audio track error!", e);
});
```

<ParameterList title="Parameters">
<Parameter name="track" required>

<ParameterType>

[ILocalAudioTrack](/zh-CN/api-reference/rtc/web/interfaces/ilocalaudiotrack) | [IRemoteAudioTrack](/zh-CN/api-reference/rtc/web/interfaces/iremoteaudiotrack)

</ParameterType>

需要进行检测的本地或远端音频轨道。

</Parameter>
<Parameter name="timeout" type="number" optional>

音频轨道检测的超时时间，单位为毫秒，默认 5,000 毫秒。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

Promise&lt;boolean&gt;

</ApiReturnType>

传入该方法的音频轨道中的音量大小是否发生了变化：

- `true`: 音量大小有变化。对于麦克风音频轨道，说明音频采集设备采集到了声音。
- `false`: 音量大小未变化，说明音频采集设备没有采集到声音，或自定义音频轨道中没有音量变化，或音频轨道被 mute。

</ApiReturns>

<a id="checksystemrequirements"></a>

### checkSystemRequirements [#checksystemrequirements]

<ApiSignature>

checkSystemRequirements(): boolean

</ApiSignature>

检查 Agora Web SDK 对正在使用的浏览器的适配情况。

该方法必须在创建客户端对象 [createClient](/zh-CN/api-reference/rtc/web/interfaces/iagorartc#createclient) 之前调用。

<ApiReturns>

<ApiReturnType>

boolean

</ApiReturnType>

是否支持当前浏览器。

- `true`: 支持。
- `false`: 不支持。

</ApiReturns>

<a id="checkvideotrackisactive"></a>

### checkVideoTrackIsActive [#checkvideotrackisactive]

<ApiSignature>

checkVideoTrackIsActive(track: [ILocalVideoTrack](/zh-CN/api-reference/rtc/web/interfaces/ilocalvideotrack) | [IRemoteVideoTrack](/zh-CN/api-reference/rtc/web/interfaces/iremotevideotrack), timeout?: number): Promise&lt;boolean&gt;

</ApiSignature>

检测视频轨道是否活跃。

SDK 通过检测指定时间范围内视频图像是否发生变动来判断视频轨道是否活跃。

声网建议通过此方法在开始通话前对视频输入设备进行可用性检测。你可以将摄像头采集到的视频轨道作为参数传入该方法，判断摄像头是否正常运行。

:::note[注意事项]
- 当视频轨道被 mute 时，会返回 `false`。
- 不建议频繁调用此方法。
:::

```javascript
const videoTrack = await AgoraRTC.createCameraVideoTrack({ cameraId });
AgoraRTC.checkVideoTrackIsActive(videoTrack).then(result => {
  console.log(`${ cameraLabel } is ${ result ? "available" : "unavailable" }`);
}).catch(e => {
  console.log("check video track error!", e);
});
```

<ParameterList title="Parameters">
<Parameter name="track" required>

<ParameterType>

[ILocalVideoTrack](/zh-CN/api-reference/rtc/web/interfaces/ilocalvideotrack) | [IRemoteVideoTrack](/zh-CN/api-reference/rtc/web/interfaces/iremotevideotrack)

</ParameterType>

需要进行检测的本地或远端视频轨道。

</Parameter>
<Parameter name="timeout" type="number" optional>

视频轨道检测的超时时间，单位为毫秒，默认 5,000 毫秒。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

Promise&lt;boolean&gt;

</ApiReturnType>

传入该方法的视频轨道中的图像是否发生了变动：

- `true`: 视频画面发生变动。对于摄像头视频轨道，说明视频采集设备采集到了画面。
- `false`: 视频画面未变动，说明视频采集设备异常或被完全遮挡，或视频轨道被 mute。

</ApiReturns>

<a id="createchannelmediarelayconfiguration"></a>

### createChannelMediaRelayConfiguration [#createchannelmediarelayconfiguration]

<ApiSignature>

createChannelMediaRelayConfiguration(): [IChannelMediaRelayConfiguration](/zh-CN/api-reference/rtc/web/interfaces/ichannelmediarelayconfiguration)

</ApiSignature>

创建跨频道媒体流转发的配置对象。

<ApiReturns>

<ApiReturnType>

[IChannelMediaRelayConfiguration](/zh-CN/api-reference/rtc/web/interfaces/ichannelmediarelayconfiguration)

</ApiReturnType>

</ApiReturns>

<a id="getlisteners"></a>

### getListeners [#getlisteners]

<ApiSignature>

getListeners(event: string): Function[]

</ApiSignature>

Inherited from EventEmitter.getListeners

指定一个事件名，获取当前所有监听这个事件的回调函数。

<ParameterList title="Parameters">
<Parameter name="event" type="string" required>

事件名称。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

Function[]

</ApiReturnType>

</ApiReturns>

<a id="getsupportedcodec"></a>

### getSupportedCodec [#getsupportedcodec]

<ApiSignature>

getSupportedCodec(): Promise&lt;object&gt;

</ApiSignature>

获取 Agora Web SDK 对当前浏览器支持的编解码格式。

调用该方法会返回声网服务与当前浏览器同时支持的编解码格式。目前而言，视频支持 VP8 及 H.264 格式，音频支持 OPUS 格式。

:::note[注意事项]
- 该方法支持所有浏览器。对于不支持 WebRTC 或无法识别的浏览器环境，编解码列表返回为空。
- 返回的音视频编码为浏览器通过 SDP 声称的编码类型，为参考值。
- 目前部分安卓手机 H.264 与其他平台 H.264 存在无法互通或单通问题，对于这部分机型推荐使用 VP8 编码格式。
:::

```javascript
AgoraRTC.getSupportedCodec().then(result => {
 console.log(`Supported video codec: ${result.video.join(",")}`);
 console.log(`Supported audio codec: ${result.audio.join(",")}`);
});
```

<ApiReturns>

<ApiReturnType>

Promise&lt;object&gt;

</ApiReturnType>

调用该方法会返回一个 `Promise` 对象，在 `.then(function(result){})` 回调中，`result` 包含以下属性：

- `video`: 数组类型，支持的视频编解码格式。可能含有 `"H264"`、`"VP8"` 两种取值，或为空数组。
- `audio`: 数组类型，支持的音频编解码格式。可能含有 `"OPUS"`，或为空数组。

</ApiReturns>

<a id="off"></a>

### off [#off]

<ApiSignature>

off(event: string, listener: Function): void

</ApiSignature>

Inherited from EventEmitter.off

取消一个指定事件的监听。

<ParameterList title="Parameters">
<Parameter name="event" type="string" required>

指定事件的名称。

</Parameter>
<Parameter name="listener" type="Function" required>

监听事件时传入的回调函数。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="on"></a>

### on [#on]

#### on [1/6] [#on-16]

<ApiSignature>

on(event: "camera-changed", listener: typeof event_camera_changed): void

</ApiSignature>

Overrides EventEmitter.on

:::info[自从]
*4.18.0*
:::

<ParameterList title="Parameters">
<Parameter name="event" type="&quot;camera-changed&quot;" required>

事件名称。

</Parameter>
<Parameter name="listener" type="typeof event_camera_changed" required>

详见 [event_camera_changed](/zh-CN/api-reference/rtc/web/interfaces/iagorartc#event_camera_changed)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

#### on [2/6] [#on-26]

<ApiSignature>

on(event: "microphone-changed", listener: typeof event_microphone_changed): void

</ApiSignature>

Overrides EventEmitter.on

:::info[自从]
*4.18.0*
:::

<ParameterList title="Parameters">
<Parameter name="event" type="&quot;microphone-changed&quot;" required>

事件名称。

</Parameter>
<Parameter name="listener" type="typeof event_microphone_changed" required>

详见 [event_microphone_changed](/zh-CN/api-reference/rtc/web/interfaces/iagorartc#event_microphone_changed)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

#### on [3/6] [#on-36]

<ApiSignature>

on(event: "playback-device-changed", listener: typeof event_playback_device_changed): void

</ApiSignature>

Overrides EventEmitter.on

:::info[自从]
*4.18.0*
:::

<ParameterList title="Parameters">
<Parameter name="event" type="&quot;playback-device-changed&quot;" required>

事件名称。

</Parameter>
<Parameter name="listener" type="typeof event_playback_device_changed" required>

详见 [event_playback_device_changed](/zh-CN/api-reference/rtc/web/interfaces/iagorartc#event_playback_device_changed)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

#### on [4/6] [#on-46]

<ApiSignature>

on(event: "autoplay-failed", listener: typeof event_autoplay_failed): void

</ApiSignature>

Overrides EventEmitter.on

:::info[自从]
*4.18.0*
:::

<ParameterList title="Parameters">
<Parameter name="event" type="&quot;autoplay-failed&quot;" required>

事件名称。

</Parameter>
<Parameter name="listener" type="typeof event_autoplay_failed" required>

详见 [event_autoplay_failed](/zh-CN/api-reference/rtc/web/interfaces/iagorartc#event_autoplay_failed)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

#### on [5/6] [#on-56]

<ApiSignature>

on(event: "security-policy-violation", listener: typeof event_security_policy_violation): void

</ApiSignature>

Overrides EventEmitter.on

:::info[自从]
*4.18.0*
:::

<ParameterList title="Parameters">
<Parameter name="event" type="&quot;security-policy-violation&quot;" required>

事件名称。

</Parameter>
<Parameter name="listener" type="typeof event_security_policy_violation" required>

详见 [event_security_policy_violation](/zh-CN/api-reference/rtc/web/interfaces/iagorartc#event_security_policy_violation)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

#### on [6/6] [#on-66]

<ApiSignature>

on(event: "audio-context-state-changed", listener: typeof event_audio_context_state_changed): void

</ApiSignature>

Overrides EventEmitter.on

:::info[自从]
*4.20.0*
:::

<ParameterList title="Parameters">
<Parameter name="event" type="&quot;audio-context-state-changed&quot;" required>

事件名称。

</Parameter>
<Parameter name="listener" type="typeof event_audio_context_state_changed" required>

详见 [event_audio_context_state_changed](/zh-CN/api-reference/rtc/web/interfaces/iagorartc#event_audio_context_state_changed)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="once"></a>

### once [#once]

<ApiSignature>

once(event: string, listener: Function): void

</ApiSignature>

Inherited from EventEmitter.once

监听一个指定的事件，当事件触发时会调用传入的回调函数。

当监听后事件第一次触发时，该监听和回调函数就会被立刻移除，也就是只监听一次指定事件。

<ParameterList title="Parameters">
<Parameter name="event" type="string" required>

指定事件的名称。

</Parameter>
<Parameter name="listener" type="Function" required>

传入的回调函数。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="preload"></a>

### preload [#preload]

<ApiSignature>

preload(appid: string, channel: string, token: string | null, uid?: [UID](/zh-CN/api-reference/rtc/web/globals#uid) | null): Promise&lt;void&gt;

</ApiSignature>

使用`appid`、`channel`、`token`、`uid` 预加载频道。

调用该方法可以减少观众频繁切换频道时加入频道的时间，从而缩短观众听到主播首帧音频以及看到首帧画面的耗时，提升观众端的视频体验。

如果当前频道已经成功预加载，观众加入、离开频道后如需再次加入该频道，只要预加载时传入的 Token 仍在有效期内，则无需重新预加载。

> - 预加载的有效时间只有两分钟。
> - 为了保护页面性能，此方法采取一次性尽力而为的策略，无法保证一定成功。但预加载失败不会影响观众正常加入频道，也不会增加加入频道的耗时。
> - 系统最多缓存 10 条最新的不同预加载数据。
> - 目前此方法不支持通过 proxy 代理进行转发。

<ParameterList title="Parameters">
<Parameter name="appid" type="string" required>

你的声网项目的 [App ID](/zh-CN/introduction/glossary)。

</Parameter>
<Parameter name="channel" type="string" required>

标识通话的频道名称，长度在 64 字节以内的字符串。以下为支持的字符集范围（共 89 个字符）:

- 26 个小写字母 a-z。
- 26 个大写字母 A-Z。
- 10 个数字 0-9。
- 空格。
- "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "&lt;", "=", ".", "&gt;", "?", "@", "[", "]", "^", "_", "\{", "\}", "|", "~", ","。

</Parameter>
<Parameter name="token" type="string | null" required>

用于鉴权的 token。

- 如果你的项目没有开启 token 鉴权，这里填 `null`。
- 安全要求不高: 你可以使用控制台生成的临时 token，详见[获取 RTC 临时 Token](/zh-CN/realtime-media/rtc/build/setup-and-access/enable-service)。
- 安全要求高：传入从你的服务端获得的正式 token，详见[使用 Token 鉴权](/zh-CN/realtime-media/rtc/build/setup-and-access/token-authentication)。

</Parameter>
<Parameter name="uid" optional>

<ParameterType>

[UID](/zh-CN/api-reference/rtc/web/globals#uid) | null

</ParameterType>

标识用户的 ID。整数或字符串，ASCII 字符，需保证唯一性。如果不指定或设为 `null`，服务器会自动分配一个整数型 uid。

- 如果使用整数作为用户 ID，需为 32 位无符号整数。建议设置范围：0 到 (2³² - 1)。
- 如果使用字符串作为用户 ID，长度不超过 255 个字符。

为保证最佳的用户体验，声网强烈建议你不要使用字符串作为用户 ID。

:::note[注意事项]
- 一个频道内的所有用户必须使用同样类型的 `uid`，即必须都为整数或都为字符串。
- 使用字符串作为用户 ID 支持与 Native SDK 2.8 及以上版本互通，请确保 Native SDK 使用 User Account 加入频道。详见[使用 String 型的用户名](/zh-CN/reference/faq/integration/string_uid)。
- 为保证水晶球数据的准确性，建议自行指定 `uid` 并保证唯一性。
:::

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

Promise&lt;void&gt;

</ApiReturnType>

</ApiReturns>

<a id="processexternalmediaaec"></a>

### processExternalMediaAEC [#processexternalmediaaec]

<ApiSignature>

processExternalMediaAEC(element: HTMLMediaElement): void

</ApiSignature>

:::info[自从]
*4.5.0*
:::

对本地播放的音频启用回声消除。

在多个用户同时播放一个媒体文件的场景中，例如一起看电影，如果用户 A 在 Chrome 浏览器上通过 [HTMLMediaElement](https://developer.mozilla.org/zh-CN/docs/Web/API/HTMLMediaElement) 使用扬声器播放媒体文件，扬声器播放的声音会和人声一起被 SDK 采集，因此其他用户会听到自己本地播放的媒体音频以及用户 A 发送的媒体音频，从而产生回声。针对这种情况，你可以调用 `processExternalMediaAEC` 方法传入 `HTMLMediaElement`，对本地播放的媒体进行回声消除，提升音频体验。

```javascript
<audio crossOrigin="anonymous" src="http://www.test.com/test.mp3" id="audioDom"></audio>
<script>
  const element = document.getElementById("audioDom");
  AgoraRTC.processExternalMediaAEC(element);
</script>
```

:::note[注意事项]
如果本地播放的媒体元素的地址是跨域地址，必须设置 [HTMLMediaElement](https://developer.mozilla.org/zh-CN/docs/Web/API/HTMLMediaElement) 中的 `crossOrigin` 属性为 `"anonymous"` 以允许跨域媒体被重采集。
:::

<ParameterList title="Parameters">
<Parameter name="element" type="HTMLMediaElement" required>

需要进行回声消除的媒体元素，详见 [HTMLMediaElement](https://developer.mozilla.org/zh-CN/docs/Web/API/HTMLMediaElement)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="registerextensions"></a>

### registerExtensions [#registerextensions]

<ApiSignature>

registerExtensions(extensions: IExtension&lt;any&gt;[]): void

</ApiSignature>

:::info[自从]
*4.10.0*
:::

注册插件。

<ParameterList title="Parameters">
<Parameter name="extensions" type="IExtension &amp; lt;any &amp; gt;[]" required>

插件实例。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="removealllisteners"></a>

### removeAllListeners [#removealllisteners]

<ApiSignature>

removeAllListeners(event?: string): void

</ApiSignature>

Inherited from EventEmitter.removeAllListeners

指定一个事件，取消其所有的监听。

<ParameterList title="Parameters">
<Parameter name="event" type="string" optional>

指定事件的名称，如果没有指定事件，则取消所有事件的所有监听。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="resumeaudiocontext"></a>

### resumeAudioContext [#resumeaudiocontext]

<ApiSignature>

resumeAudioContext(): void

</ApiSignature>

恢复音视频播放。

在某些版本的 iOS 设备上，App 通话被微信通话或系统电话打断后有概率无法自动恢复。你可以调用该方法恢复 App 通话。

声网推荐你通过 [IAgoraRTC.on](/zh-CN/api-reference/rtc/web/interfaces/iagorartc#on) 监听 `"audio-context-state-changed"` 事件，并在回调函数 [event_audio_context_state_changed](/zh-CN/api-reference/rtc/web/interfaces/iagorartc#event_audio_context_state_changed) 中进行以下处理：

- 当状态变为 `"interrupted"` 时，弹窗提示用户 App 通话被打断，需要点击按钮恢复通话。用户点击按钮后，调用 `resumeAudioContext`。
- 当状态变为 `"running"` 时，关闭弹窗。

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="setarea"></a>

### setArea [#setarea]

<ApiSignature>

setArea(area: [AREAS](/zh-CN/api-reference/rtc/web/enums/areas)[] | object): void

</ApiSignature>

:::info[自从]
*4.2.0*
:::

设置访问区域。

该功能为高级设置，适用于有访问安全限制的场景。

默认情况下，SDK 会就近选择声网服务器进行连接。设置访问区域之后，SDK 只会连接到指定区域内的声网服务器。

```javascript
// 指定仅访问北美的服务器。
AgoraRTC.setArea({
  areaCode:"NORTH_AMERICA"
})
```

<ParameterList title="Parameters">
<Parameter name="area" required>

<ParameterType>

[AREAS](/zh-CN/api-reference/rtc/web/enums/areas)[] | object

</ParameterType>

服务器的访问区域。区域码详见 [AREAS](/zh-CN/api-reference/rtc/web/enums/areas)。你可以设置 `areaCode` 参数指定单个访问区域。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="startlastmileprobetest"></a>

### startLastmileProbeTest [#startlastmileprobetest]

<ApiSignature>

startLastmileProbeTest(appid: string, channel: string, token: string | null, uid?: [UID](/zh-CN/api-reference/rtc/web/globals#uid) | null): Promise&lt;[LastmileProbeResult](/zh-CN/api-reference/rtc/web/interfaces/lastmileproberesult)&gt;

</ApiSignature>

在通话前对客户端与边缘节点之间的网络质量进行检测。

:::info[自从]
*4.24.1*
:::

<ParameterList title="Parameters">
<Parameter name="appid" type="string" required>

你的声网项目的 [App ID](/zh-CN/introduction/glossary)。

</Parameter>
<Parameter name="channel" type="string" required>

标识通话的频道名称，长度在 64 字节以内的字符串。以下为支持的字符集范围（共 89 个字符）:

- 26 个小写字母 a-z。
- 26 个大写字母 A-Z。
- 10 个数字 0-9。
- 空格。
- "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "&lt;", "=", ".", "&gt;", "?", "@", "[", "]", "^", "_", "\{", "\}", "|", "~", ","。

</Parameter>
<Parameter name="token" type="string | null" required>

用于鉴权的 Token。

- 如果你的项目没有开启 Token 鉴权，这里填 `null`。
- 安全要求不高: 你可以使用控制台生成的临时 Token，详见[获取 RTC 临时 Token](/zh-CN/realtime-media/rtc/build/setup-and-access/enable-service)。
- 安全要求高：传入从你的服务端获得的正式 Token，详见[使用 Token 鉴权](/zh-CN/realtime-media/rtc/build/setup-and-access/token-authentication)。

</Parameter>
<Parameter name="uid" optional>

<ParameterType>

[UID](/zh-CN/api-reference/rtc/web/globals#uid) | null

</ParameterType>

标识用户的 ID。整数或字符串，ASCII 字符，需保证唯一性。如果不指定或设为 `null`，服务器会自动分配一个整数型 uid。

- 如果使用整数作为用户 ID，需为 32 位无符号整数。建议设置范围：0 到 (2³² - 1)。
- 如果使用字符串作为用户 ID，长度不超过 255 个字符。

为保证最佳的用户体验，声网强烈建议你不要使用字符串作为用户 ID。

:::note[注意事项]
- 一个频道内的所有用户必须使用同样类型的 `uid`，即必须都为整数或都为字符串。
- 使用字符串作为用户 ID 支持与 Native SDK 2.8 及以上版本互通，请确保 Native SDK 使用 User Account 加入频道。详见[使用 String 型的用户名](/zh-CN/reference/faq/integration/string_uid)。
- 为保证水晶球数据的准确性，建议自行指定 `uid` 并保证唯一性。
:::

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

Promise&lt;[LastmileProbeResult](/zh-CN/api-reference/rtc/web/interfaces/lastmileproberesult)&gt;

</ApiReturnType>

</ApiReturns>