Gérer les périphériques de capture vidéo - ApsaraVideo Live

Le SDK ARTC fournit des API pour gérer les périphériques de capture vidéo sur différentes plateformes, notamment le zoom de la caméra, l'exposition, la mise au point et le contrôle du flash.

Présentation des fonctionnalités

Le SDK ARTC offre un contrôle complet des périphériques de capture vidéo. Sur les plateformes iOS et Android, vous pouvez affiner les paramètres de la caméra, tels que le zoom, l'exposition et la mise au point (manuelle ou automatique), afin d'améliorer la qualité de la capture vidéo.

Exemples de code

Gestion des périphériques de capture vidéo sous Android : Android/ARTCExample/BasicUsage/src/main/java/com/aliyun/artc/api/basicusage/CameraCommonControl/CameraActivity.java.

Gestion des périphériques de capture vidéo sous iOS : iOS/ARTCExample/BasicUsage/CameraCommonSetting/CameraCommonControlVC.swift.

Gestion des périphériques de capture vidéo sous Harmony : Harmony/ARTCExample/entry/src/main/ets/pages/basicusage/CameraPage.ets.

Prérequis

Vous disposez d'un compte Alibaba Cloud et avez créé une application Real-Time Communication (RTC). Pour plus d'informations, consultez la rubrique Créer une application. Vous avez obtenu un AppID et une AppKey depuis la console ApsaraVideo Live.
Intégration du SDK et implémentation des fonctionnalités de base :
- Vous avez intégré le SDK ARTC à votre projet et implémenté les fonctionnalités de base de Real-Time Communication (RTC). Pour plus d'informations, consultez les rubriques Intégrer le SDK et Implémenter un appel audio et vidéo.
- La caméra est active, par exemple après le lancement d'un aperçu avec startPreview ou la connexion à un canal avec joinChannel.

Implémentation

Définir le zoom de la caméra

Le SDK ARTC permet de contrôler le zoom de la caméra.

Référence de l'API

/**
 * @brief Sets the camera zoom.
 * @param zoom The zoom factor. The value ranges from 1 to the maximum zoom value supported by the camera.
 * @return
 * - 0: Success.
 * - A non-zero value: Failure.
 * @note This API is available only on iOS and Android.
 */
public abstract int setCameraZoom(float zoom);

 /**
 * @brief Gets the maximum zoom factor of the camera.
 * @return The maximum zoom factor of the camera.
 */
public abstract float GetCameraMaxZoomFactor();

/**
 * @brief Gets the current zoom factor of the camera.
 * @return The current zoom factor of the camera.
 */
public abstract float GetCurrentZoom();

Exemples

Android

// Get zoom information.
private void initZoomSeekBar() {
    if (mAliRtcEngine != null) {
        zoomSeekBar.setEnabled(true);
        // Get the maximum zoom value.
        float maxZoom = mAliRtcEngine.GetCameraMaxZoomFactor();
        float currZoom = mAliRtcEngine.GetCurrentZoom();
        // Set the SeekBar range (from 1.0 to maxZoom, with a step of 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);
        }
    }
}
// Set the zoom.
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

// Get zoom information.
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)"
}

// Set the zoom.
@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)
}

Harmony

private handleZoomChange(value: number): void {
  if (!this.rtcEngine) {
    return;
  }

  // Calculate the zoom value based on the progress: zoom = 1.0 + (value / 10.0).
  const newZoom = 1.0 + (value / 10.0);

  // Clamp the zoom value between 1.0 and 10.0.
  const clampedZoom = Math.max(1.0, Math.min(10.0, newZoom));

  this.rtcEngine.setCameraZoom(clampedZoom);
  this.zoomValue = clampedZoom.toFixed(1);

  console.info(`Set zoom: ${clampedZoom}`);
}

Définir l'exposition de la caméra

Le SDK ARTC permet d'ajuster l'exposition de la caméra pour contrôler la luminosité de l'image.

Référence de l'API

/**
 * @brief Sets the camera exposure.
 * @param exposure The exposure value.
 * @return
 * - 0: Success.
 * - A non-zero value: Failure.
 */
public abstract int SetExposure(float exposure);

/**
 * @brief Gets the current camera exposure.
 * @return The current camera exposure.
 */
public abstract float GetCurrentExposure();

/**
 * @brief Gets the minimum camera exposure.
 * @return The minimum camera exposure.
 */
public abstract float GetMinExposure();

/**
 * @brief Gets the maximum camera exposure.
 * @return The maximum camera exposure.
 */
public abstract float GetMaxExposure();

Exemples

Android

// Get exposure information.
private void initExposureSeekBar() {
    if (mAliRtcEngine != null) {
        exposureSeekBar.setEnabled(true);
        // Get the maximum exposure value.
        float maxExposure = mAliRtcEngine.GetMaxExposure();
        // Get the minimum exposure value.
        float minExposure = mAliRtcEngine.GetMinExposure();
        float currExposure = mAliRtcEngine.GetCurrentExposure();
        if(maxExposure > minExposure) {
            // Reset the SeekBar range.
            int maxProgress = (int)((maxExposure - minExposure) * 10);
            exposureSeekBar.setMax(maxProgress);
            int currProgress = (int)((currExposure - minExposure) * 10);
            exposureSeekBar.setProgress(currProgress);
        } else {
            exposureSeekBar.setEnabled(false);
        }
    }
}
// Set the exposure.
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

// Get device exposure information.
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)"
}
// Set the exposure.
@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)
}

Harmony

// Handle exposure change.
private handleExposureChange(value: number): void {
  if (!this.rtcEngine) {
    return;
  }
  // Conversion formula: exposure value = progress value / 10.
  const actualValue = value / 10.0;
  // Clamp the exposure value between -12.0 and 12.0.
  const clampedExposure = Math.max(-12.0, Math.min(12.0, actualValue));
  // Update the state.
  this.exposureSliderValue = value;
  this.exposureValue = this.formatExposureValue(clampedExposure);
  // Call the RTC engine to set the exposure compensation.
  try {
    this.rtcEngine.setExposure(clampedExposure);
    console.info(`Set exposure compensation: ${clampedExposure}`);
  } catch (error) {
    console.error('Failed to set exposure compensation:', error);
  }
}

Définir manuellement le point d'exposition

Le SDK ARTC permet de définir manuellement un point d'exposition. Lorsqu'un utilisateur appuie sur un endroit de l'écran, la caméra ajuste l'exposition en fonction des conditions d'éclairage de cette zone.

Remarque

Avant de définir un point d'exposition, appelez isCameraExposurePointSupported pour vérifier que l'appareil prend en charge cette fonctionnalité.
Les coordonnées doivent être des valeurs normalisées.

Référence de l'API

/**
 * @brief Checks whether the camera supports setting a manual exposure point.
 * @return
 * - true: Supported.
 * - false: Not supported.
 * @note This API is available only on iOS and Android and is used to check if an exposure point can be set for the current camera.
 */
public abstract boolean isCameraExposurePointSupported();
/**
 * @brief Sets the camera exposure point.
 * @param x The normalized x-coordinate. The value ranges from 0 to 1.
 * @param y The normalized y-coordinate. The value ranges from 0 to 1.
 * @return
 * - 0: Success.
 * - A non-zero value: Failure.
 * @note This API is available only on iOS and Android. After you call this method, the camera performs a one-time exposure adjustment at the specified point and maintains that exposure value.
 */
public abstract int setCameraExposurePoint(float x, float y);

Exemples

Android

// Manually set the exposure point.
mLocalViewGestureDetector = new GestureDetector(this, new GestureDetector.SimpleOnGestureListener() {
    @Override
    public boolean onDoubleTap(@NonNull MotionEvent e) {
        // Handle double-tap.
        // ...
        return true;
    }
    @Override
    public boolean onSingleTapConfirmed(@NonNull MotionEvent e) {
        // Handle single-tap.
        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)
    // Convert the tap coordinates to normalized coordinates (0-1 range) of the video frame.
    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)
}

Harmony

private handleSingleTap(touchX: number, touchY: number): void {
  if (!this.rtcEngine) {
    return;
  }
  // Get normalized coordinates.
  const normalizedCoords = this.getNormalizedCoordinates(touchX, touchY);
  if (normalizedCoords[0] !== -1 && normalizedCoords[1] !== -1) {
    this.rtcEngine.setCameraExposurePoint(normalizedCoords[0], normalizedCoords[1]);
    this.exposurePointX = normalizedCoords[0].toFixed(2);
    this.exposurePointY = normalizedCoords[1].toFixed(2);
    console.info('Set exposure point:', this.exposurePointX, this.exposurePointY);
  }
}

Définir manuellement le point de mise au point

Le SDK ARTC permet de définir manuellement un point de mise au point de la caméra. Cette fonctionnalité fonctionne de manière similaire à celle du point d'exposition, mais elle ajuste la position de la mise au point. Avant d'utiliser cette fonctionnalité, appelez isCameraFocusPointSupported pour vérifier la prise en charge par l'appareil.

Remarque

Après avoir défini manuellement un point de mise au point, la mise au point devient statique. Elle ne suit pas continuellement la zone ni ne s'ajuste dynamiquement lorsque l'objet se déplace. Pour un suivi dynamique, envisagez d'utiliser la fonctionnalité de mise au point automatique sur les visages.

Référence de l'API

/**
 * @brief Checks whether the camera supports manual focus.
 * @return
 * - true: Supported.
 * - false: Not supported.
 * @note This API is available only on iOS and Android and is used to check if a focus point can be set for the current camera.
 */
public abstract boolean isCameraFocusPointSupported();
/**
 * @brief Sets the manual focus point for the camera.
 * @param x The x-coordinate value (normalized).
 * @param y The y-coordinate value (normalized).
 * @return
 * - 0: Success.
 * - A non-zero value: Failure.
 * @note This API is available only on iOS and Android. After you call this method, the camera performs a one-time focus adjustment at the specified point and maintains that focus value.
 */
public abstract int setCameraFocusPoint(float x, float y);

Exemples

Les exemples suivants montrent comment définir le point d'exposition lors d'un simple appui et le point de mise au point lors d'un double appui.

Android

mLocalViewGestureDetector = new GestureDetector(this, new GestureDetector.SimpleOnGestureListener() {
    @Override
    public boolean onDoubleTap(@NonNull MotionEvent e) {
        // Handle double-tap.
        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) {
        // Handle single-tap.
        // ...
        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)
    // Convert the tap coordinates to normalized coordinates (0-1 range) of the video frame.
    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)
}

Harmony

private handleDoubleTap(touchX: number, touchY: number): void {
  if (!this.rtcEngine) {
    return;
  }
  // Get normalized coordinates.
  const normalizedCoords = this.getNormalizedCoordinates(touchX, touchY);
  if (normalizedCoords[0] !== -1 && normalizedCoords[1] !== -1) {
    this.rtcEngine.setCameraFocusPoint(normalizedCoords[0], normalizedCoords[1]);
    this.focusPointX = normalizedCoords[0].toFixed(2);
    this.focusPointY = normalizedCoords[1].toFixed(2);
    console.info('Set focus point:', this.focusPointX, this.focusPointY);
  }
}

Mise au point automatique sur les visages

Le SDK ARTC propose une API pour activer la mise au point automatique sur les visages. Sur les appareils compatibles, la caméra détecte automatiquement les visages dans le cadre vidéo et ajuste la mise au point pour les garder nets.

Cas d'utilisation : reconnaissance faciale, optimisation des portraits et amélioration de la qualité visuelle lors des appels vidéo.

Remarque

Avant de commencer, appelez isCameraAutoFocusFaceModeSupported pour vérifier si l'appareil actuel prend en charge cette fonctionnalité.

Référence de l'API

/**
 * @brief Checks whether the camera supports the auto-focus on faces feature.
 * @return
 * - true: Supported.
 * - false: Not supported.
 * @note This API is available only on iOS and Android. It returns false if the camera is off. 
 *       If the camera is on and supports both face detection and auto-focus, it returns true.
 */
public abstract boolean isCameraAutoFocusFaceModeSupported();

/**
 * @brief Enables or disables the auto-focus on faces feature.
 * @param enable
 * - true: Enable.
 * - false: Disable.
 * @return
 * - true: Success.
 * - false: Failure.
 * @note This API is available only on iOS and Android. If {@link AliRtcEngine#isCameraAutoFocusFaceModeSupported} returns true
 *       and you set enable to true, the camera continuously focuses on the detected faces.
 */
public abstract boolean setCameraAutoFocusFaceModeEnabled(boolean enable);

Exemples

Android

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

iOS

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

Activer ou désactiver le flash

Le SDK ARTC permet d'allumer ou d'éteindre le flash de la caméra, ce qui s'avère utile en cas de faible luminosité ou pour d'autres besoins d'éclairage spécifiques.

Remarque

Cette fonctionnalité est disponible uniquement sur iOS et Android et nécessite un flash matériel.
Le flash est généralement disponible uniquement pour la caméra arrière. Les caméras frontales ne disposent généralement pas de flash physique. Bien que certains appareils simulent un effet de flash à l'aide de l'écran, cette API ne contrôle pas cette fonction.

Référence de l'API

/**
 * @brief Turns the camera flashlight on or off.
 * @param flash Specifies whether to turn on the flashlight.
 * @return
 * - 0: Success.
 * - A non-zero value: Failure.
 * @note This API is available only on iOS and Android. Typically, only the rear camera has a flashlight.
 */
public abstract int setCameraFlash(boolean flash);

Exemples

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)
    }
}

Harmony

private handleFlashChange(value: boolean): void {
  if (!this.rtcEngine) {
    return;
  }

  this.rtcEngine.setCameraFlash(value);
}