Funciones comunes de video

El SDK de AOQ proporciona API generales de video. Qwen-Audio-Realtime no admite entrada ni salida de video. Para conocer las capacidades de medios de otros modelos, consulte su documentación de conexión.

1. Captura de video

1.1 Descripción general

La captura de video abre la cámara del dispositivo y alimenta la canalización de codificación del SDK con fotogramas de video en tiempo real. El SDK admite dos modos de captura:

Captura interna (predeterminada): El SDK administra automáticamente la cámara: abriéndola, capturando fotogramas y cerrándola. Admite el cambio entre cámaras frontal y trasera.
Captura externa: La aplicación administra la cámara u otra fuente de video. Los fotogramas capturados se introducen en el SDK mediante pushExternalVideoCapturedFrame.

1.2 Parámetros de configuración de captura

Parámetro	Tipo	Predeterminado	Descripción
width	int	1280	Ancho de captura en píxeles. No se usa en modo de captura externa.
height	int	720	Alto de captura en píxeles. No se usa en modo de captura externa.
fps	int	15	Tasa de fotogramas de captura. En el modo de captura externa, la tasa de fotogramas está determinada por la velocidad con la que se envían los fotogramas.
isExternal	bool	false	Indica si se debe usar el modo de captura externa.
cameraDirection	AoqCameraDirection	Frontal(0)	Dirección de la cámara. No se usa en modo de captura externa.

1.3 Enumeración de dirección de cámara

Valor de enumeración	Número	Descripción
AoqCameraDirectionFront	0	Cámara frontal
AoqCameraDirectionBack	1	Cámara trasera

1.4 Referencia de API

Función	Android	iOS	HarmonyOS
Iniciar captura	startVideoCapture(config)	startVideoCapture:config:	startVideoCapture(config)
Detener captura	stopVideoCapture()	stopVideoCapture	stopVideoCapture()
Cambiar cámara	switchCamera(direction)	switchCamera:	switchCamera(direction)

1.5 Ejemplo

Android

AoqVideoCaptureConfig config = new AoqVideoCaptureConfig();
config.width = 1280;
config.height = 720;
config.fps = 15;
config.cameraDirection = AoqCameraDirection.AoqCameraDirectionFront;
engine.startVideoCapture(config);

iOS

AoqVideoCaptureConfig *config = [[AoqVideoCaptureConfig alloc] init];
config.width = 1280;
config.height = 720;
config.fps = 15;
config.cameraDirection = AoqCameraDirectionFront;
[engine startVideoCapture:config];

HarmonyOS

let config: AoqVideoCaptureConfig = {
  width: 1280,
  height: 720,
  fps: 15,
  cameraDirection: AoqCameraDirection.AoqCameraDirectionFront
};
engine.startVideoCapture(config);

2. Renderizado de video

2.1 Descripción general

El renderizado de video muestra en pantalla fotogramas de video capturados localmente o recibidos remotamente. El SDK permite configurar una ventana de vista previa local y una ventana de renderizado remoto. Utilice trackType para distinguir entre el flujo de video (Video) y el flujo de pantalla compartida (Screen).

2.2 Modos de renderizado

Valor de enumeración	Número	Descripción
AoqRenderModeAuto	0	Modo automático
AoqRenderModeStretch	1	Estirar para llenar. La imagen puede distorsionarse.
AoqRenderModeFill	2	Ajustar con letterboxing. Se muestra la imagen completa.
AoqRenderModeCrop	3	Modo de recorte. Es posible que se corten partes de la imagen.

2.3 Configuración del lienzo

Parámetro	Tipo	Predeterminado	Descripción
view	Vista de plataforma	null	Vista de renderizado. Android: SurfaceView o TextureView. iOS: UIView. HarmonyOS: XComponent.
renderMode	AoqRenderMode	Auto(0)	Modo de visualización de renderizado

2.4 Referencia de API

Función	Android	iOS	HarmonyOS
Establecer vista previa local	setLocalView(trackType, canvas)	setLocalView:trackType:canvas:	setLocalView(trackType, canvas)
Establecer vista remota	setRemoteView(trackType, canvas)	setRemoteView:trackType:canvas:	setRemoteView(trackType, canvas)

Diferencias entre plataformas: Android utiliza SurfaceView o TextureView como contenedor de renderizado. iOS utiliza UIView (envuelto internamente por AoqRenderView con aceleración Metal). HarmonyOS utiliza XComponent (administrado por AoqXComponentController para renderizado nativo).

3. Configuración de códec de video

3.1 Descripción general

Configure los parámetros de codificación de video, incluido el formato de codificación, resolución, tasa de fotogramas, tasa de bits, intervalo de fotogramas clave, efecto espejo y orientación. Utilice trackType para aplicar diferentes configuraciones de codificación a la pista de video y a la pista de pantalla compartida.

3.2 Parámetros de configuración de codificación

Parámetro	Tipo	Predeterminado	Descripción
trackType	AoqTrackType	Video(1)	Tipo de pista: Video
codecType	AoqEncoderType	VideoH264(3)	Formato de codificación
width	int	720	Ancho codificado
height	int	1280	Alto codificado
fps	int	5	Tasa de cuadros de codificación
bitrate	int	500000	Tasa de bits objetivo (bps)
minBitrate	int	128000	Tasa de bits mínima (bps)
keyframeInterval	int	2	Intervalo de fotogramas clave (segundos)
mirrorMode	AoqMirrorMode	Deshabilitado(0)	Modo espejo
orientationMode	AoqOrientationMode	Auto(0)	Modo de orientación
isExternal	bool	false	Modo de codificación externa. Cuando es true, la aplicación envía fotogramas precodificados.

3.3 Enumeración de formato de codificación

Valor de enumeración	Número	Descripción
AoqEncoderTypeVideoH264	3	Codificación H.264
AoqEncoderTypeVideoJpeg	4	Codificación JPEG (para fotogramas codificados externamente)

3.4 Modo espejo

Valor de enumeración	Número	Descripción
AoqMirrorModeDisabled	0	Espejo deshabilitado
AoqMirrorModeEnabled	1	Espejo habilitado

3.5 Modo de orientación

Valor de enumeración	Número	Descripción
AoqOrientationModeAuto	0	Orientación automática
AoqOrientationModePortrait	1	Orientación vertical
AoqOrientationModeLandscape	2	Orientación horizontal

3.6 Referencia de API

Función	Android	iOS	HarmonyOS
Establecer configuración de codificación	setVideoEncoderConfig(config)	setVideoEncoderConfig:	setVideoEncoderConfig(config)

4. Entrada de fotogramas de video externos

4.1 Descripción general

La entrada de fotogramas de video externos permite que su aplicación envíe datos de fotogramas de video personalizados al SDK para escenarios de captura externa o codificación externa. Se admiten dos métodos de envío:

Enviar fotogramas sin procesar: Envíe datos de píxeles sin codificar (I420, NV12, NV21, BGRA, RGBA y formatos similares) al SDK. El SDK codifica los datos.
Enviar fotogramas codificados: Envíe datos ya codificados (por ejemplo, JPEG) directamente al SDK. El SDK los empaqueta y envía sin volver a codificarlos.

El enrutamiento se controla mediante trackType: AoqTrackTypeVideo enruta a la pista de captura de video; AoqTrackTypeScreen enruta a la pista de pantalla compartida.

4.2 Enumeración de formato de píxel

Valor de enumeración	Número	Descripción	Compatibilidad con plataformas
AoqVideoPixelFormatI420	1	I420 triplanar	Todas las plataformas
AoqVideoPixelFormatNV12	2	NV12 biplanar	Todas las plataformas
AoqVideoPixelFormatNV21	3	NV21 biplanar	Todas las plataformas
AoqVideoPixelFormatBGRA	4	BGRA empaquetado	Todas las plataformas
AoqVideoPixelFormatRGBA	5	RGBA empaquetado	Todas las plataformas
AoqVideoPixelFormatCVPixelBuffer	6	Copia cero de Apple	Solo iOS
AoqVideoPixelFormatTextureOES	7	Textura OES	Solo Android
AoqVideoPixelFormatTexture2D	8	Textura 2D	Solo Android

4.3 Estructura de datos de fotograma de video sin procesar (AoqVideoFrame)

Campo	Tipo	Descripción
format	AoqVideoPixelFormat	Formato de píxel
width	int	Ancho en píxeles
height	int	Altura en píxeles
data	byte[] / ArrayBuffer	Datos de formato empaquetado (NV12/NV21/BGRA/RGBA)
dataY / dataU / dataV	byte[] / ArrayBuffer	Datos triplanares I420
strideY / strideU / strideV	int	Pasos triplanares I420
textureId	int	ID de textura (válido para Android TextureOES/Texture2D)
transformMatrix	float[16]	Matriz de transformación de textura de 4×4 (Android)
eglContext	EGLContext	Contexto EGL compartido (Android)
pixelBuffer	CVPixelBufferRef	Copia cero de Apple (iOS)
timeStamp	long	Marca de tiempo en ms. Si es 0, el SDK utiliza el reloj local.

4.4 Estructura de datos de fotograma de video codificado (AoqVideoEncodedFrame)

Campo	Tipo	Predeterminado	Descripción
codec	AoqVideoCodecType	JPEG(0)	Formato de codificación
data	byte[] / ArrayBuffer	-	Datos codificados
width	int	-	Ancho en píxeles
height	int	-	Altura en píxeles
timeStamp	long	0	Marca de tiempo en ms

4.5 Referencia de API

Función	Android	iOS	HarmonyOS
Insertar fotograma sin procesar	pushExternalVideoCapturedFrame(trackType, frame)	pushExternalVideoCapturedFrame:frame:	pushExternalVideoCapturedFrame(trackType, frame)
Insertar fotograma codificado	pushExternalVideoEncodedFrame(trackType, frame)	pushExternalVideoEncodedFrame:frame:	pushExternalVideoEncodedFrame(trackType, frame)

5. Callbacks de fotogramas de video

5.1 Descripción general

Los callbacks de fotogramas de video le permiten obtener datos de fotogramas sin procesar en diferentes puntos de la canalización de video, para su uso en análisis de video, procesamiento personalizado, grabación y escenarios similares. Se admiten tanto los modos de solo lectura como de lectura-escritura. En el modo de lectura-escritura, puede modificar los datos del fotograma y escribirlos nuevamente en el SDK.

5.2 Posiciones de fuente de datos compatibles

Fuente de datos	Valor de enumeración	Descripción
Captured	0	Datos de video después de la captura, antes del preprocesamiento
PreEncode	1	Datos de video antes de la codificación, después del preprocesamiento
Remoto	2	Datos de video remoto después de la decodificación, antes del renderizado

5.3 Parámetros de configuración de callback

Parámetro	Tipo	Predeterminado	Descripción
format	AoqVideoPixelFormat	I420(1)	Formato de píxel para los datos de callback
alignment	AoqVideoObserverAlignment	Predeterminado(0)	Política de alineación de ancho
mode	AoqVideoObserverMode	SoloLectura(0)	Modo de solo lectura (0) o lectura-escritura (1)
mirrorApplied	bool	false	Indica si se debe aplicar efecto espejo a los datos de callback

5.4 Enumeración de alineación de ancho

Valor de enumeración	Número	Descripción
AoqVideoObserverAlignmentDefault	0	Alineación predeterminada
AoqVideoObserverAlignmentEven	1	Alineación de 2 bytes
AoqVideoObserverAlignment4	2	Alineación de 4 bytes
AoqVideoObserverAlignment8	3	Alineación de 8 bytes
AoqVideoObserverAlignment16	4	Alineación de 16 bytes

5.5 Pasos de uso

Registrar el observador: Llame a setVideoFrameObserver para configurar el listener de callback de fotogramas de video.
Habilitar la fuente de datos: Llame a enableVideoFrameObserver para seleccionar la posición de la fuente de datos e iniciar los callbacks.
Procesar datos de callback: Obtenga los datos del fotograma dentro del callback. Los datos del fotograma solo son válidos durante el callback. Cópielos si los necesita de forma asíncrona.

5.6 Referencia de API

Función	Android	iOS	HarmonyOS
Registrar observador	setVideoFrameObserver(listener)	setVideoFrameObserver:	setVideoFrameObserver(observer)
Habilitar callbacks	enableVideoFrameObserver(enabled, source, config)	enableVideoFrameObserver:videoSource:config:	enableVideoFrameObserver(enabled, source, config)

5.7 Métodos de callback

Callback	Android	iOS	HarmonyOS
Datos capturados	onCapturedVideoFrame(frame)	onCapturedVideoFrame:	onCapturedVideoFrame(frame)
Datos previos a la codificación	onPreEncodeVideoFrame(trackType, frame)	onPreEncodeVideoFrame:frame:	onPreEncodeVideoFrame(trackType, frame)
Datos remotos	onRemoteVideoFrame(trackType, frame)	onRemoteVideoFrame:frame:	onRemoteVideoFrame(trackType, frame)

Devolver true/ YES desde un callback indica que los datos han sido modificados y deben escribirse nuevamente en el SDK. Esto solo surte efecto en el modo ReadWrite con formato I420.

7. Control de envío de flujo de medios

7.1 Descripción general

Controle si se envían los flujos de medios locales. Utilice trackType para dirigirse a una pista específica (Audio, Video o Pantalla). Cuando el envío está deshabilitado, la captura y la codificación continúan, pero los datos no se envían al extremo remoto.

7.2 Referencia de API

Función	Android	iOS	HarmonyOS
Controlar el envío de transmisión	enableSendMediaStream(trackType, enable)	enableSendMediaStream:enable:	enableSendMediaStream(trackType, enable)

7.3 Enumeración de tipo de pista

Valor de enumeración	Número	Descripción
AoqTrackTypeAudio	0	Pista de audio
AoqTrackTypeVideo	1	Pista de video
AoqTrackTypeData	2	Pista de datos

8. Monitoreo del estado del dispositivo de video

8.1 Descripción general

El SDK monitorea automáticamente los cambios de estado de la cámara y notifica a la capa de aplicación a través del callback onVideoDeviceStateChanged.

8.2 Códigos de estado del dispositivo

Código de estado	Valor	Descripción
AoqVideoDeviceNone	0	Estado inicial
AoqVideoDeviceCaptureStarting	1	Iniciando captura
AoqVideoDeviceCaptureStarted	2	Captura iniciada
AoqVideoDeviceCaptureStopping	3	Deteniendo captura
AoqVideoDeviceCaptureStopped	4	Captura detenida
AoqVideoDeviceCaptureFail	5	Error en la captura

8.3 Referencia de callback

Callback	Android	iOS	HarmonyOS
Cambio de estado del dispositivo	onVideoDeviceStateChanged(state)	onVideoDeviceStateChanged:	onVideoDeviceStateChanged(state)

9. Códigos de error y advertencia de video

9.1 Códigos de error de video

Código de error	Valor	Descripción
AoqErrorCodeVideo	200	Error general de video
VideoExternalBufferFull	210	Búfer externo de video lleno
VideoDevice	220	Error general del dispositivo de video
CameraOpenFail	221	Error al abrir la cámara
CameraAuthFailed	222	Permiso de cámara denegado
CameraOccupied	223	Cámara en uso por otro proceso
CameraRunningError	224	Error de ejecución de la cámara
VideoCodec	230	Error general de códec de video
EncoderInitFail	231	Error en la inicialización del codificador
VideoRender	240	Error general de renderizado de video
RenderCreateFail	241	Error en la creación del renderizador
RenderDrawError	242	Error de dibujo de renderizado
Pantalla	300	Error general al compartir pantalla

Códigos de error adicionales de Android: ScreenPermissionDenied(310) — permiso de pantalla compartida denegado; ScreenForegroundServiceFailed(311) — error al iniciar el servicio en primer plano.

9.2 Códigos de advertencia de video

Código de advertencia	Valor	Descripción
AoqWCVideo	200	Advertencia general de video
CameraEnumerateError	201	Error de enumeración de cámaras
EncoderSwitched	202	Advertencia de cambio de codificador
RenderDowngrade	203	Advertencia de degradación de renderizado

Apéndice: Lista completa de métodos de API de video

Categoría	Método	Descripción
Control de captura	startVideoCapture	Abrir dispositivo de captura de video
Control de captura	stopVideoCapture	Cerrar dispositivo de captura de video
Control de captura	switchCamera	Cambiar entre cámara frontal y trasera
Control de renderizado	setLocalView	Establecer ventana de vista previa local
Control de renderizado	setRemoteView	Establecer ventana de renderizado remoto
Códec	setVideoEncoderConfig	Establecer parámetros de codificación de video
Entrada externa	pushExternalVideoCapturedFrame	Insertar fotograma de video sin procesar
Entrada externa	pushExternalVideoEncodedFrame	Insertar fotograma de video codificado
Compartir pantalla	startScreenCapture	Iniciar la captura de pantalla
Compartir pantalla	stopScreenCapture	Detener la captura de pantalla
Control de transmisión	enableSendMediaStream	Controlar el envío de flujo de medios
Callbacks de fotogramas	setVideoFrameObserver	Registrar observador de fotogramas de video
Callbacks de fotogramas	enableVideoFrameObserver	Habilitar o deshabilitar callbacks de fotogramas de video

​1. Captura de video

​1.1 Descripción general

​1.2 Parámetros de configuración de captura

​1.3 Enumeración de dirección de cámara

​1.4 Referencia de API

​1.5 Ejemplo

​2. Renderizado de video

​2.1 Descripción general

​2.2 Modos de renderizado

​2.3 Configuración del lienzo

​2.4 Referencia de API

​3. Configuración de códec de video

​3.1 Descripción general

​3.2 Parámetros de configuración de codificación

​3.3 Enumeración de formato de codificación

​3.4 Modo espejo

​3.5 Modo de orientación

​3.6 Referencia de API

​4. Entrada de fotogramas de video externos

​4.1 Descripción general

​4.2 Enumeración de formato de píxel

​4.3 Estructura de datos de fotograma de video sin procesar (AoqVideoFrame)

​4.4 Estructura de datos de fotograma de video codificado (AoqVideoEncodedFrame)

​4.5 Referencia de API

​5. Callbacks de fotogramas de video

​5.1 Descripción general

​5.2 Posiciones de fuente de datos compatibles

​5.3 Parámetros de configuración de callback

​5.4 Enumeración de alineación de ancho

​5.5 Pasos de uso

​5.6 Referencia de API

​5.7 Métodos de callback

​7. Control de envío de flujo de medios

​7.1 Descripción general

​7.2 Referencia de API

​7.3 Enumeración de tipo de pista

​8. Monitoreo del estado del dispositivo de video

​8.1 Descripción general

​8.2 Códigos de estado del dispositivo

​8.3 Referencia de callback

​9. Códigos de error y advertencia de video

​9.1 Códigos de error de video

​9.2 Códigos de advertencia de video

​Apéndice: Lista completa de métodos de API de video

1. Captura de video

1.1 Descripción general

1.2 Parámetros de configuración de captura

1.3 Enumeración de dirección de cámara

1.4 Referencia de API

1.5 Ejemplo

2. Renderizado de video

2.1 Descripción general

2.2 Modos de renderizado

2.3 Configuración del lienzo

2.4 Referencia de API

3. Configuración de códec de video

3.1 Descripción general

3.2 Parámetros de configuración de codificación

3.3 Enumeración de formato de codificación

3.4 Modo espejo

3.5 Modo de orientación

3.6 Referencia de API

4. Entrada de fotogramas de video externos

4.1 Descripción general

4.2 Enumeración de formato de píxel

4.3 Estructura de datos de fotograma de video sin procesar (AoqVideoFrame)

4.4 Estructura de datos de fotograma de video codificado (AoqVideoEncodedFrame)

4.5 Referencia de API

5. Callbacks de fotogramas de video

5.1 Descripción general

5.2 Posiciones de fuente de datos compatibles

5.3 Parámetros de configuración de callback

5.4 Enumeración de alineación de ancho

5.5 Pasos de uso

5.6 Referencia de API

5.7 Métodos de callback

7. Control de envío de flujo de medios

7.1 Descripción general

7.2 Referencia de API

7.3 Enumeración de tipo de pista

8. Monitoreo del estado del dispositivo de video

8.1 Descripción general

8.2 Códigos de estado del dispositivo

8.3 Referencia de callback

9. Códigos de error y advertencia de video

9.1 Códigos de error de video

9.2 Códigos de advertencia de video

Apéndice: Lista completa de métodos de API de video