視頻採集裝置管理 - ApsaraVideo Live

視頻裝置管理是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 提供配置網路攝影機自動人臉聚焦功能的介面，如果裝置支援，開啟此功能後網路攝影機會自動檢測畫面中的人臉位置並進行對焦，使人臉地區始終保持清晰對焦。

使用情境：應用於Face Service情境、人像拍攝最佳化以及視訊通話中提升視覺效果。

說明

啟動前請調用isCameraAutoFocusFaceModeSupported檢查當前裝置是否支援。

介面資訊

/**
 * @brief 是否支援網路攝影機自動人臉聚焦
 * @return
 * - true: 支援
 * - false: 不支援
 * @note 只有iOS和android提供這個介面，在camera沒有開啟的情況下返回false，
 *       在camera開啟的情況下，如果當前camera同時支援Face Service和對焦功能則返回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)
    }
}