O AOQ Client SDK oferece recursos abrangentes de vídeo, incluindo captura, renderização, configuração de codec, callbacks de dados de quadros e entrada externa de vídeo. Este documento apresenta os recursos de vídeo mais comuns para Android (Java), iOS (Objective-C) e HarmonyOS (ArkTS).
1. Captura de vídeo
1,1 Visão geral
A captura de vídeo ativa a câmera do dispositivo e envia quadros 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 a câmera: abertura, captura de quadros e fechamento. Permite alternar entre as câmeras frontal e traseira.
- Captura externa: A aplicação gerencia a câmera ou outra source de vídeo. Os quadros capturados são enviados ao SDK por meio de
pushExternalVideoCapturedFrame.
1,2 Parâmetros de configuração de captura
Parâmetro | Tipo | Padrão | Descrição |
|---|---|---|---|
width | int | 1280 | Largura da captura em pixels. Não se aplica ao modo de captura externa. |
height | int | 720 | Altura da captura em pixels. Não se aplica ao modo de captura externa. |
fps | int | 15 | Taxa de quadros da captura. No modo de captura externa, a taxa depende da velocidade de envio dos quadros. |
isExternal | bool | false | Defina se o modo de captura externa deve ser usado. |
cameraDirection | AoqCameraDirection | Front(0) | Direção da câmera. Não se aplica ao modo de captura externa. |
1,3 Enumeração de direção da câmera
Valor do enum | Número | Descrição |
|---|---|---|
AoqCameraDirectionFront | 0 | Câmera frontal |
AoqCameraDirectionBack | 1 | Câmera traseira |
1,4 Referência da API
Função | Android | iOS | HarmonyOS |
|---|---|---|---|
Iniciar captura | startVideoCapture(config) | startVideoCapture:config: | startVideoCapture(config) |
Parar captura | stopVideoCapture() | stopVideoCapture | stopVideoCapture() |
Alternar câmera | switchCamera(direction) | switchCamera: | switchCamera(direction) |
1,5 Exemplo
AndroidAoqVideoCaptureConfig config = new AoqVideoCaptureConfig();
config.width = 1280;
config.height = 720;
config.fps = 15;
config.cameraDirection = AoqCameraDirection.AoqCameraDirectionFront;
engine.startVideoCapture(config);
AoqVideoCaptureConfig *config = [[AoqVideoCaptureConfig alloc] init];
config.width = 1280;
config.height = 720;
config.fps = 15;
config.cameraDirection = AoqCameraDirectionFront;
[engine startVideoCapture:config];
let config: AoqVideoCaptureConfig = {
width: 1280,
height: 720,
fps: 15,
cameraDirection: AoqCameraDirection.AoqCameraDirectionFront
};
engine.startVideoCapture(config);
2. Renderização de vídeo
2,1 Visão geral
A renderização de vídeo exibe na tela os quadros capturados localmente ou recebidos remotamente. O SDK permite definir uma janela de pré-visualização local e uma janela de renderização remota. Utilize trackType para diferenciar o fluxo de vídeo (Video) do fluxo de compartilhamento de tela (Screen).
2,2 Modos de renderização
Valor do enum | Número | Descrição |
|---|---|---|
AoqRenderModeAuto | 0 | Modo automático |
AoqRenderModeStretch | 1 | Estica para preencher. A imagem pode ficar distorcida. |
AoqRenderModeFill | 2 | Ajusta com letterboxing. Exibe a imagem inteira. |
AoqRenderModeCrop | 3 | Modo de corte. Partes da imagem podem ser removidas. |
2,3 Configuração do canvas
Parâmetro | Tipo | Padrão | Descrição |
|---|---|---|---|
view | View da plataforma | null | Visualize de renderização. Android: SurfaceView ou TextureView. iOS: UIView. HarmonyOS: XComponent. |
renderMode | AoqRenderMode | Auto(0) | Modo de exibição da renderização |
2,4 Referência da API
Função | Android | iOS | HarmonyOS |
|---|---|---|---|
Definir pré-visualização local | setLocalView(trackType, canvas) | setLocalView:trackType:canvas: | setLocalView(trackType, canvas) |
Definir visualize remota | setRemoteView(trackType, canvas) | setRemoteView:trackType:canvas: | setRemoteView(trackType, canvas) |
ObservaçãoDiferenças entre plataformas: O Android utiliza SurfaceView ou TextureView como contêiner de renderização. O iOS usa UIView (encapsulado internamente pelo AoqRenderView com aceleração Metal). O HarmonyOS emprega o XComponent (gerenciado pelo AoqXComponentController para renderização nativa).
3. Configuração de codec de vídeo
3,1 Visão geral
Configure os parâmetros de codificação de vídeo, incluindo formato, resolução, taxa de quadros, bitrate, intervalo de keyframes, espelhamento e orientação. Use trackType para aplicar configurações de codificação distintas à faixa de vídeo e à faixa de compartilhamento de tela.
3,2 Parâmetros de configuração de codificação
Parâmetro | Tipo | Padrão | Descrição |
|---|---|---|---|
trackType | AoqTrackType | Video(1) | Tipo de faixa: Video |
codecType | AoqEncoderType | VideoH264(3) | Formato de codificação |
width | int | 720 | Largura codificada |
height | int | 1280 | Altura codificada |
fps | int | 5 | Taxa de quadros de codificação |
bitrate | int | 500000 | Bitrate alvo (bps) |
minBitrate | int | 128000 | Bitrate mínimo (bps) |
keyframeInterval | int | 2 | Intervalo de keyframes (segundos) |
mirrorMode | AoqMirrorMode | Disabled(0) | Modo de espelhamento |
orientationMode | AoqOrientationMode | Auto(0) | Modo de orientação |
isExternal | bool | false | Modo de codificação externa. Quando verdadeiro, a aplicação envia quadros pré-codificados. |
3,3 Enumeração de formato de codificação
Valor do enum | Número | Descrição |
|---|---|---|
AoqEncoderTypeVideoH264 | 3 | Codificação H.264 |
AoqEncoderTypeVideoJpeg | 4 | Codificação JPEG (para quadros codificados externamente) |
3,4 Modo de espelhamento
Valor do enum | Número | Descrição |
|---|---|---|
AoqMirrorModeDisabled | 0 | Espelhamento desativado |
AoqMirrorModeEnabled | 1 | Espelhamento ativado |
3,5 Modo de orientação
Valor do enum | Número | Descrição |
|---|---|---|
AoqOrientationModeAuto | 0 | Orientação automática |
AoqOrientationModePortrait | 1 | Orientação retrato |
AoqOrientationModeLandscape | 2 | Orientação paisagem |
3,6 Referência da API
Função | Android | iOS | HarmonyOS |
|---|---|---|---|
Definir configuração de codificação | setVideoEncoderConfig(config) | setVideoEncoderConfig: | setVideoEncoderConfig(config) |
4. Entrada externa de quadros de vídeo
4,1 Visão geral
A entrada externa de quadros de vídeo permite que sua aplicação envie dados personalizados de quadros para o SDK, atendendo a cenários de captura ou codificação externa. Dois métodos de envio são suportados:
- Enviar quadros brutos: Envia dados de pixels não codificados (I420, NV12, NV21, BGRA, RGBA e formatos similares) para o SDK. O próprio SDK codifica os dados.
- Enviar quadros codificados: Envia dados já codificados (por exemplo, JPEG) diretamente ao SDK. O SDK empacota e transmite o conteúdo sem recodificar.
O roteamento é controlado por trackType: AoqTrackTypeVideo direciona para a faixa de captura de vídeo; AoqTrackTypeScreen direciona para a faixa de compartilhamento de tela.
4,2 Enumeração de formato de pixel
Valor do enum | Número | Descrição | Suporte de plataforma |
|---|---|---|---|
AoqVideoPixelFormatI420 | 1 | I420 tri-planar | Todas as plataformas |
AoqVideoPixelFormatNV12 | 2 | NV12 bi-planar | Todas as plataformas |
AoqVideoPixelFormatNV21 | 3 | NV21 bi-planar | Todas as plataformas |
AoqVideoPixelFormatBGRA | 4 | BGRA compactado | Todas as plataformas |
AoqVideoPixelFormatRGBA | 5 | RGBA compactado | Todas as plataformas |
AoqVideoPixelFormatCVPixelBuffer | 6 | Zero-copy Apple | Apenas iOS |
AoqVideoPixelFormatTextureOES | 7 | Textura OES | Apenas Android |
AoqVideoPixelFormatTexture2D | 8 | Textura 2D | Apenas Android |
4,3 Estrutura de dados de quadro de vídeo bruto (AoqVideoFrame)
Campo | Tipo | Descrição |
|---|---|---|
format | AoqVideoPixelFormat | Formato de pixel |
width | int | Largura em pixels |
height | int | Altura em pixels |
data | byte[] / ArrayBuffer | Dados em formato compactado (NV12/NV21/BGRA/RGBA) |
dataY / dataU / dataV | byte[] / ArrayBuffer | Dados tri-planares I420 |
strideY / strideU / strideV | int | Strides tri-planares I420 |
textureId | int | ID da textura (válido para TextureOES/Texture2D no Android) |
transformMatrix | float[16] | Matriz de transformação de textura 4×4 (Android) |
eglContext | EGLContext | Contexto EGL compartilhado (Android) |
pixelBuffer | CVPixelBufferRef | Zero-copy Apple (iOS) |
timeStamp | long | Timestamp em ms. Se for 0, o SDK utiliza o relógio local. |
4,4 Estrutura de dados de quadro de vídeo codificado (AoqVideoEncodedFrame)
Campo | Tipo | Padrão | Descrição |
|---|---|---|---|
codec | AoqVideoCodecType | JPEG(0) | Formato de codificação |
data | byte[] / ArrayBuffer | - | Dados codificados |
width | int | - | Largura em pixels |
height | int | - | Altura em pixels |
timeStamp | long | 0 | Timestamp em ms |
4,5 Referência da API
Função | Android | iOS | HarmonyOS |
|---|---|---|---|
Enviar quadro bruto | pushExternalVideoCapturedFrame(trackType, frame) | pushExternalVideoCapturedFrame:frame: | pushExternalVideoCapturedFrame(trackType, frame) |
Enviar quadro codificado | pushExternalVideoEncodedFrame(trackType, frame) | pushExternalVideoEncodedFrame:frame: | pushExternalVideoEncodedFrame(trackType, frame) |
5. Callbacks de quadros de vídeo
5,1 Visão geral
Os callbacks de quadros de vídeo permitem obter dados brutos em diferentes pontos do pipeline para análise de vídeo, processamento personalizado, gravação e outros cenários. Tanto o modo somente leitura quanto o modo leitura-escrita são suportados. No modo leitura-escrita, é possível modifique os dados do quadro e devolvê-los ao SDK.
5,2 Posições de source de dados suportadas
Source de dados | Valor do enum | Descrição |
|---|---|---|
Captured | 0 | Dados de vídeo após a captura, antes do pré-processamento |
PreEncode | 1 | Dados de vídeo antes da codificação, após o pré-processamento |
Remote | 2 | Dados de vídeo remoto após decodificação, antes da renderização |
5,3 Parâmetros de configuração de callback
Parâmetro | Tipo | Padrão | Descrição |
|---|---|---|---|
format | AoqVideoPixelFormat | I420(1) | Formato de pixel para os dados do callback |
alignment | AoqVideoObserverAlignment | Default(0) | Política de alinhamento de largura |
mode | AoqVideoObserverMode | ReadOnly(0) | Modo somente leitura (0) ou leitura-escrita (1) |
mirrorApplied | bool | false | Defina se o espelhamento deve ser aplicado aos dados do callback |
5,4 Enumeração de alinhamento de largura
Valor do enum | Número | Descrição |
|---|---|---|
AoqVideoObserverAlignmentDefault | 0 | Alinhamento padrão |
AoqVideoObserverAlignmentEven | 1 | Alinhamento de 2 bytes |
AoqVideoObserverAlignment4 | 2 | Alinhamento de 4 bytes |
AoqVideoObserverAlignment8 | 3 | Alinhamento de 8 bytes |
AoqVideoObserverAlignment16 | 4 | Alinhamento de 16 bytes |
5,5 Etapas de uso
- Registre o observer: Chame
setVideoFrameObserverpara definir o listener de callback de quadros de vídeo. - Ative a source de dados: Chame
enableVideoFrameObserverpara selecione a posição da source de dados e iniciar os callbacks. - Processe os dados do callback: Obtenha os dados do quadro dentro do callback. Esses dados são válidos apenas durante a execução do callback. Faça uma cópia caso precise utilizá-los de forma assíncrona.
5,6 Referência da API
Função | Android | iOS | HarmonyOS |
|---|---|---|---|
Registrar observer | setVideoFrameObserver(listener) | setVideoFrameObserver: | setVideoFrameObserver(observer) |
Ativar callbacks | enableVideoFrameObserver(enabled, source, config) | enableVideoFrameObserver:videoSource:config: | enableVideoFrameObserver(enabled, source, config) |
5,7 Métodos de callback
Callback | Android | iOS | HarmonyOS |
|---|---|---|---|
Dados capturados | onCapturedVideoFrame(frame) | onCapturedVideoFrame: | onCapturedVideoFrame(frame) |
Dados pré-codificação | onPreEncodeVideoFrame(trackType, frame) | onPreEncodeVideoFrame:frame: | onPreEncodeVideoFrame(trackType, frame) |
Dados remotos | onRemoteVideoFrame(trackType, frame) | onRemoteVideoFrame:frame: | onRemoteVideoFrame(trackType, frame) |
ObservaçãoRetornar true/ YES em um callback indica que os dados foram modificados e devem ser gravados de volta no SDK. Isso só tem efeito no modo ReadWrite com formato I420.
7. Controle de envio de fluxo de mídia
7,1 Visão geral
Controle se os fluxos de mídia locais são enviados. Use trackType para direcionar uma faixa específica (Audio, Video ou Screen). Quando o envio está desativado, a captura e a codificação continuam, mas os dados não são transmitidos ao destino remoto.
7,2 Referência da API
Função | Android | iOS | HarmonyOS |
|---|---|---|---|
Controlar envio de fluxo | enableSendMediaStream(trackType, enable) | enableSendMediaStream:enable: | enableSendMediaStream(trackType, enable) |
7,3 Enumeração de tipo de faixa
Valor do enum | Número | Descrição |
|---|---|---|
AoqTrackTypeAudio | 0 | Faixa de áudio |
AoqTrackTypeVideo | 1 | Faixa de vídeo |
AoqTrackTypeData | 2 | Faixa de dados |
8. Monitoramento de estado do dispositivo de vídeo
8,1 Visão geral
O SDK monitora automaticamente alterações no estado da câmera e notifica a camada da aplicação por meio do callback onVideoDeviceStateChanged.
8,2 Códigos de estado do dispositivo
Código de estado | Valor | Descrição |
|---|---|---|
AoqVideoDeviceNone | 0 | Estado inicial |
AoqVideoDeviceCaptureStarting | 1 | Captura iniciando |
AoqVideoDeviceCaptureStarted | 2 | Captura iniciada |
AoqVideoDeviceCaptureStopping | 3 | Captura parando |
AoqVideoDeviceCaptureStopped | 4 | Captura parada |
AoqVideoDeviceCaptureFail | 5 | Falha na captura |
8,3 Referência de callback
Callback | Android | iOS | HarmonyOS |
|---|---|---|---|
Alteração de estado do dispositivo | onVideoDeviceStateChanged(state) | onVideoDeviceStateChanged: | onVideoDeviceStateChanged(state) |
9. Códigos de erro e aviso de vídeo
9,1 Códigos de erro de vídeo
Código de erro | Valor | Descrição |
|---|---|---|
AoqErrorCodeVideo | 200 | Erro geral de vídeo |
VideoExternalBufferFull | 210 | Buffer externo de vídeo cheio |
VideoDevice | 220 | Erro geral de dispositivo de vídeo |
CameraOpenFail | 221 | Falha ao abrir a câmera |
CameraAuthFailed | 222 | Permissão de câmera negada |
CameraOccupied | 223 | Câmera em uso por outro processo |
CameraRunningError | 224 | Erro de execução da câmera |
VideoCodec | 230 | Erro geral de codec de vídeo |
EncoderInitFail | 231 | Falha na inicialização do codificador |
VideoRender | 240 | Erro geral de renderização de vídeo |
RenderCreateFail | 241 | Falha na criação do renderizador |
RenderDrawError | 242 | Erro de desenho na renderização |
Screen | 300 | Erro geral de compartilhamento de tela |
ObservaçãoCódigos de erro adicionais para Android: ScreenPermissionDenied(310) — permissão de compartilhamento de tela negada; ScreenForegroundServiceFailed(311) — falha ao iniciar o service em primeiro plano.
9,2 Códigos de aviso de vídeo
Código de aviso | Valor | Descrição |
|---|---|---|
AoqWCVideo | 200 | Aviso geral de vídeo |
CameraEnumerateError | 201 | Erro na enumeração da câmera |
EncoderSwitched | 202 | Aviso de troca de codificador |
RenderDowngrade | 203 | Aviso de downgrade de renderização |
Apêndice: Lista completa de métodos da API de vídeo
Categoria | Método | Descrição |
|---|---|---|
Controle de captura | startVideoCapture | Abre o dispositivo de captura de vídeo |
Controle de captura | stopVideoCapture | Fecha o dispositivo de captura de vídeo |
Controle de captura | switchCamera | Alterna entre a câmera frontal e traseira |
Controle de renderização | setLocalView | Define a janela de pré-visualização local |
Controle de renderização | setRemoteView | Define a janela de renderização remota |
Codec | setVideoEncoderConfig | Define os parâmetros de codificação de vídeo |
Entrada externa | pushExternalVideoCapturedFrame | Envia quadro de vídeo bruto |
Entrada externa | pushExternalVideoEncodedFrame | Envia quadro de vídeo codificado |
Compartilhamento de tela | startScreenCapture | Inicia a captura de tela |
Compartilhamento de tela | stopScreenCapture | Para a captura de tela |
Controle de fluxo | enableSendMediaStream | Controla o envio do fluxo de mídia |
Callbacks de quadros | setVideoFrameObserver | Registra o observer de quadros de vídeo |
Callbacks de quadros | enableVideoFrameObserver | Ative ou desative os callbacks de quadros de vídeo |