SDK HarmonyOS

Referência da API AOQ HarmonyOS SDK

índice API

Ciclo de vida do motor

Gerenciamento de dispositivos de áudio

Configuração do codec de áudio

Gerenciamento de dispositivos de vídeo

Codificação de vídeo e entrada externa

Controle de fluxo de mídia

Reprodução de arquivo de áudio

Fluxos de áudio externos

Mensagens em tempo real

Retornos de chamada de quadro de áudio

Retornos de chamada de quadro de vídeo

Retornos de chamada AoqEngineEventListener

Detalhes da API

Requisitos de entrada de vídeo externa

pushExternalVideoCapturedFrame suporta vídeo e tela. Habilite primeiro a captura externa na trilha correspondente; caso contrário, ele retorna AoqECVideoExternalCaptureNotEnabled (211). pushExternalVideoEncodedFrame requer codificação externa na faixa correspondente; caso contrário, ele retorna AoqECVideoExternalEncoderNotEnabled (212).

Captura de tela

startScreenCapture(config: AoqScreenCaptureConfig): number
stopScreenCapture(): number

config especifica configurações de captura de tela. O conteúdo da tela é enviado no AoqTrackTypeScreen pista.

Para começar, 0 significa que a solicitação foi aceita; onScreenCaptureStateChanged relata o resultado de forma assíncrona. Um retorno diferente de zero rejeita a solicitação de forma síncrona sem um evento de falha duplicado. Stop retorna 0 em caso de sucesso ou um valor diferente de zero em caso de falha e relata o estado interrompido por meio desse retorno de chamada.

Com isExternal=false, o SDK captura a tela e o sistema solicita permissão. Você não precisa esperar por Iniciado antes de ativar a transmissão ou produzir quadros externos.

Para quadros brutos externos, defina isExternal=true e fornecer molduras de tela brutas através pushExternalVideoCapturedFrame para codificação SDK. Para quadros codificados externos, configure a trilha Screen para codificação externa com setVideoEncoderConfig, então ligue pushExternalVideoEncodedFrame; startScreenCapture não é obrigatório.

onScreenCaptureStateChanged

onScreenCaptureStateChanged?: (state: AoqScreenCaptureState) => void;

state contém o estado da captura de tela. Iniciado significa que a captura ou entrada externa está pronta, e não que a mídia foi enviada. Falhas de captura de tela também não são relatadas por meio de onError. Os retornos de chamada são entregues de forma assíncrona no thread JS.

###setVideoDecoderConfig

setVideoDecoderConfig(config: AoqVideoCodecConfig): number

config especifica configurações de decodificação de vídeo. Somente os seguintes campos terão efeito: trackType, codecType, width, height, fps, bitrate. Outros campos aplicam-se apenas à codificação.

A tela não suporta decodificação downstream. Se config.trackType é Tela, o método retorna AoqECUnSupport sem aplicar a configuração.

Retorna 0 em caso de sucesso ou um valor diferente de zero em caso de falha.

enableLocalAudioVolumeIndication

enableLocalAudioVolumeIndication(config: AoqAudioVolumeIndicationConfig): number

config especifica configurações de indicação de volume. Os retornos de chamada são emitidos em config.interval. Chame esse método depois startAudioCapture.

Retorna 0 em caso de sucesso ou um valor diferente de zero em caso de falha.

onLocalAudioVolumeIndication?: (volume: AoqAudioVolume) => void;

O volume argumento de retorno de chamada contém o volume de captura local.

Ciclo de vida do motor

####criarEngine

Crie a instância do mecanismo. O SDK mantém o mecanismo como um singleton global; chamar esse método novamente retorna a instância existente. Retorna nulo se o mecanismo nativo falhar na inicialização.

static createEngine(config: AoqCreateConfig, listener: AoqEngineEventListener, context: common.Context): AoqClientEngine | null

Retornos: AoqClientEngine | null -- null se a criação nativa falhar.

Observação: Ao contrário do Android, este SDK retorna nulo em caso de falha. Sempre verifique nulo o valor de retorno. O context deve ser um contexto UIability ou Page válido.

destruir

Destrua o singleton do motor e libere todos os recursos. Você deve ligar createEngine novamente antes de retomar o uso.

static destroy(): number

Retorna: 0 em caso de sucesso; diferente de zero em caso de falha.

getVersion

Obtenha a string da versão atual do SDK.

static getVersion(): string

Retorna: String de versão, por exemplo "1.0.0".

conectar

Conecte-se ao servidor de retransmissão. Os parâmetros de conexão são alocados pelo servidor de aplicação via /api/v1/allocate e entregue ao cliente.

connect(config: AoqConnectConfig): number

Retorna: 0 se a chamada foi despachada (assíncrona); diferente de zero se a validação do parâmetro falhou.

Observação: As alterações no estado da conexão são relatadas de forma assíncrona por meio de onConnectionStatusChange. Recomenda-se ligar enableSendMediaStream(false) antes de ligar connect.

desconectar

Desconecte-se do servidor e libere recursos relacionados à conexão. Dispositivos de captura/reprodução de áudio e vídeo não são interrompidos automaticamente.

disconnect(): number

Retorna: 0 se a chamada foi despachada (assíncrona); diferente de zero em caso de falha.

Gerenciamento de dispositivos de áudio

startAudioCapture

Abra o dispositivo de captura de áudio (microfone).

startAudioCapture(config: AoqAudioCaptureConfig): number

Retorna: 0 em caso de sucesso; diferente de zero em caso de falha.

stopAudioCapture

Feche o dispositivo de captura de áudio.

stopAudioCapture(): number

muteAudioCapture

Ative ou desative a captura de áudio.

muteAudioCapture(mute: boolean): number

iniciarAudioPlayer

Inicie a reprodução de áudio (reproduza áudio remoto através do alto-falante ou fone de ouvido).

startAudioPlayer(config: AoqAudioPlaybackConfig): number

pararAudioPlayer

Pare a reprodução de áudio.

stopAudioPlayer(): number

pausaAudioPlayer

Pause a reprodução de áudio com um fade-out opcional para uma transição suave.

pauseAudioPlayer(fadeMs: number): number

retomarAudioPlayer

Retome a reprodução de áudio com um fade-in opcional para uma transição suave.

resumeAudioPlayer(fadeMs: number): number

interromperAudioPlayer

Interromper a chamada de áudio atual.

interruptAudioPlayer(trackType: AoqTrackType, fadeMs: number): number

ativar viva-voz

Alterne a rota de saída de áudio entre o alto-falante e o fone de ouvido.

enableSpeakerphone(enable: boolean): number

está habilitado para viva-voz

Consulte se o alto-falante está ativo no momento.

isSpeakerphoneEnabled(): boolean

Retorna: verdadeiro se o alto-falante estiver ativo; false se o fone de ouvido estiver ativo.

Configuração do codec de áudio

####setAudioEncoderConfig

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

setAudioEncoderConfig(config: AoqAudioCodecConfig): number

####setAudioDecoderConfig

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

setAudioDecoderConfig(config: AoqAudioCodecConfig): number

Gerenciamento de dispositivos de vídeo

startVideoCapture

Abra o dispositivo de captura de vídeo (câmera). Quando config.isExternal = true, a câmera não está aberta; o chamador fornece frames via pushExternalVideoCapturedFrame.

startVideoCapture(config: AoqVideoCaptureConfig): number

pararVideoCapture

Feche o dispositivo de captura de vídeo.

stopVideoCapture(): number

mudarCâmera

Alterne entre as câmeras frontal e traseira.

switchCamera(direction: AoqCameraDirection): number

setLocalView

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

setLocalView(trackType: AoqTrackType, canvas: AoqVideoCanvas | null): number

Nota: No HarmonyOS, isso deve ser chamado após o XComponent.onLoad retorno de chamada. Passe um AoqXComponentController instância como canvas.view.

definirRemoteView

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

setRemoteView(trackType: AoqTrackType, canvas: AoqVideoCanvas | null): number

Codificação de vídeo e entrada externa

####setVideoEncoderConfig

Defina parâmetros de codificação de vídeo. A chamada é roteada para a trilha especificada por config.trackType.

setVideoEncoderConfig(config: AoqVideoCodecConfig): number

pushExternalVideoCapturedFrame

Envie um quadro de vídeo bruto capturado externamente.

pushExternalVideoCapturedFrame(trackType: AoqTrackType, frame: AoqVideoFrame): number

Para vídeo, ligue startVideoCapture(isExternal=true) primeiro. Para tela, ligue startScreenCapture(isExternal=true) primeiro. Formatos suportados: NV12, NV21, BGRA, RGBA, I420.

Se o buffer interno estiver cheio, o método retornará AoqECVideoExternalBufferFull(210). Durma e tente novamente; não faça loop ocupado.

pushExternalVideoEncodedFrame

Envie um quadro de vídeo codificado externamente. O SDK envia diretamente sem recodificação.

pushExternalVideoEncodedFrame(trackType: AoqTrackType, frame: AoqVideoEncodedFrame): number

Só consumido depois setVideoEncoderConfig(isExternal=true) está configurado.

Controle de fluxo de mídia

ativarSendMediaStream

Ative ou desative o envio de fluxo de mídia local. A chamada é roteada para a trilha especificada por trackType.

enableSendMediaStream(trackType: AoqTrackType, enable: boolean): number

Padrão recomendado: chamada enableSendMediaStream(trackType, false) após a inicialização, ative assim que a conexão for estabelecida e o handshake da sessão for concluído (onConnectionStatusChange relatórios AoqConnectionStatusConnected).

Reprodução de arquivo de áudio

startAudioFile

Comece a transmitir um arquivo de áudio local. A reprodução do arquivo de áudio é mixada no fluxo publicado e na reprodução local.

startAudioFile(fileId: string, config: AoqAudioFileMixConfig): number

stopAudioFile / pauseAudioFile / resumeAudioFile

stopAudioFile(fileId: string): number
pauseAudioFile(fileId: string): number
resumeAudioFile(fileId: string): number

getAudioFileDuration / getAudioFileCurrentPosition

getAudioFileDuration(fileId: string): number      // Returns total duration (ms); negative on failure
getAudioFileCurrentPosition(fileId: string): number // Returns current position (ms); negative on failure

setAudioFilePositionMillis

setAudioFilePositionMillis(fileId: string, positionMillis: number): number

setAudioFileVolume / getAudioFileVolume

setAudioFileVolume(fileId: string, type: AoqAudioStreamDirection, volume: number): number
getAudioFileVolume(fileId: string, type: AoqAudioStreamDirection): number // Returns [0, 100]; negative on failure

Fluxos de áudio externos

addAudioExternalStream

Adicione um fluxo de áudio externo.

addAudioExternalStream(streamId: string, config: AoqAudioExternalStreamConfig): number

pushAudioExternalStreamData

Envie dados de áudio PCM externos. Devoluções AoqECAudioExternalBufferFull(110) se o buffer interno estiver cheio.

pushAudioExternalStreamData(streamId: string, data: AoqAudioFrameData): number

setAudioExternalStreamVolume / getAudioExternalStreamVolume

setAudioExternalStreamVolume(streamId: string, type: AoqAudioStreamDirection, vol: number): number
getAudioExternalStreamVolume(streamId: string, type: AoqAudioStreamDirection): number

clearAudioExternalStreamBuffer

Limpe o buffer de fluxo de áudio externo. Nenhum valor de retorno; executa de forma assíncrona.

clearAudioExternalStreamBuffer(streamId: string, fadeoutMs: number): void

removeAudioExternalStream

removeAudioExternalStream(streamId: string): number

Mensagens em tempo real

enviarDataMsg

Envie uma mensagem de dados em tempo real pelo canal de dados MoQT.

sendDataMsg(msg: AoqDataMsg): number

Retornos de chamada de quadro de áudio

####setAudioFrameObserver

Defina o observador de retorno de chamada de dados do quadro de áudio. Registre o observador primeiro e depois ligue enableAudioFrameObserver para começar a receber retornos de chamada.

setAudioFrameObserver(observer: IAudioFrameObserver | null): number

enableAudioFrameObserver

enableAudioFrameObserver(enabled: boolean, audioSource: AoqAudioSource, config: AoqAudioObserverConfig): number

Retornos de chamada de quadro de vídeo

####setVideoFrameObserver

setVideoFrameObserver(observer: IVideoFrameObserver | null): number

enableVideoFrameObserver

enableVideoFrameObserver(enabled: boolean, videoSource: AoqVideoSource, config: AoqVideoObserverConfig): number

Retornos de chamada AoqEngineEventListener

Todos os retornos de chamada são propriedades opcionais (?).

export interface AoqEngineEventListener {
  onError?: (code: number, message: string) => void;
  onWarning?: (code: number, message: string) => void;
  onConnectionStatusChange?: (status: AoqConnectionStatus) => void;
  onStats?: (stats: AoqStats) => void;
  onAudioDeviceStateChanged?: (state: AoqAudioDeviceState) => void;
  onAudioDeviceRouteChanged?: (routeType: number) => void;
  onAudioDeviceInterrupted?: (interrupt: boolean) => void;
  onVideoDeviceStateChanged?: (state: AoqVideoDeviceState) => void;
  onAudioFileState?: (state: AoqAudioFileState) => void;
  onDataMsg?: (msg: AoqDataMsg) => void;
}

####IAudioFrameObserver

export interface IAudioFrameObserver {
  onCapturedAudioFrame?: (frame: AoqAudioFrameData) => void;
  onProcessCapturedAudioFrame?: (frame: AoqAudioFrameData) => void;
  onPublishAudioFrame?: (trackType: AoqTrackType, frame: AoqAudioFrameData) => void;
  onPlaybackAudioFrame?: (frame: AoqAudioFrameData) => void;
}

frame.dataPtr é um Uint8Array cópia da memória nativa e atualmente é somente leitura (as modificações não são gravadas no SDK).

IVideoFrameObserver

export interface IVideoFrameObserver {
  onCapturedVideoFrame?: (trackType: AoqTrackType, frame: AoqVideoFrame) => boolean;
  onPreEncodeVideoFrame?: (trackType: AoqTrackType, frame: AoqVideoFrame) => boolean;
  onRemoteVideoFrame?: (trackType: AoqTrackType, frame: AoqVideoFrame) => boolean;
}

Os buffers de quadro são Uint8Array cópias da memória nativa, válidas apenas durante o retorno de chamada. Atualmente, eles são equivalentes a somente leitura; o suporte de write-back está planejado para uma versão futura.

Tipos de dados e enumerações

Na v1.3.0, Index.ets exporta as seguintes enums e interfaces:

• Enums: AoqTrackMode, AoqScreenCaptureStateCode.
• Interfaces: AoqAudioVolumeIndicationConfig, AoqAudioVolume, AoqScreenCaptureConfig, AoqScreenCaptureState.

AoqScreenCaptureState

AoqScreenCaptureStateCode

AoqScreenCaptureConfig

AoqAudioVolume

AoqAudioVolumeIndicaçãoConfig

Modo AoqTrack

Tipos gerais

AoqCreateConfig

Ao contrário do Android, AoqCreateConfig no HarmonyOS não inclui isBTScoMode.

AoqConnectConfig

subscribeTracks não deve incluir AoqTrackTypeScreen; caso contrário, connect retorna AoqECUnSupport sem iniciar uma conexão. setRemoteView também retorna AoqECUnSupport para tela.

AoqRelayEndpoint

AoqTrackParam

AoqErrorCode

AoqWarningCode

AoqTrackType

AoqConnectionStatus

AoqEncoderType / AoqMirrorMode / AoqOrientationMode

Igual ao SDK do Android; sem alterações.

Tipos de áudio

AoqAudioCaptureConfig

AoqAudioPlaybackConfig

AoqAudioCodecConfig

Tipos de vídeo

AoqVideoCaptureConfig

AoqVideoCodecConfig

####AoqVideoCanvas

####AoqVideoPixelFormat

TextureOES e Texture2D não são suportados no HarmonyOS.

AoqVideoFrame

AoqVideoEncodedFrame

Arquivo de áudio e tipos de stream externo

AoqAudioFileMixConfig

AoqAudioExternalStreamConfig

AoqAudioFrameData

Tipos de configuração do observador

AoqAudioObserverConfig

AoqVideoObserverConfig

Tipos de estatísticas

####AoqStats

Subtipos de estatísticas

AoqAudioPublishStats: trackType / taxa de bits / bytes / encodeVolume

AoqVideoPublishStats: trackType / taxa de bits / bytes / encodeFps

AoqAudioSubscribeStats: trackType / taxa de bits / bytes / playVolume

AoqVideoSubscribeStats: trackType / taxa de bits / bytes / decodeFps / renderFps

AoqDataMsgPublishStats/AoqDataMsgSubscribeStats: trackType/taxa de bits/bytes

AoqNetworkStats: sendBitrate / sendBytes / recvBitrate / recvBytes / loss / rtt

Principais diferenças do Android SDK

Notas de arquitetura

1. AoqXComponentController: Estende XComponentController e substituições onSurfaceCreated, onSurfaceChangede onSurfaceDestroyed. Crie uma instância, anexe-a a um XComponent, e passe-o como canvas.view ao ligar setLocalView ou setRemoteView.

2. Arquitetura NAPI: fachada (AoqClientEngine.ets) -> implementação (AoqClientEngineImpl.ets) -> NAPI (libaoq_client_sdk.so). Os objetos de configuração são nivelados em parâmetros individuais na camada de implementação.

3. Monitoramento do dispositivo (interno): AoqDeviceMonitor inicia automaticamente após createEngine e encaminha o estado da rede e o estado de primeiro/segundo plano do aplicativo para o mecanismo C++.

4. Proteção UAF do observador: O novo registro segue uma sequência de três etapas: cortar a referência antiga em C++ -> enviar o observador antigo para a lápide -> apontar para o novo observador.

5. Semântica da carga útil do quadro: Uint8Array buffers em retornos de chamada de quadro de áudio/vídeo são cópias da memória nativa. O write-back não é suportado em P1; cópia zero está planejada para P2.