SDK eletrônico

Referência da API Electron do SDK do cliente AOQ

Este tópico descreve as APIs TypeScript, eventos e tipos de dados do AOQ Client SDK for Electron. O SDK é compatível com macOS x64/arm64 e Windows x64 e requer Node.js 16 ou posterior.

Pacote aplicável: aoq-electron-sdk (npm). Plataformas suportadas: macOS (x64/arm64) e Windows x64. Node.js >= 16.

índice API

Entrada e ciclo de vida do motor

Gerenciamento de dispositivos de áudio

Configuração do codec de áudio

Gerenciamento de dispositivos de vídeo

Codec 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

Indicação de volume local

Retornos de chamada de quadro de vídeo

Renderização de vídeo (YUVCanvasRenderer)

Eventos do mecanismo (IAoqEngineEvents)

Detalhes da API

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.

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

Ligar getScreenSourceList para enumerar telas e janelas e depois passar o selecionado sourceId e sourceType na configuração de captura.

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.

getScreenSourceList

getScreenSourceList(): AoqScreenSourceInfo[]

Retorna uma matriz de fontes de tela. Disponível apenas no Electron macOS e Windows.

Entrada e ciclo de vida do motor

criarAoqClientEngine

Obtém a instância do wrapper do mecanismo. É um singleton inicializado lentamente em nível de módulo. Chamar esse método novamente retorna a mesma instância, que se alinha com a semântica singleton do mecanismo nativo. É também a exportação padrão do pacote.

import createAoqClientEngine from 'aoq-electron-sdk';
export function createAoqClientEngine(): IAoqClientEngine

Retorna: O IAoqClientEngine instância do motor. Observe que este método cria apenas a camada wrapper JS e a ponte nativa. Para realmente criar o mecanismo, você também deve chamar createEngine().

criarEngine

Cria a instância do mecanismo nativo. O mecanismo é um singleton global, portanto, chamar esse método novamente retorna sucesso diretamente.

createEngine(config: AoqCreateConfig): number

Retorna: 0 no sucesso; -1 indica que a criação falhou ou que o parâmetro não é JSON válido.

No Windows, createEngine() anexa uma bomba de mensagem Win32 de 16 ms ao loop libuv do thread JS atual (necessário para captura da câmera) e o interrompe destroy(). Portanto, não bloqueie de forma síncrona o thread JS por muito tempo após createEngine().

destruir

Destrói a instância do mecanismo e libera todos os recursos.

destroy(): number

Retorna: 0 indica sucesso; não-0 indica uma falha. Se o mecanismo não for criado, 0 é retornado.

obter versão

Obtém a versão atual do SDK. Você não precisa ligar createEngine() primeiro.

getVersion(): string

Retorna: A string da versão, como "1.2.0". Uma string vazia será retornada se a versão não puder ser obtida.

conectar

Conecta-se ao servidor de retransmissão. O servidor de aplicação obtém parâmetros de conexão AOQ temporários com base no protocolo em uso e os envia ao cliente.

connect(config: AoqConnectConfig): number

Retorna: 0 indica que a chamada é despachada e executada de forma assíncrona; não-0 indica que a validação do parâmetro falhou. O resultado da conexão é notificado pelo onConnectionStatusChange evento.

desconectar

Desconecta do servidor e libera os recursos associados à conexão.

disconnect(): number

Retorna: 0 indica que a chamada é despachada e executada de forma assíncrona; não-0 indica uma falha.

Gerenciamento de dispositivos de áudio

iniciar Captura de Áudio

startAudioCapture(config: AoqAudioCaptureConfig): number

Abre o dispositivo de captura de áudio (microfone). A primeira captura aciona uma solicitação de autorização do sistema. No macOS, você deve declarar NSMicrophoneUsageDescription no Info.plist arquivo do aplicativo.

pararCaptura de Áudio

stopAudioCapture(): number

Fecha o dispositivo de captura de áudio.

muteAudioCapture

muteAudioCapture(mute: boolean): number

Ativa ou desativa a captura de áudio. mute=true mudos, e false ativa o som.

iniciarAudioPlayer

startAudioPlayer(config: AoqAudioPlaybackConfig): number

Inicia a renderização de áudio para reproduzir áudio remoto.

stopAudioPlayer / pauseAudioPlayer / resumeAudioPlayer

stopAudioPlayer(): number
pauseAudioPlayer(fadeMs: number): number
resumeAudioPlayer(fadeMs: number): number

fadeMs: a duração do fade-out ou fade-in, em milissegundos. 0 indica execução imediata.

interromperAudioPlayer

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

Interrompe a sessão de áudio atual e descarta os dados de downlink armazenados em buffer da sessão atual.

Configuração do codec de áudio

setAudioEncoderConfig(config: AoqAudioCodecConfig): number
setAudioDecoderConfig(config: AoqAudioCodecConfig): number

Recomendamos que você chame esse método antes connect(). Para usar o Opus (AoqEncoderTypeAudioOpus), o plug-in PluginOpus deverá ser integrado ao SDK ou distribuído com o pacote.

Gerenciamento de dispositivos de vídeo

startVideoCapture(config: AoqVideoCaptureConfig): number
stopVideoCapture(): number

Abre ou fecha o dispositivo de captura de vídeo. No macOS, você deve declarar NSCameraUsageDescription em Info.plist. Quando config.isExternal=true, a câmera não é aberta e os quadros são entregues por pushExternalVideoCapturedFrame.

O renderizador Electron é um ambiente Chromium e não pode incorporar visualizações nativas, portanto setLocalView / setRemoteView / switchCamera não são fornecidos. Para visualização, use o observador de quadros com YUVCanvasRenderer (consulte Renderização de vídeo).

Codec de vídeo e entrada externa

setVideoEncoderConfig(config: AoqVideoCodecConfig): number
setVideoDecoderConfig(config: AoqVideoCodecConfig): number
pushExternalVideoCapturedFrame(meta: AoqExternalVideoFrameMeta, buffer: Uint8Array): number
pushExternalVideoEncodedFrame(meta: AoqExternalVideoEncodedFrameMeta, buffer: Uint8Array): number

Notas:

• pushExternalVideoCapturedFrame consome quadros de vídeo depois startVideoCapture({ isExternal: true }) e quadros de tela depois startScreenCapture({ isExternal: true }). Ele retorna 211 quando a captura externa não está habilitada e 210 quando o buffer está cheio.
• AoqVideoPixelFormatI420 e formatos compactados (NV12/NV21/BGRA/RGBA) são suportados. Para I420, buffer deve utilizar um layout compacto (passada = largura), com os planos Y/U/V concatenados em ordem.
• pushExternalVideoEncodedFrame requer setVideoEncoderConfig({ isExternal: true }) primeiro. Ele retorna 212 quando não está habilitado. Atualmente, apenas JPEG é compatível.
• Quando meta.timeStamp é 0, o SDK o preenche com a hora local.

Controle de fluxo de mídia

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

trackType suporta AoqTrackTypeAudio, AoqTrackTypeVideoe AoqTrackTypeScreen.

Especifica se um fluxo de mídia local específico deve ser enviado. Recomendamos que você ligue enableSendMediaStream(trackType, false) após a inicialização e habilite o envio somente após onConnectionStatusChange relatórios AoqConnectionStatusConnected.

Reprodução de arquivo de áudio

startAudioFile(config: AoqAudioFileMixConfig): number
stopAudioFile(fileId: string): number
pauseAudioFile(fileId: string): number
resumeAudioFile(fileId: string): number
getAudioFileDuration(fileId: string): number
getAudioFileCurrentPosition(fileId: string): number
setAudioFilePositionMillis(fileId: string, positionMs: number): number
setAudioFileVolume(fileId: string, type: AoqAudioStreamDirection, volume: number): number
getAudioFileVolume(fileId: string, type: AoqAudioStreamDirection): number

Descrição do valor de retorno:

• getAudioFileDuration / getAudioFileCurrentPosition retorne o número de milissegundos;
• getAudioFileVolume retorna o volume atual;
• Os getters acima retornam -1 quando o mecanismo não é criado.

As alterações no estado de reprodução são relatadas através do onAudioFileState evento.

Fluxos de áudio externos

addAudioExternalStream(config: AoqAudioExternalStreamConfig): number
removeAudioExternalStream(streamId: string): number
pushAudioExternalStreamData(meta: AoqAudioExternalFrameMeta, buffer: Uint8Array): number
setAudioExternalStreamVolume(streamId: string, type: AoqAudioStreamDirection, volume: number): number
getAudioExternalStreamVolume(streamId: string, type: AoqAudioStreamDirection): number
clearAudioExternalStreamBuffer(streamId: string, fadeoutMs: number): number

Notas:

• pushAudioExternalStreamData retorna 110 (buffer de áudio externo está cheio) quando a duração do buffer excede maxBufferDuration.
• getAudioExternalStreamVolume retorna o volume atual. Ele retorna -1 quando o mecanismo não é criado.
• clearAudioExternalStreamBuffer não tem valor de retorno no lado nativo e sempre retorna 0 em uma chamada bem-sucedida.

Mensagens em tempo real

sendDataMsg(data: Uint8Array | string): number

Envia uma mensagem de dados em tempo real. Se você passar um string, ele é codificado em UTF-8 em um Buffer internamente antes de ser enviado. As mensagens do par são relatadas através do onDataMsg retorno de chamada do evento.

Retornos de chamada de quadro de áudio

setAudioFrameObserver(enable: boolean): number
enableAudioFrameObserver(params: AoqAudioObserverParams): number

Uso: Primeiro, ligue setAudioFrameObserver(true) para registrar o observador. Então ligue enableAudioFrameObserver para cada posição que você precisa. Os dados são entregues por meio dos eventos correspondentes.

engine.setAudioFrameObserver(true)
engine.enableAudioFrameObserver({
  enabled: true,
  audioSource: AoqAudioSource.AoqAudioSourceCaptured,
  sampleRate: 48000,
  channels: 1
})
engine.on('onCapturedAudioFrame', (frame) => { /* frame.buffer contains PCM data */ })

O observador de quadro no lado do Electron suporta apenas o modo somente leitura e não suporta a gravação de dados do quadro no retorno de chamada (o lado nativo é fixado em ReadOnly).

Indicação de volume local

enableLocalAudioVolumeIndication(config: AoqAudioVolumeIndicationConfig): number

Habilita ou desabilita a indicação do volume de captura local. Se config.interval<= 0, o retorno de chamada será desativado. Depois de habilitado, onLocalAudioVolumeIndication é acionado no intervalo especificado por config.interval. Você deve chamar esse método depois startAudioCapture() para obter dados de volume.

Retornos de chamada de quadro de vídeo

setVideoFrameObserver(enable: boolean): number
enableVideoFrameObserver(params: AoqVideoObserverParams): number

Os dados de retorno de chamada são entregues como AoqVideoFrameEvent através onCapturedVideoFrame / onPreEncodeVideoFrame / onRemoteVideoFrame. Para I420, buffer são os planos Y/U/V concatenados com base na passada. Outros formatos compactados são transmitidos como dados originais. O modo somente leitura também é suportado.

Renderização de vídeo (YUVCanvasRenderer)

O renderizador de software integrado ao SDK. Ele assume as responsabilidades de visualização de setLocalView / setRemoteView em plataformas móveis.

import { YUVCanvasRenderer } from 'aoq-electron-sdk';
class YUVCanvasRenderer {
  bind(canvas: HTMLCanvasElement): void
  unbind(): void
  get bound(): boolean
  drawFrame(frame: AoqVideoFrameEvent): void
}

const renderer = new YUVCanvasRenderer()
renderer.bind(document.getElementById('preview'))
engine.setVideoFrameObserver(true)
engine.enableVideoFrameObserver({
  enabled: true,
  videoSource: AoqVideoSource.AoqVideoSourceCaptured,
  format: AoqVideoPixelFormat.AoqVideoPixelFormatI420
})
engine.on('onCapturedVideoFrame', (frame) => renderer.drawFrame(frame))

Para o modo de preenchimento de renderização (como esticar ou cortar), use o CSS object-fit propriedade para controlar a tela.

Eventos do mecanismo (IAoqEngineEvents)

O motor herda de EventEmitter<IAoqEngineEvents>. Os eventos são a saída unificada para todas as notificações assíncronas do SDK e mapeiam um a um para o nativo AoqEngineEventListener retornos de chamada. Você não precisa registrar os eventos que não lhe interessam.

engine.on('onError', (code, message) => {})
engine.off('onError', handler)
engine.once('onStats', (stats) => {})
engine.removeAllListeners()

onError

onError: (code: number, message: string) => void

Retorno de chamada de erro do mecanismo. code corresponde a um valor AoqErrorCode (consulte AoqErrorCode).

emAviso

onWarning: (code: number, message: string) => void

Retorno de chamada de aviso do motor. code corresponde a um valor AoqWarningCode (consulte AoqWarningCode).

onConnectionStatusChange

onConnectionStatusChange: (status: AoqConnectionStatus) => void

Retorno de chamada de alteração do status da conexão. Transições de estado: Desconectado -> Conectando -> Conectado/Falha -> Desconectado.

nas estatísticas

onStats: (stats: AoqStats) => void

Retorno de chamada de estatísticas do mecanismo. O SDK relata periodicamente estatísticas de publicação e assinatura de áudio e vídeo e estatísticas de rede, que você pode usar para monitorar a qualidade da chamada e o status da rede em tempo real e para diagnosticar problemas de áudio e vídeo.

onAudioDeviceStateChanged

onAudioDeviceStateChanged: (state: AoqAudioDeviceState) => void

Retorno de chamada para captura de dispositivo de áudio e alterações de status de operação de reprodução.

onAudioDeviceRouteAlterado

onAudioDeviceRouteChanged: (routeType: number) => void

Retorno de chamada de alteração da rota de saída de áudio. routeType corresponde a um valor AoqAudioDeviceRouteType (consulte AoqAudioDeviceRouteType).

onAudioFileState

onAudioFileState: (state: AoqAudioFileState) => void

Retorno de chamada para status de reprodução de arquivo de áudio.

onLocalAudioVolumeIndicação

onLocalAudioVolumeIndication: (volume: AoqAudioVolume) => void

Retorno de chamada de indicação de volume de captura local. Para habilitá-lo, ligue enableLocalAudioVolumeIndication.

onVideoDeviceStateChanged

onVideoDeviceStateChanged: (state: AoqVideoDeviceState) => void

Retorno de chamada para alterações no status da operação de captura do dispositivo de vídeo.

onDataMsg

onDataMsg: (data: Uint8Array) => void

Retorno de chamada para uma mensagem de dados em tempo real recebida. data é um Buffer copiado no lado nativo e pode ser mantido de forma assíncrona com segurança. Para mensagens de texto, use Buffer.from(data).toString() para converter os dados em uma string.

Eventos de quadro de áudio

onCapturedAudioFrame:        (frame: AoqAudioFrameEvent) => void  /* raw captured data */
onProcessCapturedAudioFrame: (frame: AoqAudioFrameEvent) => void  /* data after 3A processing */
onPublishAudioFrame:         (frame: AoqAudioFrameEvent) => void  /* publishing data */
onPlaybackAudioFrame:        (frame: AoqAudioFrameEvent) => void  /* playback data */

Você deve primeiro ligar setAudioFrameObserver(true) e enableAudioFrameObserver para habilitá-lo.

Eventos de quadro de vídeo

onCapturedVideoFrame:  (frame: AoqVideoFrameEvent) => void  /* after capture, before preprocessing */
onPreEncodeVideoFrame: (frame: AoqVideoFrameEvent) => void  /* before encoding, after preprocessing */
onRemoteVideoFrame:    (frame: AoqVideoFrameEvent) => void  /* remote, after decoding and before rendering */

Você deve primeiro ligar setVideoFrameObserver(true) e enableVideoFrameObserver para habilitá-lo. Os eventos de quadro são somente leitura. Modificações para buffer no retorno de chamada não são gravados no SDK.

Evite computação pesada em retornos de chamada de eventos: retornos de chamada nativos são despachados para o thread principal JS por meio de um thread assíncrono, e operações demoradas em eventos de quadro de alta frequência causam um backlog.

Tipos de dados e enumerações

Todos os tipos são exportados da raiz do pacote, então você pode usar diretamente import { ... } from 'aoq-electron-sdk'. As enumerações são TypeScript enum tipos e estão disponíveis em tempo de execução, enquanto interfaces (interface) são apenas restrições de tipo. Se um campo marcado como opcional não for especificado, o valor padrão da tabela será usado.

AoqScreenSourceInfo

AoqScreenShareSourceType

AoqScreenCaptureConfig

Todos os campos são opcionais. isExternal o padrão é falso.

Tipos gerais

AoqCreateConfig

O isBTScoMode O campo no Android é apenas para dispositivos móveis e não é fornecido pela Electron.

AoqConnectConfig

| Sim | - | Lista de faixas publicadas localmente |

| inscrever-seFaixas | Matriz
| Sim | - | Lista de faixas locais inscritas |

Ponto final AoqRelay

AoqTrackParam

Tipos de estatísticas

Estatísticas Aoq

Um resumo das estatísticas do motor, que é reportado periodicamente através onStats. Um campo de array é um array vazio quando não possui dados, e networkStats não é entregue quando não possui dados.

 | Publicação de estatísticas para áudio |

| videoPublishStats | Matriz
| Publicação de estatísticas para vídeo | | dataMsgPublishStats | Matriz
| Publicação de estatísticas para mensagens de dados | | áudioSubscribeStats | Matriz
| Assinando estatísticas para áudio | | vídeoSubscribeStats | Matriz
| Inscrever estatísticas para vídeo | | dataMsgSubscribeStats | Matriz
| Assinando estatísticas para mensagens de dados | | estatísticas da rede | AoqNetworkStats | Estatísticas da rede |

AoqAudioPublishStats

AoqAudioSubscribeStats

AoqVideoPublishStats

AoqVideoSubscribeStats

AoqDataMsgPublishStats/AoqDataMsgSubscribeStats

AoqNetworkStats

Enumerações

AoqTrackType

Modo AoqTrack

AoqEncoderType

AoqConnectionStatus

Modo AoqMirror

Modo de Orientação Aoq

AoqErrorCode

Os códigos de erro são definidos na camada nativa. O code parâmetro de onError e os valores de retorno da API usam esses valores (a camada TS não os exporta como um enum).

Além dos códigos de erro nativos acima, a camada Electron retorna -1 quando o mecanismo não foi criado ou foi destruído, ou quando um parâmetro não é JSON válido.

Código de aviso Aoq

Tipos de áudio

AoqAudioCaptureConfig

AoqAudioPlaybackConfig

isVoipMode / isDefaultSpeaker são campos somente móveis e não são fornecidos pela Electron.

AoqAudioCodecConfig

AoqAudioDeviceRouteType

A tabela a seguir lista os valores válidos routeType valores para onAudioDeviceRouteChanged. Esses valores são definidos pela camada nativa e não são exportados como um enum pela camada TypeScript.

AoqAudioDeviceStateCode

AoqAudioDeviceState

Tipos de arquivos de áudio

AoqAudioFileMixConfig

AoqAudioFileStateCode

AoqAudioFileErrorCode

A tabela a seguir lista os valores válidos AoqAudioFileState.errorCode valores. Esses valores são definidos pela camada nativa e são entregues como number valores pela camada TypeScript.

AoqAudioFileState

Tipos de fluxo de áudio externo

AoqAudioStreamDirection

AoqAudioExternalStreamConfig

AoqAudioExternalFrameMeta

Metadados de um quadro de áudio externo. Os dados PCM são passados separadamente através do buffer parâmetro.

Evento AoqAudioFrame

Dados de evento do observador de quadro de áudio.

AoqAudioSource

AoqAudioObserverParams

O modo de retorno de chamada é fixado como somente leitura. Electron não fornece modo de leitura e gravação.

AoqAudioVolumeIndicaçãoConfig

AoqAudioVolume

Tipos de vídeo

AoqVideoCaptureConfig

cameraDirection é um campo apenas para dispositivos móveis e não existe em plataformas de desktop.

AoqVideoCodecConfig

A codificação e a decodificação compartilham a mesma estrutura (setVideoEncoderConfig / setVideoDecoderConfig).

AoqVideoPixelFormat

Formatos de pixel suportados no lado Electron (excluindo os formatos de textura/CVPixelBuffer em plataformas móveis).

AoqExternalVideoFrameMeta

Metadados de um quadro de vídeo bruto externo. Os dados de pixel são passados separadamente através do buffer parâmetro.

Quando format = I420, buffer deve utilizar um layout compacto (passada = largura), com os planos Y/U/V concatenados em ordem. Para outros formatos compactados, passe diretamente os bytes inteiros do quadro.

AoqVideoCodecType

AoqExternalVideoEncodedFrameMeta

Metadados de um quadro de vídeo codificado externamente. Os dados codificados são passados separadamente através do buffer parâmetro.

AoqVideoDeviceStateCode

AoqVideoDeviceState

Tipos de retorno de chamada de quadro de vídeo

AoqVideoFonte

Alinhamento AoqVideoObserver

AoqVideoObserverParams

O modo de retorno de chamada é fixado como somente leitura. Electron não fornece modo de leitura e gravação. Selecione I420 ao usar o integrado YUVCanvasRenderer para renderização.

AoqVideoFrameEvent

Dados de evento do observador de quadro de vídeo.

Tipos de mensagens de dados

O elétron não usa o AoqDataMsg tipo de invólucro. As mensagens de dados são enviadas e recebidas diretamente como dados binários: