AI 助理
备案控制台
官方文档
输入文档关键字查找
首页 视频直播 实时音视频 基础功能 视频采集设备管理

视频采集设备管理

更新时间：
产品详情
我的收藏

视频设备管理是RTC核心能力之一，阿里云ARTC SDK提供了丰富的API方便用户管理，不同平台有较大差异，下面将为您介绍RTC引擎的视频设备管理功能。

功能介绍

阿里云ARTC SDK的视频设备管理功能为开发者提供了便捷且全面的设备控制能力。该功能能够对不同平台（如 iOS、Android）的摄像头参数进行精细配置，支持焦距调节、曝光控制、手动/自动对焦等参数配置，显著提升视频采集质量。

示例代码

Android端视频采集设备管理：Android/ARTCExample/BasicUsage/src/main/java/com/aliyun/artc/api/basicusage/CameraCommonControl/CameraActivity.java。

iOS端视频采集设备管理：iOS/ARTCExample/BasicUsage/CameraCommonSetting/CameraCommonControlVC.swift。

前提条件

  • 一个有效的阿里云账号并创建实时音视频应用，请参考创建应用。在应用管理控制台获取App ID及App Key。

  • SDK 集成及基础功能实现：

    • 已经在项目中集成了 ARTC SDK，并实现了基础的实时音视频功能。SDK 集成请参考SDK下载/集成，实现音视频请参考：实现音视频通话。

    • 已经启动摄像头，例如已经通过startPreview启动预览或者joinChannel加入频道。

功能实现

设置缩放

ARTC SDK 支持摄像头缩放功能。

接口信息

/**
 * @brief 设置摄像头zoom
 * @param zoom 缩放级别，范围从 1 到 camera支持的最大 zoom值
 * @return
 * - 0: 成功
 * - 非0: 失败
 * @note 只有iOS和android提供这个接口
 */
public abstract int setCameraZoom(float zoom);

 /**
 * @brief 获取摄像头最大缩放比例
 * @return 摄像头最大缩放比例
 */
public abstract float GetCameraMaxZoomFactor();

/**
 * @brief 获取摄像头当前缩放比例
 * @return 摄像头缩放比例
 */
public abstract float GetCurrentZoom();

调用示例

Android

// 获取缩放信息
private void initZoomSeekBar() {
    if (mAliRtcEngine != null) {
        zoomSeekBar.setEnabled(true);
        // 获取最大zoom值
        float maxZoom = mAliRtcEngine.GetCameraMaxZoomFactor();
        float currZoom = mAliRtcEngine.GetCurrentZoom();
        // 设置SeekBar范围（1.0到maxZoom，0.1步进）
        if(maxZoom >= 1.0) {
            int maxProgress = (int)((maxZoom - 1) * 10);
            zoomSeekBar.setMax(maxProgress);
            int currProgress = (int)((currZoom - 1) * 10);
            zoomSeekBar.setProgress(currProgress);
        } else{
            zoomSeekBar.setEnabled(false);
        }
    }
}
// 设置缩放
zoomSeekBar.setOnSeekBarChangeListener(new SeekBar.OnSeekBarChangeListener() {
    @Override
    public void onProgressChanged(SeekBar seekBar, int i, boolean b) {
        if(mAliRtcEngine != null) {
            float newZoom = (float)((i+10) / 10.0);
            mAliRtcEngine.setCameraZoom(newZoom);
            zoomTextView.setText(String.format("%.1f", newZoom));
        }
    }

    @Override
    public void onStartTrackingTouch(SeekBar seekBar) {
    }

    @Override
    public void onStopTrackingTouch(SeekBar seekBar) {
    }
});

iOS

// 获取缩放信息
self.cameraZoomSlider.isEnabled = true
let maxZoom = rtcEngine.getCameraMaxZoomFactor()
let currZoom = rtcEngine.getCurrentZoom()
"Get maxZoom=\(maxZoom), currZoom=\(currZoom)".printLog()

self.cameraZoomSlider.minimumValue = 1.0
if maxZoom > 1.0 {
    self.cameraZoomSlider.maximumValue = maxZoom
} else {
    self.cameraZoomSlider.isEnabled = false
}
if currZoom >= 1.0 && currZoom <= maxZoom {
    self.cameraZoomSlider.value = currZoom
    self.cameraZoomValueLabel.text = String(format: "%.1f", self.cameraZoomSlider.value)
}
else {
    self.cameraZoomSlider.value = self.cameraZoomSlider.minimumValue
    self.cameraZoomValueLabel.text = "\(self.cameraZoomSlider.minimumValue)"
}

// 设置缩放
@IBOutlet weak var cameraZoomSlider: UISlider!
@IBOutlet weak var cameraZoomValueLabel: UILabel!
@IBAction func onCameraZoomChanged(_ sender: UISlider) {
    let currValue = sender.value
    self.cameraZoomValueLabel.text = String(format: "%.1f", currValue)
    self.rtcEngine?.setCameraZoom(currValue)
}

设置曝光度

ARTC 支持设置摄像头曝光度（Exposure)，用于控制摄像头在拍摄时的亮度调整。

接口信息

/**
 * @brief 设置摄像头曝光度
 * @param exposure 曝光度
 * @return
 * - 0: 成功
 * -非0: 失败
 */
public abstract int SetExposure(float exposure);

/**
 * @brief 获取摄像头曝光度
 * @return 摄像头曝光度
 */
public abstract float GetCurrentExposure();

/**
 * @brief 获取摄像头最小曝光度
 * @return 摄像头最小曝光度
 */
public abstract float GetMinExposure();

/**
 * @brief 获取摄像头最大曝光度
 * @return 摄像头最大曝光度
 */
public abstract float GetMaxExposure();

调用示例

Android

// 获取曝光度信息
private void initExposureSeekBar() {
    if (mAliRtcEngine != null) {
        exposureSeekBar.setEnabled(true);
        // 获取最大zoom值
        float maxExposure = mAliRtcEngine.GetMaxExposure();
        // 获取最小zoom值
        float minExposure = mAliRtcEngine.GetMinExposure();
        float currExposure = mAliRtcEngine.GetCurrentExposure();
        if(maxExposure > minExposure) {
            // 重新设置SeekBar范围
            int maxProgress = (int)(maxExposure - minExposure) * 10;
            exposureSeekBar.setMax(maxProgress);
            int currProgress = (int)((currExposure - minExposure) * 10);
            exposureSeekBar.setProgress(currProgress);
        } else {
            exposureSeekBar.setEnabled(false);
        }
    }
}
// 设置曝光度
exposureSeekBar.setOnSeekBarChangeListener(new SeekBar.OnSeekBarChangeListener() {
    @Override
    public void onProgressChanged(SeekBar seekBar, int i, boolean b) {
        if(mAliRtcEngine != null) {
            float minExposure = mAliRtcEngine.GetMinExposure();
            float newExposure = minExposure + (float)(i / 10.0);

            mAliRtcEngine.SetExposure(newExposure);
            exposureTextView.setText(String.format("% .1f", newExposure));
        }
    }

    @Override
    public void onStartTrackingTouch(SeekBar seekBar) {
    }

    @Override
    public void onStopTrackingTouch(SeekBar seekBar) {
    }
});

iOS

// 获取设备曝光度信息
self.cameraExposureSlider.isEnabled = true
let minExposure = rtcEngine.getMinExposure()
let maxExposure = rtcEngine.getMaxExposure()
let currExposure = rtcEngine.getCurrentExposure()
"Get minExposure=\(minExposure), maxExposure=\(maxExposure), currExposure=\(currExposure)".printLog()
if maxExposure > minExposure {
    self.cameraExposureSlider.minimumValue = minExposure
    self.cameraExposureSlider.maximumValue = maxExposure
} else {
    self.cameraExposureSlider.isEnabled = false
}
if currExposure >= minExposure && currExposure <= maxExposure {
    self.cameraExposureSlider.value = currExposure
    self.cameraExposureValueLabel.text = String(format: "%.1f", self.cameraExposureSlider.value)
}
else {
    self.cameraExposureSlider.value = self.cameraExposureSlider.minimumValue
    self.cameraExposureValueLabel.text = "\(self.cameraExposureSlider.minimumValue)"
}
// 设置曝光度
@IBOutlet weak var cameraExposureValueLabel: UILabel!
@IBOutlet weak var cameraExposureSlider: UISlider!
@IBAction func onCameraExposureChanged(_ sender: UISlider) {
    let currValue = sender.value
    self.cameraExposureValueLabel.text = String(format: "%.1f", currValue)
    self.rtcEngine?.setExposure(currValue)
}

手动设置曝光点

ARTC 提供手动设置摄像头曝光点的功能，根据用户指定的位置（通常为点击屏幕上的某个点），让摄像头对该区域内的亮度条件进行调整。

说明

  • 在设置曝光点时需要先调用isCameraExposurePointSupported接口检查是否支持。

  • 传入参数为归一化的坐标。

接口信息

/**
 * @brief 是否支持设置摄像头曝光点
 * @return
 * - true: 支持
 * - false: 不支持
 * @note 只有iOS和android提供这个接口，用来检查当前camera是否可以设置曝光点
 */
public abstract boolean isCameraExposurePointSupported();
/**
 * @brief 设置摄像头曝光点
 * @param x x轴坐标值（归一化）[0-1]
 * @param y y轴坐标值（归一化）[0-1]
 * @return
 * - 0: 成功
 * - 非0: 失败
 * @note 只有iOS和android提供这个接口，调用后camera对所设点做一次曝光调整，后面一直保持这个曝光值
 */
public abstract int setCameraExposurePoint(float x, float y);

调用示例

Android

// 手动设置曝光点
mLocalViewGestureDetector = new GestureDetector(this, new GestureDetector.SimpleOnGestureListener() {
    @Override
    public boolean onDoubleTap(@NonNull MotionEvent e) {
        // 处理双击
        // ...
        return true;
    }
    @Override
    public boolean onSingleTapConfirmed(@NonNull MotionEvent e) {
        // 处理单击
        if(mAliRtcEngine != null && mAliRtcEngine.isCameraExposurePointSupported()) {
            float[] normalizedCoords = getNormalizedCoordinates(e.getX(), e.getY());
            if (normalizedCoords[0] != -1 && normalizedCoords[1] != -1) {
                mAliRtcEngine.setCameraExposurePoint(normalizedCoords[0], normalizedCoords[1]);
                mCameraExposurePointX.setText(String.format("%.2f", normalizedCoords[0]));
                mCameraExposurePointY.setText(String.format("%.2f", normalizedCoords[1]));
            }
        }
        return true;
    }
});

iOS

@objc func handleSeatViewTap(_ gesture: UITapGestureRecognizer) {
    guard let localSeatView = self.localPreviewSeatView else {
        return
    }
    guard let rtcEngine = self.rtcEngine, rtcEngine.isCameraExposurePointSupported() else { return }


    let tapPoint = gesture.location(in: localSeatView)
    // 将点击坐标转换为视频帧的归一化坐标（0~1 范围）
    let normalizedX = tapPoint.x / localSeatView.bounds.width
    let normalizedY = tapPoint.y / localSeatView.bounds.height

    rtcEngine.setCameraExposurePoint(CGPoint(x: normalizedX, y: normalizedY))
    self.cameraExposurePointXTextField.text = String(format: "%.2f", normalizedX)
    self.cameraExposurePointYTextField.text = String(format: "%.2f", normalizedY)
}

手动设置聚焦点

ARTC 提供了检测个设置摄像头手动聚焦点（Focus Point）的功能，与曝光点的接口类似，但是功能侧重于调整摄像头的对焦位置。使用此功能前，请调用isCameraFocusPointSupported检查是否支持。

说明

手动设置对焦点后，聚焦是静态的，不会持续追踪该区域，也不会随着目标物体的移动动态调整焦点。如果需要动态跟踪，可以考虑使用人脸检测结合自动对焦。

接口信息

/**
 * @brief 是否支持摄像头手动聚焦
 * @return
 * - true: 支持
 * - false: 不支持
 * @note 只有iOS和android提供这个接口，用来检查当前camera是否可以设置聚焦点
 */
public abstract boolean isCameraFocusPointSupported();
/**
 * @brief 设置摄像头手动聚焦点
 * @param x x轴坐标值
 * @param y y轴坐标值
 * @return
 * - 0: 成功
 * - 非0: 失败
 * @note 只有iOS和android提供这个接口，调用后camera对所设点做一次曝光调整，后面一直保持这个对焦值
 */
public abstract int setCameraFocusPoint(float x, float y);

调用示例

示例代码演示功能，在单击画面时设置曝光点，双击时设置聚焦点。

Android

mLocalViewGestureDetector = new GestureDetector(this, new GestureDetector.SimpleOnGestureListener() {
    @Override
    public boolean onDoubleTap(@NonNull MotionEvent e) {
        // 处理双击
        if(mAliRtcEngine != null && mAliRtcEngine.isCameraFocusPointSupported()) {
            float[] normalizedCoords = getNormalizedCoordinates(e.getX(), e.getY());
            if (normalizedCoords[0] != -1 && normalizedCoords[1] != -1) {
                mAliRtcEngine.setCameraFocusPoint(normalizedCoords[0], normalizedCoords[1]);
                mCameraFocusPointX.setText(String.format("%.2f", normalizedCoords[0]));
                mCameraFocusPointY.setText(String.format("%.2f", normalizedCoords[1]));
            }
        }
        return true;
    }
    @Override
    public boolean onSingleTapConfirmed(@NonNull MotionEvent e) {
        // 处理单击
        // ...
        return true;
    }
});

iOS

@objc func handleSeatViewDoubleTap(_ gesture: UITapGestureRecognizer) {
    guard let localSeatView = self.localPreviewSeatView else {
        return
    }
    guard let rtcEngine = self.rtcEngine, rtcEngine.isCameraFocusPointSupported() else { return }
    
    let tapPoint = gesture.location(in: localSeatView)
    // 将点击坐标转换为视频帧的归一化坐标（0~1 范围）
    let normalizedX = tapPoint.x / localSeatView.bounds.width
    let normalizedY = tapPoint.y / localSeatView.bounds.height
    
    rtcEngine.setCameraFocus(CGPoint(x: normalizedX, y: normalizedY))
    self.cameraFocusPointXTextField.text = String(format: "%.2f", normalizedX)
    self.cameraFocusPointYTextField.text = String(format: "%.2f", normalizedY)
}

自动人脸聚焦

ARTC 提供配置摄像头自动人脸聚焦功能的接口，如果设备支持，开启此功能后摄像头会自动检测画面中的人脸位置并进行对焦，使人脸区域始终保持清晰对焦。

使用场景：应用于人脸识别场景、人像拍摄优化以及视频通话中提升视觉效果。

说明

启动前请调用isCameraAutoFocusFaceModeSupported检查当前设备是否支持。

接口信息

/**
 * @brief 是否支持摄像头自动人脸聚焦
 * @return
 * - true: 支持
 * - false: 不支持
 * @note 只有iOS和android提供这个接口，在camera没有打开的情况下返回false，
 *       在camera打开的情况下，如果当前camera同时支持人脸识别和对焦功能则返回true
 */
public abstract boolean isCameraAutoFocusFaceModeSupported();

/**
 * @brief 设置摄像头人脸聚焦
 * @param enable
 * - true: 开启
 * - false: 关闭
 * @return
 * - true: 成功
 * - false: 失败
 * @note 只有iOS和android提供这个接口，如果{@link AliRtcEngine#isCameraAutoFocusFaceModeSupported}返回true
 *       且此调用enable为true的情况下，实时对焦到采集到数据的人脸上
 */
public abstract boolean setCameraAutoFocusFaceModeEnabled(boolean enable);

调用示例

Android

if (mAliRtcEngine.isCameraAutoFocusFaceModeSupported()) {
    mAliRtcEngine.setCameraAutoFocusFaceModeEnabled(isChecked);
}

iOS

@IBAction func onCameraAudoFocusSwitch(_ sender: UISwitch) {
    if ((self.rtcEngine?.isCameraAutoFocusFaceModeSupported()) != nil) {
        self.rtcEngine?.setCameraAutoFocusFaceModeEnabled(sender.isOn)
    }
}

闪光灯开关

ARTC SDK 支持控制摄像头的闪光灯开关。常用于需要调节摄像头光亮度的场景，例如暗光场景拍摄、视频拍摄或特殊光照需求。

说明

  • 该接口仅支持 iOS 和 Android 平台，并且必须在设备硬件支持闪光灯功能的情况下才能正常使用。

  • 闪光灯功能通常仅适用于后置摄像头，前置摄像头通常不具备物理闪光灯（部分设备可能通过屏幕模拟闪光效果实现，但该接口不覆盖此功能）。

接口信息

/**
 * @brief 设置摄像头闪光灯开关
 * @param flash 是否打开闪光灯
 * @return
 * - 0: 设置成功
 * - 非0: 设置失败
 * @note 只有iOS和android提供这个接口，一般后置摄像头有闪光灯功能
 */
public abstract int setCameraFlash(boolean flash);

调用示例

Android

mCameraFlashSwitch = findViewById(R.id.camera_flash_switch);
mCameraFlashSwitch.setEnabled(false);
mCameraFlashSwitch.setOnCheckedChangeListener((buttonView, isChecked) -> {
    if (mAliRtcEngine != null) {
        mAliRtcEngine.setCameraFlash(isChecked);
    }
});

iOS

@IBOutlet weak var cameraFlashSwitch: UISwitch!
@IBAction func onCameraFlashSwitch(_ sender: UISwitch) {
    if self.rtcEngine?.getCurrentCameraDirection() == .back {
        self.rtcEngine?.setCameraFlash(sender.isOn)
    }
}
上一篇：质量指标监控下一篇：进阶功能