Linux 平台通过 Python 模块 aoq_client_sdk 提供 API。所有回调在 native 线程触发，使用者需自行保证线程安全。
接口目录
引擎生命周期
| 接口 | 简介 |
|---|
| create_engine | 创建引擎实例（单例模式） |
| destroy | 销毁引擎实例 |
| get_version | 获取 SDK 版本号 |
| connect | 连接 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 | 打断本轮音频通话 |
音频编码配置
| 接口 | 简介 |
|---|
| set_audio_encoder_config | 设置音频编码参数 |
| set_audio_decoder_config | 设置音频解码参数 |
视频设备管理
| 接口 | 简介 |
|---|
| start_video_capture | 打开视频采集设备（摄像头） |
| stop_video_capture | 关闭视频采集设备 |
| set_local_view | 设置或移除本地视频渲染窗口 |
| set_remote_view | 设置或移除远端视频渲染窗口 |
视频编解码与外部输入
| 接口 | 简介 |
|---|
| 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 回调
| 接口 | 简介 |
|---|
| on_captured_audio_frame | 采集到原始音频帧时触发。数据为采集后的原始 PCM，未经任何处理。 |
| on_process_captured_audio_frame | 3A 处理后的音频帧回调。数据经过 3A（AEC/AGC/ANS）处理。 |
| on_publish_audio_frame | 推流前的音频帧回调。数据为即将编码发送的音频帧。 |
| on_playback_audio_frame | 播放前的远端音频帧回调。数据为远端解码后、即将播放的音频帧。 |
IVideoFrameObserver 回调
| 接口 | 简介 |
|---|
| on_captured_video_frame | 采集到原始视频帧时触发（前处理前）。数据为采集后的裸帧，尚未经过前处理。 |
| on_pre_encode_video_frame | 编码前的视频帧回调（前处理后）。数据为前处理完成、即将编码的裸帧。 |
| on_remote_video_frame | 远端解码后、渲染前的视频帧回调。数据为远端解码完成、即将渲染的裸帧。 |
工具函数
| 接口 | 简介 |
|---|
| load_library | 手动指定并加载 native 共享库 |
接口详情
引擎生命周期
create_engine
创建引擎实例（类方法）。SDK 内部以全局单例方式持有引擎，重复调用返回已创建的实例；destroy 后需再次 create_engine 方可继续使用。
@classmethod
def create_engine(cls, config: AoqCreateConfig, listener: AoqEngineEventListener) -> "AoqClientEngine"
| 参数 | 类型 | 说明 |
|---|
| config | AoqCreateConfig | 引擎创建配置 |
| listener | AoqEngineEventListener | 引擎事件回调监听 |
destroy
销毁引擎实例（类方法），释放所有资源。
@classmethod
def destroy(cls) -> int
get_version
获取 SDK 当前版本号（静态方法）。
@staticmethod
def get_version() -> str
connect
连接 Relay 服务器。业务 AppServer 应根据所用协议获取临时 AOQ 连接参数并下发给客户端，具体操作请参见Token 鉴权。
def connect(self, config: AoqConnectConfig) -> int
| 参数 | 类型 | 说明 |
|---|
| config | AoqConnectConfig | 连接配置，包含 Token、SID、Relay 接入点列表等 |
disconnect
断开与服务器的连接，释放连接相关资源。
def disconnect(self) -> int
音频设备管理
start_audio_capture
def start_audio_capture(self, config: AoqAudioCaptureConfig) -> int
stop_audio_capture
def stop_audio_capture(self) -> int
mute_audio_capture
def mute_audio_capture(self, mute: bool) -> int
start_audio_player
def start_audio_player(self, config: AoqAudioPlaybackConfig) -> int
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
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
start_video_capture 时须将 is_external 设为 True，并通过 push_external_video_frame 提供视频帧；set_local_view、set_remote_view 及 AoqVideoCanvas.view 在 Linux 上无实际用途。如需预览，请通过视频帧回调获取数据并自行渲染。
视频编解码与外部输入
set_video_decoder_config
def set_video_decoder_config(self, config: AoqVideoCodecConfig) -> int
config 为视频解码配置。仅以下字段生效：track_type、codec_type、width、height、fps、bitrate。 其余字段仅用于编码。
在 connect 之前调用，作为订阅侧编解码参数提议。
返回值：0 表示成功；非 0 表示失败。
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 要求已调用 set_video_encoder_config(is_external=True, codec_type=VIDEO_JPEG)，否则返回 AoqErrorCode.VIDEO_EXTERNAL_ENCODER_NOT_ENABLED(212)；直接走旁路通路不做二次编码，无需依赖 start_video_capture。
媒体流发送控制
def enable_send_media_stream(self, track_type: AoqTrackType, enable: bool) -> int
音频文件播放
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
视频帧回调
def set_video_frame_observer(self, observer: Optional[IVideoFrameObserver]) -> int
def enable_video_frame_observer(self, enabled: bool, video_source: AoqVideoSource, config: AoqVideoObserverConfig) -> int
回调接口
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
on_connection_status_change
def on_connection_status_change(self, status: AoqConnectionStatus) -> None
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: ...
AoqAudioFrameData.data 已是 bytes 拷贝，可安全异步使用。
on_captured_audio_frame
采集到原始音频帧时触发。数据为采集后的原始 PCM，未经任何处理。
def on_captured_audio_frame(self, data: AoqAudioFrameData) -> None: ...
| 参数 | 类型 | 说明 |
|---|
| data | AoqAudioFrameData | 采集的音频帧数据 |
on_process_captured_audio_frame
3A 处理后的音频帧回调。数据经过 3A（AEC/AGC/ANS）处理。
def on_process_captured_audio_frame(self, data: AoqAudioFrameData) -> None: ...
| 参数 | 类型 | 说明 |
|---|
| data | AoqAudioFrameData | 3A 处理后的音频帧数据 |
on_publish_audio_frame
推流前的音频帧回调。数据为即将编码发送的音频帧。
def on_publish_audio_frame(self, track_type: AoqTrackType, data: AoqAudioFrameData) -> None: ...
| 参数 | 类型 | 说明 |
|---|
| track_type | AoqTrackType | 音频轨道类型 |
| data | AoqAudioFrameData | 推流前的音频帧数据 |
帧数据已是 bytes 拷贝，可安全异步使用。 此回调仅支持只读模式。
on_playback_audio_frame
播放前的远端音频帧回调。数据为远端解码后、即将播放的音频帧。
def on_playback_audio_frame(self, data: AoqAudioFrameData) -> None: ...
| 参数 | 类型 | 说明 |
|---|
| data | AoqAudioFrameData | 播放前的远端音频帧数据 |
IVideoFrameObserver 回调
视频帧数据监听基类。所有方法均为可选 override，默认返回 False。
class IVideoFrameObserver:
def on_captured_video_frame(self, track_type: AoqTrackType, 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: ...
on_captured_video_frame
采集到原始视频帧时触发（前处理前）。数据为采集后的裸帧，尚未经过前处理。
def on_captured_video_frame(self, track_type: AoqTrackType, frame: AoqVideoFrame) -> bool: ...
| 参数 | 类型 | 说明 |
|---|
| track_type | AoqTrackType | 帧所属轨道（Video / Screen） |
| frame | AoqVideoFrame | 采集的视频帧数据 |
on_pre_encode_video_frame
编码前的视频帧回调（前处理后）。数据为前处理完成、即将编码的裸帧。
def on_pre_encode_video_frame(self, track_type: AoqTrackType, frame: AoqVideoFrame) -> bool: ...
| 参数 | 类型 | 说明 |
|---|
| track_type | AoqTrackType | 帧所属轨道（Video / Screen） |
| frame | AoqVideoFrame | 编码前的视频帧数据 |
on_remote_video_frame
远端解码后、渲染前的视频帧回调。数据为远端解码完成、即将渲染的裸帧。
def on_remote_video_frame(self, track_type: AoqTrackType, frame: AoqVideoFrame) -> bool: ...
| 参数 | 类型 | 说明 |
|---|
| track_type | AoqTrackType | 帧所属轨道（Video / Screen） |
| frame | AoqVideoFrame | 远端解码后的视频帧数据 |
工具函数
load_library
def load_library(path: Optional[str] = None) -> ctypes.CDLL
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 | "" | 扩展参数字符串 |
| max_encoded_video_frame_bytes | int | 190 × 1024 | 编码后单帧大小上限（字节），仅用于 SDK 内部 JPEG 编码。 |
| enable_drop_oversized_video_frame | bool | False | 仅用于 SDK 内部 JPEG 编码：降至最低质量后仍超限时，是否允许丢弃该帧。 |
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 | 路径序号；<0 时 SDK 按数组下标自动填充 |
| tcp_port | int | 0 | TCP 降级端口；0 表示使用 SDK 默认端口 443。 |
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 | 外部视频缓冲区满 |
AoqWarningCode
警告码枚举。
| 枚举值 | 值 | 说明 |
|---|
| OK | 0 | 无警告 |
| AUDIO | 100 | 音频通用警告 |
| AUDIO_HOWLING | 101 | 音频啸叫检测 |
| AUDIO_DEVICE | 120 | 音频设备通用警告 |
| AUDIO_DEVICE_MIC_ENUMERATE_ERROR | 121 | 麦克风枚举错误 |
| AUDIO_DEVICE_MIC_START_TIMEOUT | 122 | 麦克风启动超时 |
| AUDIO_DEVICE_RECORDING_ERROR | 123 | 录音过程错误 |
| AUDIO_DEVICE_SPEAKER_ENUMERATE_ERROR | 124 | 扬声器枚举错误 |
| AUDIO_DEVICE_SPEAKER_START_TIMEOUT | 125 | 扬声器启动超时 |
| AUDIO_DEVICE_PLAYOUT_ERROR | 126 | 播放过程错误 |
| VIDEO | 200 | 视频通用警告 |
| VIDEO_CAMERA_ENUMERATE_ERROR | 201 | 摄像头枚举错误 |
| VIDEO_ENCODER_SWITCHED | 202 | 视频编码器已切换 |
| VIDEO_RENDER_DOWNGRADE | 203 | 视频渲染降级 |
AoqEngineEventListener 基类未声明 on_warning，但 C 桥接层会以 getattr(listener, "on_warning") 动态转发，业务侧可自行在 listener 上实现该方法接收警告。
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 | 裁剪模式 |
| 枚举值 | 值 | 说明 |
|---|
| UNKNOWN | 0 | 未知格式 |
| I420 | 1 | I420（YUV 三平面格式） |
| NV12 | 2 | NV12（YUV 半平面格式） |
| NV21 | 3 | NV21（YUV 半平面格式） |
| BGRA | 4 | BGRA（32 位） |
| RGBA | 5 | RGBA（32 位） |
| CV_PIXEL_BUFFER | 6 | Apple 平台零拷贝路径，Linux 不使用 |
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_OPUS | 编码格式 |
| 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 生效，其余仅编码使用。
| 字段 | 类型 | 默认值 | 说明 |
|---|
| is_external | bool | False | 外部编码模式；True 时由调用方推送已编码帧，SDK 不做采集和编码（仅编码生效） |
| 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 用本地时钟补齐 |
| native_pixel_buffer | int | 0 | Apple 零拷贝句柄，Linux 保留为 0 |
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 字节对齐 |
