跳转到主要内容
千问AI平台 home page
文档
SDK简介

Linux Python SDK

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"
参数类型说明
configAoqCreateConfig引擎创建配置
listenerAoqEngineEventListener引擎事件回调监听
返回值：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
参数类型说明
configAoqConnectConfig连接配置，包含 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_dirstr""SDK 工作目录
enable_dump_audioboolFalse是否开启音频 dump（调试用）
extrasstr""扩展参数字符串

AoqConnectConfig

字段类型默认值说明
tokenstr""连接鉴权 Token
sidstr""会话 ID
certificatestr""服务器证书指纹
relay_endpointsList[AoqRelayEndpoint]空Relay 接入点列表
workspace_id_hashstr""工作空间 ID Hash
publish_tracksList[AoqTrackParam]空本端发布轨道列表
subscribe_tracksList[AoqTrackParam]空本端订阅轨道列表

AoqRelayEndpoint

字段类型默认值说明
endpointstr""Relay 服务器域名或 IP
portint0Relay 服务器端口
route_indexint-1路径序号，与其他平台 SDK 的 routeIndex 对齐；<0 时 SDK 按数组下标自动填充

AoqTrackParam

字段类型默认值说明
track_typeAoqTrackTypeAoqTrackType.AUDIO轨道类型

AoqDataMsg

字段类型默认值说明
databytesb""消息数据（字节串）

枚举类型

AoqErrorCode

枚举值值说明
OK0成功
PARAM_INVALID1参数非法
STATE_INVALID2状态非法
AUDIO100音频通用错误
AUDIO_EXTERNAL_BUFFER_FULL110外部音频缓冲区满
AUDIO_DEVICE120音频设备通用错误
AUDIO_DEVICE_RECORDING_AUTH_FAILED121录音权限未获取
AUDIO_DEVICE_RECORDING_OCCUPIED122录音设备被占用
AUDIO_DEVICE_RECORDING_START_FAIL124录音启动失败
AUDIO_DEVICE_PLAYOUT_OCCUPIED125播放设备被占用
AUDIO_DEVICE_PLAYOUT_START_FAIL127播放启动失败
VIDEO200视频通用错误
VIDEO_EXTERNAL_BUFFER_FULL210外部视频缓冲区满

AoqConnectionStatus

枚举值值说明
DISCONNECTED0未连接
CONNECTING1连接中
CONNECTED2已连接
FAILED3连接失败

AoqTrackType

枚举值值说明
AUDIO0音频轨道
VIDEO1视频轨道
DATA2数据消息轨道

AoqEncoderType

枚举值值说明
UNKNOWN0未知格式
AUDIO_PCM1音频 PCM
AUDIO_OPUS2音频 Opus
VIDEO_H2643视频 H.264
VIDEO_JPEG4视频 JPEG
DATA_TEXT5数据文本

AoqMirrorMode

枚举值值说明
DISABLED0关闭镜像
ENABLED1开启镜像

AoqOrientationMode

枚举值值说明
AUTO0自动适应
PORTRAIT1竖屏
LANDSCAPE2横屏

AoqRenderMode

枚举值值说明
AUTO0自适应模式
STRETCH1拉伸模式
FILL2填充模式
CROP3裁剪模式

AoqVideoPixelFormat

枚举值值说明
UNKNOWN0未知格式
I4201I420（YUV 三平面格式）
NV122NV12（YUV 半平面格式）
NV213NV21（YUV 半平面格式）
BGRA4BGRA（32 位）
RGBA5RGBA（32 位）

AoqCameraDirection

枚举值值说明
FRONT0前置摄像头（平台通用枚举；Linux 不支持摄像头采集）
BACK1后置摄像头（平台通用枚举；Linux 不支持摄像头采集）

音频类型

AoqAudioCaptureConfig

字段类型默认值说明
is_externalboolFalse是否为外部采集模式
channelint1声道数（默认单声道）

AoqAudioPlaybackConfig

字段类型默认值说明
is_externalboolFalse是否为外部播放模式
channelint1声道数（默认单声道）

AoqAudioCodecConfig

字段类型默认值说明
track_typeAoqTrackTypeAUDIO轨道类型
codec_typeAoqEncoderTypeAUDIO_PCM编码格式
sample_rateint48000采样率（Hz）
channelint1声道数
bitrateint32000比特率（bps）

AoqAudioFileMixConfig

字段类型默认值说明
file_namestr""文件名（含路径），非空
cyclesint-1循环次数，-1 表示无限循环
start_pos_msint0起始播放位置（毫秒）
publish_volumeint100推流音量，取值范围 [0-100]
playout_volumeint100播放音量，取值范围 [0-100]

AoqAudioExternalStreamConfig

字段类型默认值说明
track_typeAoqTrackTypeAUDIO音频轨道类型
codec_typeAoqEncoderTypeAUDIO_PCM音频流格式
channelsint1声道数
sample_rateint48000采样率（Hz）
playout_volumeint100播放音量 [0-100]
publish_volumeint100推流音量 [0-100]
max_buffer_durationint1000最大缓冲时长（毫秒）
enable_3aboolFalse是否对输入 PCM 进行 3A 处理

AoqAudioFrameData

音频裸数据，用于外部输入或观察者回调。
字段类型默认值说明
databytesb""音频 PCM 原始数据（回调中为 bytes 拷贝）
num_of_samplesint0采样点数（单声道）
bytes_per_sampleint0每个采样点的字节数
num_of_channelsint0声道数
samples_per_secint0每秒采样点数（采样率）
push_sequenceint0PCM 输入轮次
time_stampint0时间戳
auto_gen_muteboolFalseTrue 表示 SDK 生成的静音数据

AoqAudioObserverConfig

字段类型默认值说明
sample_rateint48000回调音频采样率（Hz）
channelsint1回调音频声道数
modeAoqAudioObserverModeREAD_ONLY读写模式

AoqAudioStreamDirection

枚举值值说明
PUBLISH0发布流（推流）
PLAYOUT1播放流（拉流）

AoqAudioExternalStreamToggle

枚举值值说明
NORMAL0正常状态
PAUSE1暂停状态

AoqAudioSource

枚举值值说明
CAPTURED0采集的音频数据
PROCESS_CAPTURED13A 处理后的音频数据
PUBLISH2推流的音频数据
PLAYBACK3播放的音频数据

AoqAudioObserverMode

枚举值值说明
READ_ONLY0只读模式
READ_WRITE1读写模式

视频类型

AoqVideoCaptureConfig

字段类型默认值说明
widthint1280采集宽度（像素），is_external=True 时无效
heightint720采集高度（像素），is_external=True 时无效
fpsint15采集帧率，is_external=True 时无效
is_externalboolFalse是否使用外部采集。Linux 仅支持 True；调用 start_video_capture 后通过 push_external_video_frame 提供视频帧
camera_directionAoqCameraDirectionFRONT移动端摄像头方向；Linux 无对应能力，保留 FRONT 即可

AoqVideoCodecConfig

视频编解码参数（编解码共用）。解码时仅 track_type/codec_type/width/height/fps/bitrate 生效，其余仅编码使用。
字段类型默认值说明
track_typeAoqTrackTypeVIDEO轨道类型
codec_typeAoqEncoderTypeVIDEO_H264编码格式
widthint540编码宽度（像素）
heightint960编码高度（像素）
fpsint5编码帧率
bitrateint500000目标比特率（bps）
min_bitrateint128000最小比特率（bps）
keyframe_intervalint2关键帧间隔（秒）
mirror_modeAoqMirrorModeDISABLED镜像模式
orientation_modeAoqOrientationModeAUTO视频方向模式

AoqVideoCanvas

字段类型默认值说明
viewint0渲染窗口句柄。Linux 无渲染后端，该字段无实际用途，保持 0 即可
render_modeAoqRenderModeAUTO渲染模式。Linux 无渲染后端，该字段无实际用途

AoqVideoFrame

外部视频帧 / 视频帧回调数据。使用打包格式（NV12/NV21/BGRA/RGBA）时填 data；使用 I420 三平面时填 data_y/u/v 与对应 stride（两者互斥）。
字段类型默认值说明
formatAoqVideoPixelFormatUNKNOWN像素格式
widthint0视频宽度（像素）
heightint0视频高度（像素）
databytesb""打包格式数据（NV12/NV21/BGRA/RGBA）
data_ybytesb""I420 Y 平面数据
data_ubytesb""I420 U 平面数据
data_vbytesb""I420 V 平面数据
stride_yint0Y 平面行跨度
stride_uint0U 平面行跨度
stride_vint0V 平面行跨度
time_stampint0时间戳（毫秒）；0 时 SDK 用本地时钟补齐

AoqVideoEncodedFrame

外部已编码视频帧（如 JPEG）。
字段类型默认值说明
codecAoqEncoderTypeVIDEO_JPEG编码格式
databytesb""编码后数据
widthint0宽度（像素）
heightint0高度（像素）
time_stampint0时间戳（毫秒）；0 时 SDK 用本地时钟补齐

AoqVideoObserverConfig

字段类型默认值说明
formatAoqVideoPixelFormatI420期望回调像素格式
alignmentAoqVideoObserverAlignmentDEFAULT宽度对齐策略
modeAoqVideoObserverModeREAD_ONLY读写模式
mirror_appliedboolFalse是否对回调数据应用镜像

AoqVideoSource

枚举值值说明
CAPTURED0采集后的视频数据（前处理前）
PRE_ENCODE1编码前的视频数据（前处理后）
REMOTE2远端解码后、渲染前的视频数据

AoqVideoObserverMode

枚举值值说明
READ_ONLY0只读模式
READ_WRITE1读写模式

AoqVideoObserverAlignment

枚举值值说明
DEFAULT0默认对齐
EVEN1偶数对齐
ALIGN_424 字节对齐
ALIGN_838 字节对齐
ALIGN_16416 字节对齐
Linux Python SDK - 千问AI平台