Fonctionnalités audio du SDK AOQ - capture, lecture, mixage, rappels de trames - Alibaba Cloud Model Studio

Le SDK Client AOQ offre des capacités audio complètes : capture et lecture audio, configuration des codecs, gestion du haut-parleur, mixage de fichiers, injection de flux audio externes et rappels de données de trames audio. Ce document présente les fonctionnalités audio courantes pour Android (Java), iOS (Objective-C) et HarmonyOS (ArkTS).

Capture audio

La capture audio active le microphone de l'appareil et injecte les données audio 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 le microphone (ouverture, enregistrement et fermeture).
Capture externe : L'application contrôle directement le microphone et transmet les données PCM capturées au SDK via l'API de flux audio externe.

Paramètres de configuration

Paramètre	Type	Valeur par défaut	Description
isExternal	bool	false	Active le mode de capture externe.
isVoipMode	bool	false	Active le mode VoIP (AEC matériel). Valable sur mobile. Si la capture et la lecture sont toutes deux configurées, le premier paramétrage appliqué prévaut.
channel	int	1	Nombre de canaux de capture. Valeurs acceptées : 1 (mono) ou 2 (stéréo).

Référence API

Fonction	Android	iOS	HarmonyOS
Démarrer la capture	`startAudioCapture(config)`	`startAudioCapture:config:`	`startAudioCapture(config)`
Arrêter la capture	`stopAudioCapture()`	`stopAudioCapture`	`stopAudioCapture()`
Couper / rétablir le son	`muteAudioCapture(mute)`	`muteAudioCapture:`	`muteAudioCapture(mute)`

Exemple

Android

AoqAudioCaptureConfig config = new AoqAudioCaptureConfig();
config.isVoipMode = true;
config.channel = 1;
engine.startAudioCapture(config);

iOS

AoqAudioCaptureConfig *config = [[AoqAudioCaptureConfig alloc] init];
config.isVoipMode = YES;
config.channel = 1;
[engine startAudioCapture:config];

HarmonyOS

const config: AoqAudioCaptureConfig = { isVoipMode: true, channel: 1 };
engine.startAudioCapture(config);

Lecture audio

La lecture audio restitue les données audio distantes reçues sur le haut-parleur local ou le casque. Le SDK propose des contrôles avancés tels que la pause et la reprise avec fondu entrant ou sortant, ainsi que l'interruption du tour de parole en cours dans une conversation audio.

Paramètres de configuration

Paramètre	Type	Valeur par défaut	Description
isVoipMode	bool	false	Active le mode VoIP (AEC matériel). Valable sur mobile. Si la capture et la lecture sont toutes deux configurées, le premier paramétrage appliqué prévaut.
isDefaultSpeaker	bool	true	Définit le haut-parleur comme périphérique de sortie par défaut. Valable sur mobile et uniquement hors mode VoIP.
isExternal	bool	false	Active le mode de lecture externe.
channel	int	1	Nombre de canaux de lecture. Valeurs acceptées : 1 (mono) ou 2 (stéréo).

Référence API

Fonction	Android	iOS	HarmonyOS
Démarrer la lecture	`startAudioPlayer(config)`	`startAudioPlayer:config:`	`startAudioPlayer(config)`
Arrêter la lecture	`stopAudioPlayer()`	`stopAudioPlayer`	`stopAudioPlayer()`
Mettre en pause	`pauseAudioPlayer(fadeMs)`	`pauseAudioPlayer:`	`pauseAudioPlayer(fadeMs)`
Reprendre la lecture	`resumeAudioPlayer(fadeMs)`	`resumeAudioPlayer:`	`resumeAudioPlayer(fadeMs)`
Interrompre la conversation	`interruptAudioPlayer(trackType, fadeMs)`	`interruptAudioPlayer:fadeMs:`	`interruptAudioPlayer(trackType, fadeMs)`

RemarqueParamètre fadeMs : Durée du fondu entrant ou sortant en millisecondes lors de la mise en pause ou de la reprise de la lecture. Définissez cette valeur à 0 pour une transition immédiate.

Gestion du haut-parleur

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

Fonction	Android	iOS	HarmonyOS
Basculer le haut-parleur	`enableSpeakerphone(enable)`	`enableSpeakerphone:`	`enableSpeakerphone(enable)`
Vérifier l'état du haut-parleur	`isSpeakerphoneEnabled()`	`isSpeakerphoneEnabled`	`isSpeakerphoneEnabled()`

RemarqueLe basculement vers le haut-parleur n'est autorisé qu'en mode VoIP. Hors de ce mode, l'appel à enableSpeakerphone déclenche une notification d'erreur OnError(AoqECAudioDeviceEarpieceRequiresVoipMode).

RemarqueComportement spécifique à iOS : Les iPad ne disposent que du mode haut-parleur. Lorsque la catégorie AVAudioSession n'est pas PlayAndRecord, cette méthode retourne toujours YES.

Configuration du codec audio

Configurez le format d'encodage, la fréquence d'échantillonnage, le nombre de canaux et le débit binaire pour la liaison montante (encodeur) et la liaison descendante (décodeur). Ces paramètres déterminent le format utilisé pour la publication et la récupération des flux.

Paramètres de configuration

Paramètre	Type	Valeur par défaut	Description
trackType	AoqTrackType	Audio	Type de piste audio. Un seul flux audio est actuellement pris en charge.
codecType	AoqEncoderType	AudioPCM	Type d'encodage : AudioPCM(1) ou AudioOpus(2).
sampleRate	int	48000	Fréquence d'échantillonnage. Opus prend en charge 8K/16K/48K. PCM prend en charge 8K/16K/32K/48K.
channel	int	1	Nombre de canaux. Valeurs acceptées : 1 (mono) ou 2 (stéréo).
bitrate	int	32000	Débit binaire en bps.

Référence API

Fonction	Android	iOS	HarmonyOS
Configurer l'encodeur	`setAudioEncoderConfig(config)`	`setAudioEncoderConfig:`	`setAudioEncoderConfig(config)`
Configurer le décodeur	`setAudioDecoderConfig(config)`	`setAudioDecoderConfig:`	`setAudioDecoderConfig(config)`

Formats d'encodage pris en charge

Valeur d'énumération	Valeur numérique	Description
AoqEncoderTypeAudioPCM	1	Audio PCM brut
AoqEncoderTypeAudioOpus	2	Encodage Opus

Mixage de fichiers audio

Mélangez un fichier audio local au flux audio actuel pour la publication ou la lecture locale. Chaque fichier audio est identifié par un fileId attribué par l'application, ce qui permet de gérer simultanément plusieurs instances de fichiers.

Paramètres de configuration du mixage

Paramètre	Type	Valeur par défaut	Description
fileName	String	-	Chemin du fichier audio (nom inclus).
cycles	int	-1	Nombre de boucles. La valeur -1 indique une boucle infinie.
startPosMs	long	0	Position de départ de la lecture en millisecondes.
publishVolume	int	100	Volume de publication [0–100].
playoutVolume	int	100	Volume de lecture locale [0–100].

Référence API

Fonction	Android	iOS	HarmonyOS
Démarrer la lecture	`startAudioFile(fileId, config)`	`startAudioFile:config:`	`startAudioFile(fileId, config)`
Arrêter la lecture	`stopAudioFile(fileId)`	`stopAudioFile:`	`stopAudioFile(fileId)`
Mettre en pause	`pauseAudioFile(fileId)`	`pauseAudioFile:`	`pauseAudioFile(fileId)`
Reprendre	`resumeAudioFile(fileId)`	`resumeAudioFile:`	`resumeAudioFile(fileId)`
Obtenir la durée du fichier	`getAudioFileDuration(fileId)`	`getAudioFileDuration:`	`getAudioFileDuration(fileId)`
Obtenir la position actuelle	`getAudioFileCurrentPosition(fileId)`	`getAudioFileCurrentPosition:`	`getAudioFileCurrentPosition(fileId)`
Aller à une position précise	`setAudioFilePositionMillis(fileId, pos)`	`setAudioFilePositionMillis:positionMillis:`	`setAudioFilePositionMillis(fileId, pos)`
Régler le volume	`setAudioFileVolume(fileId, type, vol)`	`setAudioFileVolume:type:volume:`	`setAudioFileVolume(fileId, type, vol)`
Obtenir le volume	`getAudioFileVolume(fileId, type)`	`getAudioFileVolume:type:`	`getAudioFileVolume(fileId, type)`

RemarqueCible du volume (type) : AoqAudioStreamPublish(0) règle le volume de publication. AoqAudioStreamPlayout(1) règle le volume de lecture locale.

Rappels d'état

Code d'état	Valeur	Description
AoqAudioFileNone	0	État initial
AoqAudioFileStarted	1	Lecture démarrée
AoqAudioFileStopped	2	Lecture arrêtée
AoqAudioFilePaused	3	Lecture en pause
AoqAudioFileResumed	4	Lecture reprise
AoqAudioFileEnded	5	Lecture terminée
AoqAudioFileBuffering	6	Mise en mémoire tampon
AoqAudioFileBufferingEnd	7	Fin de la mise en mémoire tampon
AoqAudioFileFailed	8	Échec de la lecture

Flux audio externes

Les flux audio externes permettent d'injecter des données audio PCM générées par l'application dans le pipeline audio du SDK pour la publication ou la lecture locale. Les cas d'usage typiques incluent la synthèse vocale TTS, la sortie audio de modèles IA et les effets sonores d'arrière-plan. Chaque flux audio externe est identifié par un streamId attribué par l'application.

Paramètres de configuration

Paramètre	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. Valeurs acceptées : 8/12/16/24/32/44,1/48/64/88,2/96/176,4/192 kHz.
playoutVolume	int	100	Volume de lecture locale [0–100].
publishVolume	int	100	Volume de publication [0–100].
maxBufferDuration	int	600000	Durée maximale du tampon en millisecondes. Plage valide : [100, ~]. L'envoi échoue si le tampon est plein.
enable3A	bool	false	Active le traitement 3A sur les données PCM d'entrée.

Référence API

Fonction	Android	iOS	HarmonyOS
Ajouter un flux externe	`addAudioExternalStream(streamId, config)`	`addAudioExternalStream:config:`	`addAudioExternalStream(streamId, config)`
Envoyer des données audio	`pushAudioExternalStreamData(streamId, data)`	`pushAudioExternalStreamData:data:`	`pushAudioExternalStreamData(streamId, data)`
Régler le volume	`setAudioExternalStreamVolume(streamId, type, vol)`	`setAudioExternalStreamVolume:type:volume:`	`setAudioExternalStreamVolume(streamId, type, vol)`
Obtenir le volume	`getAudioExternalStreamVolume(streamId, type)`	`getAudioExternalStreamVolume:type:`	`getAudioExternalStreamVolume(streamId, type)`
Vider le tampon	`clearAudioExternalStreamBuffer(streamId, fadeoutMs)`	`clearAudioExternalStreamBuffer:fadeoutMs:`	`clearAudioExternalStreamBuffer(streamId, fadeoutMs)`
Supprimer le flux	`removeAudioExternalStream(streamId)`	`removeAudioExternalStream:`	`removeAudioExternalStream(streamId)`

Bonnes pratiques pour l'envoi de données

Appelez pushAudioExternalStreamData dans une boucle afin de garantir le bon envoi des données.
Si le code d'erreur 110 (tampon plein) est retourné, attendez 30 ms avant de réessayer. Ne supprimez pas les données.
Avant la fermeture du moteur, arrêtez d'abord la boucle d'envoi, puis appelez removeAudioExternalStream.
Pour une capture en temps réel, chaque trame dure 10 ms ; appelez la fonction push dès que des données sont disponibles. Pour une entrée basée sur un fichier, chaque trame dure 40 ms ; appelez push toutes les 30 ms.

Rappels de trames audio

Les rappels de trames audio permettent d'obtenir des données PCM brutes à différentes étapes du pipeline audio, pour des besoins d'analyse audio, de traitement personnalisé, d'enregistrement ou autres scénarios similaires.

Positions des sources de données prises en charge

Source de données	Valeur d'énumération	Description
Captured	0	Données audio brutes après capture, avant le traitement 3A.
ProcessCaptured	1	Données audio après traitement 3A. Les rappels ne démarrent qu'après une connexion réussie.
Publish	2	Données audio sur le point d'être publiées. Nécessite une connexion réussie.
Playback	3	Données audio sur le point d'être lues (liaison descendante distante).

Paramètres de configuration des rappels

Paramètre	Type	Valeur par défaut	Description
sampleRate	int	48000	Fréquence d'échantillonnage pour l'audio du rappel.
channels	int	1	Nombre de canaux pour l'audio du rappel. Valeurs acceptées : 1 ou 2.
mode	AoqAudioObserverMode	ReadOnly	Mode lecture seule (0) ou lecture-écriture (1).

Étapes d'utilisation

Enregistrez l'observateur : Appelez setAudioFrameObserver pour définir l'écouteur de rappel de trame audio.
Activez la source de données : Appelez enableAudioFrameObserver pour sélectionner la position de la source de données et démarrer les rappels.
Traitez les données du rappel : Exploitez les données PCM dans le rappel.

Référence API

Fonction	Android	iOS	HarmonyOS
Enregistrer l'observateur	`setAudioFrameObserver(listener)`	`setAudioFrameObserver:`	`setAudioFrameObserver(observer)`
Activer les rappels	`enableAudioFrameObserver(enabled, source, config)`	`enableAudioFrameObserver:audioSource:config:`	`enableAudioFrameObserver(enabled, source, config)`

Méthodes de rappel

Rappel	Android	iOS	HarmonyOS
Données capturées	`onCapturedAudioFrame(frame)`	`onCapturedAudioFrame:`	`onCapturedAudioFrame(frame)`
Données post-3A	`onProcessCapturedAudioFrame(frame)`	`onProcessCapturedAudioFrame:`	`onProcessCapturedAudioFrame(frame)`
Données de publication	`onPublishAudioFrame(trackType, frame)`	`onPublishAudioFrame:frame:`	`onPublishAudioFrame(trackType, frame)`
Données de lecture	`onPlaybackAudioFrame(frame)`	`onPlaybackAudioFrame:`	`onPlaybackAudioFrame(frame)`

État audio et routage

Le SDK surveille automatiquement les changements d'état des périphériques audio et les bascules de routage, puis notifie la couche applicative via des rappels.

Codes d'état des périphériques

Code d'état	Valeur	Description
AoqAudioDeviceNone	0	État initial
RecordStarting	1	Démarrage de la capture
RecordStarted	2	Capture démarrée
RecordStopping	3	Arrêt de la capture en cours
RecordStopped	4	Capture arrêtée
RecordFail	5	Échec de la capture
PlayStarting	6	Démarrage de la lecture
PlayStarted	7	Lecture démarrée
PlayStopping	8	Arrêt de la lecture en cours
PlayStopped	9	Lecture arrêtée
PlayFail	10	Échec de la lecture

Types de routage des périphériques

Route	Valeur	Description
Default	0	Par défaut
Headset	1	Casque filaire
Earpiece	2	Écouteur
HeadsetNoMic	3	Casque sans microphone
SpeakerPhone	4	Haut-parleur
Usb	5	Périphérique USB
Bluetooth	6	Bluetooth SCO
BluetoothA2dp	7	Bluetooth A2DP

Référence des rappels

Rappel	Android	iOS	HarmonyOS
Changement d'état du périphérique	`onAudioDeviceStateChanged(state)`	`onAudioDeviceStateChanged:`	`onAudioDeviceStateChanged(state, reason)`
Changement de route	`onAudioDeviceRouteChanged(routeType)`	`onAudioDeviceRouteChanged:`	`onAudioDeviceRouteChanged(routeType)`
Interruption du périphérique	`onAudioDeviceInterrupted(interrupt)`	`onAudioDeviceInterrupted:`	`onAudioDeviceInterrupted(interrupt)`
État du fichier	`onAudioFileState(state)`	`onAudioFileState:`	`onAudioFileState(fileId, stateCode, errorCode)`

Codes d'erreur et d'avertissement audio

Codes d'erreur audio

Code d'erreur	Valeur	Description
AoqErrorCodeAudio	100	Erreur audio générale
AudioExternalBufferFull	110	Tampon externe plein
AudioDevice	120	Erreur générale du périphérique
RecordingAuthFailed	121	Autorisation de microphone refusée
RecordingOccupied	122	Microphone utilisé par un autre processus
RecordingBackgroundStart	123	Enregistrement démarré en arrière-plan
RecordingStartFail	124	Échec du démarrage de l'enregistrement
PlayoutOccupied	125	Périphérique de lecture utilisé par un autre processus
PlayoutBackgroundStart	126	Lecture démarrée en arrière-plan
PlayoutStartFail	127	Échec du démarrage de la lecture
EarpieceRequiresVoipMode	128	L'écouteur nécessite l'activation du mode VoIP

Codes d'avertissement audio

Code d'avertissement	Valeur	Description
AoqWCAudio	100	Avertissement audio général
AudioHowling	101	Larsen détecté
AudioDevice	120	Avertissement général du périphérique
MicEnumerateError	121	Erreur d'énumération du microphone
MicStartTimeout	122	Délai d'attente dépassé pour le démarrage du microphone
RecordingError	123	Erreur d'enregistrement
SpeakerEnumerateError	124	Erreur d'énumération du haut-parleur
SpeakerStartTimeout	125	Délai d'attente dépassé pour le démarrage du haut-parleur
PlayoutError	126	Erreur de lecture

Spécifique iOS : Contrôle d'AVAudioSession

Sur iOS, l'API setAudioSessionRestriction permet un contrôle précis de la manière dont le SDK gère l'AVAudioSession système.

Contrôle	Description
SetCategory	Autorise le SDK à définir la catégorie de session.
ConfigureSession	Autorise le SDK à configurer les paramètres de session.
DeactivateSession	Autorise le SDK à désactiver la session.
ActivateSession	Autorise le SDK à activer la session.

Transmettez une combinaison binaire de valeurs de restriction pour limiter le contrôle du SDK sur l'AVAudioSession et éviter les conflits avec d'autres composants audio de la couche applicative.