Copy

功能介紹

AOQ Client SDK 內部視頻模組可滿足應用中對基本視頻功能的需求，但在特定情境中，SDK 內部的視頻採集模組可能無法滿足開發需求，需要實現自訂視頻採集功能，例如：

解決網路攝影機裝置被佔用或不相容問題。
需要從定製的採集系統、視頻檔案中擷取視頻資料後交給 SDK 傳輸。
需要將 AI 產生的畫面、螢幕錄製、虛擬網路攝影機等內容通過 SDK 推流傳輸。

AOQ Client SDK 支援兩種自訂視頻採集模式：

原始幀模式：自行採集原始視訊框架（BGRA、I420、NV12、NV21 等格式），通過 pushExternalVideoCapturedFrame 推送給 SDK 進行編碼和傳輸。SDK 內部完成編碼、傳輸等完整流程。
編碼幀模式：自行完成視頻編碼（目前支援 JPEG），通過 pushExternalVideoEncodedFrame 直推已編碼資料給 SDK，跳過 SDK 內部編碼器，直接打包發送。

範例程式碼

暫無

前提條件

已建立引擎執行個體（調用 createEngine）。
已成功串連伺服器（onConnectionStatusChange 回調狀態為 AoqConnectionStatusConnected）。

功能實現

根據業務情境選擇以下兩種模式之一。兩種模式不可混用：同一時間只能使用其中一種推送介面。

模式一：原始幀模式

自行採集原始視訊框架（BGRA、I420、NV12、NV21 等格式），推送給 SDK 進行編碼和傳輸。SDK 內部完成編碼、傳輸等完整流程。

1. 配置視頻編碼參數

SDK 內部編碼器會對推送的原始幀進行編碼，可根據業務需要調整編碼參數。

AoqClientEngine.AoqVideoCodecConfig config = new AoqClientEngine.AoqVideoCodecConfig();
config.width            = 1280;
config.height           = 720;
config.fps              = 2;
config.bitrate          = 500000;   // 起始碼率 500kbps
config.minBitrate       = 128000;   // 最小碼率 128kbps
config.keyframeInterval = 2;
// isExternal 保持預設 false，SDK 內部編碼

engine.setVideoEncoderConfig(config);

參數說明：

參數	類型	預設值	說明
trackType	AoqTrackType	AoqTrackTypeVideo	視頻軌道類型
codecType	AoqEncoderType	AoqEncoderTypeVideoH264	編碼器類型
width	int	720	編碼寬度（像素）
height	int	1280	編碼高度（像素）
fps	int	5	幀率
bitrate	int	500000	起始碼率（bps）
minBitrate	int	128000	最小碼率（bps）
keyframeInterval	int	2	主要畫面格間隔（秒）
isExternal	boolean	false	原始幀模式保持 false
mirrorMode	AoqMirrorMode	AoqMirrorModeDisabled	鏡像模式
orientationMode	AoqOrientationMode	AoqOrientationModeAuto	畫面方向模式

2. 以外部採集模式啟動視頻採集

調用 startVideoCapture 並設定 isExternal=true，告知 SDK 不開啟網路攝影機，由外部源提供視訊框架。這是原始幀模式的前置條件，未調用則 SDK 不會消費推送的幀資料。

AoqClientEngine.AoqVideoCaptureConfig config = new AoqClientEngine.AoqVideoCaptureConfig();
config.isExternal = true;  // 不開啟網路攝影機，由外部源推送視訊框架
// isExternal=true 時 width/height/fps 無效，實際解析度和幀率由推送資料決定
int ret = engine.startVideoCapture(config);

參數說明：

參數	類型	預設值	說明
width	int	1280	採集寬度（`isExternal=true` 時無效）
height	int	720	採集高度（`isExternal=true` 時無效）
fps	int	15	採集幀率（`isExternal=true` 時無效）
isExternal	boolean	false	true：不開啟網路攝影機，由外部源推送幀資料
cameraDirection	AoqCameraDirection	AoqCameraDirectionFront	網路攝影機方向（`isExternal=true` 時無效）

3. 推送原始視訊框架

調用 pushExternalVideoCapturedFrame 介面，將採集到的原始視訊框架傳入 SDK。SDK 內部完成編碼和傳輸。支援的視訊框架格式：BGRA、I420、NV12、NV21、RGBA。Apple 平台額外支援 CVPixelBuffer 零拷貝格式。

3.1 BGRA 格式

BGRA 為打包格式，每個像素 4 位元組（Blue、Green、Red、Alpha），一幀資料量 = width x height x 4。

// 構造 BGRA 視訊框架
AoqClientEngine.AoqVideoFrame frame = new AoqClientEngine.AoqVideoFrame();
frame.format    = AoqClientEngine.AoqVideoPixelFormat.AoqVideoPixelFormatBGRA;
frame.width     = 1280;
frame.height    = 720;

frame.data      = bgraBytes; // byte[]，長度 = width * height * 4

frame.timeStamp = System.currentTimeMillis();

int ret = engine.pushExternalVideoCapturedFrame(
    AoqClientEngine.AoqTrackType.AoqTrackTypeVideo, frame);

3.2 I420 格式

I420 為三平面格式（Y、U、V 分離），Y 平面大小 = width x height，U/V 平面各為 (width/2) x (height/2)。

// 構造 I420 視訊框架
AoqClientEngine.AoqVideoFrame frame = new AoqClientEngine.AoqVideoFrame();
frame.format    = AoqClientEngine.AoqVideoPixelFormat.AoqVideoPixelFormatI420;
frame.width     = 1280;
frame.height    = 720;

frame.dataY     = yPlane;  // byte[]，長度 = width * height

frame.dataU     = uPlane;  // byte[]，長度 = (width/2) * (height/2)

frame.dataV     = vPlane;  // byte[]，長度 = (width/2) * (height/2)

frame.strideY   = 1280;    // Y 平面行位元組數
frame.strideU   = 640;     // U 平面行位元組數
frame.strideV   = 640;     // V 平面行位元組數
frame.timeStamp = System.currentTimeMillis();

int ret = engine.pushExternalVideoCapturedFrame(
    AoqClientEngine.AoqTrackType.AoqTrackTypeVideo, frame);

3.3 NV12 / NV21 格式

NV12 和 NV21 為半平面格式，Y 平面 + UV 交錯平面。NV12 為 UV 交替排列，NV21 為 VU 交替排列。資料量 = width x height x 3 / 2，打包在 data 欄位中。

// 構造 NV12 視訊框架（NV21 同理，修改 format 即可）
AoqClientEngine.AoqVideoFrame frame = new AoqClientEngine.AoqVideoFrame();
frame.format    = AoqClientEngine.AoqVideoPixelFormat.AoqVideoPixelFormatNV12;
frame.width     = 1280;
frame.height    = 720;

frame.data      = nv12Bytes; // byte[]，長度 = width * height * 3 / 2

frame.timeStamp = System.currentTimeMillis();

int ret = engine.pushExternalVideoCapturedFrame(
    AoqClientEngine.AoqTrackType.AoqTrackTypeVideo, frame);

3.4 CVPixelBuffer 格式（Apple 平台）

iOS / macOS 平台支援直接傳遞 CVPixelBufferRef，實現零拷貝傳輸，避免記憶體拷貝帶來的效能開銷。

// iOS / macOS 平台
let frame = AoqVideoFrame()
frame.format      = .cvPixelBuffer
frame.width       = 1280
frame.height      = 720
frame.pixelBuffer = pixelBuffer  // CVPixelBufferRef
frame.timeStamp   = Int64(Date().timeIntervalSince1970 * 1000)

// SDK 內部非同步持有 pixelBuffer，需要額外 +1 引用計數
// SDK 消費完畢後會自行釋放
let _ = Unmanaged.passRetained(pixelBuffer)

engine.pushExternalVideoCapturedFrame(.video, frame: frame)

4. 停止原始幀採集

當不再需要推送視訊框架時，先停止推幀定時器，再調用 stopVideoCapture 關閉視頻採集。

// 1. 停止推幀定時器
stopExternalFramePush();
// 2. 停止視頻採集
engine.stopVideoCapture();

模式二：編碼幀模式

自行完成視頻編碼（目前支援 JPEG），直推已編碼資料給 SDK，跳過 SDK 內部編碼器，直接打包發送。此模式不需要調用 startVideoCapture 等採集相關介面。

1. 配置視頻編碼參數並啟用外部編碼

調用 setVideoEncoderConfig 並設定 isExternal=true，告知 SDK 跳過內部編碼器，由外部提供已編碼資料。

AoqClientEngine.AoqVideoCodecConfig config = new AoqClientEngine.AoqVideoCodecConfig();
config.width      = 1280;
config.height     = 720;
config.fps        = 2;
config.isExternal = true;  // 跳過內部編碼，由外部推送已編碼幀

engine.setVideoEncoderConfig(config);

設定完成後即可直接推送編碼幀，無需調用 startVideoCapture。

2. 推送編碼視訊框架

調用 pushExternalVideoEncodedFrame 介面，將已編碼的視頻資料直傳給 SDK。目前僅支援 JPEG 編碼格式。

// 從 Bitmap 產生 JPEG 資料
android.graphics.Bitmap bmp = android.graphics.Bitmap.createBitmap(
    width, height, android.graphics.Bitmap.Config.ARGB_8888);
// ... 填充 Bitmap 內容 ...

java.io.ByteArrayOutputStream baos = new java.io.ByteArrayOutputStream();
bmp.compress(android.graphics.Bitmap.CompressFormat.JPEG, 85, baos);
bmp.recycle();

// 構造編碼幀並推送
AoqClientEngine.AoqVideoEncodedFrame frame = new AoqClientEngine.AoqVideoEncodedFrame();
frame.codec     = AoqClientEngine.AoqVideoCodecType.AoqVideoCodecTypeJPEG;
frame.data      = baos.toByteArray();
frame.width     = width;
frame.height    = height;
frame.timeStamp = System.currentTimeMillis();

int ret = engine.pushExternalVideoEncodedFrame(
    AoqClientEngine.AoqTrackType.AoqTrackTypeVideo, frame);

AoqVideoEncodedFrame 參數說明：

參數	類型	預設值	說明
codec	AoqVideoCodecType	AoqVideoCodecTypeJPEG	編碼格式，目前僅支援 JPEG
data	byte[]	null	編碼後的資料
width	int	0	畫面寬度（像素）
height	int	0	畫面高度（像素）
timeStamp	long	0	時間戳記（毫秒），為 0 時 SDK 使用本地時鐘補充

3. 停止編碼幀推送

編碼幀模式無需管理採集裝置，停止推幀定時器即可。

stopExternalFramePush();

視訊框架格式參考

AoqVideoFrame（原始幀模式使用）

欄位	類型	說明
format	AoqVideoPixelFormat	像素格式
width	int	畫面寬度（像素）
height	int	畫面高度（像素）
data	byte[]	打包格式資料（NV12/NV21/BGRA/RGBA）
dataY	byte[]	I420 Y 平面資料
dataU	byte[]	I420 U 平面資料
dataV	byte[]	I420 V 平面資料
strideY	int	I420 Y 平面行位元組數
strideU	int	I420 U 平面行位元組數
strideV	int	I420 V 平面行位元組數
textureId	int	Android 紋理 ID（TextureOES/Texture2D）
transformMatrix	float[]	紋理變換矩陣（4x4 行優先）
eglContext	EGLContext	Android 共用 EGL context（紋理模式使用）
pixelBuffer	CVPixelBufferRef	Apple 零拷貝 CVPixelBuffer（僅 iOS/macOS）
timeStamp	long	時間戳記（毫秒），為 0 時 SDK 用本地時鐘補充

AoqVideoPixelFormat 枚舉值

枚舉值	數值	說明
AoqVideoPixelFormatUnknown	0	未知格式
AoqVideoPixelFormatI420	1	I420 三平面格式
AoqVideoPixelFormatNV12	2	NV12 半平面格式（UV 交替）
AoqVideoPixelFormatNV21	3	NV21 半平面格式（VU 交替）
AoqVideoPixelFormatBGRA	4	BGRA 打包格式
AoqVideoPixelFormatRGBA	5	RGBA 打包格式
AoqVideoPixelFormatCVPixelBuffer	6	Apple CVPixelBuffer（僅 iOS/macOS）
AoqVideoPixelFormatTextureOES	7	Android OES 外部紋理
AoqVideoPixelFormatTexture2D	8	Android 2D 紋理

AoqVideoEncodedFrame（編碼幀模式使用）

欄位	類型	說明
codec	AoqVideoCodecType	編碼格式
data	byte[]	編碼後的資料
width	int	畫面寬度（像素）
height	int	畫面高度（像素）
timeStamp	long	時間戳記（毫秒），為 0 時 SDK 用本地時鐘補充

AoqVideoCodecType 枚舉值

枚舉值	數值	說明
AoqVideoCodecTypeJPEG	0	JPEG 編碼格式

注意事項

原始幀模式：必須先調用 startVideoCapture(isExternal=true) 再推送幀，否則 SDK 返回參數錯誤。
編碼幀模式：只需調用 setVideoEncoderConfig(isExternal=true) 即可推送，不需要調用 startVideoCapture。
原始幀模式與編碼幀模式不可混用：同一時間只能使用其中一種推送介面。
編碼幀模式目前僅支援 JPEG 格式。
視訊框架資料在推送後由 SDK 內部管理生命週期，調用方無需在推送後繼續持有資料引用。

​功能介紹

​範例程式碼

​前提條件

​功能實現

​模式一：原始幀模式

​1. 配置視頻編碼參數

​2. 以外部採集模式啟動視頻採集

​3. 推送原始視訊框架

​3.1 BGRA 格式

​3.2 I420 格式

​3.3 NV12 / NV21 格式

​3.4 CVPixelBuffer 格式（Apple 平台）

​4. 停止原始幀採集

​模式二：編碼幀模式

​1. 配置視頻編碼參數並啟用外部編碼

​2. 推送編碼視訊框架

​3. 停止編碼幀推送

​視訊框架格式參考

​AoqVideoFrame（原始幀模式使用）

​AoqVideoPixelFormat 枚舉值

​AoqVideoEncodedFrame（編碼幀模式使用）

​AoqVideoCodecType 枚舉值

​注意事項