Funciones de audio comunes

Captura de audio

La captura de audio abre el micrófono del dispositivo y alimenta la canalización de codificación del SDK con datos de audio en tiempo real. El SDK admite dos modos de captura:

Captura interna (predeterminado): El SDK administra automáticamente el micrófono: apertura, grabación y cierre.
Captura externa: La aplicación administra el micrófono directamente y alimenta los datos PCM capturados en el SDK a través de la API de flujo de audio externo.

Parámetros de configuración

Parámetro	Tipo	Predeterminado	Descripción
isExternal	bool	false	Si se debe usar el modo de captura externa
isVoipMode	bool	false	Indica si se debe habilitar el modo VoIP (AEC por hardware). Válido en dispositivos móviles. Si se configuran tanto la captura como la reproducción, tendrá efecto la que se configure primero.
channel	int	1	Número de canales de captura. Admite 1 (mono) o 2 (estéreo).

Referencia de API

Función	Android	iOS	HarmonyOS
Iniciar captura	`startAudioCapture(config)`	`startAudioCapture:config:`	`startAudioCapture(config)`
Detener captura	`stopAudioCapture()`	`stopAudioCapture`	`stopAudioCapture()`
Silenciar/reactivar	`muteAudioCapture(mute)`	`muteAudioCapture:`	`muteAudioCapture(mute)`

Ejemplo

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

Reproducción de audio

La reproducción de audio renderiza los datos de audio remotos recibidos en el altavoz o auricular local. El SDK admite controles avanzados, incluyendo pausa/reanudación con fundido de entrada/salida e interrupción del turno actual de una conversación de audio.

Parámetros de configuración

Parámetro	Tipo	Predeterminado	Descripción
isVoipMode	bool	false	Indica si se debe habilitar el modo VoIP (AEC por hardware). Válido en dispositivos móviles. Si se configuran tanto la captura como la reproducción, tendrá efecto la que se configure primero.
isDefaultSpeaker	bool	true	Indica si se debe usar el altavoz de forma predeterminada. Válido en dispositivos móviles y solo en modo no VoIP.
isExternal	bool	false	Indica si se debe usar el modo de reproducción externa.
channel	int	1	Número de canales de reproducción. Admite 1 (mono) o 2 (estéreo).

Referencia de API

Función	Android	iOS	HarmonyOS
Iniciar reproducción	`startAudioPlayer(config)`	`startAudioPlayer:config:`	`startAudioPlayer(config)`
Detener reproducción	`stopAudioPlayer()`	`stopAudioPlayer`	`stopAudioPlayer()`
Pausar reproducción	`pauseAudioPlayer(fadeMs)`	`pauseAudioPlayer:`	`pauseAudioPlayer(fadeMs)`
Reanudar reproducción	`resumeAudioPlayer(fadeMs)`	`resumeAudioPlayer:`	`resumeAudioPlayer(fadeMs)`
Interrumpir conversación	`interruptAudioPlayer(trackType, fadeMs)`	`interruptAudioPlayer:fadeMs:`	`interruptAudioPlayer(trackType, fadeMs)`

Parámetro fadeMs: La duración de fundido de entrada o salida en milisegundos al pausar o reanudar la reproducción. Establezca en 0 para un cambio inmediato.

Gestión de altavoces

Cambiar el dispositivo de salida de audio entre el altavoz y el auricular.

Función	Android	iOS	HarmonyOS
Cambiar altavoz	`enableSpeakerphone(enable)`	`enableSpeakerphone:`	`enableSpeakerphone(enable)`
Consultar estado del altavoz	`isSpeakerphoneEnabled()`	`isSpeakerphoneEnabled`	`isSpeakerphoneEnabled()`

El cambio de altavoz solo está permitido en modo VoIP. Cuando no está en modo VoIP, llamar a enableSpeakerphone activa una notificación de error OnError(AoqECAudioDeviceEarpieceRequiresVoipMode).

Comportamiento específico de iOS: Los dispositivos iPad solo tienen modo altavoz. Cuando la categoría AVAudioSession no es PlayAndRecord, este método siempre devuelve YES.

Configuración del códec de audio

Configure el formato de codificación, la frecuencia de muestreo, el número de canales y la tasa de bits para el enlace ascendente (codificador) y descendente (decodificador) de audio. Estas configuraciones determinan el formato para publicar y extraer flujos.

Parámetros de configuración

Parámetro	Tipo	Predeterminado	Descripción
trackType	AoqTrackType	Audio	Tipo de pista de audio. Actualmente solo se admite un flujo de audio.
codecType	AoqEncoderType	AudioOpus	Tipo de codificación: AudioPCM(1) o AudioOpus(2)
sampleRate	int	48000	Frecuencia de muestreo. Opus admite 8K/16K/48K. PCM admite 8K/16K/32K/48K.
channel	int	1	Recuento de canales. Admite 1 (mono) o 2 (estéreo).
bitrate	int	32000	Tasa de bits en bps.

Referencia de API

Función	Android	iOS	HarmonyOS
Establecer configuración del codificador	`setAudioEncoderConfig(config)`	`setAudioEncoderConfig:`	`setAudioEncoderConfig(config)`
Establecer configuración del decodificador	`setAudioDecoderConfig(config)`	`setAudioDecoderConfig:`	`setAudioDecoderConfig(config)`

Formatos de codificación admitidos

Valor de enumeración	Número	Descripción
AoqEncoderTypeAudioPCM	1	Audio PCM sin procesar
AoqEncoderTypeAudioOpus	2	Codificación Opus

Mezcla de archivos de audio

Mezcle un archivo de audio local en el flujo de audio actual para su publicación y/o reproducción local. Cada archivo de audio se identifica mediante un fileId asignado por la aplicación, lo que permite gestionar múltiples instancias de archivos simultáneamente.

Parámetros de configuración de mezcla

Parámetro	Tipo	Predeterminado	Descripción
fileName	String	-	Ruta del archivo de audio (incluido el nombre del archivo)
cycles	int	-1	Número de bucles. -1 significa repetir indefinidamente.
startPosMs	long	0	Posición de inicio de reproducción en milisegundos
publishVolume	int	100	Volumen de publicación [0–100]
playoutVolume	int	100	Volumen de reproducción local [0–100]

Referencia de API

Función	Android	iOS	HarmonyOS
Iniciar reproducción	`startAudioFile(fileId, config)`	`startAudioFile:config:`	`startAudioFile(fileId, config)`
Detener reproducción	`stopAudioFile(fileId)`	`stopAudioFile:`	`stopAudioFile(fileId)`
Pausar	`pauseAudioFile(fileId)`	`pauseAudioFile:`	`pauseAudioFile(fileId)`
Reanudar	`resumeAudioFile(fileId)`	`resumeAudioFile:`	`resumeAudioFile(fileId)`
Obtener duración del archivo	`getAudioFileDuration(fileId)`	`getAudioFileDuration:`	`getAudioFileDuration(fileId)`
Obtener posición actual	`getAudioFileCurrentPosition(fileId)`	`getAudioFileCurrentPosition:`	`getAudioFileCurrentPosition(fileId)`
Buscar posición	`setAudioFilePositionMillis(fileId, pos)`	`setAudioFilePositionMillis:positionMillis:`	`setAudioFilePositionMillis(fileId, pos)`
Establecer volumen	`setAudioFileVolume(fileId, type, vol)`	`setAudioFileVolume:type:volume:`	`setAudioFileVolume(fileId, type, vol)`
Obtener volumen	`getAudioFileVolume(fileId, type)`	`getAudioFileVolume:type:`	`getAudioFileVolume(fileId, type)`

Dirección del volumen (tipo): AoqAudioStreamPublish(0) controla el volumen de publicación. AoqAudioStreamPlayout(1) controla el volumen de reproducción local.

Callbacks de estado

Código de estado	Valor	Descripción
AoqAudioFileNone	0	Estado inicial
AoqAudioFileStarted	1	Reproducción iniciada
AoqAudioFileStopped	2	Reproducción detenida
AoqAudioFilePaused	3	Reproducción en pausa
AoqAudioFileResumed	4	Reproducción reanudada
AoqAudioFileEnded	5	Reproducción finalizada
AoqAudioFileBuffering	6	Buffering
AoqAudioFileBufferingEnd	7	Almacenamiento en búfer finalizado
AoqAudioFileFailed	8	Error en la reproducción

Secuencias de audio externas

Los flujos de audio externos le permiten inyectar datos de audio PCM generados por la aplicación en la canalización de audio del SDK para su publicación y/o reproducción local. Los casos de uso típicos incluyen la salida de síntesis TTS, la salida de audio de modelos de IA y efectos de sonido de fondo. Cada flujo de audio externo se identifica mediante un streamId asignado por la aplicación.

Parámetros de configuración

Parámetro	Tipo	Predeterminado	Descripción
trackType	AoqTrackType	Audio	Tipo de pista de audio
codecType	AoqEncoderType	AudioPCM	Formato de flujo de audio
channels	int	1	Recuento de canales
sampleRate	int	48000	Frecuencia de muestreo. Admite 8/12/16/24/32/44.1/48/64/88.2/96/176.4/192 kHz.
playoutVolume	int	100	Volumen de reproducción local [0–100]
publishVolume	int	100	Volumen de publicación [0–100]
maxBufferDuration	int	600000	Duración máxima del búfer en milisegundos. Rango válido: [100, ~]. El envío falla si el búfer está lleno.
enable3A	bool	false	Indica si se debe aplicar el procesamiento 3A al PCM de entrada

Referencia de API

Función	Android	iOS	HarmonyOS
Agregar flujo externo	`addAudioExternalStream(streamId, config)`	`addAudioExternalStream:config:`	`addAudioExternalStream(streamId, config)`
Enviar datos de audio	`pushAudioExternalStreamData(streamId, data)`	`pushAudioExternalStreamData:data:`	`pushAudioExternalStreamData(streamId, data)`
Establecer volumen	`setAudioExternalStreamVolume(streamId, type, vol)`	`setAudioExternalStreamVolume:type:volume:`	`setAudioExternalStreamVolume(streamId, type, vol)`
Obtener volumen	`getAudioExternalStreamVolume(streamId, type)`	`getAudioExternalStreamVolume:type:`	`getAudioExternalStreamVolume(streamId, type)`
Borrar búfer	`clearAudioExternalStreamBuffer(streamId, fadeoutMs)`	`clearAudioExternalStreamBuffer:fadeoutMs:`	`clearAudioExternalStreamBuffer(streamId, fadeoutMs)`
Eliminar flujo	`removeAudioExternalStream(streamId)`	`removeAudioExternalStream:`	`removeAudioExternalStream(streamId)`

Mejores prácticas para enviar datos

Llame a pushAudioExternalStreamData en un bucle para garantizar que los datos se envíen correctamente.
Si se devuelve el código de error 110 (búfer lleno), espere 30 ms y reintente. No descarte datos.
Antes de que el motor se cierre, detenga primero el bucle de envío y luego llame a removeAudioExternalStream.
Para captura en tiempo real, cada trama es de 10 ms; llame a push siempre que haya datos disponibles. Para entrada basada en archivos, cada trama es de 40 ms; llame a push una vez cada 30 ms.

Devoluciones de llamada de cuadros de audio

Los callbacks de tramas de audio le permiten obtener datos PCM sin procesar en diferentes puntos de la canalización de audio, para su uso en análisis de audio, procesamiento personalizado, grabación y escenarios similares.

Posiciones de fuente de datos admitidas

Fuente de datos	Valor de enumeración	Descripción
Captured	0	Datos de audio sin procesar después de la captura, antes del procesamiento 3A
ProcessCaptured	1	Datos de audio después del procesamiento 3A. Los callbacks comienzan solo después de una conexión exitosa.
Publicar	2	Datos de audio a punto de publicarse. Requiere una conexión exitosa.
Playback	3	Datos de audio a punto de reproducirse (enlace descendente remoto)

Parámetros de configuración de callback

Parámetro	Tipo	Predeterminado	Descripción
sampleRate	int	48000	Tasa de muestreo para el audio del callback
channels	int	1	Recuento de canales para el audio del callback. Admite 1 o 2.
mode	AoqAudioObserverMode	ReadOnly	Modo de solo lectura (0) o lectura-escritura (1)

Pasos de uso

Registrar el observador: Llame a setAudioFrameObserver para configurar el listener de callback de tramas de audio.
Habilitar la fuente de datos: Llame a enableAudioFrameObserver para seleccionar la posición de la fuente de datos e iniciar los callbacks.
Manejar datos de callback: Procesar datos PCM en el callback.

Referencia de API

Función	Android	iOS	HarmonyOS
Registrar observador	`setAudioFrameObserver(listener)`	`setAudioFrameObserver:`	`setAudioFrameObserver(observer)`
Habilitar callbacks	`enableAudioFrameObserver(enabled, source, config)`	`enableAudioFrameObserver:audioSource:config:`	`enableAudioFrameObserver(enabled, source, config)`

Métodos de callback

Callback	Android	iOS	HarmonyOS
Datos capturados	`onCapturedAudioFrame(frame)`	`onCapturedAudioFrame:`	`onCapturedAudioFrame(frame)`
Datos post-3A	`onProcessCapturedAudioFrame(frame)`	`onProcessCapturedAudioFrame:`	`onProcessCapturedAudioFrame(frame)`
Publicar datos	`onPublishAudioFrame(trackType, frame)`	`onPublishAudioFrame:frame:`	`onPublishAudioFrame(trackType, frame)`
Datos de reproducción	`onPlaybackAudioFrame(frame)`	`onPlaybackAudioFrame:`	`onPlaybackAudioFrame(frame)`

Estado y enrutamiento de audio

El SDK monitorea automáticamente los cambios de estado de los dispositivos de audio y los cambios de enrutamiento, y notifica a la capa de aplicación mediante callbacks.

Códigos de estado del dispositivo

Código de estado	Valor	Descripción
AoqAudioDeviceNone	0	Estado inicial
RecordStarting	1	Iniciando captura
RecordStarted	2	Captura iniciada
RecordStopping	3	Deteniendo captura
RecordStopped	4	Captura detenida
RecordFail	5	Error en la captura
PlayStarting	6	Iniciando reproducción
PlayStarted	7	Reproducción iniciada
PlayStopping	8	Deteniendo reproducción
PlayStopped	9	Reproducción detenida
PlayFail	10	Error en la reproducción

Tipos de enrutamiento de dispositivos

Ruta	Valor	Descripción
Valor predeterminado	0	Valor predeterminado
Headset	1	Auriculares con cable
Auricular	2	Auricular
HeadsetNoMic	3	Auriculares sin micrófono
SpeakerPhone	4	Altavoz
Usb	5	Dispositivo USB
Bluetooth	6	Bluetooth SCO
BluetoothA2dp	7	Bluetooth A2DP

Referencia de callbacks

Callback	Android	iOS	HarmonyOS
Cambio de estado del dispositivo	`onAudioDeviceStateChanged(state)`	`onAudioDeviceStateChanged:`	`onAudioDeviceStateChanged(state, reason)`
Cambio de ruta	`onAudioDeviceRouteChanged(routeType)`	`onAudioDeviceRouteChanged:`	`onAudioDeviceRouteChanged(routeType)`
Dispositivo interrumpido	`onAudioDeviceInterrupted(interrupt)`	`onAudioDeviceInterrupted:`	`onAudioDeviceInterrupted(interrupt)`
Estado del archivo	`onAudioFileState(state)`	`onAudioFileState:`	`onAudioFileState(fileId, stateCode, errorCode)`

Códigos de error y advertencia de audio

Códigos de error de audio

Código de error	Valor	Descripción
AoqErrorCodeAudio	100	Error general de audio
AudioExternalBufferFull	110	Búfer externo lleno
AudioDevice	120	Error general del dispositivo
RecordingAuthFailed	121	Permiso de micrófono denegado
RecordingOccupied	122	Micrófono en uso por otro proceso
RecordingBackgroundStart	123	Grabación iniciada en segundo plano
RecordingStartFail	124	Error al iniciar la grabación
PlayoutOccupied	125	Dispositivo de reproducción en uso por otro proceso
PlayoutBackgroundStart	126	Reproducción iniciada en segundo plano
PlayoutStartFail	127	Error al iniciar la reproducción
EarpieceRequiresVoipMode	128	El auricular requiere que el modo VoIP esté habilitado

Códigos de advertencia de audio

Código de advertencia	Valor	Descripción
AoqWCAudio	100	Advertencia general de audio
AudioHowling	101	Acople detectado
AudioDevice	120	Advertencia general del dispositivo
MicEnumerateError	121	Error de enumeración de micrófono
MicStartTimeout	122	Tiempo de espera agotado al iniciar el micrófono
RecordingError	123	Error de grabación
SpeakerEnumerateError	124	Error de enumeración de altavoces
SpeakerStartTimeout	125	Tiempo de espera agotado al iniciar el altavoz
PlayoutError	126	Error de reproducción

Solo iOS: Control de AVAudioSession

En iOS, la API setAudioSessionRestriction le brinda control detallado sobre cómo el SDK administra la AVAudioSession del sistema.

Control	Descripción
SetCategory	Indica si el SDK puede establecer la categoría de la sesión
ConfigureSession	Indica si el SDK puede configurar los parámetros de la sesión
DeactivateSession	Indica si el SDK puede desactivar la sesión
ActivateSession	Indica si el SDK puede activar la sesión

Pase una combinación bit a bit de valores de restricción para limitar el control del SDK sobre AVAudioSession y evitar conflictos con otros componentes de audio en la capa de aplicación.

​Captura de audio

​Parámetros de configuración

​Referencia de API

​Ejemplo

​Reproducción de audio

​Parámetros de configuración

​Referencia de API

​Gestión de altavoces

​Configuración del códec de audio

​Parámetros de configuración

​Referencia de API

​Formatos de codificación admitidos

​Mezcla de archivos de audio

​Parámetros de configuración de mezcla

​Referencia de API

​Callbacks de estado

​Secuencias de audio externas

​Parámetros de configuración

​Referencia de API

​Mejores prácticas para enviar datos

​Devoluciones de llamada de cuadros de audio

​Posiciones de fuente de datos admitidas

​Parámetros de configuración de callback

​Pasos de uso

​Referencia de API

​Métodos de callback

​Estado y enrutamiento de audio

​Códigos de estado del dispositivo

​Tipos de enrutamiento de dispositivos

​Referencia de callbacks

​Códigos de error y advertencia de audio

​Códigos de error de audio

​Códigos de advertencia de audio

​Solo iOS: Control de AVAudioSession

Captura de audio

Parámetros de configuración

Referencia de API

Ejemplo

Reproducción de audio

Parámetros de configuración

Referencia de API

Gestión de altavoces

Configuración del códec de audio

Parámetros de configuración

Referencia de API

Formatos de codificación admitidos

Mezcla de archivos de audio

Parámetros de configuración de mezcla

Referencia de API

Callbacks de estado

Secuencias de audio externas

Parámetros de configuración

Referencia de API

Mejores prácticas para enviar datos

Devoluciones de llamada de cuadros de audio

Posiciones de fuente de datos admitidas

Parámetros de configuración de callback

Pasos de uso

Referencia de API

Métodos de callback

Estado y enrutamiento de audio

Códigos de estado del dispositivo

Tipos de enrutamiento de dispositivos

Referencia de callbacks

Códigos de error y advertencia de audio

Códigos de error de audio

Códigos de advertencia de audio

Solo iOS: Control de AVAudioSession