本文介紹 AOQ Client SDK Linux 版的 Python 介面、回調和資料類型。
aoq_client_sdk 提供 API。所有回調在 native 線程觸發,使用者需自行保證安全執行緒。
介面目錄
引擎生命週期
介面 | 簡介 |
|---|---|
create_engine | 建立引擎執行個體(單例模式) |
destroy | 銷毀引擎執行個體 |
get_version | 擷取 SDK 版本號碼 |
connect | 串連 Relay 伺服器 |
disconnect | 斷開伺服器串連 |
音訊裝置管理
介面 | 簡介 |
|---|---|
start_audio_capture | 啟動音頻採集(Linux 為空白實現,不會開啟麥克風) |
stop_audio_capture | 停止音頻採集(Linux 無實際效果) |
mute_audio_capture | 靜音或取消靜音音頻採集(Linux 無裝置採集能力) |
start_audio_player | 啟動音頻播放(Linux 為空白實現,不會開啟擴音器) |
stop_audio_player | 停止音頻播放(Linux 無實際效果) |
pause_audio_player | 暫停音頻播放(Linux 無裝置播放能力) |
resume_audio_player | 恢複音頻播放(Linux 無裝置播放能力) |
interrupt_audio_player | 打斷本輪語音通話 |
音頻編碼配置
介面 | 簡介 |
|---|---|
set_audio_encoder_config | 設定音頻編碼參數 |
set_audio_decoder_config | 設定音頻解碼參數 |
視頻裝置管理
介面 | 簡介 |
|---|---|
start_video_capture | 啟動視頻採集(Linux 僅支援外部採集模式) |
stop_video_capture | 停止視頻採集(Linux 僅適用於外部採集模式) |
set_local_view | 設定或移除本地視頻渲染視窗(Linux 無渲染實現) |
set_remote_view | 設定或移除遠端視頻渲染視窗(Linux 無渲染實現) |
視頻編解碼與外部輸入
介面 | 簡介 |
|---|---|
set_video_encoder_config | 設定視頻編碼參數 |
set_video_decoder_config | 設定視頻解碼參數 |
push_external_video_frame | 推送外部採集視訊框架 |
push_external_video_encoded_frame | 推送外部已編碼視訊框架 |
媒體流發送控制
介面 | 簡介 |
|---|---|
enable_send_media_stream | 控制本地媒體流的發送開關 |
音頻檔案播放
介面 | 簡介 |
|---|---|
start_audio_file | 開始推流播放本地音頻檔案 |
stop_audio_file | 停止音頻檔案播放 |
pause_audio_file | 暫停音頻檔案播放 |
resume_audio_file | 恢複音頻檔案播放 |
get_audio_file_duration | 擷取音頻檔案總時間長度 |
get_audio_file_current_position | 擷取音頻檔案當前播放位置 |
set_audio_file_position_millis | 設定音頻檔案播放位置(seek) |
set_audio_file_volume | 設定音頻檔案音量 |
get_audio_file_volume | 擷取音頻檔案當前音量 |
外部音頻流
介面 | 簡介 |
|---|---|
add_audio_external_stream | 新增一條外部音頻流 |
remove_audio_external_stream | 移除外部音頻流 |
push_audio_external_stream_data | 輸入外部音頻 PCM 資料 |
set_audio_external_stream_volume | 設定外部音頻流音量 |
get_audio_external_stream_volume | 擷取外部音頻流音量 |
clear_audio_external_stream_buffer | 清空外部音頻流緩衝 |
即時訊息
介面 | 簡介 |
|---|---|
send_data_msg | 發送即時資料訊息 |
音訊框架回調
介面 | 簡介 |
|---|---|
set_audio_frame_observer | 設定音訊框架資料回調監聽 |
enable_audio_frame_observer | 開啟或關閉指定位置的音訊框架回調 |
視訊框架回調
介面 | 簡介 |
|---|---|
set_video_frame_observer | 設定視訊框架資料回調監聽 |
enable_video_frame_observer | 開啟或關閉指定位置的視訊框架回調 |
回調介面
回調 | 簡介 |
|---|---|
on_error | 引擎錯誤回調 |
on_connection_status_change | 串連狀態變化回調 |
on_data_msg | 收到即時資料訊息回調 |
IAudioFrameObserver | 音訊框架資料監聽基類 |
IVideoFrameObserver | 視訊框架資料監聽基類 |
工具函數
介面 | 簡介 |
|---|---|
load_library | 手動指定並載入 native 共用庫 |
介面詳情
引擎生命週期
create_engine
建立引擎執行個體(類方法)。SDK 內部以全域單例方式持有引擎,重複調用返回已建立的執行個體;destroy 後需再次 create_engine 方可繼續使用。
參數 | 類型 | 說明 |
|---|---|---|
config | AoqCreateConfig | 引擎建立配置 |
listener | AoqEngineEventListener | 引擎事件回調監聽 |
destroy
銷毀引擎執行個體(類方法),釋放所有資源。
get_version
擷取 SDK 目前的版本號(靜態方法)。
connect
串連 Relay 伺服器。業務 AppServer 應根據所用協議擷取臨時 AOQ 串連參數並下發給用戶端,具體操作請參見Token 鑒權。
參數 | 類型 | 說明 |
|---|---|---|
config | AoqConnectConfig | 串連配置,包含 Token、SID、Relay 存取點列表等 |
disconnect
斷開與伺服器的串連,釋放串連相關資源。
音訊裝置管理
start_audio_capture
stop_audio_capture
mute_audio_capture
start_audio_player
stop_audio_player / pause_audio_player / resume_audio_player
interrupt_audio_player
音頻編碼配置
視頻裝置管理
start_video_capture 時須將 is_external 設為 True,並通過 push_external_video_frame 提供視訊框架;set_local_view、set_remote_view 及 AoqVideoCanvas.view 在 Linux 上無實際用途。如需預覽,請通過視訊框架回調擷取資料並自行渲染。
視頻編解碼與外部輸入
- set_video_decoder_config 僅 track_type/codec_type/width/height/fps/bitrate 欄位生效。
- push_external_video_frame 僅在 start_video_capture(is_external=True) 後消費;打包格式(NV12/NV21/BGRA/RGBA)填
frame.data,I420 三平面填frame.data_y/u/v與對應 stride;若緩衝區滿返回 AoqErrorCode.VIDEO_EXTERNAL_BUFFER_FULL(210)。 - push_external_video_encoded_frame 要求 start_video_capture(is_external=True) 且 set_video_encoder_config(codec_type=VIDEO_JPEG),直接走旁路通路不做二次編碼。
媒體流發送控制
音頻檔案播放
外部音頻流
即時訊息
音訊框架回調
視訊框架回調
回調介面
AoqEngineEventListener
引擎事件回調基類。所有方法均為可選 override,預設空實現;回調在 native 線程觸發,使用者需自行保證安全執行緒。
on_error
on_connection_status_change
on_data_msg
IAudioFrameObserver
音訊框架資料監聽基類。所有方法均為可選 override,預設空實現。
AoqAudioFrameData.data 已是 bytes 拷貝,可安全非同步使用。
IVideoFrameObserver
視訊框架資料監聽基類。所有方法均為可選 override,預設返回 False。
工具函數
load_library
libAoqClientSdk.so:AOQ_CLIENT_SDK_LIB 環境變數、模組同目錄、同級 lib 目錄、系統預設路徑。載入失敗拋出 OSError(典型原因:依賴庫不在 LD_LIBRARY_PATH 中)。
資料類型與枚舉
資料類型均為 Python dataclass,直接構造並按欄位賦值即可。
通用類型
AoqCreateConfig
欄位 | 類型 | 預設值 | 說明 |
|---|---|---|---|
work_dir | str | "" | SDK 工作目錄 |
enable_dump_audio | bool | False | 是否開啟音頻 dump(調試用) |
extras | str | "" | 擴充參數字串 |
AoqConnectConfig
欄位 | 類型 | 預設值 | 說明 |
|---|---|---|---|
token | str | "" | 串連鑒權 Token |
sid | str | "" | 會話 ID |
certificate | str | "" | 伺服器憑證指紋 |
relay_endpoints | List[AoqRelayEndpoint] | 空 | Relay 存取點列表 |
workspace_id_hash | str | "" | 工作空間 ID Hash |
publish_tracks | List[AoqTrackParam] | 空 | 本端發布軌道列表 |
subscribe_tracks | List[AoqTrackParam] | 空 | 本端訂閱軌道列表 |
AoqRelayEndpoint
欄位 | 類型 | 預設值 | 說明 |
|---|---|---|---|
endpoint | str | "" | Relay 伺服器網域名稱或 IP |
port | int | 0 | Relay 伺服器連接埠 |
route_index | int | -1 | 路徑序號,與其他平台 SDK 的 routeIndex 對齊;<0 時 SDK 按數組下標自動填滿 |
AoqTrackParam
欄位 | 類型 | 預設值 | 說明 |
|---|---|---|---|
track_type | AoqTrackType | AoqTrackType.AUDIO | 軌道類型 |
AoqDataMsg
欄位 | 類型 | 預設值 | 說明 |
|---|---|---|---|
data | bytes | b"" | 訊息資料(位元組串) |
枚舉類型
AoqErrorCode
枚舉值 | 值 | 說明 |
|---|---|---|
OK | 0 | 成功 |
PARAM_INVALID | 1 | 參數非法 |
STATE_INVALID | 2 | 狀態非法 |
AUDIO | 100 | 音頻通用錯誤 |
AUDIO_EXTERNAL_BUFFER_FULL | 110 | 外部音頻緩衝區滿 |
AUDIO_DEVICE | 120 | 音訊裝置通用錯誤 |
AUDIO_DEVICE_RECORDING_AUTH_FAILED | 121 | 錄音許可權未擷取 |
AUDIO_DEVICE_RECORDING_OCCUPIED | 122 | 錄音裝置被佔用 |
AUDIO_DEVICE_RECORDING_START_FAIL | 124 | 錄音啟動失敗 |
AUDIO_DEVICE_PLAYOUT_OCCUPIED | 125 | 播放裝置被佔用 |
AUDIO_DEVICE_PLAYOUT_START_FAIL | 127 | 播放啟動失敗 |
VIDEO | 200 | 視頻通用錯誤 |
VIDEO_EXTERNAL_BUFFER_FULL | 210 | 外部視頻緩衝區滿 |
AoqConnectionStatus
枚舉值 | 值 | 說明 |
|---|---|---|
DISCONNECTED | 0 | 未串連 |
CONNECTING | 1 | 串連中 |
CONNECTED | 2 | 已串連 |
FAILED | 3 | 串連失敗 |
AoqTrackType
枚舉值 | 值 | 說明 |
|---|---|---|
AUDIO | 0 | 音頻軌道 |
VIDEO | 1 | 視頻軌道 |
DATA | 2 | 資料訊息軌道 |
AoqEncoderType
枚舉值 | 值 | 說明 |
|---|---|---|
UNKNOWN | 0 | 未知格式 |
AUDIO_PCM | 1 | 音頻 PCM |
AUDIO_OPUS | 2 | 音頻 Opus |
VIDEO_H264 | 3 | 視頻 H.264 |
VIDEO_JPEG | 4 | 視頻 JPEG |
DATA_TEXT | 5 | 資料文本 |
AoqMirrorMode
枚舉值 | 值 | 說明 |
|---|---|---|
DISABLED | 0 | 關閉鏡像 |
ENABLED | 1 | 開啟鏡像 |
AoqOrientationMode
枚舉值 | 值 | 說明 |
|---|---|---|
AUTO | 0 | 自動適應 |
PORTRAIT | 1 | 豎屏 |
LANDSCAPE | 2 | 橫屏 |
AoqRenderMode
枚舉值 | 值 | 說明 |
|---|---|---|
AUTO | 0 | 自適應模式 |
STRETCH | 1 | 展開模式 |
FILL | 2 | 填充模式 |
CROP | 3 | 裁剪模式 |
AoqVideoPixelFormat
枚舉值 | 值 | 說明 |
|---|---|---|
UNKNOWN | 0 | 未知格式 |
I420 | 1 | I420(YUV 三平面格式) |
NV12 | 2 | NV12(YUV 半平面格式) |
NV21 | 3 | NV21(YUV 半平面格式) |
BGRA | 4 | BGRA(32 位) |
RGBA | 5 | RGBA(32 位) |
AoqCameraDirection
枚舉值 | 值 | 說明 |
|---|---|---|
FRONT | 0 | 自拍(平台通用枚舉;Linux 不支援網路攝影機採集) |
BACK | 1 | 後置網路攝影機(平台通用枚舉;Linux 不支援網路攝影機採集) |
音訊類型
AoqAudioCaptureConfig
欄位 | 類型 | 預設值 | 說明 |
|---|---|---|---|
is_external | bool | False | 是否為外部採集模式 |
channel | int | 1 | 聲道數(預設單聲道) |
AoqAudioPlaybackConfig
欄位 | 類型 | 預設值 | 說明 |
|---|---|---|---|
is_external | bool | False | 是否為外部播放模式 |
channel | int | 1 | 聲道數(預設單聲道) |
AoqAudioCodecConfig
欄位 | 類型 | 預設值 | 說明 |
|---|---|---|---|
track_type | AoqTrackType | AUDIO | 軌道類型 |
codec_type | AoqEncoderType | AUDIO_PCM | 編碼格式 |
sample_rate | int | 48000 | 採樣率(Hz) |
channel | int | 1 | 聲道數 |
bitrate | int | 32000 | 位元速率(bps) |
AoqAudioFileMixConfig
欄位 | 類型 | 預設值 | 說明 |
|---|---|---|---|
file_name | str | "" | 檔案名稱(含路徑),非空 |
cycles | int | -1 | 迴圈次數,-1 表示無限迴圈 |
start_pos_ms | int | 0 | 起始播放位置(毫秒) |
publish_volume | int | 100 | 推流音量,取值範圍 [0-100] |
playout_volume | int | 100 | 播放音量,取值範圍 [0-100] |
AoqAudioExternalStreamConfig
欄位 | 類型 | 預設值 | 說明 |
|---|---|---|---|
track_type | AoqTrackType | AUDIO | 音頻軌道類型 |
codec_type | AoqEncoderType | AUDIO_PCM | 音頻流格式 |
channels | int | 1 | 聲道數 |
sample_rate | int | 48000 | 採樣率(Hz) |
playout_volume | int | 100 | 播放音量 [0-100] |
publish_volume | int | 100 | 推流音量 [0-100] |
max_buffer_duration | int | 1000 | 最大緩衝時間長度(毫秒) |
enable_3a | bool | False | 是否對輸入 PCM 進行 3A 處理 |
AoqAudioFrameData
音頻裸資料,用於外部輸入或觀察者回調。
欄位 | 類型 | 預設值 | 說明 |
|---|---|---|---|
data | bytes | b"" | 音頻 PCM 未經處理資料(回調中為 bytes 拷貝) |
num_of_samples | int | 0 | 採樣點數(單聲道) |
bytes_per_sample | int | 0 | 每個採樣點的位元組數 |
num_of_channels | int | 0 | 聲道數 |
samples_per_sec | int | 0 | 每秒採樣點數(採樣率) |
push_sequence | int | 0 | PCM 輸入輪次 |
time_stamp | int | 0 | 時間戳記 |
auto_gen_mute | bool | False | True 表示 SDK 產生的靜音資料 |
AoqAudioObserverConfig
欄位 | 類型 | 預設值 | 說明 |
|---|---|---|---|
sample_rate | int | 48000 | 回調音頻採樣率(Hz) |
channels | int | 1 | 回調音頻聲道數 |
mode | AoqAudioObserverMode | READ_ONLY | 讀寫入模式 |
AoqAudioStreamDirection
枚舉值 | 值 | 說明 |
|---|---|---|
PUBLISH | 0 | 發布流(推流) |
PLAYOUT | 1 | 播放流(拉流) |
AoqAudioExternalStreamToggle
枚舉值 | 值 | 說明 |
|---|---|---|
NORMAL | 0 | 正常狀態 |
PAUSE | 1 | 暫停狀態 |
AoqAudioSource
枚舉值 | 值 | 說明 |
|---|---|---|
CAPTURED | 0 | 採集的音頻資料 |
PROCESS_CAPTURED | 1 | 3A 處理後的音頻資料 |
PUBLISH | 2 | 推流的音頻資料 |
PLAYBACK | 3 | 播放的音頻資料 |
AoqAudioObserverMode
枚舉值 | 值 | 說明 |
|---|---|---|
READ_ONLY | 0 | 唯讀模式 |
READ_WRITE | 1 | 讀寫入模式 |
視頻類型
AoqVideoCaptureConfig
欄位 | 類型 | 預設值 | 說明 |
|---|---|---|---|
width | int | 1280 | 採集寬度(像素),is_external=True 時無效 |
height | int | 720 | 採集高度(像素),is_external=True 時無效 |
fps | int | 15 | 採集幀率,is_external=True 時無效 |
is_external | bool | False | 是否使用外部採集。Linux 僅支援 True;調用 start_video_capture 後通過 push_external_video_frame 提供視訊框架 |
camera_direction | AoqCameraDirection | FRONT | 移動端網路攝影機方向;Linux 無對應能力,保留 FRONT 即可 |
AoqVideoCodecConfig
視頻編解碼參數(編解碼共用)。解碼時僅 track_type/codec_type/width/height/fps/bitrate 生效,其餘僅編碼使用。
欄位 | 類型 | 預設值 | 說明 |
|---|---|---|---|
track_type | AoqTrackType | VIDEO | 軌道類型 |
codec_type | AoqEncoderType | VIDEO_H264 | 編碼格式 |
width | int | 540 | 編碼寬度(像素) |
height | int | 960 | 編碼高度(像素) |
fps | int | 5 | 編碼幀率 |
bitrate | int | 500000 | 目標位元速率(bps) |
min_bitrate | int | 128000 | 最小位元速率(bps) |
keyframe_interval | int | 2 | 主要畫面格間隔(秒) |
mirror_mode | AoqMirrorMode | DISABLED | 鏡像模式 |
orientation_mode | AoqOrientationMode | AUTO | 視頻方向模式 |
AoqVideoCanvas
欄位 | 類型 | 預設值 | 說明 |
|---|---|---|---|
view | int | 0 | 渲染視窗控制代碼。Linux 無渲染後端,該欄位無實際用途,保持 0 即可 |
render_mode | AoqRenderMode | AUTO | 渲染模式。Linux 無渲染後端,該欄位無實際用途 |
AoqVideoFrame
外部視訊框架 / 視訊框架回調資料。使用打包格式(NV12/NV21/BGRA/RGBA)時填 data;使用 I420 三平面時填 data_y/u/v 與對應 stride(兩者互斥)。
欄位 | 類型 | 預設值 | 說明 |
|---|---|---|---|
format | AoqVideoPixelFormat | UNKNOWN | 像素格式 |
width | int | 0 | 視頻寬度(像素) |
height | int | 0 | 視頻高度(像素) |
data | bytes | b"" | 打包格式資料(NV12/NV21/BGRA/RGBA) |
data_y | bytes | b"" | I420 Y 平面資料 |
data_u | bytes | b"" | I420 U 平面資料 |
data_v | bytes | b"" | I420 V 平面資料 |
stride_y | int | 0 | Y 平面行跨度 |
stride_u | int | 0 | U 平面行跨度 |
stride_v | int | 0 | V 平面行跨度 |
time_stamp | int | 0 | 時間戳記(毫秒);0 時 SDK 用本地時鐘補齊 |
AoqVideoEncodedFrame
外部已編碼視訊框架(如 JPEG)。
欄位 | 類型 | 預設值 | 說明 |
|---|---|---|---|
codec | AoqEncoderType | VIDEO_JPEG | 編碼格式 |
data | bytes | b"" | 編碼後資料 |
width | int | 0 | 寬度(像素) |
height | int | 0 | 高度(像素) |
time_stamp | int | 0 | 時間戳記(毫秒);0 時 SDK 用本地時鐘補齊 |
AoqVideoObserverConfig
欄位 | 類型 | 預設值 | 說明 |
|---|---|---|---|
format | AoqVideoPixelFormat | I420 | 期望回調像素格式 |
alignment | AoqVideoObserverAlignment | DEFAULT | 寬度對齊策略 |
mode | AoqVideoObserverMode | READ_ONLY | 讀寫入模式 |
mirror_applied | bool | False | 是否對回調資料應用鏡像 |
AoqVideoSource
枚舉值 | 值 | 說明 |
|---|---|---|
CAPTURED | 0 | 採集後的視頻資料(前處理前) |
PRE_ENCODE | 1 | 編碼前的視頻資料(前處理後) |
REMOTE | 2 | 遠端解碼後、渲染前的視頻資料 |
AoqVideoObserverMode
枚舉值 | 值 | 說明 |
|---|---|---|
READ_ONLY | 0 | 唯讀模式 |
READ_WRITE | 1 | 讀寫入模式 |
AoqVideoObserverAlignment
枚舉值 | 值 | 說明 |
|---|---|---|
DEFAULT | 0 | 預設對齊 |
EVEN | 1 | 偶數對齊 |
ALIGN_4 | 2 | 4 位元組對齊 |
ALIGN_8 | 3 | 8 位元組對齊 |
ALIGN_16 | 4 | 16 位元組對齊 |