Le SDK Client AOQ offre des capacités vidéo complètes, incluant la capture vidéo, le rendu, la configuration des codecs, les rappels de données de trames et l'entrée vidéo externe. Ce document présente les fonctionnalités vidéo courantes pour Android (Java), iOS (Objective-C) et HarmonyOS (ArkTS).
1. Capture vidéo
1,1 Présentation
La capture vidéo active la caméra de l'appareil et injecte les trames vidéo en temps réel dans le pipeline d'encodage du SDK. Deux modes de capture sont pris en charge :
- Capture interne (par défaut) : Le SDK gère automatiquement la caméra (ouverture, capture des trames et fermeture). Il permet également de basculer entre les caméras avant et arrière.
- Capture externe : L'application gère la caméra ou toute autre source vidéo. Les trames capturées sont transmises au SDK via
pushExternalVideoCapturedFrame.
1,2 Paramètres de configuration de la capture
Paramètre | Type | Valeur par défaut | Description |
|---|---|---|---|
width | int | 1280 | Largeur de capture en pixels. Non utilisé en mode de capture externe. |
height | int | 720 | Hauteur de capture en pixels. Non utilisé en mode de capture externe. |
fps | int | 15 | Fréquence d'images de capture. En mode externe, cette fréquence dépend de la vitesse d'injection des trames. |
isExternal | bool | false | Indique si le mode de capture externe doit être utilisé. |
cameraDirection | AoqCameraDirection | Front(0) | Orientation de la caméra. Non utilisé en mode de capture externe. |
1,3 Énumération de l'orientation de la caméra
Valeur d'énumération | Nombre | Description |
|---|---|---|
AoqCameraDirectionFront | 0 | Caméra frontale |
AoqCameraDirectionBack | 1 | Caméra arrière |
1,4 Référence API
Fonction | Android | iOS | HarmonyOS |
|---|---|---|---|
Démarrer la capture | startVideoCapture(config) | startVideoCapture:config: | startVideoCapture(config) |
Arrêter la capture | stopVideoCapture() | stopVideoCapture | stopVideoCapture() |
Changer de caméra | switchCamera(direction) | switchCamera: | switchCamera(direction) |
1,5 Exemple
AndroidAoqVideoCaptureConfig config = new AoqVideoCaptureConfig();
config.width = 1280;
config.height = 720;
config.fps = 15;
config.cameraDirection = AoqCameraDirection.AoqCameraDirectionFront;
engine.startVideoCapture(config);
AoqVideoCaptureConfig *config = [[AoqVideoCaptureConfig alloc] init];
config.width = 1280;
config.height = 720;
config.fps = 15;
config.cameraDirection = AoqCameraDirectionFront;
[engine startVideoCapture:config];
let config: AoqVideoCaptureConfig = {
width: 1280,
height: 720,
fps: 15,
cameraDirection: AoqCameraDirection.AoqCameraDirectionFront
};
engine.startVideoCapture(config);
2. Rendu vidéo
2,1 Présentation
Le rendu vidéo affiche à l'écran les trames capturées localement ou reçues à distance. Le SDK permet de définir une fenêtre d'aperçu local ainsi qu'une fenêtre de rendu distant. Utilisez trackType pour distinguer le flux vidéo (Video) du flux de partage d'écran (Screen).
2,2 Modes de rendu
Valeur d'énumération | Nombre | Description |
|---|---|---|
AoqRenderModeAuto | 0 | Mode automatique |
AoqRenderModeStretch | 1 | Étirement pour remplir. L'image peut être déformée. |
AoqRenderModeFill | 2 | Ajustement avec bandes noires. L'image complète est visible. |
AoqRenderModeCrop | 3 | Mode recadrage. Des parties de l'image peuvent être coupées. |
2,3 Configuration du canevas
Paramètre | Type | Valeur par défaut | Description |
|---|---|---|---|
view | Vue de la plateforme | null | Vue de rendu. Android : SurfaceView ou TextureView. iOS : UIView. HarmonyOS : XComponent. |
renderMode | AoqRenderMode | Auto(0) | Mode d'affichage du rendu |
2,4 Référence API
Fonction | Android | iOS | HarmonyOS |
|---|---|---|---|
Définir l'aperçu local | setLocalView(trackType, canvas) | setLocalView:trackType:canvas: | setLocalView(trackType, canvas) |
Définir la vue distante | setRemoteView(trackType, canvas) | setRemoteView:trackType:canvas: | setRemoteView(trackType, canvas) |
RemarqueDifférences selon la plateforme : Android utilise SurfaceView ou TextureView comme conteneur de rendu. iOS utilise UIView (encapsulé en interne par AoqRenderView avec accélération Metal). HarmonyOS utilise XComponent (géré par AoqXComponentController pour un rendu natif).
3. Configuration du codec vidéo
3,1 Présentation
Configurez les paramètres d'encodage vidéo tels que le format d'encodage, la résolution, la fréquence d'images, le débit binaire, l'intervalle d'images clés, l'effet miroir et l'orientation. Utilisez trackType pour appliquer des configurations d'encodage distinctes à la piste vidéo et à la piste de partage d'écran.
3,2 Paramètres de configuration de l'encodage
Paramètre | Type | Valeur par défaut | Description |
|---|---|---|---|
trackType | AoqTrackType | Video(1) | Type de piste : Video |
codecType | AoqEncoderType | VideoH264(3) | Format d'encodage |
width | int | 720 | Largeur encodée |
height | int | 1280 | Hauteur encodée |
fps | int | 5 | Fréquence d'images d'encodage |
bitrate | int | 500000 | Débit binaire cible (bps) |
minBitrate | int | 128000 | Débit binaire minimal (bps) |
keyframeInterval | int | 2 | Intervalle d'images clés (secondes) |
mirrorMode | AoqMirrorMode | Disabled(0) | Mode miroir |
orientationMode | AoqOrientationMode | Auto(0) | Mode d'orientation |
isExternal | bool | false | Mode d'encodage externe. Si vrai, l'application injecte des trames pré-encodées. |
3,3 Énumération des formats d'encodage
Valeur d'énumération | Nombre | Description |
|---|---|---|
AoqEncoderTypeVideoH264 | 3 | Encodage H.264 |
AoqEncoderTypeVideoJpeg | 4 | Encodage JPEG (pour les trames encodées externes) |
3,4 Mode miroir
Valeur d'énumération | Nombre | Description |
|---|---|---|
AoqMirrorModeDisabled | 0 | Miroir désactivé |
AoqMirrorModeEnabled | 1 | Miroir activé |
3,5 Mode d'orientation
Valeur d'énumération | Nombre | Description |
|---|---|---|
AoqOrientationModeAuto | 0 | Orientation automatique |
AoqOrientationModePortrait | 1 | Orientation portrait |
AoqOrientationModeLandscape | 2 | Orientation paysage |
3,6 Référence API
Fonction | Android | iOS | HarmonyOS |
|---|---|---|---|
Définir la configuration d'encodage | setVideoEncoderConfig(config) | setVideoEncoderConfig: | setVideoEncoderConfig(config) |
4. Entrée de trames vidéo externes
4,1 Présentation
L'entrée de trames vidéo externes permet à votre application d'injecter des données de trames personnalisées dans le SDK pour des scénarios de capture externe ou d'encodage externe. Deux méthodes d'injection sont prises en charge :
- Injection de trames brutes : Transmettez des données de pixels non encodées (I420, NV12, NV21, BGRA, RGBA et formats similaires) au SDK. Celui-ci se charge alors de l'encodage.
- Injection de trames encodées : Transmettez directement au SDK des données déjà encodées (par exemple, JPEG). Le SDK les encapsule et les envoie sans réencodage.
Le routage est contrôlé par trackType : AoqTrackTypeVideo dirige vers la piste de capture vidéo ; AoqTrackTypeScreen dirige vers la piste de partage d'écran.
4,2 Énumération des formats de pixels
Valeur d'énumération | Nombre | Description | Prise en charge par plateforme |
|---|---|---|---|
AoqVideoPixelFormatI420 | 1 | I420 tri-planaire | Toutes les plateformes |
AoqVideoPixelFormatNV12 | 2 | NV12 bi-planaire | Toutes les plateformes |
AoqVideoPixelFormatNV21 | 3 | NV21 bi-planaire | Toutes les plateformes |
AoqVideoPixelFormatBGRA | 4 | BGRA compact | Toutes les plateformes |
AoqVideoPixelFormatRGBA | 5 | RGBA compact | Toutes les plateformes |
AoqVideoPixelFormatCVPixelBuffer | 6 | Zéro copie Apple | iOS uniquement |
AoqVideoPixelFormatTextureOES | 7 | Texture OES | Android uniquement |
AoqVideoPixelFormatTexture2D | 8 | Texture 2D | Android uniquement |
4,3 Structure des données de trame vidéo brute (AoqVideoFrame)
Champ | Type | Description |
|---|---|---|
format | AoqVideoPixelFormat | Format de pixel |
width | int | Largeur en pixels |
height | int | Hauteur en pixels |
data | byte[] / ArrayBuffer | Données au format compact (NV12/NV21/BGRA/RGBA) |
dataY / dataU / dataV | byte[] / ArrayBuffer | Données I420 tri-planaires |
strideY / strideU / strideV | int | Pas (strides) I420 tri-planaires |
textureId | int | ID de texture (valable pour Android TextureOES/Texture2D) |
transformMatrix | float[16] | Matrice de transformation de texture 4×4 (Android) |
eglContext | EGLContext | Contexte EGL partagé (Android) |
pixelBuffer | CVPixelBufferRef | Zéro copie Apple (iOS) |
timeStamp | long | Horodatage en ms. Si 0, le SDK utilise l'horloge locale. |
4,4 Structure des données de trame vidéo encodée (AoqVideoEncodedFrame)
Champ | Type | Valeur par défaut | Description |
|---|---|---|---|
codec | AoqVideoCodecType | JPEG(0) | Format d'encodage |
data | byte[] / ArrayBuffer | - | Données encodées |
width | int | - | Largeur en pixels |
height | int | - | Hauteur en pixels |
timeStamp | long | 0 | Horodatage en ms |
4,5 Référence API
Fonction | Android | iOS | HarmonyOS |
|---|---|---|---|
Injecter une trame brute | pushExternalVideoCapturedFrame(trackType, frame) | pushExternalVideoCapturedFrame:frame: | pushExternalVideoCapturedFrame(trackType, frame) |
Injecter une trame encodée | pushExternalVideoEncodedFrame(trackType, frame) | pushExternalVideoEncodedFrame:frame: | pushExternalVideoEncodedFrame(trackType, frame) |
5. Rappels de trames vidéo
5,1 Présentation
Les rappels de trames vidéo permettent d'obtenir des données de trames brutes à différentes étapes du pipeline vidéo, afin de réaliser des analyses vidéo, des traitements personnalisés, des enregistrements ou d'autres opérations similaires. Les modes lecture seule et lecture-écriture sont tous deux pris en charge. En mode lecture-écriture, vous avez la possibilité de modifier les données de la trame et de les réinjecter dans le SDK.
5,2 Positions des sources de données prises en charge
Source de données | Valeur d'énumération | Description |
|---|---|---|
Captured | 0 | Données vidéo après capture, avant prétraitement |
PreEncode | 1 | Données vidéo avant encodage, après prétraitement |
Remote | 2 | Données vidéo distantes après décodage, avant rendu |
5,3 Paramètres de configuration des rappels
Paramètre | Type | Valeur par défaut | Description |
|---|---|---|---|
format | AoqVideoPixelFormat | I420(1) | Format de pixel pour les données de rappel |
alignment | AoqVideoObserverAlignment | Default(0) | Politique d'alignement de la largeur |
mode | AoqVideoObserverMode | ReadOnly(0) | Mode lecture seule (0) ou lecture-écriture (1) |
mirrorApplied | bool | false | Indique si l'effet miroir doit être appliqué aux données de rappel |
5,4 Énumération de l'alignement de la largeur
Valeur d'énumération | Nombre | Description |
|---|---|---|
AoqVideoObserverAlignmentDefault | 0 | Alignement par défaut |
AoqVideoObserverAlignmentEven | 1 | Alignement sur 2 octets |
AoqVideoObserverAlignment4 | 2 | Alignement sur 4 octets |
AoqVideoObserverAlignment8 | 3 | Alignement sur 8 octets |
AoqVideoObserverAlignment16 | 4 | Alignement sur 16 octets |
5,5 Étapes d'utilisation
- Enregistrer l'observateur : Appelez
setVideoFrameObserverpour définir l'écouteur de rappel de trames vidéo. - Activer la source de données : Appelez
enableVideoFrameObserverpour sélectionner la position de la source de données et démarrer les rappels. - Traiter les données de rappel : Récupérez les données de trame dans le rappel. Ces données ne sont valides que pendant la durée du rappel. Copiez-les si vous devez les utiliser de manière asynchrone.
5,6 Référence API
Fonction | Android | iOS | HarmonyOS |
|---|---|---|---|
Enregistrer l'observateur | setVideoFrameObserver(listener) | setVideoFrameObserver: | setVideoFrameObserver(observer) |
Activer les rappels | enableVideoFrameObserver(enabled, source, config) | enableVideoFrameObserver:videoSource:config: | enableVideoFrameObserver(enabled, source, config) |
5,7 Méthodes de rappel
Rappel | Android | iOS | HarmonyOS |
|---|---|---|---|
Données capturées | onCapturedVideoFrame(frame) | onCapturedVideoFrame: | onCapturedVideoFrame(frame) |
Données pré-encodage | onPreEncodeVideoFrame(trackType, frame) | onPreEncodeVideoFrame:frame: | onPreEncodeVideoFrame(trackType, frame) |
Données distantes | onRemoteVideoFrame(trackType, frame) | onRemoteVideoFrame:frame: | onRemoteVideoFrame(trackType, frame) |
RemarqueLe retour de true/ YES depuis un rappel indique que les données ont été modifiées et doivent être réinjectées dans le SDK. Cela ne prend effet qu'en mode ReadWrite avec le format I420.
7. Contrôle de l'envoi des flux multimédias
7,1 Présentation
Contrôlez l'envoi des flux multimédias locaux. Utilisez trackType pour cibler une piste spécifique (Audio, Video ou Screen). Lorsque l'envoi est désactivé, la capture et l'encodage continuent, mais les données ne sont pas transmises au destinataire distant.
7,2 Référence API
Fonction | Android | iOS | HarmonyOS |
|---|---|---|---|
Contrôler l'envoi du flux | enableSendMediaStream(trackType, enable) | enableSendMediaStream:enable: | enableSendMediaStream(trackType, enable) |
7,3 Énumération des types de pistes
Valeur d'énumération | Nombre | Description |
|---|---|---|
AoqTrackTypeAudio | 0 | Piste audio |
AoqTrackTypeVideo | 1 | Piste vidéo |
AoqTrackTypeData | 2 | Piste de données |
8. Surveillance de l'état des périphériques vidéo
8,1 Présentation
Le SDK surveille automatiquement les changements d'état de la caméra et notifie la couche applicative via le rappel onVideoDeviceStateChanged.
8,2 Codes d'état du périphérique
Code d'état | Valeur | Description |
|---|---|---|
AoqVideoDeviceNone | 0 | État initial |
AoqVideoDeviceCaptureStarting | 1 | Démarrage de la capture |
AoqVideoDeviceCaptureStarted | 2 | Capture démarrée |
AoqVideoDeviceCaptureStopping | 3 | Arrêt de la capture en cours |
AoqVideoDeviceCaptureStopped | 4 | Capture arrêtée |
AoqVideoDeviceCaptureFail | 5 | Échec de la capture |
8,3 Référence des rappels
Rappel | Android | iOS | HarmonyOS |
|---|---|---|---|
Changement d'état du périphérique | onVideoDeviceStateChanged(state) | onVideoDeviceStateChanged: | onVideoDeviceStateChanged(state) |
9. Codes d'erreur et d'avertissement vidéo
9,1 Codes d'erreur vidéo
Code d'erreur | Valeur | Description |
|---|---|---|
AoqErrorCodeVideo | 200 | Erreur vidéo générale |
VideoExternalBufferFull | 210 | Tampon externe vidéo plein |
VideoDevice | 220 | Erreur générale du périphérique vidéo |
CameraOpenFail | 221 | Échec de l'ouverture de la caméra |
CameraAuthFailed | 222 | Autorisation de caméra refusée |
CameraOccupied | 223 | Caméra utilisée par un autre processus |
CameraRunningError | 224 | Erreur de fonctionnement de la caméra |
VideoCodec | 230 | Erreur générale de codec vidéo |
EncoderInitFail | 231 | Échec de l'initialisation de l'encodeur |
VideoRender | 240 | Erreur générale de rendu vidéo |
RenderCreateFail | 241 | Échec de la création du moteur de rendu |
RenderDrawError | 242 | Erreur de dessin du rendu |
Screen | 300 | Erreur générale de partage d'écran |
RemarqueCodes d'erreur supplémentaires pour Android : ScreenPermissionDenied(310) — autorisation de partage d'écran refusée ; ScreenForegroundServiceFailed(311) — échec du démarrage du service de premier plan.
9,2 Codes d'avertissement vidéo
Code d'avertissement | Valeur | Description |
|---|---|---|
AoqWCVideo | 200 | Avertissement vidéo général |
CameraEnumerateError | 201 | Erreur d'énumération des caméras |
EncoderSwitched | 202 | Avertissement de changement d'encodeur |
RenderDowngrade | 203 | Avertissement de dégradation du rendu |
Annexe : Liste complète des méthodes API vidéo
Catégorie | Méthode | Description |
|---|---|---|
Contrôle de la capture | startVideoCapture | Ouvrir le périphérique de capture vidéo |
Contrôle de la capture | stopVideoCapture | Fermer le périphérique de capture vidéo |
Contrôle de la capture | switchCamera | Basculer entre la caméra avant et arrière |
Contrôle du rendu | setLocalView | Définir la fenêtre d'aperçu local |
Contrôle du rendu | setRemoteView | Définir la fenêtre de rendu distant |
Codec | setVideoEncoderConfig | Définir les paramètres d'encodage vidéo |
Entrée externe | pushExternalVideoCapturedFrame | Injecter une trame vidéo brute |
Entrée externe | pushExternalVideoEncodedFrame | Injecter une trame vidéo encodée |
Partage d'écran | startScreenCapture | Démarrer la capture d'écran |
Partage d'écran | stopScreenCapture | Arrêter la capture d'écran |
Contrôle du flux | enableSendMediaStream | Contrôler l'envoi du flux multimédia |
Rappels de trames | setVideoFrameObserver | Enregistrer un observateur de trames vidéo |
Rappels de trames | enableVideoFrameObserver | Activer ou désactiver les rappels de trames vidéo |