Skip to main content
功能參考

視頻常用功能介紹

AOQ Client SDK 提供了完整的視頻能力，覆蓋視頻採集、渲染顯示、編碼配置、幀資料回調、外部視頻輸入等核心情境。本文檔基於 Android（Java）、iOS（Objective-C）、Ohos（ArkTS）三個平台的公開 API，對視頻常用功能進行統一介紹。

1. 視頻採集

1.1 功能說明

視頻採集用於開啟裝置網路攝影機，將即時視訊框架資料送入 SDK 編碼推流管線。SDK 支援兩種採集模式：
  • 內部採集（預設）：SDK 自動管理網路攝影機裝置的開啟、幀採集和關閉，支援前後置網路攝影機切換。
  • 外部採集：由應用自行管理網路攝影機或其他視頻源，採集到的幀資料通過 pushExternalVideoCapturedFrame 介面輸入 SDK。

1.2 採集配置參數

參數

類型

預設值

說明

width

int

1280

採集寬度（像素），外部採集時無效

height

int

720

採集高度（像素），外部採集時無效

fps

int

15

採集幀率，外部採集時由送幀節奏決定

isExternal

bool

false

是否使用外部採集模式

cameraDirection

AoqCameraDirection

Front(0)

網路攝影機方向，外部採集時無效

1.3 網路攝影機方向枚舉

枚舉值

數值

說明

AoqCameraDirectionFront

0

自拍

AoqCameraDirectionBack

1

後置網路攝影機

1.4 API 對照

功能

Android

iOS

Ohos

開啟採集

startVideoCapture(config)

startVideoCapture:config:

startVideoCapture(config)

關閉採集

stopVideoCapture()

stopVideoCapture

stopVideoCapture()

切換網路攝影機

switchCamera(direction)

switchCamera:

switchCamera(direction)

1.5 使用樣本

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];
Ohos 
let config: AoqVideoCaptureConfig = {
  width: 1280,
  height: 720,
  fps: 15,
  cameraDirection: AoqCameraDirection.AoqCameraDirectionFront
};
engine.startVideoCapture(config);

2. 視頻渲染

2.1 功能說明

視頻渲染用於將本地採集或遠端接收的視訊框架資料顯示到螢幕上。SDK 支援設定本地預覽視窗和遠端渲染視窗，通過 trackType 區分視頻流（Video）和螢幕畫面分享流（Screen）。

2.2 渲染模式

枚舉值

數值

說明

AoqRenderModeAuto

0

自動模式

AoqRenderModeStretch

1

展開平鋪，畫面可能變形

AoqRenderModeFill

2

填充黑邊，畫面完整顯示

AoqRenderModeCrop

3

裁剪模式，畫面內容可能丟失

2.3 畫布配置

參數

類型

預設值

說明

view

平台視圖

null

渲染視圖（Android: SurfaceView/TextureView, iOS: UIView, Ohos: XComponent）

renderMode

AoqRenderMode

Auto(0)

渲染顯示模式

2.4 API 對照

功能

Android

iOS

Ohos

設定本地預覽

setLocalView(trackType, canvas)

setLocalView:trackType:canvas:

setLocalView(trackType, canvas)

設定遠端渲染

setRemoteView(trackType, canvas)

setRemoteView:trackType:canvas:

setRemoteView(trackType, canvas)

平台差異：Android 使用 SurfaceView 或 TextureView 作為渲染容器；iOS 使用 UIView（內部通過 AoqRenderView 封裝，支援 Metal 加速）；Ohos 使用 XComponent（通過 AoqXComponentController 管理 native 渲染視圖）。

3. 視頻編碼配置

3.1 功能說明

設定視頻編碼參數，包括編碼格式、解析度、幀率、碼率、主要畫面格間隔、鏡像和方向等。通過 trackType 區分視頻軌道和螢幕畫面分享軌道的編碼配置。

3.2 編碼配置參數

參數

類型

預設值

說明

trackType

AoqTrackType

Video(1)

軌道類型：Video

codecType

AoqEncoderType

VideoH264(3)

編碼格式

width

int

720

編碼寬度

height

int

1280

編碼高度

fps

int

5

編碼幀率

bitrate

int

500000

目標碼率（bps）

minBitrate

int

128000

最小碼率（bps）

keyframeInterval

int

2

主要畫面格間隔（秒）

mirrorMode

AoqMirrorMode

Disabled(0)

鏡像模式

orientationMode

AoqOrientationMode

Auto(0)

方向模式

isExternal

bool

false

外部編碼模式（true 時由應用推送已編碼幀）

3.3 編碼格式枚舉

枚舉值

數值

說明

AoqEncoderTypeVideoH264

3

H.264 編碼

AoqEncoderTypeVideoJpeg

4

JPEG 編碼（用於外部編碼幀）

3.4 鏡像模式

枚舉值

數值

說明

AoqMirrorModeDisabled

0

禁用鏡像

AoqMirrorModeEnabled

1

啟用鏡像

3.5 方向模式

枚舉值

數值

說明

AoqOrientationModeAuto

0

自動方向

AoqOrientationModePortrait

1

豎屏方向

AoqOrientationModeLandscape

2

橫屏方向

3.6 API 對照

功能

Android

iOS

Ohos

設定編碼參數

setVideoEncoderConfig(config)

setVideoEncoderConfig:

setVideoEncoderConfig(config)

4. 外部視訊框架輸入

4.1 功能說明

外部視訊框架輸入允許應用將自訂的視訊框架資料推送到 SDK，用於外部採集或外部編碼情境。支援兩種推送方式：
  • 推送原始幀：將未編碼的像素資料（I420/NV12/NV21/BGRA/RGBA 等格式）推送給 SDK，由 SDK 進行編碼。
  • 推送已編碼幀：將已編碼的資料（如 JPEG）直推給 SDK，SDK 不做二次編碼，直接打包發送。
通過 trackType 路由，AoqTrackTypeVideo 對應視頻採集的外部幀，AoqTrackTypeScreen 對應螢幕畫面分享的外部幀。

4.2 像素格式枚舉

枚舉值

數值

說明

平台支援

AoqVideoPixelFormatI420

1

I420 三平面

全平台

AoqVideoPixelFormatNV12

2

NV12 雙平面

全平台

AoqVideoPixelFormatNV21

3

NV21 雙平面

全平台

AoqVideoPixelFormatBGRA

4

BGRA 打包

全平台

AoqVideoPixelFormatRGBA

5

RGBA 打包

全平台

AoqVideoPixelFormatCVPixelBuffer

6

Apple 零拷貝

僅 iOS

AoqVideoPixelFormatTextureOES

7

OES 紋理

僅 Android

AoqVideoPixelFormatTexture2D

8

2D 紋理

僅 Android

4.3 原始視訊框架資料結構 (AoqVideoFrame)

欄位

類型

說明

format

AoqVideoPixelFormat

像素格式

width

int

寬度（像素）

height

int

高度（像素）

data

byte[] / ArrayBuffer

打包格式資料（NV12/NV21/BGRA/RGBA）

dataY / dataU / dataV

byte[] / ArrayBuffer

I420 三平面資料

strideY / strideU / strideV

int

I420 三平面步長

textureId

int

紋理 ID（Android TextureOES/Texture2D 時有效）

transformMatrix

float[16]

4x4 紋理變換矩陣（Android）

eglContext

EGLContext

共用 EGL 上下文（Android）

pixelBuffer

CVPixelBufferRef

Apple 零拷貝（iOS）

timeStamp

long

時間戳記（ms），0 時 SDK 用本地時鐘補

4.4 已編碼視訊框架資料結構 (AoqVideoEncodedFrame)

欄位

類型

預設值

說明

codec

AoqVideoCodecType

JPEG(0)

編碼格式

data

byte[] / ArrayBuffer

-

編碼後資料

width

int

-

寬度（像素）

height

int

-

高度（像素）

timeStamp

long

0

時間戳記（ms）

4.5 API 對照

功能

Android

iOS

Ohos

推送原始幀

pushExternalVideoCapturedFrame(trackType, frame)

pushExternalVideoCapturedFrame:frame:

pushExternalVideoCapturedFrame(trackType, frame)

推送已編碼幀

pushExternalVideoEncodedFrame(trackType, frame)

pushExternalVideoEncodedFrame:frame:

pushExternalVideoEncodedFrame(trackType, frame)

5. 視訊框架資料回調

5.1 功能說明

視訊框架回調允許開發人員在視頻管線的不同位置擷取原始幀資料，用於視頻分析、自訂處理、錄製等情境。支援唯讀和讀寫兩種模式，讀寫入模式下可修改幀資料並寫回 SDK。

5.2 支援的資料來源位置

資料來源

枚舉值

說明

Captured

0

採集後的視頻資料（前處理前）

PreEncode

1

編碼前的視頻資料（前處理後）

Remote

2

遠端解碼後、渲染前的視頻資料

5.3 回調配置參數

參數

類型

預設值

說明

format

AoqVideoPixelFormat

I420(1)

期望回調的像素格式

alignment

AoqVideoObserverAlignment

Default(0)

寬度對齊策略

mode

AoqVideoObserverMode

ReadOnly(0)

唯讀(0)/讀寫(1) 模式

mirrorApplied

bool

false

是否對回調資料應用鏡像

5.4 寬度對齊枚舉

枚舉值

數值

說明

AoqVideoObserverAlignmentDefault

0

預設對齊

AoqVideoObserverAlignmentEven

1

2 位元組對齊

AoqVideoObserverAlignment4

2

4 位元組對齊

AoqVideoObserverAlignment8

3

8 位元組對齊

AoqVideoObserverAlignment16

4

16 位元組對齊

5.5 使用步驟

  1. 註冊觀察者：調用 setVideoFrameObserver 設定視訊框架回調監聽器
  2. 啟用資料來源：調用 enableVideoFrameObserver 選擇需要監聽的資料來源位置，開啟回調
  3. 處理回調資料：在回呼函數中擷取幀資料（僅回調期間有效，非同步使用需自行拷貝）

5.6 API 對照

功能

Android

iOS

Ohos

註冊觀察者

setVideoFrameObserver(listener)

setVideoFrameObserver:

setVideoFrameObserver(observer)

啟用回調

enableVideoFrameObserver(enabled, source, config)

enableVideoFrameObserver:videoSource:config:

enableVideoFrameObserver(enabled, source, config)

5.7 回調方法

回調

Android

iOS

Ohos

採集後資料

onCapturedVideoFrame(frame)

onCapturedVideoFrame:

onCapturedVideoFrame(frame)

編碼前資料

onPreEncodeVideoFrame(trackType, frame)

onPreEncodeVideoFrame:frame:

onPreEncodeVideoFrame(trackType, frame)

遠端資料

onRemoteVideoFrame(trackType, frame)

onRemoteVideoFrame:frame:

onRemoteVideoFrame(trackType, frame)

回調方法返回 true/YES 表示資料已修改、需寫回 SDK（僅 ReadWrite 模式且 I420 格式時生效）。

7. 媒體流發送控制

7.1 功能說明

控制本地媒體流的發送開關，通過 trackType 路由到不同軌道（Audio/Video/Screen）。停用發送後，採集和編碼繼續運行，但資料不會發送到遠端。

7.2 API 對照

功能

Android

iOS

Ohos

控制流程發送

enableSendMediaStream(trackType, enable)

enableSendMediaStream:enable:

enableSendMediaStream(trackType, enable)

7.3 軌道類型枚舉

枚舉值

數值

說明

AoqTrackTypeAudio

0

音頻軌道

AoqTrackTypeVideo

1

視頻軌道

AoqTrackTypeData

2

資料軌道

8. 視頻裝置狀態監控

8.1 功能說明

SDK 自動監測視頻採集裝置（網路攝影機）的狀態變化，並通過 onVideoDeviceStateChanged 回調通知應用程式層。

8.2 裝置狀態代碼

狀態代碼

值

說明

AoqVideoDeviceNone

0

初始狀態

AoqVideoDeviceCaptureStarting

1

採集啟動中

AoqVideoDeviceCaptureStarted

2

採集已啟動

AoqVideoDeviceCaptureStopping

3

採集停止中

AoqVideoDeviceCaptureStopped

4

採集已停止

AoqVideoDeviceCaptureFail

5

採集失敗

8.3 回調對照

回調

Android

iOS

Ohos

裝置狀態變化

onVideoDeviceStateChanged(state)

onVideoDeviceStateChanged:

onVideoDeviceStateChanged(state)

9. 視頻錯誤碼與警告碼

9.1 視頻錯誤碼

錯誤碼

值

說明

AoqErrorCodeVideo

200

通用視頻錯誤

VideoExternalBufferFull

210

視頻外部緩衝區已滿

VideoDevice

220

視頻裝置通用錯誤

CameraOpenFail

221

網路攝影機開啟失敗

CameraAuthFailed

222

網路攝影機許可權被拒絕

CameraOccupied

223

網路攝影機被佔用

CameraRunningError

224

網路攝影機運行錯誤

VideoCodec

230

視頻編解碼通用錯誤

EncoderInitFail

231

編碼器初始化失敗

VideoRender

240

視頻渲染通用錯誤

RenderCreateFail

241

渲染器建立失敗

RenderDrawError

242

渲染繪製錯誤

Screen

300

螢幕畫面分享通用錯誤

Android 額外錯誤碼：ScreenPermissionDenied(310) 螢幕畫面分享許可權被拒絕、ScreenForegroundServiceFailed(311) 前台服務啟動失敗。

9.2 視頻警告碼

警告碼

值

說明

AoqWCVideo

200

通用視頻警告

CameraEnumerateError

201

網路攝影機枚舉錯誤

EncoderSwitched

202

編碼器切換警告

RenderDowngrade

203

渲染降級警告

附錄：完整視頻 API 方法列表

分類

方法名

說明

採集控制

startVideoCapture

開啟視頻採集裝置

採集控制

stopVideoCapture

關閉視頻採集裝置

採集控制

switchCamera

切換前後置網路攝影機

渲染控制

setLocalView

設定本地預覽視窗

渲染控制

setRemoteView

設定遠端渲染視窗

編解碼

setVideoEncoderConfig

設定視頻編碼參數

外部輸入

pushExternalVideoCapturedFrame

推送原始視訊框架

外部輸入

pushExternalVideoEncodedFrame

推送已編碼視訊框架

螢幕畫面分享

startScreenCapture

啟動螢幕採集

螢幕畫面分享

stopScreenCapture

停止螢幕採集

流量控制

enableSendMediaStream

控制媒體流發送

幀回調

setVideoFrameObserver

註冊視訊框架觀察者

幀回調

enableVideoFrameObserver

啟用/禁用視訊框架回調

使用 API
文本產生
映像產生
視頻產生
音頻
即時多模態
Realtime API
向量與排序
更多模型
工具包/架構
模型生產
檔案管理
更多