AidStream Python 接口文档

AidStream Python 接口文档

概述

AidStream 提供 Python 绑定（通过 pybind11），使开发者可以在 Python 中调用 AidStream SDK 的核心功能。Python 绑定的模块名为 aidstreamgst。

warning

Python 绑定当前仅暴露了 C++ API 的一个子集。部分高级功能（如 AidStreamEngine、Splice API、滚动录制等）目前在 Python 中不可用。

安装与导入

import aidstreamgst

枚举类型

LogLevel - 日志级别

成员	描述
LogLevel.SINFO	信息级别日志
LogLevel.SWARNING	警告级别日志
LogLevel.SERROR	错误级别日志
LogLevel.SDEBUG	调试级别日志
LogLevel.SOFF	关闭日志

StreamType - 输出流类型

warning

Python 绑定仅暴露了 5 个 StreamType 中的 3 个，RTMPSINK 和 MP4 类型暂不支持。

成员	描述
StreamType.EMPTY	无输出（fakesink）
StreamType.WAYLANDSINK	Wayland 显示输出
StreamType.RTSPSINK	RTSP 推流输出

Image 类

Image 类封装了从 GStreamer 管道回调中获取的图像帧数据和元数据。

属性	类型	描述
width	int	图像宽度
height	int	图像高度
size	int	图像数据所占内存大小（字节）
fps	float	帧率（C++ 类型为 double，Python 中表现为 float）
pipe_status	int	管道状态

方法	描述
to_bytes()	将当前帧数据复制为 Python bytes 对象（线程安全）
as_memoryview()	返回当前帧数据的零拷贝 memoryview 视图（不持有底层内存，仅可在回调内即时使用）

def my_callback(img):
    # 获取图像尺寸和帧率
    print(f"width: {img.width}, height: {img.height}, fps: {img.fps}")

    # 获取图像数据为 bytes
    raw_bytes = img.to_bytes()

    # 或者获取零拷贝视图（仅回调内有效）
    mem = img.as_memoryview()

    return 0

mat_image 类

mat_image 是 OpenCV cv::Mat 的 Python 封装，支持 buffer protocol，可直接转换为 numpy 数组。

方法	描述
is_empty()	返回 True 表示图像为空

import numpy as np

def my_callback(img):
    mat = aidstreamgst.get_data(img.height, img.width, img.to_bytes())
    if mat.is_empty():
        print("Empty image")
        return -1
    arr = np.array(mat, copy=False)
    # 对 arr 进行图像处理...
    return 0

API 函数

set_log_level

设置日志级别。

参数	类型	描述
log_level	LogLevel	日志级别枚举值

aidstreamgst.set_log_level(aidstreamgst.LogLevel.SINFO)

clogger

创建日志文件并设置日志路径与文件名前缀。

参数	类型	描述
destinationPath	str	日志文件路径及前缀，如 "./aidclog_aidstream_"

aidstreamgst.clogger("./aidclog_aidstream_")

start_stream

根据 stream id 启动流。此函数为阻塞调用，回调函数是 GIL 安全的。

参数	类型	描述
stream_id	str	在配置文件 aidstream-gst.conf 中定义的流 ID
cb	Callable[[Image], int]	回调函数，接收 Image 对象，返回 int（0 表示成功）

def my_callback(img):
    print(f"Received frame: {img.width}x{img.height} at {img.fps}fps")
    return 0

# 启动流（阻塞调用）
aidstreamgst.start_stream("stream1", my_callback)

shutdown

停止管道并释放资源。等价于 C++ 中的 gstreamer_pipeline_shutdown()。

参数	类型	默认值	描述
stream_id	str	"all_stream"	要停止的流 ID。传入具体的 stream_id 可停止单个流，传入 "all_stream" 则停止全部流。

# 停止所有流
aidstreamgst.shutdown()

# 停止指定流
aidstreamgst.shutdown("stream1")

get_data

将图像数据转换为 OpenCV Mat 对象。

参数	类型	描述
height	int	图像高度
width	int	图像宽度
data	bytes	图像原始数据（通过 img.to_bytes() 获取）

mat = aidstreamgst.get_data(img.height, img.width, img.to_bytes())

get_stream_status

获取当前流的运行状态。

返回值	描述
1	流正在运行
0	流空闲
-1	未初始化

status = aidstreamgst.get_stream_status()
print(f"Stream status: {status}")

完整示例

import aidstreamgst
import signal

running = True

def my_callback(img):
    """回调函数：在每个视频帧上调用"""
    print(f"Frame: {img.width}x{img.height}, fps: {img.fps:.1f}")
    # 获取图像字节数据
    img_bytes = img.to_bytes()
    return 0

def main():
    # 设置日志
    aidstreamgst.clogger("./aidclog_aidstream_")
    aidstreamgst.set_log_level(aidstreamgst.LogLevel.SINFO)

    # 启动流（使用配置文件中的 stream id）
    aidstreamgst.start_stream("1", my_callback)

if __name__ == "__main__":
    main()