Skip to main content

Référence de l’API du SDK client AOQ pour Android

Le SDK client AOQ pour Android offre un ensemble complet de fonctionnalités de communication audio et vidéo en temps réel. Il couvre la gestion du cycle de vie du moteur, la capture et la lecture audio/vidéo, la configuration des codecs, l'injection de flux audio externes, le mixage de fichiers audio, la messagerie en temps réel ainsi que les callbacks de trames audio et vidéo. Ce document constitue la référence complète de l'API Java pour la plateforme Android.

Le SDK AOQ fournit des API vidéo générales. Qwen-Audio-Realtime ne prend pas en charge l’entrée ni la sortie vidéo. Pour les capacités de médias des autres modèles, consultez leur documentation de connexion.

Index des API

Cycle de vie du moteur

API

Description

createEngine

Crée l'instance du moteur (singleton)

destroy

Détruit l'instance du moteur

getVersion

Récupère la chaîne de version du SDK

connect

Établit la connexion au serveur Relay

disconnect

Ferme la connexion au serveur

Gestion des périphériques audio

API

Description

startAudioCapture

Ouvre le périphérique de capture audio (microphone)

stopAudioCapture

Ferme le périphérique de capture audio

muteAudioCapture

Active ou désactive la sourdine de la capture audio

startAudioPlayer

Lance la lecture audio (flux distant)

stopAudioPlayer

Arrête la lecture audio

pauseAudioPlayer

Suspend la lecture audio avec un fondu de sortie optionnel

resumeAudioPlayer

Reprend la lecture audio avec un fondu d'entrée optionnel

interruptAudioPlayer

Interrompt le tour de parole audio en cours

enableSpeakerphone

Bascule la sortie audio entre le haut-parleur et l'écouteur

isSpeakerphoneEnabled

Vérifie si le haut-parleur est actuellement actif

Configuration du codec audio

API

Description

setAudioEncoderConfig

Définit les paramètres d'encodage audio

setAudioDecoderConfig

Définit les paramètres de décodage audio

Gestion des périphériques vidéo

API

Description

startVideoCapture

Ouvre le périphérique de capture vidéo (caméra)

stopVideoCapture

Ferme le périphérique de capture vidéo

switchCamera

Bascule entre la caméra avant et la caméra arrière

setLocalView

Définit ou supprime la vue de rendu vidéo locale

setRemoteView

Définit ou supprime la vue de rendu vidéo distante

Encodage vidéo et entrée externe

API

Description

setVideoEncoderConfig

Définit les paramètres d'encodage vidéo

pushExternalVideoCapturedFrame

Injecte une trame vidéo brute capturée en externe

pushExternalVideoEncodedFrame

Injecte une trame vidéo déjà encodée en externe

Contrôle des flux multimédias / Messagerie en temps réel

API

Description

enableSendMediaStream

Active ou désactive l'envoi du flux multimédia local

sendDataMsg

Envoie un message de données en temps réel

Lecture de fichiers audio

API

Description

startAudioFile

Démarre la diffusion d'un fichier audio local

stopAudioFile

Arrête la lecture du fichier audio

pauseAudioFile

Suspend la lecture du fichier audio

resumeAudioFile

Reprend la lecture du fichier audio

getAudioFileDuration

Obtient la durée totale du fichier audio

getAudioFileCurrentPosition

Obtient la position de lecture actuelle

setAudioFilePositionMillis

Se positionne à un instant donné dans le fichier audio

setAudioFileVolume

Règle le volume du fichier audio

getAudioFileVolume

Récupère le volume actuel du fichier audio

Flux audio externes

API

Description

addAudioExternalStream

Ajoute un flux audio externe

removeAudioExternalStream

Supprime un flux audio externe

pushAudioExternalStreamData

Injecte des données audio PCM externes

setAudioExternalStreamVolume

Définit le volume d'un flux audio externe

getAudioExternalStreamVolume

Obtient le volume d'un flux audio externe

clearAudioExternalStreamBuffer

Vide le tampon d'un flux audio externe

Callbacks de trames audio/vidéo

API

Description

setAudioFrameObserver

Définit l'écouteur de callback pour les données de trames audio

enableAudioFrameObserver

Active ou désactive les callbacks de trames audio à un point précis

setVideoFrameObserver

Définit l'écouteur de callback pour les données de trames vidéo

enableVideoFrameObserver

Active ou désactive les callbacks de trames vidéo à un point précis

Callbacks AoqClientListener

Callback

Description

onError

Callback d'erreur du moteur

onWarning

Callback d'avertissement du moteur

onConnectionStatusChange

Callback de changement d'état de connexion

onStats

Callback de statistiques du moteur

onAudioDeviceStateChanged

Callback de changement d'état du périphérique audio

onAudioDeviceRouteChanged

Callback de changement de route de sortie audio

onAudioDeviceInterrupted

Callback d'interruption du périphérique audio

onVideoDeviceStateChanged

Callback de changement d'état du périphérique vidéo

onAudioDeviceFocusChanged

Callback de changement de focus audio

onAudioFileState

Callback d'état de lecture du fichier audio

onDataMsg

Callback de réception d'un message de données en temps réel

Détails des API

Cycle de vie du moteur

createEngine Crée l'instance du moteur. Le SDK conserve le moteur sous forme de singleton global ; tout appel ultérieur à cette méthode retourne l'instance existante.
@NonNull
public static AoqClientEngine createEngine(
    @NonNull Context context,
    @NonNull AoqCreateConfig config,
    @NonNull AoqClientListener listener)

Paramètre

Type

Description

context

Context

Contexte de l'application Android

config

AoqCreateConfig

Configuration de création du moteur

listener

AoqClientListener

Écouteur de callbacks d'événements du moteur

Retourne : une instance AoqClientEngine ; jamais null. destroy Détruit l'instance du moteur et libère toutes les ressources associées.
public static int destroy()
Retourne : 0 en cas de succès ; une valeur non nulle en cas d'échec. getVersion
@NonNull
public static String getVersion()
Retourne : la chaîne de version, par exemple "1.0.0". connect Se connecte au serveur Relay. AppServer transmet les paramètres de connexion au client. Cet appel revient immédiatement. Le résultat réel de la connexion est signalé par le callback onConnectionStatusChange.
Dans la documentation générale de l’API SDK, AppServer attribue les paramètres de connexion via /api/v1/allocate. Pour un modèle précis, consultez Connexion AOQ Qwen-Omni-Realtime, Connexion AOQ Qwen-Audio-Realtime ou Connexion AOQ Qwen-LiveTranslate-Realtime.
public abstract int connect(@NonNull AoqConnectConfig config)
Retourne : 0 si l'appel a été dispatché (asynchrone) ; une valeur non nulle si la validation des paramètres échoue. disconnect
public abstract int disconnect()
Retourne : 0 si l'appel a été dispatché (asynchrone) ; une valeur non nulle en cas d'échec.

Gestion des périphériques audio

public abstract int startAudioCapture(@NonNull AoqAudioCaptureConfig config)
public abstract int stopAudioCapture()
public abstract int muteAudioCapture(boolean mute)
public abstract int startAudioPlayer(@NonNull AoqAudioPlaybackConfig config)
public abstract int stopAudioPlayer()
public abstract int pauseAudioPlayer(int fadeMs)
public abstract int resumeAudioPlayer(int fadeMs)
public abstract int interruptAudioPlayer(@NonNull AoqTrackType trackType, int fadeMs)
public abstract int enableSpeakerphone(boolean enable)
public abstract boolean isSpeakerphoneEnabled()
fadeMs : durée du fondu de sortie ou d'entrée en millisecondes ; 0 signifie immédiat.

Configuration du codec audio

public abstract int setAudioEncoderConfig(@NonNull AoqAudioCodecConfig config)
public abstract int setAudioDecoderConfig(@NonNull AoqAudioCodecConfig config)

Gestion des périphériques vidéo

public abstract int startVideoCapture(@NonNull AoqVideoCaptureConfig config)
public abstract int stopVideoCapture()
public abstract int switchCamera(@NonNull AoqCameraDirection direction)
public abstract int setLocalView(@NonNull AoqTrackType trackType, @Nullable AoqVideoCanvas canvas)
public abstract int setRemoteView(@NonNull AoqTrackType trackType, @Nullable AoqVideoCanvas canvas)
Passez AoqTrackTypeVideo comme paramètre trackType pour setLocalView et setRemoteView.

Encodage vidéo et entrée externe

public abstract int setVideoEncoderConfig(@NonNull AoqVideoCodecConfig config)
public abstract int pushExternalVideoCapturedFrame(@NonNull AoqTrackType trackType, @NonNull AoqVideoFrame frame)
public abstract int pushExternalVideoEncodedFrame(@NonNull AoqTrackType trackType, @NonNull AoqVideoEncodedFrame frame)
pushExternalVideoCapturedFrame ne consomme les trames qu'après l'appel de startVideoCapture(isExternal=true). Si le tampon interne est plein, la méthode retourne AoqErrorCodeVideoExternalBufferFull (210).

Contrôle des flux multimédias

public abstract int enableSendMediaStream(@NonNull AoqTrackType trackType, boolean enable)
Modèle recommandé : appelez enableSendMediaStream(false) après l'initialisation, puis activez l'envoi une fois que onConnectionStatusChange signale l'état Connected.

Lecture de fichiers audio

public abstract int startAudioFile(@NonNull String fileId, @NonNull AoqAudioFileMixConfig config)
public abstract int stopAudioFile(@NonNull String fileId)
public abstract int pauseAudioFile(@NonNull String fileId)
public abstract int resumeAudioFile(@NonNull String fileId)
public abstract long getAudioFileDuration(@NonNull String fileId)
public abstract long getAudioFileCurrentPosition(@NonNull String fileId)
public abstract int setAudioFilePositionMillis(@NonNull String fileId, long positionMillis)
public abstract int setAudioFileVolume(@NonNull String fileId, @NonNull AoqAudioStreamDirection type, int volume)
public abstract int getAudioFileVolume(@NonNull String fileId, @NonNull AoqAudioStreamDirection type)

Flux audio externes

public abstract int addAudioExternalStream(@NonNull String streamId, @NonNull AoqAudioExternalStreamConfig config)
public abstract int removeAudioExternalStream(@NonNull String streamId)
public abstract int pushAudioExternalStreamData(@NonNull String streamId, @NonNull AoqAudioFrameData data)
public abstract int setAudioExternalStreamVolume(@NonNull String streamId, @NonNull AoqAudioStreamDirection type, int volume)
public abstract int getAudioExternalStreamVolume(@NonNull String streamId, @NonNull AoqAudioStreamDirection type)
public abstract void clearAudioExternalStreamBuffer(@NonNull String streamId, int fadeoutMs)
Si pushAudioExternalStreamData retourne AoqErrorCodeAudioExternalBufferFull (110), le tampon interne est plein. Patientez 30 ms avant de réessayer.

Messagerie en temps réel

public abstract int sendDataMsg(@NonNull AoqDataMsg msg)

Callbacks de trames audio

public abstract int setAudioFrameObserver(@Nullable AoqClientListener.AoqAudioFrameListener listener)
public abstract int enableAudioFrameObserver(boolean enabled, @NonNull AoqAudioSource audioSource, @NonNull AoqAudioObserverConfig config)

Callbacks de trames vidéo

public abstract int setVideoFrameObserver(@Nullable AoqClientListener.AoqVideoFrameListener listener)
public abstract int enableVideoFrameObserver(boolean enabled, @NonNull AoqVideoSource videoSource, @NonNull AoqVideoObserverConfig config)

Callbacks AoqClientListener

AoqClientListener centralise la réception de tous les événements asynchrones du SDK. Toutes les méthodes de callback possèdent une implémentation vide par défaut ; vous pouvez donc ne surcharger que celles qui vous intéressent.
public void onError(int code, String message)
public void onWarning(int code, String message)
public void onConnectionStatusChange(@NonNull AoqConnectionStatus status)
public void onStats(@NonNull AoqStats stats)
public void onAudioDeviceStateChanged(@NonNull AoqAudioDeviceState state)
public void onAudioDeviceRouteChanged(int routeType)
public void onAudioDeviceInterrupted(boolean interrupt)
public void onVideoDeviceStateChanged(@NonNull AoqVideoDeviceState state)
public void onAudioDeviceFocusChanged(int audioFocus)
public void onAudioFileState(@NonNull AoqAudioFileState state)
public void onDataMsg(@NonNull AoqDataMsg msg)
Transitions d'état de connexion : Disconnected → Connecting → Connected/Failed → Disconnected.

AoqAudioFrameListener

public interface AoqAudioFrameListener {
    default void onCapturedAudioFrame(@NonNull AoqAudioFrameData frame) {}
    default void onProcessCapturedAudioFrame(@NonNull AoqAudioFrameData frame) {}
    default void onPublishAudioFrame(@NonNull AoqTrackType trackType, @NonNull AoqAudioFrameData frame) {}
    default void onPlaybackAudioFrame(@NonNull AoqAudioFrameData frame) {}
}

AoqVideoFrameListener

public interface AoqVideoFrameListener {
    default boolean onCapturedVideoFrame(@NonNull AoqVideoFrameData frame) { return false; }
    default boolean onPreEncodeVideoFrame(@NonNull AoqTrackType trackType, @NonNull AoqVideoFrameData frame) { return false; }
    default boolean onRemoteVideoFrame(@NonNull AoqTrackType trackType, @NonNull AoqVideoFrameData frame) { return false; }
}
Retournez true pour indiquer que vous avez modifié les données de la trame et souhaitez que le SDK les relise (la réécriture n'est effective que pour le format I420). Le ByteBuffer et le textureId contenus dans frame ne sont valides que pendant la durée du callback ; copiez-les avant toute utilisation asynchrone.

Types de données et énumérations

Types généraux

AoqCreateConfig

Champ

Type

Valeur par défaut

Description

workDir

String

""

Répertoire de travail du SDK

isBTScoMode

boolean

false

true : mode Bluetooth SCO ; false : mode A2DP

enableDumpAudio

boolean

false

Active le dump audio (pour le débogage)

extras

String

""

Chaîne de paramètres supplémentaires

AoqConnectConfig

Champ

Type

Valeur par défaut

Description

token

String

""

Jeton d'authentification

sid

String

""

ID de session

certFingerprint

String

""

Empreinte du certificat serveur

relayEndpoints

List<AoqRelayEndpoint>

vide

Liste des endpoints Relay

workspaceIdHash

String

""

Hash de l'ID de l'espace de travail

publishTracks

List<AoqTrackParam>

vide

Pistes locales à publier

subscribeTracks

List<AoqTrackParam>

vide

Pistes distantes auxquelles s'abonner

Types de statistiques

AoqNetworkStats

Champ

Type

Description

sendBitrate

int

Débit d'envoi (bps)

sendBytes

long

Octets envoyés cumulés

recvBitrate

int

Débit de réception (bps)

recvBytes

long

Octets reçus cumulés

loss

int

Taux de perte de paquets (0–100)

rtt

int

Temps d'aller-retour (ms)

Énumérations

AoqErrorCode

Valeur d'énumération

Valeur

Description

AoqErrorCodeOK

0

Succès

AoqErrorCodeParamInvalid

1

Paramètre invalide

AoqErrorCodeStateInvalid

2

État invalide

AoqErrorCodeUnSupport

3

Non pris en charge

AoqErrorCodeAudio

100

Erreur audio générique

AoqErrorCodeAudioExternalBufferFull

110

Tampon audio externe plein

AoqErrorCodeAudioDevice

120

Erreur générique du périphérique audio

AoqErrorCodeAudioDeviceRecordingAuthFailed

121

Autorisation d'enregistrement refusée

AoqErrorCodeAudioDeviceRecordingOccupied

122

Périphérique d'enregistrement occupé

AoqErrorCodeAudioDeviceRecordingBackgroundStart

123

Échec du démarrage de l'enregistrement en arrière-plan

AoqErrorCodeAudioDeviceRecordingStartFail

124

Échec du démarrage de l'enregistrement

AoqErrorCodeAudioDevicePlayoutOccupied

125

Périphérique de lecture occupé

AoqErrorCodeAudioDevicePlayoutBackgroundStart

126

Échec du démarrage de la lecture en arrière-plan

AoqErrorCodeAudioDevicePlayoutStartFail

127

Échec du démarrage de la lecture

AoqErrorCodeAudioDeviceEarpieceRequiresVoipMode

128

L'écouteur nécessite le mode VoIP

AoqErrorCodeVideo

200

Erreur vidéo générique

AoqErrorCodeVideoExternalBufferFull

210

Tampon vidéo externe plein

AoqErrorCodeVideoExternalCaptureNotEnabled

211

Capture vidéo externe non activée

AoqErrorCodeVideoExternalEncoderNotEnabled

212

Encodeur vidéo externe non activé

AoqErrorCodeVideoDevice

220

Erreur générique du périphérique vidéo

AoqErrorCodeVideoDeviceCameraOpenFail

221

Échec de l'ouverture de la caméra

AoqErrorCodeVideoDeviceCameraAuthFailed

222

Autorisation de la caméra refusée

AoqErrorCodeVideoDeviceCameraOccupied

223

Caméra occupée

AoqErrorCodeVideoDeviceCameraRunningError

224

Erreur d'exécution de la caméra

AoqErrorCodeVideoCodec

230

Erreur générique du codec vidéo

AoqErrorCodeVideoCodecEncoderInitFail

231

Échec de l'initialisation de l'encodeur vidéo

AoqErrorCodeVideoRender

240

Erreur générique de rendu vidéo

AoqErrorCodeVideoRenderCreateFail

241

Échec de la création du moteur de rendu vidéo

AoqErrorCodeVideoRenderDrawError

242

Erreur de dessin lors du rendu vidéo

AoqWarningCode

Valeur d'énumération

Valeur

Description

AoqWCOK

0

Aucun avertissement

AoqWCAudio

100

Avertissement audio générique

AoqWCAudioHowling

101

Larsen détecté

AoqWCAudioDevice

120

Avertissement générique du périphérique audio

AoqWCAudioDeviceMicEnumerateError

121

Erreur d'énumération du microphone

AoqWCAudioDeviceMicStartTimeout

122

Délai d'attente dépassé pour le démarrage du microphone

AoqWCAudioDeviceRecordingError

123

Erreur d'enregistrement

AoqWCAudioDeviceSpeakerEnumerateError

124

Erreur d'énumération du haut-parleur

AoqWCAudioDeviceSpeakerStartTimeout

125

Délai d'attente dépassé pour le démarrage du haut-parleur

AoqWCAudioDevicePlayoutError

126

Erreur de lecture

AoqWCVideo

200

Avertissement vidéo générique

AoqWCVideoCameraEnumerateError

201

Erreur d'énumération de la caméra

AoqWCVideoEncoderSwitched

202

Changement d'encodeur vidéo

AoqWCVideoRenderDowngrade

203

Dégradation du rendu vidéo

AoqTrackType

Valeur d'énumération

Valeur

Description

AoqTrackTypeAudio

0

Piste audio

AoqTrackTypeVideo

1

Piste vidéo

AoqTrackTypeData

2

Piste de messagerie de données

AoqEncoderType

Valeur d'énumération

Valeur

Description

AoqEncoderTypeUnknown

0

Format inconnu

AoqEncoderTypeAudioPCM

1

Audio PCM

AoqEncoderTypeAudioOpus

2

Audio Opus

AoqEncoderTypeVideoH264

3

Vidéo H.264

AoqEncoderTypeVideoJpeg

4

Vidéo JPEG

AoqEncoderTypeDataText

5

Données texte

AoqConnectionStatus

Valeur d'énumération

Valeur

Description

AoqConnectionStatusDisconnected

0

Déconnecté

AoqConnectionStatusConnecting

1

Connexion en cours

AoqConnectionStatusConnected

2

Connecté

AoqConnectionStatusFailed

3

Échec de la connexion

Types audio

AoqAudioCaptureConfig

Champ

Type

Valeur par défaut

Description

isExternal

boolean

false

Indique s'il faut utiliser le mode de capture externe

isVoipMode

boolean

false

Indique s'il faut activer le mode VoIP (affecte le routage du périphérique, ex. écouteur)

channel

int

1

Nombre de canaux (par défaut : mono)

AoqAudioPlaybackConfig

Champ

Type

Valeur par défaut

Description

isVoipMode

boolean

false

Indique s'il faut activer le mode VoIP (AEC matériel) ; s'applique aux appareils mobiles

isDefaultSpeaker

boolean

true

Indique s'il faut utiliser le haut-parleur par défaut ; s'applique aux appareils mobiles

isExternal

boolean

false

Indique s'il faut utiliser le mode de lecture externe

channel

int

1

Nombre de canaux (par défaut : mono)

AoqAudioCodecConfig

Champ

Type

Valeur par défaut

Description

trackType

AoqTrackType

Audio

Type de piste

codecType

AoqEncoderType

AudioPCM

Format du codec

sampleRate

int

48000

Fréquence d'échantillonnage (Hz)

channel

int

1

Nombre de canaux

bitrate

int

32000

Débit binaire (bps)

Types vidéo

AoqVideoCaptureConfig

Champ

Type

Valeur par défaut

Description

width

int

1280

Largeur de capture (pixels) ; ignoré lorsque isExternal=true

height

int

720

Hauteur de capture (pixels) ; ignoré lorsque isExternal=true

fps

int

15

Fréquence d'images de capture ; ignoré lorsque isExternal=true

isExternal

boolean

false

Mode de capture externe ; si true, la caméra n'est pas ouverte

cameraDirection

AoqCameraDirection

Front

Orientation de la caméra ; ignoré lorsque isExternal=true

AoqVideoCodecConfig

Champ

Type

Valeur par défaut

Description

trackType

AoqTrackType

Video

Type de piste

codecType

AoqEncoderType

VideoH264

Format du codec

width

int

720

Largeur d'encodage (pixels)

height

int

1280

Hauteur d'encodage (pixels)

fps

int

5

Fréquence d'images d'encodage

bitrate

int

500000

Débit binaire cible (bps)

minBitrate

int

128000

Débit binaire minimum (bps)

keyframeInterval

int

2

Intervalle d'images clés (secondes)

mirrorMode

AoqMirrorMode

Disabled

Mode miroir

orientationMode

AoqOrientationMode

Auto

Mode d'orientation vidéo

isExternal

boolean

false

Si true, le SDK ignore le réencodage ; utilisez pushExternalVideoEncodedFrame pour fournir des données pré-encodées

AoqVideoPixelFormat

Valeur d'énumération

Valeur

Description

AoqVideoPixelFormatUnknown

0

Format inconnu

AoqVideoPixelFormatI420

1

I420 (YUV planaire)

AoqVideoPixelFormatNV12

2

NV12 (YUV semi-planaire)

AoqVideoPixelFormatNV21

3

NV21 (YUV semi-planaire)

AoqVideoPixelFormatBGRA

4

BGRA 32 bits

AoqVideoPixelFormatRGBA

5

RGBA 32 bits

AoqVideoPixelFormatTextureOES

7

Texture OES externe

AoqVideoPixelFormatTexture2D

8

Texture 2D standard

Types de flux audio externes

AoqAudioExternalStreamConfig

Champ

Type

Valeur par défaut

Description

trackType

AoqTrackType

Audio

Type de piste audio

codecType

AoqEncoderType

AudioPCM

Format du flux audio

channels

int

1

Nombre de canaux

sampleRate

int

48000

Fréquence d'échantillonnage (Hz)

playoutVolume

int

100

Volume de lecture [0–100]

publishVolume

int

100

Volume de publication [0–100]

maxBufferDuration

int

1000

Durée maximale du tampon (millisecondes)

enable3A

boolean

false

Indique s'il faut appliquer le traitement 3A au PCM d'entrée

AoqAudioStreamDirection

Valeur d'énumération

Valeur

Description

AoqAudioStreamPublish

0

Flux de publication (envoi)

AoqAudioStreamPlayout

1

Flux de lecture (réception)

Types de messages de données

AoqDataMsg

Champ

Type

Valeur par défaut

Description

data

byte[]

new byte[0]

Données du message (tableau d'octets)