Skip to main content

AOQ Client SDK Linux Python API 參考

本文介紹 AOQ Client SDK Linux 版的 Python 介面、回調和資料類型。

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 方可繼續使用。
@classmethod
def create_engine(cls, config: AoqCreateConfig, listener: AoqEngineEventListener) -> "AoqClientEngine"

參數

類型

說明

config

AoqCreateConfig

引擎建立配置

listener

AoqEngineEventListener

引擎事件回調監聽

傳回值:AoqClientEngine 引擎執行個體;建立失敗時拋出 RuntimeError。

destroy

銷毀引擎執行個體(類方法),釋放所有資源。
@classmethod
def destroy(cls) -> int
傳回值:0 表示成功;非 0 表示失敗。

get_version

擷取 SDK 目前的版本號(靜態方法)。
@staticmethod
def get_version() -> str
傳回值:版本號碼字串,如 "1.0.0"。

connect

串連 Relay 伺服器。業務 AppServer 應根據所用協議擷取臨時 AOQ 串連參數並下發給用戶端,具體操作請參見Token 鑒權。
def connect(self, config: AoqConnectConfig) -> int

參數

類型

說明

config

AoqConnectConfig

串連配置,包含 Token、SID、Relay 存取點列表等

傳回值:0 表示調用已下發(非同步執行);非 0 表示參數校正失敗。

disconnect

斷開與伺服器的串連,釋放串連相關資源。
def disconnect(self) -> int
傳回值:0 表示調用已下發(非同步執行);非 0 表示失敗。

音訊裝置管理

start_audio_capture

def start_audio_capture(self, config: AoqAudioCaptureConfig) -> int
Linux 版中該方法為空白實現:返回 0,但不會開啟音效卡或麥克風。音頻輸入請通過外部音頻流介面提供。

stop_audio_capture

def stop_audio_capture(self) -> int
由於 Linux 版不會設定音頻採集裝置狀態,該方法沒有實際效果。

mute_audio_capture

def mute_audio_capture(self, mute: bool) -> int
Linux 版不支援麥克風採集,該方法不能控制實際音頻採集裝置。

start_audio_player

def start_audio_player(self, config: AoqAudioPlaybackConfig) -> int
Linux 版中該方法為空白實現:返回 0,但不會開啟音效卡或擴音器。音訊輸出請通過音訊框架回調擷取資料並自行播放。

stop_audio_player / pause_audio_player / resume_audio_player

def stop_audio_player(self) -> int
def pause_audio_player(self, fade_ms: int = 0) -> int
def resume_audio_player(self, fade_ms: int = 0) -> int
Linux 版不支援擴音器播放,以上方法不能控制實際音頻播放裝置。fade_ms:淡出或淡入時間長度(毫秒);0 表示立即執行。

interrupt_audio_player

def interrupt_audio_player(self, track_type: int, fade_ms: int = 0) -> int
打斷本輪語音通話。

音頻編碼配置

def set_audio_encoder_config(self, config: AoqAudioCodecConfig) -> int
def set_audio_decoder_config(self, config: AoqAudioCodecConfig) -> int

視頻裝置管理

def start_video_capture(self, config: AoqVideoCaptureConfig) -> int
def stop_video_capture(self) -> int
def set_local_view(self, track_type: int, canvas: Optional[AoqVideoCanvas]) -> int
def set_remote_view(self, track_type: int, canvas: Optional[AoqVideoCanvas]) -> int
Linux 版不支援網路攝影機採集,也沒有視頻渲染後端。調用 start_video_capture 時須將 is_external 設為 True,並通過 push_external_video_frame 提供視訊框架;set_local_view、set_remote_view 及 AoqVideoCanvas.view 在 Linux 上無實際用途。如需預覽,請通過視訊框架回調擷取資料並自行渲染。

視頻編解碼與外部輸入

def set_video_encoder_config(self, config: AoqVideoCodecConfig) -> int
def set_video_decoder_config(self, config: AoqVideoCodecConfig) -> int
def push_external_video_frame(self, frame: AoqVideoFrame, track_type: AoqTrackType = AoqTrackType.VIDEO) -> int
def push_external_video_encoded_frame(self, track_type: AoqTrackType, frame: AoqVideoEncodedFrame) -> int
注意:
  • 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),直接走旁路通路不做二次編碼。

媒體流發送控制

def enable_send_media_stream(self, track_type: AoqTrackType, enable: bool) -> int
建議初始化後根據業務需要,分別調用 enable_send_media_stream(AoqTrackType.AUDIO, False) 和 enable_send_media_stream(AoqTrackType.VIDEO, False) 關閉音頻、視頻軌道發送;待 on_connection_status_change(CONNECTED) 後,再分別開啟所需軌道。

音頻檔案播放

def start_audio_file(self, file_id: str, config: AoqAudioFileMixConfig) -> int
def stop_audio_file(self, file_id: str) -> int
def pause_audio_file(self, file_id: str) -> int
def resume_audio_file(self, file_id: str) -> int
def get_audio_file_duration(self, file_id: str) -> int
def get_audio_file_current_position(self, file_id: str) -> int
def set_audio_file_position_millis(self, file_id: str, position_ms: int) -> int
def set_audio_file_volume(self, file_id: str, type_: AoqAudioStreamDirection, volume: int) -> int
def get_audio_file_volume(self, file_id: str, type_: AoqAudioStreamDirection) -> int

外部音頻流

def add_audio_external_stream(self, stream_id: str, config: AoqAudioExternalStreamConfig) -> int
def remove_audio_external_stream(self, stream_id: str) -> int
def push_audio_external_stream_data(self, stream_id: str, data: AoqAudioFrameData) -> int
def set_audio_external_stream_volume(self, stream_id: str, type_: AoqAudioStreamDirection, volume: int) -> int
def get_audio_external_stream_volume(self, stream_id: str, type_: AoqAudioStreamDirection) -> int
def clear_audio_external_stream_buffer(self, stream_id: str, fadeout_ms: int = -1) -> None
注意:push_audio_external_stream_data 緩衝區滿時返回 AoqErrorCode.AUDIO_EXTERNAL_BUFFER_FULL(110),建議等待約 20ms 後重試同一幀。

即時訊息

def send_data_msg(self, msg: AoqDataMsg) -> int

音訊框架回調

def set_audio_frame_observer(self, observer: Optional[IAudioFrameObserver]) -> int
def enable_audio_frame_observer(self, enabled: bool, audio_source: AoqAudioSource, config: AoqAudioObserverConfig) -> int
set_audio_frame_observer 傳 None 表示登出觀察者。

視訊框架回調

def set_video_frame_observer(self, observer: Optional[IVideoFrameObserver]) -> int
def enable_video_frame_observer(self, enabled: bool, video_source: AoqVideoSource, config: AoqVideoObserverConfig) -> int
set_video_frame_observer 傳 None 表示登出觀察者。

回調介面

AoqEngineEventListener

引擎事件回調基類。所有方法均為可選 override,預設空實現;回調在 native 線程觸發,使用者需自行保證安全執行緒。
class AoqEngineEventListener:
    def on_error(self, code: int, message: str) -> None: ...
    def on_connection_status_change(self, status: AoqConnectionStatus) -> None: ...
    def on_data_msg(self, msg: AoqDataMsg) -> None: ...

on_error

def on_error(self, code: int, message: str) -> None
引擎錯誤回調。code 對應 AoqErrorCode 枚舉值。

on_connection_status_change

def on_connection_status_change(self, status: AoqConnectionStatus) -> None
串連狀態變化回調。狀態流轉:DISCONNECTED -> CONNECTING -> CONNECTED/FAILED -> DISCONNECTED。

on_data_msg

def on_data_msg(self, msg: AoqDataMsg) -> None
收到即時資料訊息回調。

IAudioFrameObserver

音訊框架資料監聽基類。所有方法均為可選 override,預設空實現。
class IAudioFrameObserver:
    def on_captured_audio_frame(self, data: AoqAudioFrameData) -> None: ...
    def on_process_captured_audio_frame(self, data: AoqAudioFrameData) -> None: ...
    def on_publish_audio_frame(self, track_type: AoqTrackType, data: AoqAudioFrameData) -> None: ...
    def on_playback_audio_frame(self, data: AoqAudioFrameData) -> None: ...
回調在 native 音頻線程觸發,禁止在其中做任何耗時操作。AoqAudioFrameData.data 已是 bytes 拷貝,可安全非同步使用。

IVideoFrameObserver

視訊框架資料監聽基類。所有方法均為可選 override,預設返回 False。
class IVideoFrameObserver:
    def on_captured_video_frame(self, frame: AoqVideoFrame) -> bool: ...
    def on_pre_encode_video_frame(self, track_type: AoqTrackType, frame: AoqVideoFrame) -> bool: ...
    def on_remote_video_frame(self, track_type: AoqTrackType, frame: AoqVideoFrame) -> bool: ...
回調在 native 視頻線程觸發,禁止在其中做任何耗時操作。幀中像素資料已是 bytes 拷貝;當前 Python 層為拷貝語義,修改寫回暫不支援,建議始終返回 False。

工具函數

load_library

def load_library(path: Optional[str] = None) -> ctypes.CDLL
載入 native 共用庫。一般無需手動調用,首次使用引擎時自動載入。path 為空白時按以下順序尋找 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 位元組對齊