Skip to main content
AOQ SDK overview

Referência da API Android do AOQ Client SDK

O AOQ Client SDK para Android oferece um conjunto completo de recursos de comunicação de áudio e vídeo em tempo real, incluindo gerenciamento do ciclo de vida do mecanismo, captura e reprodução de áudio e vídeo, configuração de codec, injeção de fluxo de áudio externo, mixagem de arquivos de áudio, mensagens em tempo real e callbacks de quadros de áudio e vídeo. Este documento é a referência completa da API Java para a plataforma Android.

Índice de APIs

Ciclo de vida do mecanismo

API

Descrição

createEngine

Crie a instância do mecanismo (singleton)

destroy

Destrói a instância do mecanismo

getVersion

Obtém a string de versão do SDK

connect

Conecta ao servidor Relay

disconnect

Desconecta do servidor

Gerenciamento de dispositivos de áudio

API

Descrição

startAudioCapture

Abre o dispositivo de captura de áudio (microfone)

stopAudioCapture

Fecha o dispositivo de captura de áudio

muteAudioCapture

Silencia ou reativa a captura de áudio

startAudioPlayer

Inicia a reprodução de áudio (reproduz áudio remoto)

stopAudioPlayer

Interrompe a reprodução de áudio

pauseAudioPlayer

Pausa a reprodução de áudio com fade-out opcional

resumeAudioPlayer

Retoma a reprodução de áudio com fade-in opcional

interruptAudioPlayer

Interrompe o turno atual da chamada de áudio

enableSpeakerphone

Alterna a saída de áudio entre alto-falante e auricular

isSpeakerphoneEnabled

Consulta se o alto-falante está ativo no momento

Configuração de codec de áudio

API

Descrição

setAudioEncoderConfig

Defina os parâmetros de codificação de áudio

setAudioDecoderConfig

Defina os parâmetros de decodificação de áudio

Gerenciamento de dispositivos de vídeo

API

Descrição

startVideoCapture

Abre o dispositivo de captura de vídeo (câmera)

stopVideoCapture

Fecha o dispositivo de captura de vídeo

switchCamera

Alterna entre as câmeras frontal e traseira

setLocalView

Defina ou remova a visualização de renderização de vídeo local

setRemoteView

Defina ou remova a visualização de renderização de vídeo remoto

Codificação de vídeo e entrada externa

API

Descrição

setVideoEncoderConfig

Defina os parâmetros de codificação de vídeo

pushExternalVideoCapturedFrame

Envia um quadro de vídeo bruto capturado externamente

pushExternalVideoEncodedFrame

Envia um quadro de vídeo codificado externamente

Controle de fluxo de mídia / mensagens em tempo real

API

Descrição

enableSendMediaStream

Ative ou desative o envio de fluxo de mídia local

sendDataMsg

Envia uma mensagem de dados em tempo real

Reprodução de arquivo de áudio

API

Descrição

startAudioFile

Inicia o streaming de um arquivo de áudio local

stopAudioFile

Para a reprodução do arquivo de áudio

pauseAudioFile

Pausa a reprodução do arquivo de áudio

resumeAudioFile

Retoma a reprodução do arquivo de áudio

getAudioFileDuration

Obtém a duração total do arquivo de áudio

getAudioFileCurrentPosition

Obtém a posição atual da reprodução

setAudioFilePositionMillis

Busca uma posição específica no arquivo de áudio

setAudioFileVolume

Defina o volume do arquivo de áudio

getAudioFileVolume

Obtém o volume atual do arquivo de áudio

Fluxos de áudio externos

API

Descrição

addAudioExternalStream

Adiciona um fluxo de áudio externo

removeAudioExternalStream

Remove um fluxo de áudio externo

pushAudioExternalStreamData

Envia dados de áudio PCM externos

setAudioExternalStreamVolume

Defina o volume de um fluxo de áudio externo

getAudioExternalStreamVolume

Obtém o volume de um fluxo de áudio externo

clearAudioExternalStreamBuffer

Limpa o buffer de um fluxo de áudio externo

Callbacks de quadros de áudio/vídeo

API

Descrição

setAudioFrameObserver

Defina o listener de callback de dados de quadro de áudio

enableAudioFrameObserver

Ative ou desative callbacks de quadro de áudio em um ponto especificado

setVideoFrameObserver

Defina o listener de callback de dados de quadro de vídeo

enableVideoFrameObserver

Ative ou desative callbacks de quadro de vídeo em um ponto especificado

Callbacks do AoqClientListener

Callback

Descrição

onError

Callback de erro do mecanismo

onWarning

Callback de aviso do mecanismo

onConnectionStatusChange

Callback de alteração de estado de conexão

onStats

Callback de estatísticas do mecanismo

onAudioDeviceStateChanged

Callback de alteração de estado do dispositivo de áudio

onAudioDeviceRouteChanged

Callback de alteração de rota de saída de áudio

onAudioDeviceInterrupted

Callback de interrupção do dispositivo de áudio

onVideoDeviceStateChanged

Callback de alteração de estado do dispositivo de vídeo

onAudioDeviceFocusChanged

Callback de alteração de foco de áudio

onAudioFileState

Callback de estado de reprodução de arquivo de áudio

onDataMsg

Callback de recebimento de mensagem de dados em tempo real

Detalhes da API

Ciclo de vida do mecanismo

createEngine Crie a instância do mecanismo. O SDK mantém o mecanismo como um singleton global; chamar este método novamente retorna a instância existente.
@NonNull
public static AoqClientEngine createEngine(
    @NonNull Context context,
    @NonNull AoqCreateConfig config,
    @NonNull AoqClientListener listener)

Parâmetro

Tipo

Descrição

context

Context

Contexto da aplicação Android

config

AoqCreateConfig

Configuração de criação do mecanismo

listener

AoqClientListener

Listener de callback de eventos do mecanismo

Retorno: Instância de AoqClientEngine; nunca nula. destroy Destrua a instância do mecanismo e libere todos os recursos.
public static int destroy()
Retorno: 0 em caso de sucesso; diferente de zero em caso de falha. getVersion
@NonNull
public static String getVersion()
Retorno: String de versão, por exemplo "1.0.0". connect Conecte-se ao servidor Relay. O servidor da aplicação aloca os parâmetros de conexão via /api/v1/allocate e os entrega ao cliente.
public abstract int connect(@NonNull AoqConnectConfig config)
Retorno: 0 se a chamada foi despachada (assíncrona); diferente de zero se a validação de parâmetros falhar. disconnect
public abstract int disconnect()
Retorno: 0 se a chamada foi despachada (assíncrona); diferente de zero em caso de falha.

Gerenciamento de dispositivos de áudio

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: duração do fade-out/fade-in em milissegundos; 0 significa imediato.

Configuração de codec de áudio

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

Gerenciamento de dispositivos de vídeo

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)
Passe AoqTrackTypeVideo como parâmetro trackType para setLocalView e setRemoteView.

Codificação de vídeo e entrada externa

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 só consome quadros após a chamada de startVideoCapture(isExternal=true). Se o buffer interno estiver cheio, o método retorna AoqErrorCodeVideoExternalBufferFull (210).

Controle de fluxo de mídia

public abstract int enableSendMediaStream(@NonNull AoqTrackType trackType, boolean enable)
Padrão recomendado: chame enableSendMediaStream(false) após a inicialização e ative somente quando onConnectionStatusChange reportar Connected.

Reprodução de arquivo de áudio

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)

Fluxos de áudio externos

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)
Quando pushAudioExternalStreamData retornar AoqErrorCodeAudioExternalBufferFull (110), significa que o buffer interno está cheio. Aguarde 30 ms e tente novamente.

Mensagens em tempo real

public abstract int sendDataMsg(@NonNull AoqDataMsg msg)

Callbacks de quadro de áudio

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

Callbacks de quadro de vídeo

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

Callbacks do AoqClientListener

AoqClientListener é o ponto unificado de entrega para todos os eventos assíncronos do SDK. Todos os métodos de callback possuem uma implementação vazia padrão, portanto, substitua apenas aqueles relevantes para sua aplicação.
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)
Transições de estado de conexão: 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; }
}
Retorne true para indicar que você modificou os dados do quadro e deseja que o SDK os leia novamente (a gravação de volta só tem efeito para o formato I420). O ByteBuffer e o textureId em frame são válidos apenas durante o callback; copie-os antes de qualquer uso assíncrono.

Tipos de dados e enumerações

Tipos gerais

AoqCreateConfig

Campo

Tipo

Padrão

Descrição

workDir

String

""

Diretório de trabalho do SDK

isBTScoMode

boolean

false

true: modo Bluetooth SCO; false: modo A2DP

enableDumpAudio

boolean

false

Ativar dump de áudio (para depuração)

extras

String

""

String de parâmetros extras

AoqConnectConfig

Campo

Tipo

Padrão

Descrição

token

String

""

Token de autenticação

sid

String

""

ID da sessão

certFingerprint

String

""

Impressão digital do certificado do servidor

relayEndpoints

List<AoqRelayEndpoint>

vazio

Lista de endpoints Relay

workspaceIdHash

String

""

Hash do ID do workspace

publishTracks

List<AoqTrackParam>

vazio

Faixas locais a serem publicadas

subscribeTracks

List<AoqTrackParam>

vazio

Faixas remotas para assinatura

Tipos de estatísticas

AoqNetworkStats

Campo

Tipo

Descrição

sendBitrate

int

Taxa de bits de envio (bps)

sendBytes

long

Bytes enviados acumulados

recvBitrate

int

Taxa de bits de recebimento (bps)

recvBytes

long

Bytes recebidos acumulados

loss

int

Taxa de perda de pacotes (0–100)

rtt

int

Tempo de ida e volta (ms)

Enumerações

AoqErrorCode

Valor da enumeração

Valor

Descrição

AoqErrorCodeOK

0

Sucesso

AoqErrorCodeParamInvalid

1

Parâmetro inválido

AoqErrorCodeStateInvalid

2

Estado inválido

AoqErrorCodeUnSupport

3

Não suportado

AoqErrorCodeAudio

100

Erro genérico de áudio

AoqErrorCodeAudioExternalBufferFull

110

Buffer de áudio externo cheio

AoqErrorCodeAudioDevice

120

Erro genérico de dispositivo de áudio

AoqErrorCodeAudioDeviceRecordingAuthFailed

121

Permissão de gravação não concedida

AoqErrorCodeAudioDeviceRecordingOccupied

122

Dispositivo de gravação em uso

AoqErrorCodeAudioDeviceRecordingBackgroundStart

123

Falha ao iniciar gravação em segundo plano

AoqErrorCodeAudioDeviceRecordingStartFail

124

Falha ao iniciar gravação

AoqErrorCodeAudioDevicePlayoutOccupied

125

Dispositivo de reprodução em uso

AoqErrorCodeAudioDevicePlayoutBackgroundStart

126

Falha ao iniciar reprodução em segundo plano

AoqErrorCodeAudioDevicePlayoutStartFail

127

Falha ao iniciar reprodução

AoqErrorCodeAudioDeviceEarpieceRequiresVoipMode

128

Auricular requer modo VoIP

AoqErrorCodeVideo

200

Erro genérico de vídeo

AoqErrorCodeVideoExternalBufferFull

210

Buffer de vídeo externo cheio

AoqErrorCodeVideoExternalCaptureNotEnabled

211

Captura de vídeo externa não ativada

AoqErrorCodeVideoExternalEncoderNotEnabled

212

Codificador de vídeo externo não ativado

AoqErrorCodeVideoDevice

220

Erro genérico de dispositivo de vídeo

AoqErrorCodeVideoDeviceCameraOpenFail

221

Falha ao abrir câmera

AoqErrorCodeVideoDeviceCameraAuthFailed

222

Permissão de câmera não concedida

AoqErrorCodeVideoDeviceCameraOccupied

223

Câmera em uso

AoqErrorCodeVideoDeviceCameraRunningError

224

Erro de execução da câmera

AoqErrorCodeVideoCodec

230

Erro genérico de codec de vídeo

AoqErrorCodeVideoCodecEncoderInitFail

231

Falha na inicialização do codificador de vídeo

AoqErrorCodeVideoRender

240

Erro genérico de renderização de vídeo

AoqErrorCodeVideoRenderCreateFail

241

Falha na criação do renderizador de vídeo

AoqErrorCodeVideoRenderDrawError

242

Erro de desenho na renderização de vídeo

AoqWarningCode

Valor da enumeração

Valor

Descrição

AoqWCOK

0

Sem avisos

AoqWCAudio

100

Aviso genérico de áudio

AoqWCAudioHowling

101

Microfonia detectada

AoqWCAudioDevice

120

Aviso genérico de dispositivo de áudio

AoqWCAudioDeviceMicEnumerateError

121

Erro de enumeração de microfone

AoqWCAudioDeviceMicStartTimeout

122

Timeout ao iniciar microfone

AoqWCAudioDeviceRecordingError

123

Erro de gravação

AoqWCAudioDeviceSpeakerEnumerateError

124

Erro de enumeração de alto-falante

AoqWCAudioDeviceSpeakerStartTimeout

125

Timeout ao iniciar alto-falante

AoqWCAudioDevicePlayoutError

126

Erro de reprodução

AoqWCVideo

200

Aviso genérico de vídeo

AoqWCVideoCameraEnumerateError

201

Erro de enumeração de câmera

AoqWCVideoEncoderSwitched

202

Codificador de vídeo alternado

AoqWCVideoRenderDowngrade

203

Renderização de vídeo rebaixada

AoqTrackType

Valor da enumeração

Valor

Descrição

AoqTrackTypeAudio

0

Faixa de áudio

AoqTrackTypeVideo

1

Faixa de vídeo

AoqTrackTypeData

2

Faixa de mensagens de dados

AoqEncoderType

Valor da enumeração

Valor

Descrição

AoqEncoderTypeUnknown

0

Formato desconhecido

AoqEncoderTypeAudioPCM

1

Áudio PCM

AoqEncoderTypeAudioOpus

2

Áudio Opus

AoqEncoderTypeVideoH264

3

Vídeo H.264

AoqEncoderTypeVideoJpeg

4

Vídeo JPEG

AoqEncoderTypeDataText

5

Texto de dados

AoqConnectionStatus

Valor da enumeração

Valor

Descrição

AoqConnectionStatusDisconnected

0

Desconectado

AoqConnectionStatusConnecting

1

Conectando

AoqConnectionStatusConnected

2

Conectado

AoqConnectionStatusFailed

3

Falha na conexão

Tipos de áudio

AoqAudioCaptureConfig

Campo

Tipo

Padrão

Descrição

isExternal

boolean

false

Indica se deve usar o modo de captura externa

isVoipMode

boolean

false

Indica se deve ativar o modo VoIP (afeta o roteamento do dispositivo, ex.: auricular)

channel

int

1

Contagem de canais (padrão: mono)

AoqAudioPlaybackConfig

Campo

Tipo

Padrão

Descrição

isVoipMode

boolean

false

Indica se deve ativar o modo VoIP (AEC de hardware); aplica-se a dispositivos móveis

isDefaultSpeaker

boolean

true

Indica se deve usar o alto-falante por padrão; aplica-se a dispositivos móveis

isExternal

boolean

false

Indica se deve usar o modo de reprodução externa

channel

int

1

Contagem de canais (padrão: mono)

AoqAudioCodecConfig

Campo

Tipo

Padrão

Descrição

trackType

AoqTrackType

Audio

Tipo de faixa

codecType

AoqEncoderType

AudioPCM

Formato do codec

sampleRate

int

48000

Taxa de amostragem (Hz)

channel

int

1

Contagem de canais

bitrate

int

32000

Taxa de bits (bps)

Tipos de vídeo

AoqVideoCaptureConfig

Campo

Tipo

Padrão

Descrição

width

int

1280

Largura de captura (pixels); ignorado quando isExternal=true

height

int

720

Altura de captura (pixels); ignorado quando isExternal=true

fps

int

15

Taxa de quadros de captura; ignorado quando isExternal=true

isExternal

boolean

false

Modo de captura externa; quando verdadeiro, a câmera não é aberta

cameraDirection

AoqCameraDirection

Front

Direção da câmera; ignorado quando isExternal=true

AoqVideoCodecConfig

Campo

Tipo

Padrão

Descrição

trackType

AoqTrackType

Video

Tipo de faixa

codecType

AoqEncoderType

VideoH264

Formato do codec

width

int

720

Largura de codificação (pixels)

height

int

1280

Altura de codificação (pixels)

fps

int

5

Taxa de quadros de codificação

bitrate

int

500000

Taxa de bits alvo (bps)

minBitrate

int

128000

Taxa de bits mínima (bps)

keyframeInterval

int

2

Intervalo de quadros-chave (segundos)

mirrorMode

AoqMirrorMode

Disabled

Modo espelho

orientationMode

AoqOrientationMode

Auto

Modo de orientação de vídeo

isExternal

boolean

false

Quando verdadeiro, o SDK ignora a recodificação; use pushExternalVideoEncodedFrame para entregar dados pré-codificados

AoqVideoPixelFormat

Valor da enumeração

Valor

Descrição

AoqVideoPixelFormatUnknown

0

Formato desconhecido

AoqVideoPixelFormatI420

1

I420 (YUV planar)

AoqVideoPixelFormatNV12

2

NV12 (YUV semi-planar)

AoqVideoPixelFormatNV21

3

NV21 (YUV semi-planar)

AoqVideoPixelFormatBGRA

4

BGRA 32-bit

AoqVideoPixelFormatRGBA

5

RGBA 32-bit

AoqVideoPixelFormatTextureOES

7

Textura OES externa

AoqVideoPixelFormatTexture2D

8

Textura 2D padrão

Tipos de fluxo de áudio externo

AoqAudioExternalStreamConfig

Campo

Tipo

Padrão

Descrição

trackType

AoqTrackType

Audio

Tipo de faixa de áudio

codecType

AoqEncoderType

AudioPCM

Formato do fluxo de áudio

channels

int

1

Contagem de canais

sampleRate

int

48000

Taxa de amostragem (Hz)

playoutVolume

int

100

Volume de reprodução [0–100]

publishVolume

int

100

Volume de publicação [0–100]

maxBufferDuration

int

1000

Duração máxima do buffer (milissegundos)

enable3A

boolean

false

Indica se deve aplicar processamento 3A ao PCM de entrada

AoqAudioStreamDirection

Valor da enumeração

Valor

Descrição

AoqAudioStreamPublish

0

Fluxo de publicação (envio)

AoqAudioStreamPlayout

1

Fluxo de reprodução (recebimento)

Tipos de mensagem de dados

AoqDataMsg

Campo

Tipo

Padrão

Descrição

data

byte[]

new byte[0]

Dados da mensagem (array de bytes)

Referência da API de Geração de Texto
Geração de Imagens
  • FAQ
Geração de Vídeo
Áudio
Incorporação de Texto
Produção de Modelos
Referência da API Android do AOQ Client SDK - Alibaba Cloud Model Studio