Cette rubrique décrit les API Python, les rappels (callbacks) et les types de données du SDK client AOQ pour Linux.
aoq_client_sdk. Tous les rappels sont déclenchés sur des threads natifs ; vous devez garantir vous-même la sécurité des threads.
Index des API
Cycle de vie du moteur
API | Description |
|---|---|
create_engine | Crée l'instance du moteur (singleton) |
destroy | Détruit l'instance du moteur |
get_version | Récupère la version du SDK |
connect | Se connecte au serveur relais |
disconnect | Se déconnecte du serveur |
Gestion des périphériques audio
API | Description |
|---|---|
start_audio_capture | Démarre la capture audio (implémentation vide sous Linux ; n'ouvre pas de microphone) |
stop_audio_capture | Arrête la capture audio (sans effet réel sous Linux) |
mute_audio_capture | Active ou désactive le mode muet pour la capture audio (la capture par périphérique n'est pas disponible sous Linux) |
start_audio_player | Démarre la lecture audio (implémentation vide sous Linux ; n'ouvre pas de haut-parleur) |
stop_audio_player | Arrête la lecture audio (sans effet réel sous Linux) |
pause_audio_player | Met en pause la lecture audio (la lecture par périphérique n'est pas disponible sous Linux) |
resume_audio_player | Reprend la lecture audio (la lecture par périphérique n'est pas disponible sous Linux) |
interrupt_audio_player | Interrompt la session audio en cours |
Configuration de l'encodage audio
API | Description |
|---|---|
set_audio_encoder_config | Définit les paramètres d'encodage audio |
set_audio_decoder_config | Définit les paramètres de décodage audio |
Gestion des périphériques vidéo
API | Description |
|---|---|
start_video_capture | Démarre la capture vidéo (seul le mode de capture externe est pris en charge sous Linux) |
stop_video_capture | Arrête la capture vidéo (s'applique uniquement au mode de capture externe sous Linux) |
set_local_view | Définit ou supprime la fenêtre de rendu vidéo locale (aucune implémentation de rendu sous Linux) |
set_remote_view | Définit ou supprime la fenêtre de rendu vidéo distante (aucune implémentation de rendu sous Linux) |
Codec vidéo et entrée externe
API | Description |
|---|---|
set_video_encoder_config | Définit les paramètres d'encodage vidéo |
set_video_decoder_config | Définit les paramètres de décodage vidéo |
push_external_video_frame | Transmet une trame vidéo capturée en externe |
push_external_video_encoded_frame | Transmet une trame vidéo encodée en externe |
Contrôle des flux multimédias
API | Description |
|---|---|
enable_send_media_stream | Active ou désactive l'envoi d'un flux multimédia local |
Lecture de fichiers audio
API | Description |
|---|---|
start_audio_file | Démarre la lecture d'un fichier audio local vers le flux de publication |
stop_audio_file | Arrête la lecture du fichier audio |
pause_audio_file | Met en pause la lecture du fichier audio |
resume_audio_file | Reprend la lecture du fichier audio |
get_audio_file_duration | Consulte la durée totale du fichier audio |
get_audio_file_current_position | Consulte la position de lecture actuelle du fichier audio |
set_audio_file_position_millis | Définit la position de lecture du fichier audio (recherche) |
set_audio_file_volume | Définit le volume du fichier audio |
get_audio_file_volume | Consulte le volume actuel du fichier audio |
Flux audio externes
API | Description |
|---|---|
add_audio_external_stream | Ajoute un flux audio externe |
remove_audio_external_stream | Supprime un flux audio externe |
push_audio_external_stream_data | Alimente le flux avec des données PCM audio externes |
set_audio_external_stream_volume | Définit le volume d'un flux audio externe |
get_audio_external_stream_volume | Consulte le volume d'un flux audio externe |
clear_audio_external_stream_buffer | Vide le tampon d'un flux audio externe |
Messagerie en temps réel
API | Description |
|---|---|
send_data_msg | Envoie un message de données en temps réel |
Rappels de trames audio
API | Description |
|---|---|
set_audio_frame_observer | Définit l'écouteur de rappel pour les données de trames audio |
enable_audio_frame_observer | Active ou désactive le rappel de trame audio à une position spécifiée |
Rappels de trames vidéo
API | Description |
|---|---|
set_video_frame_observer | Définit l'écouteur de rappel pour les données de trames vidéo |
enable_video_frame_observer | Active ou désactive le rappel de trame vidéo à une position spécifiée |
Interfaces de rappel
Rappel | Description |
|---|---|
on_error | Rappel d'erreur du moteur |
on_connection_status_change | Rappel de changement d'état de la connexion |
on_data_msg | Rappel pour un message de données en temps réel reçu |
IAudioFrameObserver | Classe de base pour les écouteurs de données de trames audio |
IVideoFrameObserver | Classe de base pour les écouteurs de données de trames vidéo |
Fonctions utilitaires
API | Description |
|---|---|
load_library | Spécifie et charge manuellement la bibliothèque partagée native |
Détails des API
Cycle de vie du moteur
create_engine
Crée l'instance du moteur (méthode de classe). Le SDK conserve le moteur comme un singleton global ; ainsi, un nouvel appel à cette méthode renvoie l'instance existante. Après un appel à destroy, vous devez rappeler create_engine avant de pouvoir continuer à utiliser le moteur.
Paramètres | Type | Description |
|---|---|---|
config | AoqCreateConfig | Configuration de création du moteur |
listener | AoqEngineEventListener | Écouteur de rappel pour les événements du moteur |
destroy
Détruit l'instance du moteur (méthode de classe) et libère toutes les ressources.
get_version
Récupère la version actuelle du SDK (méthode statique).
connect
Se connecte au serveur relais. Le serveur d'application obtient les paramètres de connexion AOQ temporaires selon le protocole utilisé et les transmet au client. Pour plus d'informations, consultez Authentification par jeton.
Paramètres | Type | Description |
|---|---|---|
config | AoqConnectConfig | Configuration de connexion, incluant le jeton, le SID et la liste des points d'accès relais |
disconnect
Se déconnecte du serveur et libère les ressources associées à la connexion.
Gestion des périphériques audio
start_audio_capture
stop_audio_capture
mute_audio_capture
start_audio_player
stop_audio_player / pause_audio_player / resume_audio_player
interrupt_audio_player
Configuration de l'encodage audio
Gestion des périphériques vidéo
start_video_capture, définissez is_external sur True et fournissez les trames en appelant push_external_video_frame. Les méthodes set_local_view, set_remote_view et AoqVideoCanvas.view n'ont aucun effet réel sous Linux. Pour prévisualiser la vidéo, récupérez les trames via un rappel de trame vidéo et effectuez le rendu vous-même.
Codec vidéo et entrée externe
- Pour set_video_decoder_config, seuls les champs track_type/codec_type/width/height/fps/bitrate prennent effet.
- push_external_video_frame n'est consommé qu'après un appel à start_video_capture(is_external=True). Pour les formats packés (NV12/NV21/BGRA/RGBA), remplissez
frame.data; pour les trois plans I420, remplissezframe.data_y/u/vainsi que le stride correspondant. Si le tampon est plein, la méthode renvoie AoqErrorCode.VIDEO_EXTERNAL_BUFFER_FULL(210). - push_external_video_encoded_frame nécessite un appel préalable à start_video_capture(is_external=True) et à set_video_encoder_config(codec_type=VIDEO_JPEG), et emprunte le chemin de contournement sans ré-encodage.
Contrôle des flux multimédias
Lecture de fichiers audio
Flux audio externes
Messagerie en temps réel
Rappels de trames audio
Rappels de trames vidéo
Interfaces de rappel
AoqEngineEventListener
Classe de base pour les rappels d'événements du moteur. Toutes les méthodes sont des surcharges optionnelles dotées d'implémentations vides par défaut. Les rappels sont déclenchés sur des threads natifs ; vous devez garantir vous-même la sécurité des threads.
on_error
on_connection_status_change
on_data_msg
IAudioFrameObserver
Classe de base pour les écouteurs de données de trames audio. Toutes les méthodes sont des surcharges optionnelles dotées d'implémentations vides par défaut.
AoqAudioFrameData.data est déjà une copie de type bytes et peut être utilisée en toute sécurité de manière asynchrone.
IVideoFrameObserver
Classe de base pour les écouteurs de données de trames vidéo. Toutes les méthodes sont des surcharges optionnelles et renvoient False par défaut.
Fonctions utilitaires
load_library
libAoqClientSdk.so est recherché dans l'ordre suivant : la variable d'environnement AOQ_CLIENT_SDK_LIB, le répertoire du module, le répertoire lib au même niveau, puis les chemins système par défaut. En cas d'échec du chargement, une exception OSError est levée. Une cause fréquente est l'absence d'une bibliothèque dépendante dans LD_LIBRARY_PATH.
Types de données et énumérations
Tous les types de données sont des dataclasses Python. Vous pouvez les construire directement et attribuer des valeurs aux champs.
Types généraux
AoqCreateConfig
Champ | Type | Valeur par défaut | Description |
|---|---|---|---|
work_dir | str | "" | Répertoire de travail du SDK |
enable_dump_audio | bool | False | Indique s'il faut activer le dump audio (pour le débogage) |
extras | str | "" | Chaîne de paramètres étendus |
AoqConnectConfig
Champ | Type | Valeur par défaut | Description |
|---|---|---|---|
token | str | "" | Jeton d'authentification de la connexion |
sid | str | "" | ID de session |
certificate | str | "" | Empreinte du certificat serveur |
relay_endpoints | List[AoqRelayEndpoint] | None | Liste des points d'accès relais |
workspace_id_hash | str | "" | Hachage de l'ID d'espace de travail |
publish_tracks | List[AoqTrackParam] | None | Liste des pistes publiées localement |
subscribe_tracks | List[AoqTrackParam] | None | Liste des pistes auxquelles on s'est abonné localement |
AoqRelayEndpoint
Champ | Type | Valeur par défaut | Description |
|---|---|---|---|
endpoint | str | "" | Nom de domaine ou adresse IP du serveur relais |
port | int | 0 | Port du serveur relais |
route_index | int | -1 | Index du chemin, aligné sur routeIndex dans les SDK pour d'autres plateformes. Si la valeur est inférieure à 0, le SDK la remplit automatiquement en fonction de l'indice du tableau. |
AoqTrackParam
Champ | Type | Valeur par défaut | Description |
|---|---|---|---|
track_type | AoqTrackType | AoqTrackType.AUDIO | Type de piste |
AoqDataMsg
Champ | Type | Valeur par défaut | Description |
|---|---|---|---|
data | bytes | b"" | Données du message (chaîne d'octets) |
Énumérations
AoqErrorCode
Valeur d'énumération | Valeur | Description |
|---|---|---|
OK | 0 | Succès |
PARAM_INVALID | 1 | Paramètre non valide |
STATE_INVALID | 2 | État non valide |
AUDIO | 100 | Erreur audio générique |
AUDIO_EXTERNAL_BUFFER_FULL | 110 | Le tampon audio externe est plein |
AUDIO_DEVICE | 120 | Erreur générique du périphérique audio |
AUDIO_DEVICE_RECORDING_AUTH_FAILED | 121 | Autorisation d'enregistrement non accordée |
AUDIO_DEVICE_RECORDING_OCCUPIED | 122 | Le périphérique d'enregistrement est utilisé |
AUDIO_DEVICE_RECORDING_START_FAIL | 124 | Échec du démarrage de l'enregistrement |
AUDIO_DEVICE_PLAYOUT_OCCUPIED | 125 | Le périphérique de lecture est utilisé |
AUDIO_DEVICE_PLAYOUT_START_FAIL | 127 | Échec du démarrage de la lecture |
VIDEO | 200 | Erreur vidéo générique |
VIDEO_EXTERNAL_BUFFER_FULL | 210 | Le tampon vidéo externe est plein |
AoqConnectionStatus
Valeur d'énumération | Valeur | Description |
|---|---|---|
DISCONNECTED | 0 | Déconnecté |
CONNECTING | 1 | Connexion en cours |
CONNECTED | 2 | Connecté |
FAILED | 3 | Échec de la connexion |
AoqTrackType
Valeur d'énumération | Valeur | Description |
|---|---|---|
AUDIO | 0 | Piste audio |
VIDEO | 1 | Piste vidéo |
DATA | 2 | Piste de messages de données |
AoqEncoderType
Valeur d'énumération | Valeur | Description |
|---|---|---|
UNKNOWN | 0 | Format inconnu |
AUDIO_PCM | 1 | Audio PCM |
AUDIO_OPUS | 2 | Audio Opus |
VIDEO_H264 | 3 | Vidéo H.264 |
VIDEO_JPEG | 4 | Vidéo JPEG |
DATA_TEXT | 5 | Texte du message |
AoqMirrorMode
Valeur d'énumération | Valeur | Description |
|---|---|---|
DISABLED | 0 | Mise en miroir désactivée |
ENABLED | 1 | Mise en miroir activée |
AoqOrientationMode
Valeur d'énumération | Valeur | Description |
|---|---|---|
AUTO | 0 | Ajustement automatique |
PORTRAIT | 1 | Portrait |
LANDSCAPE | 2 | Paysage |
AoqRenderMode
Valeur d'énumération | Valeur | Description |
|---|---|---|
AUTO | 0 | Mode adaptatif |
STRETCH | 1 | Mode étiré |
FILL | 2 | Mode remplissage |
CROP | 3 | Mode recadrage |
AoqVideoPixelFormat
Valeur d'énumération | Valeur | Description |
|---|---|---|
UNKNOWN | 0 | Format inconnu |
I420 | 1 | I420 (format planaire YUV) |
NV12 | 2 | NV12 (format semi-planaire YUV) |
NV21 | 3 | NV21 (format semi-planaire YUV) |
BGRA | 4 | BGRA (32 bits) |
RGBA | 5 | RGBA (32 bits) |
AoqCameraDirection
Valeur d'énumération | Valeur | Description |
|---|---|---|
FRONT | 0 | Caméra frontale (valeur d'énumération générique de la plateforme ; la capture caméra n'est pas prise en charge sous Linux) |
BACK | 1 | Caméra arrière (valeur d'énumération générique de la plateforme ; la capture caméra n'est pas prise en charge sous Linux) |
Types audio
AoqAudioCaptureConfig
Field | Type | Default value | Description |
|---|---|---|---|
is_external | bool | False | Indique s'il faut utiliser le mode de capture externe |
channel | int | 1 | Nombre de canaux (mono par défaut) |
AoqAudioPlaybackConfig
Field | Type | Default value | Description |
|---|---|---|---|
is_external | bool | False | Indique s'il faut utiliser le mode de lecture externe |
channel | int | 1 | Nombre de canaux (mono par défaut) |
AoqAudioCodecConfig
Field | Type | Default value | Description |
|---|---|---|---|
track_type | AoqTrackType | AUDIO | Type de piste |
codec_type | AoqEncoderType | AUDIO_PCM | Format de codec |
sample_rate | int | 48000 | Fréquence d'échantillonnage, en Hz |
channel | int | 1 | Nombre de canaux |
bitrate | int | 32000 | Débit binaire, en bit/s |
AoqAudioFileMixConfig
Field | Type | Default value | Description |
|---|---|---|---|
file_name | str | "" | Nom du fichier (incluant le chemin). Ne peut pas être vide. |
cycles | int | -1 | Nombre de boucles. La valeur -1 indique une boucle illimitée. |
start_pos_ms | int | 0 | Position de début de lecture, en millisecondes |
publish_volume | int | 100 | Volume de publication. Valeurs valides : 0 à 100. |
playout_volume | int | 100 | Volume de lecture. Valeurs valides : 0 à 100. |
AoqAudioExternalStreamConfig
Field | Type | Default value | Description |
|---|---|---|---|
track_type | AoqTrackType | AUDIO | Type de piste audio |
codec_type | AoqEncoderType | AUDIO_PCM | Format du flux audio |
channels | int | 1 | Nombre de canaux |
sample_rate | int | 48000 | Fréquence d'échantillonnage, en Hz |
playout_volume | int | 100 | Volume de lecture. Valeurs valides : 0 à 100. |
publish_volume | int | 100 | Volume de publication. Valeurs valides : 0 à 100. |
max_buffer_duration | int | 1000 | Durée maximale du tampon, en millisecondes |
enable_3a | bool | False | Indique s'il faut appliquer le traitement 3A au PCM d'entrée |
AoqAudioFrameData
Données audio brutes, utilisées pour les entrées externes ou les rappels d'observateur.
Field | Type | Default value | Description |
|---|---|---|---|
data | bytes | b"" | Données PCM audio brutes (une copie bytes dans les rappels) |
num_of_samples | int | 0 | Nombre d'échantillons (par canal) |
bytes_per_sample | int | 0 | Octets par échantillon |
num_of_channels | int | 0 | Nombre de canaux |
samples_per_sec | int | 0 | Nombre d'échantillons par seconde (fréquence d'échantillonnage) |
push_sequence | int | 0 | Tour d'entrée PCM |
time_stamp | int | 0 | Horodatage |
auto_gen_mute | bool | False | La valeur True indique des données silencieuses générées par le SDK |
AoqAudioObserverConfig
Field | Type | Default value | Description |
|---|---|---|---|
sample_rate | int | 48000 | Fréquence d'échantillonnage de l'audio de rappel, en Hz |
channels | int | 1 | Nombre de canaux audio dans le rappel |
mode | AoqAudioObserverMode | READ_ONLY | Mode lecture-écriture |
AoqAudioStreamDirection
Enum value | Value | Description |
|---|---|---|
PUBLISH | 0 | Flux de publication |
PLAYOUT | 1 | Flux de lecture (flux d'abonnement) |
AoqAudioExternalStreamToggle
Enum value | Value | Description |
|---|---|---|
NORMAL | 0 | État normal |
PAUSE | 1 | État en pause |
AoqAudioSource
Enum value | Value | Description |
|---|---|---|
CAPTURED | 0 | Données audio capturées |
PROCESS_CAPTURED | 1 | Données audio après traitement 3A |
PUBLISH | 2 | Données audio à publier |
PLAYBACK | 3 | Données audio à lire |
AoqAudioObserverMode
Enum value | Value | Description |
|---|---|---|
READ_ONLY | 0 | Mode lecture seule |
READ_WRITE | 1 | Mode lecture-écriture |
Types vidéo
AoqVideoCaptureConfig
Field | Type | Default value | Description |
|---|---|---|---|
width | int | 1280 | Largeur de capture, en pixels. Ce paramètre est inefficace lorsque is_external=True. |
height | int | 720 | Hauteur de capture, en pixels. Ce paramètre est inefficace lorsque is_external=True. |
fps | int | 15 | Fréquence d'images de capture. Ce paramètre est inefficace lorsque is_external=True. |
is_external | bool | False | Indique s'il faut utiliser la capture externe. Linux prend uniquement en charge la valeur True. Après avoir appelé start_video_capture, fournissez les images en appelant push_external_video_frame. |
camera_direction | AoqCameraDirection | FRONT | Direction de la caméra pour les plateformes mobiles. Linux ne dispose pas de cette capacité. Conservez la valeur FRONT. |
AoqVideoCodecConfig
Paramètres de codec vidéo, partagés par l'encodage et le décodage. Pour le décodage, seuls les champs track_type/codec_type/width/height/fps/bitrate prennent effet ; les autres champs sont utilisés uniquement pour l'encodage.
Field | Type | Default value | Description |
|---|---|---|---|
track_type | AoqTrackType | VIDEO | Type de piste |
codec_type | AoqEncoderType | VIDEO_H264 | Format de codec |
width | int | 540 | Largeur d'encodage, en pixels |
height | int | 960 | Hauteur d'encodage, en pixels |
fps | int | 5 | Fréquence d'images d'encodage |
bitrate | int | 500000 | Débit binaire cible, en bit/s |
min_bitrate | int | 128000 | Débit binaire minimum, en bit/s |
keyframe_interval | int | 2 | Intervalle d'images clés, en secondes |
mirror_mode | AoqMirrorMode | DISABLED | Mode miroir |
orientation_mode | AoqOrientationMode | AUTO | Mode d'orientation vidéo |
AoqVideoCanvas
Field | Type | Default value | Description |
|---|---|---|---|
view | int | 0 | Handle de fenêtre de rendu. Linux ne dispose pas de backend de rendu, ce champ n'a donc aucun effet réel. Conservez la valeur 0. |
render_mode | AoqRenderMode | AUTO | Mode de rendu. Linux ne dispose pas de backend de rendu, ce champ n'a donc aucun effet réel. |
AoqVideoFrame
Image vidéo externe ou données de rappel d'image vidéo. Lorsque vous utilisez un format packé (NV12/NV21/BGRA/RGBA), renseignez le champ data. Lorsque vous utilisez les trois plans I420, renseignez les champs data_y/u/v et le stride correspondant. Les deux méthodes sont mutuellement exclusives.
Field | Type | Default value | Description |
|---|---|---|---|
format | AoqVideoPixelFormat | UNKNOWN | Format de pixel |
width | int | 0 | Largeur vidéo, en pixels |
height | int | 0 | Hauteur vidéo, en pixels |
data | bytes | b"" | Données au format packé (NV12/NV21/BGRA/RGBA) |
data_y | bytes | b"" | Données du plan Y I420 |
data_u | bytes | b"" | Données du plan U I420 |
data_v | bytes | b"" | Données du plan V I420 |
stride_y | int | 0 | Stride du plan Y |
stride_u | int | 0 | Stride du plan U |
stride_v | int | 0 | Stride du plan V |
time_stamp | int | 0 | Horodatage, en millisecondes. Si la valeur est 0, le SDK la remplit avec l'horloge locale. |
AoqVideoEncodedFrame
Une image vidéo encodée en externe, telle qu'une image JPEG.
Field | Type | Default value | Description |
|---|---|---|---|
codec | AoqEncoderType | VIDEO_JPEG | Format de codec |
data | bytes | b"" | Données encodées |
width | int | 0 | Largeur, en pixels |
height | int | 0 | Hauteur, en pixels |
time_stamp | int | 0 | Horodatage, en millisecondes. Si la valeur est 0, le SDK la remplit avec l'horloge locale. |
AoqVideoObserverConfig
Field | Type | Default value | Description |
|---|---|---|---|
format | AoqVideoPixelFormat | I420 | Format de pixel attendu des données de rappel |
alignment | AoqVideoObserverAlignment | DEFAULT | Politique d'alignement de la largeur |
mode | AoqVideoObserverMode | READ_ONLY | Mode lecture-écriture |
mirror_applied | bool | False | Indique s'il faut appliquer un effet miroir aux données de rappel |
AoqVideoSource
Enum value | Value | Description |
|---|---|---|
CAPTURED | 0 | Données vidéo capturées avant le prétraitement |
PRE_ENCODE | 1 | Données vidéo avant encodage, après prétraitement |
REMOTE | 2 | Données vidéo distantes après décodage et avant rendu |
AoqVideoObserverMode
Enum value | Value | Description |
|---|---|---|
READ_ONLY | 0 | Mode lecture seule |
READ_WRITE | 1 | Mode lecture-écriture |
AoqVideoObserverAlignment
Enum value | Value | Description |
|---|---|---|
DEFAULT | 0 | Alignement par défaut |
EVEN | 1 | Alignement sur nombre pair |
ALIGN_4 | 2 | Alignement sur 4 octets |
ALIGN_8 | 3 | Alignement sur 8 octets |
ALIGN_16 | 4 | Alignement sur 16 octets |