SDK Linux C++

Referência da API C++ do SDK do cliente AOQ Linux

índice API

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

Retornos de chamada AoqEngineEventListener

Interfaces de ouvinte de dados de quadro

Detalhes da API

Captura de tela

virtual int startScreenCapture(const AoqScreenCaptureConfig& config);
virtual int stopScreenCapture();

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. Esses métodos retornam de forma síncrona e não fornecem um onScreenCaptureStateChanged retorno de chamada.

O Linux suporta apenas entrada externa de quadros brutos. Definir isExternal=true. A captura de tela interna e a enumeração de origem não são suportadas; sourceId e sourceType não existem na configuração do Linux.

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.

Ciclo de vida do motor

criarEngine

Cria a instância do mecanismo. O SDK mantém o mecanismo como um singleton global, portanto, chamar esse método novamente retorna a instância existente.

static AoqClientEngine* createEngine(const AoqCreateConfig& config,
                                    AoqEngineEventListener* listener);

Retorna: um ponteiro para a instância do mecanismo. nullptr é retornado em caso de falha. O ciclo de vida do ouvinte deve durar mais que o do mecanismo.

destruir

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

static int destroy();

Retorna: 0 indica sucesso; um não-0 valor indica uma falha.

obter versão

Obtém a versão atual do SDK.

static const char* getVersion();

Retorna: a string da versão, que é mantida pelo SDK.

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. Para obter mais informações, consulte Autenticação de token.

virtual int connect(const AoqConnectConfig& config);

Retorna: 0 indica sucesso e a operação é executada de forma assíncrona; não-0 indica uma falha. O resultado da conexão é notificado por onConnectionStatusChange.

relayEndpoints/publishTracks/subscribeTracks são todas estruturas de "ponteiro de matriz estilo C + comprimento". A memória é mantida pelo chamador e só precisa ser válida durante a chamada de conexão.

desconectar

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

virtual int disconnect();

Retorna: 0 indica sucesso; um não-0 valor indica uma falha.

Gerenciamento de dispositivos de áudio

virtual int startAudioCapture(const AoqAudioCaptureConfig& config);
virtual int stopAudioCapture();
virtual int muteAudioCapture(bool mute);
virtual int startAudioPlayer(const AoqAudioPlaybackConfig& config);
virtual int stopAudioPlayer();
virtual int pauseAudioPlayer(int fadeMs);
virtual int resumeAudioPlayer(int fadeMs);
virtual int interruptAudioPlayer(AoqTrackType trackType, int fadeMs);

Restrição importante no Linux: startAudioCapture/startAudioPlayer têm implementações vazias na compilação do Linux (eles retornam 0 diretamente e não abra nenhum dispositivo de placa de som), e stopAudioCapture/stopAudioPlayer não têm efeito real porque o estado interno não está definido. No Linux, use fluxos de áudio externos (2.8) para entrada de áudio e use retornos de chamada de quadro de áudio (2.10) para reproduzir você mesmo a saída de áudio. Para obter mais informações, consulte 4.3.

Configuração do codec de áudio

virtual int setAudioEncoderConfig(const AoqAudioCodecConfig& config);
virtual int setAudioDecoderConfig(const AoqAudioCodecConfig& config);

Recomendamos que você chame esse método antes connect(). Uma combinação inválida da taxa de amostragem e do modo aciona o onError retorno de chamada com AoqECParamInvalid durante a conexão.

Gerenciamento de dispositivos de vídeo

virtual int startVideoCapture(const AoqVideoCaptureConfig& config);
virtual int stopVideoCapture();
virtual int setLocalView(AoqTrackType trackType, const AoqVideoCanvas& canvas);
virtual int setRemoteView(AoqTrackType trackType, const AoqVideoCanvas& canvas);

Restrição importante no Linux: A captura de câmera no Linux é uma implementação de espaço reservado e não produz quadros. Usar startVideoCapture({.isExternal = true}) + pushExternalVideoCapturedFrame para entregar quadros. setLocalView/setRemoteView não tem back-end de renderização no Linux (AoqVideoCanvas.view suporta apenas visualizações de renderização Apple NSView* / Windows HWND / Android). Para visualização, renderize você mesmo por meio do retorno de chamada do quadro de vídeo (2.12). Para obter mais informações, consulte 4.3.

Codec de vídeo e entrada externa

virtual int setVideoEncoderConfig(const AoqVideoCodecConfig& config);
virtual int setVideoDecoderConfig(const AoqVideoCodecConfig& config);
virtual int pushExternalVideoCapturedFrame(AoqTrackType trackType, const AoqVideoFrame& frame);
virtual int pushExternalVideoEncodedFrame(AoqTrackType trackType, const AoqVideoEncodedFrame& frame);

Notas:

• setVideoDecoderConfig é uma proposta de codec para o assinante e deve ser chamada antes connect. Durante a decodificação, apenas trackType/codecType/width/height/fps/bitrate entrar em vigor.
• pushExternalVideoCapturedFrame requer startVideoCapture(isExternal=true) para vídeo ou startScreenCapture(isExternal=true) para Tela primeiro. Ele retorna AoqECVideoExternalCaptureNotEnabled(211) quando a captura externa não é iniciada, AoqECParamInvalid quando o formato não é suportado, e AoqECVideoExternalBufferFull(210) quando o buffer está cheio.
• pushExternalVideoEncodedFrame requer setVideoEncoderConfig(isExternal=true) primeiro. O SDK empacota e envia o quadro diretamente, sem recodificação. Atualmente, apenas JPEG é compatível.
• Quando frame.timeStamp é 0, o SDK o preenche com a hora local.

Controle de fluxo de mídia

virtual int enableSendMediaStream(AoqTrackType trackType, bool enable);

Especifica se um fluxo de mídia local específico deve ser enviado. trackType pode ser AoqTrackTypeAudio ou AoqTrackTypeVideo ou AoqTrackTypeScreen. Um valor de retorno de 0 indica que a chamada é despachada e executada de forma assíncrona. Recomendamos que você desative o envio após a inicialização e ative-o somente após onConnectionStatusChange relatórios AoqConnectionStatusConnected.

Reprodução de arquivo de áudio

virtual int startAudioFile(const char* fileId, const AoqAudioFileMixConfig& config);
virtual int stopAudioFile(const char* fileId);
virtual int pauseAudioFile(const char* fileId);
virtual int resumeAudioFile(const char* fileId);
virtual int64_t getAudioFileDuration(const char* fileId);
virtual int64_t getAudioFileCurrentPosition(const char* fileId);
virtual int setAudioFilePositionMillis(const char* fileId, int64_t positionMillis);
virtual int setAudioFileVolume(const char* fileId, AoqAudioStreamDirection type, int volume);
virtual int getAudioFileVolume(const char* fileId, AoqAudioStreamDirection type);

Descrição do valor de retorno:

• getAudioFileDuration/getAudioFileCurrentPosition: Um valor >=0 é o valor em milissegundos; um valor <0 indica uma falha e seu valor absoluto é -AoqErrorCode.
• getAudioFileVolume: Um valor de 0-100 é o volume; um valor <0 indica uma falha e seu valor absoluto é -AoqErrorCode.

As alterações no estado de reprodução são relatadas através do onAudioFileState retorno de chamada. A mixagem de arquivos usa o caminho de publicação e não depende da placa de som local. Portanto, no Linux, você pode usá-lo para enviar um arquivo local como fonte de áudio.

Fluxos de áudio externos

virtual int addAudioExternalStream(const char* streamId, const AoqAudioExternalStreamConfig& config);
virtual int pushAudioExternalStreamData(const char* streamId, AoqAudioFrameData& data);
virtual int setAudioExternalStreamVolume(const char* streamId, AoqAudioStreamDirection type, int vol);
virtual int getAudioExternalStreamVolume(const char* streamId, AoqAudioStreamDirection type);
virtual void clearAudioExternalStreamBuffer(const char* streamId, int fadeoutMs);
virtual int removeAudioExternalStream(const char* streamId);

Notas:

• Quando pushAudioExternalStreamData retorna AoqECAudioExternalBufferFull(110), o buffer interno do SDK estará cheio. Recomendamos que você espere 20 ms e depois envie o quadro de dados atual novamente.

• Prática recomendada: em cenários de captura em tempo real, envie 10 ms de dados por vez e envie sempre que os dados estiverem disponíveis. Em cenários de origem de arquivo, envie 40 ms de dados por vez em intervalos de 30 ms e lide com o AoqECAudioExternalBufferFull valor de retorno.

• getAudioExternalStreamVolume: Um valor de 0-100 é o volume; um valor <0 indica uma falha e seu valor absoluto é -AoqErrorCode.

• clearAudioExternalStreamBuffer retorna void e não tem valor de retorno.

• data.pushSequence é usado para notificação de conclusão de consumo do SDK (rodada de entrada PCM).

  Não existe um dispositivo de captura real no Linux. Este grupo de APIs é o caminho principal para o uplink de áudio.

Mensagens em tempo real

virtual int sendDataMsg(const AoqDataMsg& msg);

Envia uma mensagem de dados em tempo real. msg.data aponta para a memória mantida pelo chamador e só precisa ser válido durante a chamada. As mensagens do par são relatadas através do onDataMsg retorno de chamada.

Retornos de chamada de quadro de áudio

virtual int setAudioFrameObserver(IAudioFrameObserver* observer) = 0;
virtual int enableAudioFrameObserver(bool enabled, AoqAudioSource audioSource,
                                     const AoqAudioObserverConfig& config) = 0;

Uso: Primeiro, ligue setAudioFrameObserver(observer) para registrar o ouvinte. Então ligue enableAudioFrameObserver para cada posição que você precisa. O ciclo de vida do observador deve cobrir todo o período de retorno de chamada. Libere o observador somente depois de cancelar seu registro.

Suporte ao modo leitura-gravação (consulte a declaração IAudioFrameObserver): onCapturedAudioFrame/onProcessCapturedAudioFrame/onPlaybackAudioFrame suporta o modo leitura-gravação, enquanto onPublishAudioFrame suporta apenas o modo somente leitura.

No Linux, setAudioFrameObserver completa o registro por meio de envio assíncrono (PostTask para o thread de controle), portanto, o retorno de chamada pode entrar em vigor um pouco após o retorno da chamada. Antes de liberar o observador, deixe um intervalo de segurança suficiente ou mantenha o objeto vivo.

Indicação de volume local

virtual int enableLocalAudioVolumeIndication(const AoqAudioVolumeIndicationConfig& config);

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.

Não há captura de dispositivo no Linux. Os dados de volume neste retorno de chamada vêm do caminho de mixagem de publicação/reprodução (mixer).

Retornos de chamada de quadro de vídeo

virtual int setVideoFrameObserver(IVideoFrameObserver* observer) = 0;
virtual int enableVideoFrameObserver(bool enabled, AoqVideoSource videoSource,
                                     const AoqVideoObserverConfig& config) = 0;

Se o retorno de chamada retornar true, os dados serão modificados e deverão ser gravados novamente no SDK. Isso entra em vigor apenas para I420/CVPixelBuffer, o que significa apenas I420 no Linux. Se o retorno de chamada retornar false, os dados serão somente leitura.

O Linux não possui renderização integrada. Este grupo de retornos de chamada é a única maneira de obter a imagem de vídeo remota (AoqVideoSourceRemote).

Retornos de chamada AoqEngineEventListener

AoqEngineEventListener é o ponto de entrada unificado para todas as notificações de eventos assíncronos do SDK. Você o herda e implementa e depois o transmite quando liga createEngine.

Principais diferenças do Android: todos os retornos de chamada nesta classe são funções virtuais puras (= 0) sem implementação vazia padrão. No Linux, você deve implementar totalmente os 10 métodos a seguir; caso contrário, a classe derivada não poderá ser instanciada. Os retornos de chamada podem ser acionados em threads internos do SDK.

class AOQ_API AoqEngineEventListener {
public:
  AoqEngineEventListener();
  virtual ~AoqEngineEventListener();
  virtual void onError(int code, const char* message) = 0;
  virtual void onWarning(int code, const char* message) = 0;
  virtual void onConnectionStatusChange(AoqConnectionStatus status) = 0;
  virtual void onStats(const AoqStats& stats) = 0;
  virtual void onAudioDeviceStateChanged(const AoqAudioDeviceState& state) = 0;
  virtual void onAudioDeviceRouteChanged(int routeType) = 0;
  virtual void onAudioFileState(const AoqAudioFileState& state) = 0;
  virtual void onLocalAudioVolumeIndication(const AoqAudioVolume& volume) = 0;
  virtual void onVideoDeviceStateChanged(const AoqVideoDeviceState& state) = 0;
  virtual void onDataMsg(const AoqDataMsg& msg) = 0;
};

onError

Retorno de chamada de erro do mecanismo. code corresponde a um AoqErrorCode valor enum (ver 3.3), e message é válido apenas durante o retorno de chamada.

emAviso

Retorno de chamada de aviso do motor. code corresponde a um AoqWarningCode valor enum (ver 3.3).

onConnectionStatusChange

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

nas estatísticas

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.

AoqStats usa internamente uma estrutura "ponteiro de matriz + contagem". O ponteiro é válido apenas durante o retorno de chamada, portanto, você mesmo deve copiar os dados para uso assíncrono.

onAudioDeviceStateChanged

Retorno de chamada para captura de dispositivo de áudio e alterações de status de operação de reprodução. state.reason é um AoqErrorCode valor.

onAudioDeviceRouteAlterado

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

Não acionado no Linux: a compilação do Linux não inclui o ouvinte de dispositivo de plataforma (AOQ_HAS_NATIVE_DEVICE_MONITOR é definido apenas no Windows/macOS) e os dispositivos de áudio do lado do servidor não geram eventos de rota. Você ainda deve implementar este método (virtual puro), mas a implementação pode estar vazia.

onAudioFileState

Retorno de chamada para status de reprodução de arquivo de áudio. state.fileId é válido apenas durante o retorno de chamada.

onLocalAudioVolumeIndicação

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

onVideoDeviceStateChanged

Retorno de chamada para alterações no status da operação de captura do dispositivo de vídeo. state.reason é um AoqErrorCode valor.

onDataMsg

Retorno de chamada para uma mensagem de dados em tempo real recebida. msg.data é garantido que será válido apenas durante o retorno de chamada. Se precisar usá-lo de forma assíncrona, copie você mesmo.

Interfaces de ouvinte de dados de quadro

IAudioFrameObserver

Interface para escuta de dados de áudio. Não execute nenhuma operação demorada nos retornos de chamada. Caso contrário, poderão ocorrer anomalias de áudio. Todos os métodos são funções virtuais puras e devem ser totalmente implementados.

class AOQ_API IAudioFrameObserver {
public:
  virtual ~IAudioFrameObserver() {}
  virtual void onCapturedAudioFrame(const AoqAudioFrameData& data) = 0;
  virtual void onProcessCapturedAudioFrame(const AoqAudioFrameData& data) = 0;
  virtual void onPublishAudioFrame(AoqTrackType trackType, const AoqAudioFrameData& data) = 0;
  virtual void onPlaybackAudioFrame(const AoqAudioFrameData& data) = 0;
};

Todos os retornos de chamada anteriores suportam a configuração da taxa de amostragem e do número de canais usando AoqAudioObserverConfig.

No Linux, onPlaybackAudioFrame é o principal caminho para obtenção do PCM de downlink remoto. Como o módulo 3A não é compilado no Linux, os dados do onProcessCapturedAudioFrame (dados após processamento 3A) são essencialmente iguais aos dados brutos capturados. Para obter mais informações, consulte 4.3.

IVideoFrameObservador

Interface para escuta de dados de vídeo. Não execute nenhuma operação demorada nos retornos de chamada. Caso contrário, poderão ocorrer interrupções no vídeo. Todos os métodos são funções virtuais puras.

class AOQ_API IVideoFrameObserver {
public:
  virtual ~IVideoFrameObserver() {}
  virtual bool onCapturedVideoFrame(AoqTrackType trackType, AoqVideoFrame& frame) = 0;
  virtual bool onPreEncodeVideoFrame(AoqTrackType trackType, AoqVideoFrame& frame) = 0;
  virtual bool onRemoteVideoFrame(AoqTrackType trackType, AoqVideoFrame& frame) = 0;
};

Retorna: true indica que os dados foram modificados e devem ser gravados novamente no SDK, que entra em vigor apenas para I420/CVPixelBuffer; false indica somente leitura. Os ponteiros em frame são válidos apenas durante o retorno de chamada. Para usá-los de forma assíncrona, copie-os você mesmo.

Tipos de dados e enumerações

AoqScreenCaptureStateCode

Enumeração do estado de captura de tela. O tipo está definido, mas o SDK atual não fornece um retorno de chamada de estado correspondente.

AoqScreenCaptureState

AoqScreenCaptureConfig

Todos os tipos são definidos em AoqClientEngine.h no AoqClientSdk espaço para nome. Todas as estruturas são tipos POD com valores padrão, então você obtém os valores padrão na tabela simplesmente declarando-os. Os campos marcados como apenas móveis são excluídos pela compilação condicional no Linux e não existem nas estruturas.

Tipos gerais

AoqCreateConfig

Os campos de string devem permanecer válidos pelo menos até createEngine retorna. O mecanismo os copia internamente conforme necessário. O isBTScoMode field no Android é apenas móvel e não existe no Linux.

AoqConnectConfig

Ponto final AoqRelay

Observe que o nome do campo route_index usa caixa de cobra, ao contrário da caixa de camelo usada pelos outros campos.

AoqTrackParam

AoqDataMsg

Quando os dados são usados ​​em um retorno de chamada, é garantido que eles serão válidos apenas durante o retorno de chamada. Para uso assíncrono, copie você mesmo os dados.

Tipos de estatísticas

Estatísticas Aoq

Um resumo das estatísticas do motor, que é reportado periodicamente através onStats. Ele usa uma estrutura de "ponteiro de array + contagem", na qual todos os ponteiros são padronizados para nullptr e todas as contagens são padronizadas para 0.

AoqAudioPublishStats

AoqAudioSubscribeStats

AoqVideoPublishStats

AoqVideoSubscribeStats

AoqDataMsgPublishStats/AoqDataMsgSubscribeStats

AoqNetworkStats

Enumerações

AoqTrackType

Modo AoqTrack

AoqEncoderType

AoqConnectionStatus

AoqErrorCode

Nota de nomenclatura: em cabeçalhos C++, os literais enum usam a abreviação AoqEC* formulário (ao contrário do completo AoqErrorCode* formulário no Android), mas os valores são idênticos.

Código de aviso Aoq

Modo AoqMirror

Modo de Orientação Aoq

Modo AoqRender

Isso é usado apenas como AoqVideoCanvas.renderMode. O Linux não tem implementação de renderização, portanto esta enumeração não entra em vigor.

AoqAudioStreamDirection

AoqAudioExternalStreamToggle

Esta enumeração é declarada no cabeçalho, mas nenhuma API pública a utiliza atualmente. É uma definição reservada.

Tipos de áudio

AoqAudioCaptureConfig

isVoipMode é um campo somente móvel e não existe no Linux.

AoqAudioPlaybackConfig

isVoipMode/isDefaultSpeaker são campos somente móveis e não existem no Linux.

AoqAudioCodecConfig

Restrições de taxa de amostragem (extraídas dos comentários no arquivo de cabeçalho):

• Codificação: Opus suporta 8/16/48K e PCM suporta 8/16/32/48K;
• Decodificação: 24K é suportado adicionalmente, mas 24K é limitado ao modo Segmento (o modo Stream não suporta 24K);
• Uma combinação inválida aciona o onError retorno de chamada com AoqECParamInvalid durante connect.

AoqAudioDeviceRouteType

Esta é apenas uma referência para o routeType valores de onAudioDeviceRouteChanged. O Linux não aciona esse retorno de chamada.

AoqAudioDeviceStateCode

AoqAudioDeviceState

AoqAudioFrameData

Dados de áudio brutos. É usado tanto para alimentação de fluxo externo através de pushAudioExternalStreamData e o IAudioFrameObserver retorno de chamada.

AoqAudioSource

Modo AoqAudioObserver

AoqAudioObserverConfig

Taxas de amostragem suportadas: 8, 12, 16, 24, 32, 44,1, 48, 64, 88,2, 96, 176,4 e 192K.

AoqAudioVolumeIndicaçãoConfig

AoqAudioVolume

Arquivo de áudio e tipos de fluxo de áudio externo

AoqAudioFileMixConfig

fileId não faz parte do corpo da configuração e é passado como um parâmetro separado para startAudioFile.

AoqAudioFileStateCode

AoqAudioFileErrorCode

AoqAudioFileState

AoqAudioExternalStreamConfig

Taxas de amostragem suportadas: 8, 12, 16, 24, 32, 44,1, 48, 64, 88,2, 96, 176,4 e 192K.

streamId não faz parte do corpo da configuração e é passado como um parâmetro separado para addAudioExternalStream.

Tipos de vídeo

AoqVideoCanvas

Significados da plataforma de view: NSView* na Apple, HWND no Windows e o objeto adaptador de visualização de renderização interna do SDK no Android. Você deve garantir que o ciclo de vida do view é mais longo do que o período durante o qual é definido pelo setLocalView/setRemoteView.

Nenhuma implementação de plataforma correspondente no Linux. Esta estrutura não tem uso prático no Linux.

AoqVideoCaptureConfig

cameraDirection é um campo apenas para dispositivos móveis e não existe em plataformas de desktop (incluindo Linux). No Linux, recomendamos que você sempre defina isExternal = true.

AoqVideoCodecConfig

A codificação e a decodificação compartilham a mesma estrutura. Para decodificação, apenas trackType/codecType/width/height/fps/bitrate entrar em vigor e participar da negociação como proposta de subscrição. minBitrate/keyframeInterval/mirrorMode/orientationMode/isExternal são usados ​​apenas para codificação.

AoqVideoPixelFormat

Os valores enum 6/7/8 ainda são visíveis no arquivo de cabeçalho (eles não são excluídos pela compilação condicional), mas o Linux não possui a capacidade de plataforma correspondente. Se você passá-los, eles serão tratados como formatos não suportados.

AoqVideoFrame

Um quadro de vídeo bruto externo. É usado para ambos pushExternalVideoCapturedFrame e o IVideoFrameObserver retorno de chamada.

AoqVideoCodecType

AoqVideoEncodedFrame

Um quadro de vídeo codificado externamente. O chamador executa a codificação e o SDK empacota e envia o quadro diretamente, sem recodificação.

AoqVideoDeviceStateCode

AoqVideoDeviceState

AoqVideoFonte

Modo AoqVideoObserver

Alinhamento AoqVideoObserver

AoqVideoObserverConfig