Copyright (c) 2026 Tencent. All rights reserved.
Module: TXDeviceManager @ TXLiteAVSDK
Function: 音视频设备管理（摄像头、麦克风、扬声器、音频路由等）
Version: 13.5
音视频设备管理接口，Flutter SDK：
tencent_rtc_sdk。通过 TRTCCloud 的 getDeviceManager() 获取实例后即可调用。平台分类 | 适用平台 | 不支持平台上的返回值 |
仅移动端 | Android / iOS / HarmonyOS | int / double 返回 -1；bool 返回 false。 |
仅桌面端 | Windows / macOS | int 返回 -1；bool 返回 false；List 返回空列表；TXDeviceInfo 返回空对象。 |
仅 Windows | Windows | int 返回 -1。 |
函数列表
移动端设备接口
API | 描述 |
查询当前是否使用前置摄像头（仅移动端）。 | |
切换前置或后置摄像头（仅移动端）。 | |
获取摄像头的最大缩放倍数（仅移动端）。 | |
设置摄像头的缩放倍数（仅移动端）。 | |
查询是否支持自动识别人脸位置（仅移动端）。 | |
开启自动对焦功能（仅移动端）。 | |
设置摄像头的对焦位置（仅移动端）。 | |
开启/关闭闪光灯，即手电筒模式（仅移动端）。 | |
设置音频路由（仅移动端）。 |
桌面端设备接口
API | 描述 |
获取设备列表（仅桌面端）。 | |
设置当前要使用的设备（仅桌面端）。 | |
获取当前正在使用的设备（仅桌面端）。 | |
设置当前设备的音量（仅桌面端）。 | |
获取当前设备的音量（仅桌面端）。 | |
设置当前设备的静音状态（仅桌面端）。 | |
查询当前设备是否静音（仅桌面端）。 | |
设置 SDK 使用的音频设备跟随系统默认设备（仅桌面端）。 |
设备测试（桌面端）
API | 描述 |
开始摄像头测试（仅桌面端）。 | |
结束摄像头测试（仅桌面端）。 | |
开始麦克风测试（仅桌面端）。 | |
开始麦克风测试，并可指定是否回放麦克风声音（仅桌面端）。 | |
结束麦克风测试（仅桌面端）。 | |
开始扬声器测试（仅桌面端）。 | |
结束扬声器测试（仅桌面端）。 |
Windows 音量合成器
API | 描述 |
设置 Windows 系统音量合成器中当前进程的音量（仅 Windows）。 | |
获取 Windows 系统音量合成器中当前进程的音量（仅 Windows）。 | |
设置 Windows 系统音量合成器中当前进程的静音状态（仅 Windows）。 | |
获取 Windows 系统音量合成器中当前进程的静音状态（仅 Windows）。 |
通用接口
API | 描述 |
设置摄像头采集偏好。 | |
设置设备状态变化回调（ onDeviceChanged）。 |
接口详情
以下按函数列表顺序逐一说明各接口的签名、功能、参数、返回值及注意事项。
isFrontCamera
bool isFrontCamera()
查询当前是否使用前置摄像头（仅移动端）。
返回值
true：当前使用前置摄像头；false：当前使用后置摄像头，或当前平台不支持该接口。switchCamera
int switchCamera(bool frontCamera)
切换前置或后置摄像头（仅移动端）。
参数 | 类型 | 描述 |
frontCamera | bool | true：前置摄像头；false：后置摄像头。 |
返回值
接口调用结果；当前平台不支持时返回
-1。getCameraZoomMaxRatio
double getCameraZoomMaxRatio()
获取摄像头的最大缩放倍数（仅移动端）。
返回值
摄像头支持的最大缩放倍数；当前平台不支持时返回
-1。setCameraZoomRatio
int setCameraZoomRatio(double ratio)
设置摄像头的缩放倍数（仅移动端）。
参数 | 类型 | 描述 |
ratio | double | 缩放倍数，取值范围：1 - 5。 1：最远视角（正常镜头）；5：最近视角（放大镜头）。建议最大值不超过 5，超过后画面会变得模糊。 |
返回值
接口调用结果；当前平台不支持时返回
-1。isAutoFocusEnabled
bool isAutoFocusEnabled()
查询是否支持自动识别人脸位置（仅移动端）。
返回值
true：支持；false：不支持，或当前平台不支持该接口。enableCameraAutoFocus
int enableCameraAutoFocus(bool enabled)
开启自动对焦功能（仅移动端）。
开启后，SDK 会自动检测画面中的人脸，并保持对焦在人脸位置上。
参数 | 类型 | 描述 |
enabled | bool | true：开启；false：关闭。 |
返回值
接口调用结果；当前平台不支持时返回
-1。setCameraFocusPosition
int setCameraFocusPosition(double x, double y)
设置摄像头的对焦位置（仅移动端）。
您可以通过该接口实现如下交互：
1. 用户在本地摄像头的预览画面上点击某个区域。
2. 在用户点击的位置显示一个矩形框，提示摄像头将在此处对焦。
3. 通过本接口将点击位置的坐标传给 SDK，SDK 会控制摄像头按照该位置进行对焦。
参数 | 类型 | 描述 |
x | double | 期望对焦点的横坐标。 |
y | double | 期望对焦点的纵坐标。 |
说明：
返回值
0：操作成功；负数：操作失败（当前平台不支持时返回
-1）。enableCameraTorch
int enableCameraTorch(bool enabled)
开启/关闭闪光灯，即手电筒模式（仅移动端）。
参数 | 类型 | 描述 |
enabled | bool | true：开启；false：关闭。 |
返回值
接口调用结果；当前平台不支持时返回
-1。setAudioRoute
int setAudioRoute(TXAudioRoute route)
设置音频路由（仅移动端）。
手机有两个音频播放设备：一个是位于手机顶部的听筒，一个是位于手机底部的立体声扬声器。
设置为听筒时：声音比较小，只有将耳朵凑近才能听清楚，隐私性较好，适合用于接听电话。
设置为扬声器时：声音比较大，不用将手机贴脸也能听清，即“免提”功能。
参数 | 类型 | 描述 |
route |
返回值
接口调用结果；当前平台不支持时返回
-1。getDevicesList
List<TXDeviceInfo> getDevicesList(TXMediaDeviceType type)
获取设备列表（仅桌面端）。
参数 | 类型 | 描述 |
type |
返回值
示例代码
List<TXDeviceInfo> cameras = deviceManager.getDevicesList(TXMediaDeviceType.camera);for (TXDeviceInfo device in cameras) {debugPrint('${device.deviceName} (${device.devicePid})');}
setCurrentDevice
int setCurrentDevice(TXMediaDeviceType type, String deviceId)
设置当前要使用的设备（仅桌面端）。
参数 | 类型 | 描述 |
type | ||
deviceId | String |
返回值
0：操作成功；负数：操作失败（当前平台不支持时返回
-1）。getCurrentDevice
TXDeviceInfo getCurrentDevice(TXMediaDeviceType type)
获取当前正在使用的设备（仅桌面端）。
参数 | 类型 | 描述 |
type |
返回值
setCurrentDeviceVolume
int setCurrentDeviceVolume(TXMediaDeviceType type, int volume)
设置当前设备的音量（仅桌面端）。
该接口用于设置麦克风的采集音量或扬声器的播放音量，不支持设置摄像头。
参数 | 类型 | 描述 |
type | ||
volume | int | 音量大小，取值范围：0 - 100，默认值：100。 |
返回值
接口调用结果；当前平台不支持时返回
-1。getCurrentDeviceVolume
int getCurrentDeviceVolume(TXMediaDeviceType type)
获取当前设备的音量（仅桌面端）。
该接口用于获取麦克风的采集音量或扬声器的播放音量，不支持获取摄像头。
参数 | 类型 | 描述 |
type |
返回值
当前设备的音量；当前平台不支持时返回
-1。setCurrentDeviceMute
int setCurrentDeviceMute(TXMediaDeviceType type, bool mute)
设置当前设备的静音状态（仅桌面端）。
该接口用于设置麦克风或扬声器静音，不支持设置摄像头。
参数 | 类型 | 描述 |
type | ||
mute | bool | true：静音；false：取消静音。 |
返回值
接口调用结果；当前平台不支持时返回
-1。getCurrentDeviceMute
bool getCurrentDeviceMute(TXMediaDeviceType type)
查询当前设备是否静音（仅桌面端）。
该接口用于查询麦克风或扬声器是否静音，不支持查询摄像头。
参数 | 类型 | 描述 |
type |
返回值
true：当前设备已静音；false：当前设备未静音，或当前平台不支持该接口。enableFollowingDefaultAudioDevice
int enableFollowingDefaultAudioDevice(TXMediaDeviceType type, bool enable)
设置 SDK 使用的音频设备跟随系统默认设备（仅桌面端）。
该接口仅支持设置麦克风和扬声器，不支持摄像头跟随系统默认设备。
参数 | 类型 | 描述 |
type | ||
enable | bool | 是否跟随系统默认的音频设备。 true：跟随。当系统默认音频设备发生改变或有新的音频设备插入时，SDK 立即切换音频设备。false：不跟随。当系统默认音频设备发生改变或有新的音频设备插入时，SDK 不会切换音频设备。 |
返回值
接口调用结果；当前平台不支持时返回
-1。startCameraDeviceTest
int startCameraDeviceTest(int viewId)
开始摄像头测试（仅桌面端）。
参数 | 类型 | 描述 |
viewId | int | 用于渲染摄像头测试画面的控件 ID。 |
说明：
返回值
接口调用结果；当前平台不支持时返回
-1。stopCameraDeviceTest
void stopCameraDeviceTest()
结束摄像头测试（仅桌面端）。
startMicDeviceTest
int startMicDeviceTest(int interval)
开始麦克风测试（仅桌面端）。
该接口用于测试麦克风是否能正常工作。检测到的麦克风音量（取值范围：0 - 100）会通过
TRTCCloudListener 中的 onTestMicVolume 回调通知给您。参数 | 类型 | 描述 |
interval | int | 音量回调的时间间隔。 |
说明：
返回值
接口调用结果；当前平台不支持时返回
-1。startMicDeviceTestAndPlayback
int startMicDeviceTestAndPlayback(int interval, bool playback)
开始麦克风测试，并可指定是否回放麦克风声音（仅桌面端）。
该接口用于测试麦克风是否能正常工作。检测到的麦克风音量（取值范围：0 - 100）会通过
TRTCCloudListener 中的 onTestMicVolume 回调通知给您。参数 | 类型 | 描述 |
interval | int | 音量回调的时间间隔。 |
playback | bool | 是否回放麦克风声音。为 true 时，用户在测试麦克风时会听到自己的声音。 |
返回值
接口调用结果；当前平台不支持时返回
-1。stopMicDeviceTest
void stopMicDeviceTest()
结束麦克风测试（仅桌面端）。
startSpeakerDeviceTest
int startSpeakerDeviceTest(String filePath)
开始扬声器测试（仅桌面端）。
该接口通过播放指定的音频文件，来测试播放设备是否能正常工作。如果用户在测试时能听到声音，说明播放设备工作正常。播放音量会通过
TRTCCloudListener 中的 onTestSpeakerVolume 回调通知给您。参数 | 类型 | 描述 |
filePath | String | 音频文件的路径。 |
返回值
接口调用结果；当前平台不支持时返回
-1。stopSpeakerDeviceTest
void stopSpeakerDeviceTest()
结束扬声器测试（仅桌面端）。
setApplicationPlayVolume
int setApplicationPlayVolume(int volume)
设置 Windows 系统音量合成器中当前进程的音量（仅 Windows）。
参数 | 类型 | 描述 |
volume | int | 当前进程的音量大小。 |
返回值
接口调用结果；当前平台不支持时返回
-1。getApplicationPlayVolume
int getApplicationPlayVolume()
获取 Windows 系统音量合成器中当前进程的音量（仅 Windows）。
返回值
当前进程的音量；当前平台不支持时返回
-1。setApplicationMuteState
int setApplicationMuteState(bool mute)
设置 Windows 系统音量合成器中当前进程的静音状态（仅 Windows）。
参数 | 类型 | 描述 |
mute | bool | true：静音；false：取消静音。 |
返回值
接口调用结果；当前平台不支持时返回
-1。getApplicationMuteState
int getApplicationMuteState()
获取 Windows 系统音量合成器中当前进程的静音状态（仅 Windows）。
返回值
当前进程的静音状态；当前平台不支持时返回
-1。setCameraCaptureParam
void setCameraCaptureParam(TXCameraCaptureParam params)
设置摄像头采集偏好。
参数 | 类型 | 描述 |
params |
示例代码
deviceManager.setCameraCaptureParam(TXCameraCaptureParam(mode: TXCameraCaptureMode.manual,width: 1280,height: 720,));
setDeviceObserver
int setDeviceObserver(TXDeviceObserver? observer)
设置设备状态变化回调（
onDeviceChanged）。参数 | 类型 | 描述 |
observer | TXDeviceObserver? |
返回值
0：设置成功。示例代码
deviceManager.setDeviceObserver(TXDeviceObserver(onDeviceChanged: (String deviceId, TXMediaDeviceType type, TXMediaDeviceState state) {debugPrint('device changed: $deviceId, $type, $state');},));
类型定义
TXAudioRoute
音频路由（即声音的播放模式）。
枚举值 | 数值 | 描述 |
unknown | -1 | 未知，使用默认路由设备。 |
speakerPhone | 0 | 扬声器：使用手机底部的扬声器播放（即“免提”），音量较大，适合外放音乐。 |
earpiece | 1 | 听筒：使用手机顶部的听筒播放，音量较小，适合需要保护隐私的通话场景。 |
wiredHeadset | 2 | 有线耳机。 |
bluetoothHeadset | 3 | 蓝牙耳机。 |
soundCard | 4 | 声卡。 |
TXMediaDeviceType
设备类型（仅适用于桌面平台）。
该枚举值定义了摄像头、麦克风和扬声器三种类型的音视频设备，便于您使用同一套设备管理接口管理这三种设备。
枚举值 | 数值 | 描述 |
unknown | -1 | 未定义的设备类型。 |
mic | 0 | 麦克风。 |
speaker | 1 | 扬声器或听筒。 |
camera | 2 | 摄像头。 |
TXMediaDeviceState
设备操作。
该枚举值用于在
onDeviceChanged 回调中通知本地设备的状态变化。枚举值 | 数值 | 描述 |
add | 0 | 设备已被插入。 |
remove | 1 | 设备已被移除。 |
active | 2 | 设备已启用。 |
defaultDeviceChanged | 3 | 系统默认设备已变更。 |
TXCameraCaptureMode
摄像头采集偏好。
该枚举类型用于设置摄像头采集参数。
枚举值 | 数值 | 描述 |
auto | 0 | 自动调整采集参数。SDK 根据实际的采集设备性能及网络情况，选择合适的摄像头输出参数，在设备性能与视频预览质量之间维持平衡。 |
performance | 1 | 优先保证设备性能。SDK 根据用户设置的编码器分辨率和帧率，选择最接近的摄像头输出参数，从而保证设备性能。 |
highQuality | 2 | 优先保证视频预览质量。SDK 选择较高的摄像头输出参数，从而提高预览视频的质量。在这种情况下，会消耗更多的 CPU 及内存做视频前处理。 |
manual | 3 | 允许用户设置本地摄像头采集的视频宽高。 |
TXCameraCaptureParam
摄像头采集参数。
该设置能决定本地预览图像画质。
字段 | 类型 | 默认值 | 描述 |
mode | TXCameraCaptureMode.auto | ||
width | int | 640 | 采集图像宽度。 |
height | int | 360 | 采集图像高度。 |
TXDeviceInfo
设备信息。
字段 | 类型 | 默认值 | 描述 |
deviceName | String | '' | 设备名称。 |
devicePid | String | '' | 设备 ID。 |
deviceProperties | String | '' | 设备属性。 |
TXDeviceObserver
设备状态变化回调。
onDeviceChanged
final void Function(String deviceId, TXMediaDeviceType type, TXMediaDeviceState state) onDeviceChanged
本地设备的通断状态发生变化（仅适用于桌面系统）。
当本地设备（包括摄像头、麦克风以及扬声器）被插入或者拔出时，SDK 便会抛出此事件回调。
参数 | 类型 | 描述 |
deviceId | String | 设备 ID。 |
type | ||
state |
