Recursos de áudio do AOQ SDK - captura, reprodução, mixagem, callbacks de frame - Alibaba Cloud Model Studio: Central de Documentação do Alibaba Cloud

O AOQ Client SDK oferece recursos abrangentes de áudio, incluindo captura, reprodução, configuração de codec, gerenciamento de alto-falante, mixagem de arquivos, injeção de streams de áudio externos e callbacks de dados de frames de áudio. Este documento apresenta os recursos de áudio mais utilizados nas plataformas Android (Java), iOS (Objective-C) e HarmonyOS (ArkTS).

Captura de áudio

A captura de áudio ativa o microfone do dispositivo e envia dados de áudio em tempo real para o pipeline de codificação do SDK. O SDK suporta dois modos de captura:

Captura interna (padrão): O SDK gerencia automaticamente o microfone, abrindo, gravando e fechando o dispositivo.
Captura externa: A aplicação gerencia o microfone diretamente e alimenta o SDK com os dados PCM capturados por meio da API de stream de áudio externo.

Parâmetros de configuração

Parâmetro	Tipo	Padrão	Descrição
isExternal	bool	false	Defina se o modo de captura externa será utilizado
isVoipMode	bool	false	Indica se o modo VoIP (AEC via hardware) deve ser ativado. Válido apenas em dispositivos móveis. Se tanto a captura quanto a reprodução forem configuradas, prevalece a definição feita primeiro.
channel	int	1	Quantidade de canais de captura. Suporta 1 (mono) ou 2 (estéreo).

Referência da API

Função	Android	iOS	HarmonyOS
Iniciar captura	`startAudioCapture(config)`	`startAudioCapture:config:`	`startAudioCapture(config)`
Parar captura	`stopAudioCapture()`	`stopAudioCapture`	`stopAudioCapture()`
Silenciar/reativar	`muteAudioCapture(mute)`	`muteAudioCapture:`	`muteAudioCapture(mute)`

Exemplo

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

Reprodução de áudio

A reprodução de áudio renderiza os dados de áudio remoto recebidos no alto-falante ou fone de ouvido local. O SDK oferece controles avançados, como pausa e retomada com efeitos de fade in/fade out, além da capacidade de interromper o turno atual de uma conversa de áudio.

Parâmetros de configuração

Parâmetro	Tipo	Padrão	Descrição
isVoipMode	bool	false	Indica se o modo VoIP (AEC via hardware) deve ser ativado. Válido apenas em dispositivos móveis. Se tanto a captura quanto a reprodução forem configuradas, prevalece a definição feita primeiro.
isDefaultSpeaker	bool	true	Defina se o alto-falante será usado por padrão. Válido em dispositivos móveis e exclusivamente fora do modo VoIP.
isExternal	bool	false	Especifica se o modo de reprodução externa será utilizado.
channel	int	1	Quantidade de canais de reprodução. Suporta 1 (mono) ou 2 (estéreo).

Referência da API

Função	Android	iOS	HarmonyOS
Iniciar reprodução	`startAudioPlayer(config)`	`startAudioPlayer:config:`	`startAudioPlayer(config)`
Parar reprodução	`stopAudioPlayer()`	`stopAudioPlayer`	`stopAudioPlayer()`
Pausar reprodução	`pauseAudioPlayer(fadeMs)`	`pauseAudioPlayer:`	`pauseAudioPlayer(fadeMs)`
Retomar reprodução	`resumeAudioPlayer(fadeMs)`	`resumeAudioPlayer:`	`resumeAudioPlayer(fadeMs)`
Interromper conversa	`interruptAudioPlayer(trackType, fadeMs)`	`interruptAudioPlayer:fadeMs:`	`interruptAudioPlayer(trackType, fadeMs)`

ObservaçãoParâmetro fadeMs: Representa a duração do fade-in ou fade-out, em milissegundos, ao pausar ou retomar a reprodução. Defina como 0 para uma transição imediata.

Gerenciamento de alto-falante

Alterne o dispositivo de saída de áudio entre o alto-falante e o auricular.

Função	Android	iOS	HarmonyOS
Alternar alto-falante	`enableSpeakerphone(enable)`	`enableSpeakerphone:`	`enableSpeakerphone(enable)`
Consultar estado do alto-falante	`isSpeakerphoneEnabled()`	`isSpeakerphoneEnabled`	`isSpeakerphoneEnabled()`

ObservaçãoA alternância de alto-falante é permitida apenas no modo VoIP. Fora desse modo, a chamada de enableSpeakerphone gera uma notificação de erro OnError(AoqECAudioDeviceEarpieceRequiresVoipMode).

ObservaçãoComportamento específico do iOS: Dispositivos iPad operam somente no modo de alto-falante. Quando a categoria AVAudioSession não for PlayAndRecord, este método sempre retorna YES.

Configuração de codec de áudio

Configure o formato de codificação, taxa de amostragem, número de canais e bitrate para o uplink (codificador) e downlink (decodificador) de áudio. Essas definições determinam o formato utilizado na publicação e no pull de streams.

Parâmetros de configuração

Parâmetro	Tipo	Padrão	Descrição
trackType	AoqTrackType	Audio	Tipo de faixa de áudio. Atualmente, há suporte para apenas um stream de áudio.
codecType	AoqEncoderType	AudioPCM	Tipo de codificação: AudioPCM(1) ou AudioOpus(2)
sampleRate	int	48000	Taxa de amostragem. Opus suporta 8K/16K/48K. PCM suporta 8K/16K/32K/48K.
channel	int	1	Número de canais. Suporta 1 (mono) ou 2 (estéreo).
bitrate	int	32000	Bitrate em bps.

Referência da API

Função	Android	iOS	HarmonyOS
Definir configuração do codificador	`setAudioEncoderConfig(config)`	`setAudioEncoderConfig:`	`setAudioEncoderConfig(config)`
Definir configuração do decodificador	`setAudioDecoderConfig(config)`	`setAudioDecoderConfig:`	`setAudioDecoderConfig(config)`

Formatos de codificação suportados

Valor do enum	Número	Descrição
AoqEncoderTypeAudioPCM	1	Áudio PCM bruto
AoqEncoderTypeAudioOpus	2	Codificação Opus

Mixagem de arquivos de áudio

Misture um arquivo de áudio local ao stream de áudio atual para publicação e/ou reprodução local. Cada arquivo de áudio é identificado por um fileId atribuído pela aplicação, permitindo o gerenciamento simultâneo de múltiplas instâncias de arquivos.

Parâmetros de configuração de mixagem

Parâmetro	Tipo	Padrão	Descrição
fileName	String	-	Caminho do arquivo de áudio (incluindo o nome do arquivo)
cycles	int	-1	Número de repetições. -1 indica loop infinito.
startPosMs	long	0	Posição inicial de reprodução em milissegundos
publishVolume	int	100	Volume de publicação [0–100]
playoutVolume	int	100	Volume de reprodução local [0–100]

Referência da API

Função	Android	iOS	HarmonyOS
Iniciar reprodução	`startAudioFile(fileId, config)`	`startAudioFile:config:`	`startAudioFile(fileId, config)`
Parar reprodução	`stopAudioFile(fileId)`	`stopAudioFile:`	`stopAudioFile(fileId)`
Pausar	`pauseAudioFile(fileId)`	`pauseAudioFile:`	`pauseAudioFile(fileId)`
Retomar	`resumeAudioFile(fileId)`	`resumeAudioFile:`	`resumeAudioFile(fileId)`
Obter duração do arquivo	`getAudioFileDuration(fileId)`	`getAudioFileDuration:`	`getAudioFileDuration(fileId)`
Obter posição atual	`getAudioFileCurrentPosition(fileId)`	`getAudioFileCurrentPosition:`	`getAudioFileCurrentPosition(fileId)`
Buscar posição	`setAudioFilePositionMillis(fileId, pos)`	`setAudioFilePositionMillis:positionMillis:`	`setAudioFilePositionMillis(fileId, pos)`
Definir volume	`setAudioFileVolume(fileId, type, vol)`	`setAudioFileVolume:type:volume:`	`setAudioFileVolume(fileId, type, vol)`
Obter volume	`getAudioFileVolume(fileId, type)`	`getAudioFileVolume:type:`	`getAudioFileVolume(fileId, type)`

ObservaçãoDireção do volume (type): AoqAudioStreamPublish(0) controla o volume de publicação. AoqAudioStreamPlayout(1) controla o volume de reprodução local.

Callbacks de estado

Código de estado	Valor	Descrição
AoqAudioFileNone	0	Estado inicial
AoqAudioFileStarted	1	Reprodução iniciada
AoqAudioFileStopped	2	Reprodução parada
AoqAudioFilePaused	3	Reprodução pausada
AoqAudioFileResumed	4	Reprodução retomada
AoqAudioFileEnded	5	Reprodução finalizada
AoqAudioFileBuffering	6	Buffering em andamento
AoqAudioFileBufferingEnd	7	Buffering concluído
AoqAudioFileFailed	8	Falha na reprodução

Streams de áudio externos

Streams de áudio externos permitem injetar dados de áudio PCM gerados pela aplicação no pipeline de áudio do SDK para publicação e/ou reprodução local. Casos de uso típicos incluem saída de síntese TTS, áudio gerado por modelos de IA e efeitos sonoros de fundo. Cada stream de áudio externo é identificado por um streamId atribuído pela aplicação.

Parâmetros de configuração

Parâmetro	Tipo	Padrão	Descrição
trackType	AoqTrackType	Audio	Tipo de faixa de áudio
codecType	AoqEncoderType	AudioPCM	Formato do stream de áudio
channels	int	1	Número de canais
sampleRate	int	48000	Taxa de amostragem. Suporta 8/12/16/24/32/44,1/48/64/88,2/96/176,4/192 kHz.
playoutVolume	int	100	Volume de reprodução local [0–100]
publishVolume	int	100	Volume de publicação [0–100]
maxBufferDuration	int	600000	Duração máxima do buffer em milissegundos. Faixa válida: [100, ~]. O push falha se o buffer estiver cheio.
enable3A	bool	false	Defina se o processamento 3A deve ser aplicado ao PCM de entrada

Referência da API

Função	Android	iOS	HarmonyOS
Adicionar stream externo	`addAudioExternalStream(streamId, config)`	`addAudioExternalStream:config:`	`addAudioExternalStream(streamId, config)`
Enviar dados de áudio	`pushAudioExternalStreamData(streamId, data)`	`pushAudioExternalStreamData:data:`	`pushAudioExternalStreamData(streamId, data)`
Definir volume	`setAudioExternalStreamVolume(streamId, type, vol)`	`setAudioExternalStreamVolume:type:volume:`	`setAudioExternalStreamVolume(streamId, type, vol)`
Obter volume	`getAudioExternalStreamVolume(streamId, type)`	`getAudioExternalStreamVolume:type:`	`getAudioExternalStreamVolume(streamId, type)`
Limpar buffer	`clearAudioExternalStreamBuffer(streamId, fadeoutMs)`	`clearAudioExternalStreamBuffer:fadeoutMs:`	`clearAudioExternalStreamBuffer(streamId, fadeoutMs)`
Remover stream	`removeAudioExternalStream(streamId)`	`removeAudioExternalStream:`	`removeAudioExternalStream(streamId)`

Melhores práticas para envio de dados

Chame pushAudioExternalStreamData em loop para garantir que os dados sejam enviados com sucesso.
Se o código de erro 110 (buffer cheio) for retornado, aguarde 30 ms e tente novamente. Não descarte os dados.
Antes de encerrar a engine, pare primeiro o loop de envio e depois chame removeAudioExternalStream.
Para captura em tempo real, cada frame tem 10 ms — envie os dados assim que estiverem disponíveis. Para entrada baseada em arquivo, cada frame tem 40 ms — envie uma vez a cada 30 ms.

Callbacks de frames de áudio

Os callbacks de frames de áudio permitem obter dados PCM brutos em diferentes pontos do pipeline de áudio, possibilitando análise de áudio, processamento personalizado, gravação e cenários similares.

Posições de source de dados suportadas

Source de dados	Valor do enum	Descrição
Captured	0	Dados de áudio brutos após a captura, antes do processamento 3A
ProcessCaptured	1	Dados de áudio após o processamento 3A. Os callbacks iniciam somente após uma conexão bem-sucedida.
Publish	2	Dados de áudio prestes a serem publicados. Requer uma conexão estabelecida com sucesso.
Playback	3	Dados de áudio prestes a serem reproduzidos (downlink remoto)

Parâmetros de configuração de callback

Parâmetro	Tipo	Padrão	Descrição
sampleRate	int	48000	Taxa de amostragem para o áudio do callback
channels	int	1	Número de canais para o áudio do callback. Suporta 1 ou 2.
mode	AoqAudioObserverMode	ReadOnly	Modo somente leitura (0) ou leitura e escrita (1)

Etapas de uso

Registre o observer: Chame setAudioFrameObserver para definir o listener de callback de frames de áudio.
Ative a source de dados: Chame enableAudioFrameObserver para selecione a posição da source de dados e iniciar os callbacks.
Processe os dados do callback: Manipule os dados PCM dentro do callback.

Referência da API

Função	Android	iOS	HarmonyOS
Registrar observer	`setAudioFrameObserver(listener)`	`setAudioFrameObserver:`	`setAudioFrameObserver(observer)`
Ativar callbacks	`enableAudioFrameObserver(enabled, source, config)`	`enableAudioFrameObserver:audioSource:config:`	`enableAudioFrameObserver(enabled, source, config)`

Métodos de callback

Callback	Android	iOS	HarmonyOS
Dados capturados	`onCapturedAudioFrame(frame)`	`onCapturedAudioFrame:`	`onCapturedAudioFrame(frame)`
Dados pós-3A	`onProcessCapturedAudioFrame(frame)`	`onProcessCapturedAudioFrame:`	`onProcessCapturedAudioFrame(frame)`
Dados de publicação	`onPublishAudioFrame(trackType, frame)`	`onPublishAudioFrame:frame:`	`onPublishAudioFrame(trackType, frame)`
Dados de reprodução	`onPlaybackAudioFrame(frame)`	`onPlaybackAudioFrame:`	`onPlaybackAudioFrame(frame)`

Estado e roteamento de áudio

O SDK monitora automaticamente alterações no estado dos dispositivos de áudio e mudanças de roteamento, notificando a camada da aplicação por meio de callbacks.

Códigos de estado do dispositivo

Código de estado	Valor	Descrição
AoqAudioDeviceNone	0	Estado inicial
RecordStarting	1	Captura iniciando
RecordStarted	2	Captura iniciada
RecordStopping	3	Captura parando
RecordStopped	4	Captura parada
RecordFail	5	Falha na captura
PlayStarting	6	Reprodução iniciando
PlayStarted	7	Reprodução iniciada
PlayStopping	8	Reprodução parando
PlayStopped	9	Reprodução parada
PlayFail	10	Falha na reprodução

Tipos de roteamento de dispositivo

Rota	Valor	Descrição
Default	0	Padrão
Headset	1	Fone de ouvido com fio
Earpiece	2	Auricular
HeadsetNoMic	3	Fone de ouvido sem microfone
SpeakerPhone	4	Alto-falante
Usb	5	Dispositivo USB
Bluetooth	6	Bluetooth SCO
BluetoothA2dp	7	Bluetooth A2DP

Referência de callbacks

Callback	Android	iOS	HarmonyOS
Alteração de estado do dispositivo	`onAudioDeviceStateChanged(state)`	`onAudioDeviceStateChanged:`	`onAudioDeviceStateChanged(state, reason)`
Alteração de rota	`onAudioDeviceRouteChanged(routeType)`	`onAudioDeviceRouteChanged:`	`onAudioDeviceRouteChanged(routeType)`
Dispositivo interrompido	`onAudioDeviceInterrupted(interrupt)`	`onAudioDeviceInterrupted:`	`onAudioDeviceInterrupted(interrupt)`
Estado do arquivo	`onAudioFileState(state)`	`onAudioFileState:`	`onAudioFileState(fileId, stateCode, errorCode)`

Códigos de erro e aviso de áudio

Códigos de erro de áudio

Código de erro	Valor	Descrição
AoqErrorCodeAudio	100	Erro geral de áudio
AudioExternalBufferFull	110	Buffer externo cheio
AudioDevice	120	Erro geral de dispositivo
RecordingAuthFailed	121	Permissão de microfone negada
RecordingOccupied	122	Microfone em uso por outro processo
RecordingBackgroundStart	123	Gravação iniciada em segundo plano
RecordingStartFail	124	Falha ao iniciar gravação
PlayoutOccupied	125	Dispositivo de reprodução em uso por outro processo
PlayoutBackgroundStart	126	Reprodução iniciada em segundo plano
PlayoutStartFail	127	Falha ao iniciar reprodução
EarpieceRequiresVoipMode	128	O auricular exige que o modo VoIP esteja ativado

Códigos de aviso de áudio

Código de aviso	Valor	Descrição
AoqWCAudio	100	Aviso geral de áudio
AudioHowling	101	Microfonia detectada
AudioDevice	120	Aviso geral de dispositivo
MicEnumerateError	121	Erro na enumeração do microfone
MicStartTimeout	122	Tempo limite de início do microfone
RecordingError	123	Erro de gravação
SpeakerEnumerateError	124	Erro na enumeração do alto-falante
SpeakerStartTimeout	125	Tempo limite de início do alto-falante
PlayoutError	126	Erro de reprodução

Exclusivo para iOS: Controle de AVAudioSession

No iOS, a API setAudioSessionRestriction oferece controle granular sobre como o SDK gerencia a AVAudioSession do sistema.

Controle	Descrição
SetCategory	Defina se o SDK pode configure a categoria da sessão
ConfigureSession	Defina se o SDK pode configure os parâmetros da sessão
DeactivateSession	Defina se o SDK pode desativar a sessão
ActivateSession	Defina se o SDK pode ative a sessão

Passe uma combinação bitwise dos valores de restrição para limitar o controle do SDK sobre a AVAudioSession e evitar conflitos com outros componentes de áudio na camada da aplicação.