设备管理

音视频设备管理相关的 API。

音频设备

getCurrentMicDeviceId

获取当前使用的麦克风设备 ID。

方法签名

typescript

getCurrentMicDeviceId(): string | undefined

使用示例

javascript

const currentMicId = engine.getCurrentMicDeviceId();
console.log('当前麦克风 ID:', currentMicId);

switchMicrophone

切换麦克风设备。

方法签名

typescript

switchMicrophone(deviceId: string): Promise<void>

参数说明

参数	类型	描述
deviceId	string	麦克风设备 ID

使用示例

javascript

// 获取麦克风列表
const microphones = await AliRtcEngine.getMicrophoneList();

// 切换到第一个麦克风
if (microphones.length > 0) {
  await engine.switchMicrophone(microphones[0].deviceId);
}

startAudioCapture

开始音频采集。

方法签名

typescript

startAudioCapture(deviceId?: string): Promise<void>

参数说明

参数	类型	描述
deviceId	string	(可选) 麦克风设备 ID

使用示例

javascript

// 使用默认麦克风
await engine.startAudioCapture();

// 使用指定麦克风
await engine.startAudioCapture('specific-device-id');

stopAudioCapture

停止音频采集。

方法签名

typescript

stopAudioCapture(): void

说明

调用此接口后，入会后、离会再入会，采集设备保持关闭状态

setAudioConstraints

设置音频采集参数。

方法签名

typescript

setAudioConstraints(constraints: MediaTrackConstraints): Promise<void>

参数说明

参数	类型	描述
constraints	MediaTrackConstraints	音频采集参数

使用示例

javascript

// 设置音频采集参数
await engine.setAudioConstraints({
  echoCancellation: true,
  noiseSuppression: true,
  autoGainControl: true,
  sampleRate: 48000,
  channelCount: 1,
});

视频设备

switchCamera

切换摄像头。

方法签名

typescript

switchCamera(deviceId: string): Promise<void>

参数说明

参数	类型	描述
deviceId	string	摄像头设备 ID

使用示例

javascript

// 获取摄像头列表
const cameras = await AliRtcEngine.getCameraList();

// 切换到第一个摄像头
if (cameras.length > 0) {
  await engine.switchCamera(cameras[0].deviceId);
}

startPreview

开始本地视频预览。

方法签名

typescript

startPreview(videoTrack?: AliRtcVideoTrack): Promise<void>

参数说明

参数	类型	描述
videoTrack	AliRtcVideoTrack	(可选) 视频轨道类型

使用示例

javascript

// 设置预览视图
engine.setLocalViewConfig('local-video', 1);

// 开始预览
await engine.startPreview(1);

stopPreview

停止本地视频预览。

方法签名

typescript

stopPreview(): Promise<void>

使用示例

javascript

await engine.stopPreview();

setCameraCapturerConfiguration

设置摄像头采集配置。

方法签名

typescript

setCameraCapturerConfiguration(config: AliEngineCameraCapturerConfiguration): Promise<void>

参数说明

参数	类型	描述
config	AliEngineCameraCapturerConfiguration	摄像头采集配置

AliEngineCameraCapturerConfiguration 接口

typescript

interface AliEngineCameraCapturerConfiguration {
  width?: number; // 视频宽度（像素）
  height?: number; // 视频高度（像素）
  frameRate?: number; // 采集帧率（fps）
  maxSendFrameRate?: number; // 最大发送帧率（fps）
  bitrate?: number; // 码率（kbps）
  cameraDirection?: AliRtcCameraDirection; // 摄像头方向
  deviceId?: string; // 设备ID
}

配置参数详解

视频分辨率 (width & height)

分辨率类型	宽度	高度	适用场景
低清	320	240	网络条件较差
标清	640	480	一般通话场景
高清	1280	720	高质量通话
全高清	1920	1080	专业会议场景

帧率 (frameRate & maxSendFrameRate)

frameRate: 摄像头采集帧率，建议值：
- 15: 标准帧率，适合大多数场景
- 30: 高帧率，适合动态内容较多的场景
- 60: 超高帧率，适合游戏或高动态场景
maxSendFrameRate: 最大发送帧率，用于限制网络传输时的帧率
- 通常设置为采集帧率的一半或相等
- 可根据网络状况动态调整

码率 (bitrate)

推荐码率配置（单位：kbps）：

分辨率	15fps	30fps
320x240	200	400
640x480	500	1000
1280x720	1200	2000
1920x1080	2000	4000

摄像头方向 (cameraDirection)

typescript

enum AliRtcCameraDirection {
  CAMERA_INVALID = -1, // 无效
  CAMERA_REAR = 0, // 后置摄像头
  CAMERA_FRONT = 1, // 前置摄像头
}

使用示例

基础配置

javascript

// 标清配置
await engine.setCameraCapturerConfiguration({
  width: 640,
  height: 480,
  frameRate: 15,
  maxSendFrameRate: 15,
  bitrate: 500,
  cameraDirection: AliRtcEngine.AliRtcCameraDirection.CAMERA_FRONT,
});

高清配置

javascript

// 高清配置
await engine.setCameraCapturerConfiguration({
  width: 1280,
  height: 720,
  frameRate: 30,
  maxSendFrameRate: 30,
  bitrate: 2000,
  cameraDirection: AliRtcEngine.AliRtcCameraDirection.CAMERA_FRONT,
});

指定设备配置

javascript

// 获取摄像头列表
const cameras = await AliRtcEngine.getCameraList();

// 使用指定摄像头
await engine.setCameraCapturerConfiguration({
  width: 1280,
  height: 720,
  frameRate: 30,
  maxSendFrameRate: 30,
  bitrate: 2000,
  deviceId: cameras[0].deviceId,
});

自适应配置

javascript

// 根据网络状况自适应配置
function getAdaptiveConfig(networkQuality) {
  const configs = {
    poor: {
      width: 320,
      height: 240,
      frameRate: 10,
      maxSendFrameRate: 10,
      bitrate: 200,
    },
    normal: {
      width: 640,
      height: 480,
      frameRate: 15,
      maxSendFrameRate: 15,
      bitrate: 500,
    },
    good: {
      width: 1280,
      height: 720,
      frameRate: 30,
      maxSendFrameRate: 30,
      bitrate: 2000,
    },
  };

  return configs[networkQuality] || configs.normal;
}

// 应用自适应配置
const config = getAdaptiveConfig('good');
await engine.setCameraCapturerConfiguration(config);

最佳实践

分辨率选择
- 移动端建议使用 640x480 或 1280x720
- PC端可以使用更高分辨率如 1920x1080
帧率设置
- 一般通话场景使用 15fps
- 需要流畅画面时使用 30fps
- 避免使用过高帧率增加CPU负担
码率配置
- 根据分辨率和帧率合理设置码率
- 网络条件不好时适当降低码率
设备兼容性
- 部分设备可能不支持某些分辨率
- 建议先检测设备能力再设置配置

注意事项

配置参数为可选，未设置的参数将使用默认值
修改配置后需要重新开始预览才能生效
某些设备可能不支持所有配置组合
高分辨率和高帧率会增加CPU和网络负担

enableLocalVideo

启用或禁用本地视频。

方法签名

typescript

enableLocalVideo(enabled?: boolean): Promise<void>

参数说明

参数	类型	描述
enabled	boolean	(可选) 是否启用，默认 true

说明

在纯音频模式下无法启用本地视频
启用时会开始摄像头采集
禁用时会停止摄像头采集
部分 Android 设备需要重新创建视频轨道以避免切换摄像头错误

使用示例

javascript

// 启用本地视频
await engine.enableLocalVideo(true);

// 禁用本地视频
await engine.enableLocalVideo(false);

// 默认启用
await engine.enableLocalVideo();

setCameraCapturerContentHint

设置摄像头采集内容提示。

方法签名

typescript

setCameraCapturerContentHint(contentHint: string): Promise<void>

参数说明

参数	类型	描述
contentHint	string	内容提示

说明

用于优化摄像头采集的编码策略
根据采集内容类型选择合适的编码参数
常用值：'motion'（运动内容）、'detail'（细节内容）、'text'（文本内容）

使用示例

javascript

// 设置为运动内容优化
await engine.setCameraCapturerContentHint('motion');

// 设置为细节内容优化
await engine.setCameraCapturerContentHint('detail');

// 设置为文本内容优化
await engine.setCameraCapturerContentHint('text');

getCurrentCameraDeviceId

获取当前摄像头设备 ID。

方法签名

typescript

getCurrentCameraDeviceId(): string | undefined

使用示例

javascript

const currentCameraId = engine.getCurrentCameraDeviceId();
console.log('当前摄像头 ID:', currentCameraId);

isCameraOn

检查摄像头是否开启。

方法签名

typescript

isCameraOn(): boolean

返回值

true: 摄像头已开启
false: 摄像头未开启

使用示例

javascript

const cameraStatus = engine.isCameraOn();
console.log('摄像头状态:', cameraStatus ? '开启' : '关闭');

muteLocalCamera

静音/取消静音本地摄像头。

方法签名

typescript

muteLocalCamera(mute: boolean): Promise<void>

参数说明

参数	类型	描述
mute	boolean	是否静音摄像头

使用示例

javascript

// 静音摄像头
await engine.muteLocalCamera(true);

// 取消静音摄像头
await engine.muteLocalCamera(false);

设备管理 ​

音频设备 ​

getCurrentMicDeviceId ​

方法签名 ​

使用示例 ​

switchMicrophone ​

方法签名 ​

参数说明 ​

使用示例 ​

startAudioCapture ​

方法签名 ​

参数说明 ​

使用示例 ​

stopAudioCapture ​

方法签名 ​

说明 ​

setAudioConstraints ​

方法签名 ​

参数说明 ​

使用示例 ​

视频设备 ​

switchCamera ​

方法签名 ​

参数说明 ​

使用示例 ​

startPreview ​

方法签名 ​

参数说明 ​

使用示例 ​

stopPreview ​

方法签名 ​

使用示例 ​

setCameraCapturerConfiguration ​

方法签名 ​

参数说明 ​

AliEngineCameraCapturerConfiguration 接口 ​

配置参数详解 ​

视频分辨率 (width & height) ​

帧率 (frameRate & maxSendFrameRate) ​

码率 (bitrate) ​

摄像头方向 (cameraDirection) ​

使用示例 ​

基础配置 ​

高清配置 ​

指定设备配置 ​

自适应配置 ​

最佳实践 ​

注意事项 ​

enableLocalVideo ​

方法签名 ​

参数说明 ​

说明 ​

使用示例 ​

setCameraCapturerContentHint ​

方法签名 ​

参数说明 ​

说明 ​

使用示例 ​

getCurrentCameraDeviceId ​

方法签名 ​

使用示例 ​

isCameraOn ​

方法签名 ​

返回值 ​

使用示例 ​

muteLocalCamera ​

方法签名 ​

参数说明 ​

使用示例 ​

设备管理

音频设备

getCurrentMicDeviceId

方法签名

使用示例

switchMicrophone

方法签名

参数说明

使用示例

startAudioCapture

方法签名

参数说明

使用示例

stopAudioCapture

方法签名

说明

setAudioConstraints

方法签名

参数说明

使用示例

视频设备

switchCamera

方法签名

参数说明

使用示例

startPreview

方法签名

参数说明

使用示例

stopPreview

方法签名

使用示例

setCameraCapturerConfiguration

方法签名

参数说明

AliEngineCameraCapturerConfiguration 接口

配置参数详解

视频分辨率 (width & height)

帧率 (frameRate & maxSendFrameRate)

码率 (bitrate)

摄像头方向 (cameraDirection)

使用示例

基础配置

高清配置

指定设备配置

自适应配置

最佳实践

注意事项

enableLocalVideo

方法签名

参数说明

说明

使用示例

setCameraCapturerContentHint

方法签名

参数说明

说明

使用示例

getCurrentCameraDeviceId

方法签名

使用示例

isCameraOn

方法签名

返回值

使用示例

muteLocalCamera

方法签名

参数说明

使用示例