@tencentcloud/sdk-mcp 1.4.7 → 1.6.0-beta.1

package/resource/knowledge/trtc/c++/ITXDeviceManager.md

@@ -0,0 +1,403 @@
+Copyright (c) 2021 Tencent. All rights reserved.
+
+Module:   音视频设备管理模块
+
+Function: 用于管理摄像头、麦克风和扬声器等音视频相关的硬件设备
+
+## ITXDeviceManager
+
+|函数列表|描述|
+|---------|---------|
+|isFrontCamera|判断当前是否为前置摄像头（仅适用于移动端）。|
+|switchCamera|切换前置或后置摄像头（仅适用于移动端）。|
+|getCameraZoomMaxRatio|获取摄像头的最大缩放倍数（仅适用于移动端）。|
+|setCameraZoomRatio|设置摄像头的缩放倍数（仅适用于移动端）。|
+|isAutoFocusEnabled|查询是否支持自动识别人脸位置（仅适用于移动端）。|
+|enableCameraAutoFocus|开启自动对焦功能（仅适用于移动端）。|
+|setCameraFocusPosition|设置摄像头的对焦位置（仅适用于移动端）。|
+|enableCameraTorch|开启/关闭闪光灯，也就是手电筒模式（仅适用于移动端）。|
+|setAudioRoute|设置音频路由（仅适用于移动端）。|
+|getDevicesList|获取设备列表（仅适用于桌面端）。|
+|setCurrentDevice|设置当前要使用的设备（仅适用于桌面端）。|
+|getCurrentDevice|获取当前正在使用的设备（仅适用于桌面端）。|
+|setCurrentDeviceVolume|设置当前设备的音量（仅适用于桌面端）。|
+|getCurrentDeviceVolume|获取当前设备的音量（仅适用于桌面端）。|
+|setCurrentDeviceMute|设置当前设备的静音状态（仅适用于桌面端）。|
+|getCurrentDeviceMute|获取当前设备的静音状态（仅适用于桌面端）。|
+|enableFollowingDefaultAudioDevice|设置 SDK 使用的音频设备根据跟随系统默认设备（仅适用于桌面端）。|
+|startCameraDeviceTest|开始摄像头测试（仅适用于桌面端）。|
+|stopCameraDeviceTest|结束摄像头测试（仅适用于桌面端）。|
+|startMicDeviceTest|开始麦克风测试（仅适用于桌面端）。|
+|startMicDeviceTest|开始麦克风测试（仅适用于桌面端）。|
+|stopMicDeviceTest|结束麦克风测试（仅适用于桌面端）。|
+|startSpeakerDeviceTest|开始扬声器测试（仅适用于桌面端）。|
+|stopSpeakerDeviceTest|结束扬声器测试（仅适用于桌面端）。|
+|startCameraDeviceTest|开始摄像头测试（仅适用于桌面端）。|
+|setApplicationPlayVolume|设置 Windows 系统音量合成器中当前进程的音量（仅适用于 Windows 系统）。|
+|getApplicationPlayVolume|获取 Windows 系统音量合成器中当前进程的音量（仅适用于 Windows 系统）。|
+|setApplicationMuteState|设置 Windows 系统音量合成器中当前进程的静音状态（仅适用于 Windows 系统）。|
+|getApplicationMuteState|获取 Windows 系统音量合成器中当前进程的静音状态（仅适用于 Windows 系统）。|
+|setCameraCapturerParam|设置摄像头采集偏好。|
+|setDeviceObserver|设置 onDeviceChanged 事件回调。|
+|setSystemVolumeType|设置系统音量类型（仅适用于移动端）。|
+
+## 结构体类型
+
+|函数列表|描述|
+|---------|---------|
+|TXCameraCaptureParam|摄像头采集参数。|
+|ITXDeviceInfo|音视频设备的相关信息（仅适用于桌面平台）。|
+|ITXDeviceCollection|设备信息列表（仅适用于桌面平台）。|
+
+## 枚举类型
+
+|枚举类型|描述|
+|---------|---------|
+|TXSystemVolumeType|系统音量类型（仅适用于移动设备）。|
+|TXAudioRoute|音频路由（即声音的播放模式）。|
+|TXMediaDeviceType|设备类型（仅适用于桌面平台）。|
+|TXMediaDeviceState|设备操作。|
+|TXCameraCaptureMode|摄像头采集偏好。|
+
+## isFrontCamera
+
+**判断当前是否为前置摄像头（仅适用于移动端）。**
+
+## switchCamera
+
+**切换前置或后置摄像头（仅适用于移动端）。**
+
+## getCameraZoomMaxRatio
+
+**获取摄像头的最大缩放倍数（仅适用于移动端）。**
+
+## setCameraZoomRatio
+
+**设置摄像头的缩放倍数（仅适用于移动端）。**
+
+|参数|描述|
+|---------|---------|
+|zoomRatio|取值范围 [1, 5]，取值为1表示最远视角（正常镜头），取值为5表示最近视角（放大镜头）。最大值推荐为5，若超过5，视频数据会变得模糊不清。|
+
+## isAutoFocusEnabled
+
+**查询是否支持自动识别人脸位置（仅适用于移动端）。**
+
+## enableCameraAutoFocus
+
+**开启自动对焦功能（仅适用于移动端）。**
+
+开启后，SDK 会自动检测画面中的人脸位置，并将摄像头的焦点始终对焦在人脸位置上。
+
+## setCameraFocusPosition
+
+**设置摄像头的对焦位置（仅适用于移动端）。**
+
+您可以通过该接口实现如下交互：
+
+1. 在本地摄像头的预览画面上，允许用户单击操作。
+
+2. 在用户的单击位置显示一个矩形方框，以示摄像头会在此处对焦。
+
+3. 随后将用户点击位置的坐标通过本接口传递给 SDK，之后 SDK 会操控摄像头按照用户期望的位置进行对焦。
+
+|参数|描述|
+|---------|---------|
+|position|对焦位置，请传入期望对焦点的坐标值|
+
+> **注意**
+>
+
+> 使用该接口的前提是先通过 enableCameraAutoFocus 关闭自动对焦功能。
+>
+**返回值说明：**
+
+0：操作成功；负数：操作失败。
+
+## enableCameraTorch
+
+**开启/关闭闪光灯，也就是手电筒模式（仅适用于移动端）。**
+
+## setAudioRoute
+
+**设置音频路由（仅适用于移动端）。**
+
+手机有两个音频播放设备：一个是位于手机顶部的听筒，一个是位于手机底部的立体声扬声器。
+
+设置音频路由为听筒时，声音比较小，只有将耳朵凑近才能听清楚，隐私性较好，适合用于接听电话。
+
+设置音频路由为扬声器时，声音比较大，不用将手机贴脸也能听清，因此可以实现“免提”的功能。
+
+## getDevicesList
+
+**获取设备列表（仅适用于桌面端）。**
+
+|参数|描述|
+|---------|---------|
+|type|设备类型，指定需要获取哪种设备的列表。详见 TXMediaDeviceType 定义。|
+
+> **注意**
+>
+> -  使用完毕后请调用 release 方法释放资源，这样可以让 SDK 维护 ITXDeviceCollection 对象的生命周期。
+> -  不要使用 delete 释放返回的 Collection 对象，` delete ITXDeviceCollection* ` 指针会导致异常崩溃。
+> -  type 只支持 ` TXMediaDeviceTypeMic `、` TXMediaDeviceTypeSpeaker `、` TXMediaDeviceTypeCamera `。
+> -  此接口只支持 Mac 和 Windows 平台。
+
+## setCurrentDevice
+
+**设置当前要使用的设备（仅适用于桌面端）。**
+
+|参数|描述|
+|---------|---------|
+|deviceId|设备 ID，您可以通过接口 getDevicesList 获得设备 ID。|
+|type|设备类型，详见 TXMediaDeviceType 定义。|
+**返回值说明：**
+
+0：操作成功；负数：操作失败。
+
+## getCurrentDevice
+
+**获取当前正在使用的设备（仅适用于桌面端）。**
+
+## setCurrentDeviceVolume
+
+**设置当前设备的音量（仅适用于桌面端）。**
+
+这里的音量指的是麦克风的采集音量或者扬声器的播放音量，摄像头是不支持设置音量的。
+
+|参数|描述|
+|---------|---------|
+|volume|音量大小，取值范围为 [0, 100]，默认值：100。|
+
+## getCurrentDeviceVolume
+
+**获取当前设备的音量（仅适用于桌面端）。**
+
+这里的音量指的是麦克风的采集音量或者扬声器的播放音量，摄像头是不支持获取音量的。
+
+## setCurrentDeviceMute
+
+**设置当前设备的静音状态（仅适用于桌面端）。**
+
+这里的音量指的是麦克风和扬声器，摄像头是不支持静音操作的。
+
+## getCurrentDeviceMute
+
+**获取当前设备的静音状态（仅适用于桌面端）。**
+
+这里的音量指的是麦克风和扬声器，摄像头是不支持静音操作的。
+
+## enableFollowingDefaultAudioDevice
+
+**设置 SDK 使用的音频设备根据跟随系统默认设备（仅适用于桌面端）。**
+
+仅支持设置麦克风和扬声器类型，摄像头暂不支持跟随系统默认设备
+| 参数 | 描述 |
+| --- | --- |
+| enable | 是否跟随系统默认的音频设备。<br>-  true：跟随。当系统默认音频设备发生改变或者有新音频设备插入时，SDK 立即切换音频设备。<br>-  false：不跟随。当系统默认音频设备发生改变或者有新音频设备插入时，SDK 不会切换音频设备。 |
+| type | 设备类型，详见 TXMediaDeviceType 定义。 |
+
+## startCameraDeviceTest
+
+**开始摄像头测试（仅适用于桌面端）。**
+
+> **注意**
+>
+
+> 在测试过程中可以使用 setCurrentDevice 接口切换摄像头。
+>
+
+## stopCameraDeviceTest
+
+**结束摄像头测试（仅适用于桌面端）。**
+
+## startMicDeviceTest
+
+**开始麦克风测试（仅适用于桌面端）。**
+
+该接口可以测试麦克风是否能正常工作，测试到的麦克风采集音量的大小，会以回调的形式通知给您，其中 volume 的取值范围为 [0, 100]。
+
+|参数|描述|
+|---------|---------|
+|interval|麦克风音量的回调间隔，单位为毫秒（ms）。|
+
+> **注意**
+>
+
+> 该接口调用后默认会回播麦克风录制到的声音到扬声器中。
+>
+
+## startMicDeviceTest
+
+**开始麦克风测试（仅适用于桌面端）。**
+
+该接口可以测试麦克风是否能正常工作，测试到的麦克风采集音量的大小，会以回调的形式通知给您，其中 volume 的取值范围为 [0, 100]。
+
+|参数|描述|
+|---------|---------|
+|interval|麦克风音量的回调间隔，单位为毫秒（ms）。|
+|playback|是否开启回播麦克风声音，开启后用户测试麦克风时会听到自己的声音。|
+
+## stopMicDeviceTest
+
+**结束麦克风测试（仅适用于桌面端）。**
+
+## startSpeakerDeviceTest
+
+**开始扬声器测试（仅适用于桌面端）。**
+
+该接口通过播放指定的音频文件，用于测试播放设备是否能正常工作。如果用户在测试时能听到声音，说明播放设备能正常工作。
+
+|参数|描述|
+|---------|---------|
+|filePath|声音文件的路径|
+
+## stopSpeakerDeviceTest
+
+**结束扬声器测试（仅适用于桌面端）。**
+
+## startCameraDeviceTest
+
+**开始摄像头测试（仅适用于桌面端）。**
+
+该接口支持自定义渲染，即您可以通过接 ITRTCVideoRenderCallback 回调接口接管摄像头的渲染画面。
+
+## setApplicationPlayVolume
+
+**设置 Windows 系统音量合成器中当前进程的音量（仅适用于 Windows 系统）。**
+
+## getApplicationPlayVolume
+
+**获取 Windows 系统音量合成器中当前进程的音量（仅适用于 Windows 系统）。**
+
+## setApplicationMuteState
+
+**设置 Windows 系统音量合成器中当前进程的静音状态（仅适用于 Windows 系统）。**
+
+## getApplicationMuteState
+
+**获取 Windows 系统音量合成器中当前进程的静音状态（仅适用于 Windows 系统）。**
+
+## setCameraCapturerParam
+
+**设置摄像头采集偏好。**
+
+## setDeviceObserver
+
+**设置 onDeviceChanged 事件回调。**
+
+## setSystemVolumeType
+
+**设置系统音量类型（仅适用于移动端）。**
+
+@deprecated v9.5 版本开始不推荐使用，建议使用 ` TRTCCloud ` 中的 ` startLocalAudio(quality) ` 接口替代之，通过 quality 参数来决策音质。
+
+## TXSystemVolumeType(Deprecated)
+
+**系统音量类型（仅适用于移动设备）。**
+
+@deprecated v9.5 版本开始不推荐使用。
+
+现代智能手机中一般都具备两套系统音量类型，即“通话音量”和“媒体音量”。
+-  通话音量：手机专门为接打电话所设计的音量类型，自带回声抵消（AEC）功能，并且支持通过蓝牙耳机上的麦克风进行拾音，缺点是音质比较一般。
+
+当您通过手机侧面的音量按键下调手机音量时，如果无法将其调至零（也就是无法彻底静音），说明您的手机当前处于通话音量。
+-  媒体音量：手机专门为音乐场景所设计的音量类型，无法使用系统的 AEC 功能，并且不支持通过蓝牙耳机的麦克风进行拾音，但具备更好的音乐播放效果。
+
+当您通过手机侧面的音量按键下调手机音量时，如果能够将手机音量调至彻底静音，说明您的手机当前处于媒体音量。
+
+SDK 目前提供了三种系统音量类型的控制模式：自动切换模式、全程通话音量模式、全程媒体音量模式。
+
+|枚举|取值|描述|
+|---------|---------|---------|
+|TXSystemVolumeTypeAuto|0|自动切换模式|
+|TXSystemVolumeTypeMedia|1|全程媒体音量|
+|TXSystemVolumeTypeVOIP|2|全程通话音量|
+
+## TXAudioRoute
+
+**音频路由（即声音的播放模式）。**
+
+音频路由，即声音是从手机的扬声器还是从听筒中播放出来，因此该接口仅适用于手机等移动端设备。
+
+手机有两个扬声器：一个是位于手机顶部的听筒，一个是位于手机底部的立体声扬声器。
+-  设置音频路由为听筒时，声音比较小，只有将耳朵凑近才能听清楚，隐私性较好，适合用于接听电话。
+
+-  设置音频路由为扬声器时，声音比较大，不用将手机贴脸也能听清，因此可以实现“免提”的功能。
+
+|枚举|取值|描述|
+|---------|---------|---------|
+|TXAudioRouteSpeakerphone|0|Speakerphone：使用扬声器播放（即“免提”），扬声器位于手机底部，声音偏大，适合外放音乐。|
+|TXAudioRouteEarpiece|1|Earpiece：使用听筒播放，听筒位于手机顶部，声音偏小，适合需要保护隐私的通话场景。|
+
+## TXMediaDeviceType
+
+**设备类型（仅适用于桌面平台）。**
+
+该枚举值用于定义三种类型的音视频设备，即摄像头、麦克风和扬声器，以便让一套设备管理接口可以操控三种不同类型的设备。
+
+|枚举|取值|描述|
+|---------|---------|---------|
+|TXMediaDeviceTypeUnknown|-1|未定义的设备类型|
+|TXMediaDeviceTypeMic|0|麦克风类型设备|
+|TXMediaDeviceTypeSpeaker|1|扬声器类型设备|
+|TXMediaDeviceTypeCamera|2|摄像头类型设备|
+
+## TXMediaDeviceState
+
+**设备操作。**
+
+该枚举值用于本地设备的状态变化通知 onDeviceChanged。
+
+|枚举|取值|描述|
+|---------|---------|---------|
+|TXMediaDeviceStateAdd|0|设备已被插入|
+|TXMediaDeviceStateRemove|1|设备已被移除|
+|TXMediaDeviceStateActive|2|设备已启用|
+|TXMediaDefaultDeviceChanged|3|系统默认设备变更|
+
+## TXCameraCaptureMode
+
+**摄像头采集偏好。**
+
+该枚举类型用于摄像头采集参数设置。
+| 枚举 | 取值 | 描述 |
+| --- | --- | --- |
+| TXCameraResolutionStrategyAuto | 0 | 自动调整采集参数。<br>SDK 根据实际的采集设备性能及网络情况，选择合适的摄像头输出参数，在设备性能及视频预览质量之间，维持平衡。 |
+| TXCameraResolutionStrategyPerformance | 1 | 优先保证设备性能。<br>SDK 根据用户设置编码器的分辨率和帧率，选择最接近的摄像头输出参数，从而保证设备性能。 |
+| TXCameraResolutionStrategyHighQuality | 2 | 优先保证视频预览质量。<br>SDK选择较高的摄像头输出参数，从而提高预览视频的质量。在这种情况下，会消耗更多的 CPU 及内存做视频前处理。 |
+| TXCameraCaptureManual | 3 | 允许用户设置本地摄像头采集的视频宽高。 |
+
+## TXCameraCaptureParam
+
+**摄像头采集参数。**
+
+该设置能决定本地预览图像画质。
+
+|枚举类型|描述|
+|---------|---------|
+|height|**字段含义：** 采集图像宽度|
+|mode|**字段含义：** 摄像头采集偏好，请参见 TXCameraCaptureMode|
+|width|**字段含义：** 采集图像长度|
+
+## TXMediaDeviceInfo
+
+**音视频设备的相关信息（仅适用于桌面平台）。**
+
+该结构体用于描述一个音视频设备的关键信息，例如设备 ID、设备名称等等，以便用户能够在用户界面上选择自己期望使用的音视频设备。
+
+|枚举类型|描述|
+|---------|---------|
+|getDeviceName()|设备名称 （UTF-8）|
+|getDevicePID()|设备 ID （UTF-8）|
+
+## ITXDeviceCollection
+
+**设备信息列表（仅适用于桌面平台）。**
+
+此结构体的作用相当于 std::vector<ITXDeviceInfo>，用于解决不同版本的 STL 容器的二进制兼容问题。
+| 枚举类型 | 描述 |
+| --- | --- |
+| getCount() | 设备数量 |
+| index) | 设备信息（JSON 格式）<br><strong>注意</strong><br>示例：{"SupportedResolution":[{"width":640,"height":480},{"width":320,"height":240}]}<br>param index 设备索引，值为 [0,getCount)，return 返回 JSON 格式的设备信息 |
+| release() | 释放设备列表，请不要使用 delete 释放资源 !!! |