🧩 一、appsink 是什么？

appsink 是 GStreamer 提供的一个 应用程序可控的接收端（sink）元素，用于将 pipeline 处理后的原始数据（如音视频帧）传递给应用程序代码。它是连接 GStreamer 流水线与用户逻辑的关键桥梁。

• 用途：从 pipeline 中提取 GstBuffer 或封装好的 GstSample（含 buffer + caps + timestamp）
• 典型场景：AI 推理输入、截图、自定义渲染、内存保存、测试验证等
• 方向：数据流终点（Sink），只接收上游数据

---

📦 二、基础信息（来自 Factory & Plugin Details）

项目	值
Long-name	AppSink
Klass	Generic/Sink
Description	Allow the application to get access to raw buffer
Authors	David Schleef, Wim Taymans
Plugin	app（gstapp.dll）
Version	1.18.6
License	LGPL
Source	gst-plugins-base

✅ 属于官方基础插件，稳定可靠，跨平台支持良好。

---

🔌 三、Pad 与 Caps 支持

• Pad Template: sink
  • Availability: Always（始终存在）
  • Capabilities: ANY
    • 表示可接收任意格式的数据
    • ⚠️ 但强烈建议通过 caps 属性显式限制格式（如 video/x-raw, format=BGR），避免应用层处理未知格式导致崩溃

---

⚙️ 四、Element Properties（属性详解）

以下是 appsink 所有可配置属性及其含义（按功能分类）：

1. 核心控制属性

属性	类型	默认值	说明
emit-signals	gboolean	false	是否启用信号机制。设为 true 后，当新 preroll/sample 到达时会触发 new-preroll/ new-sample 信号（事件驱动模式必需）。
caps	GstCaps*	NULL	限制输入数据格式。例如：video/x-raw, width=640, height=480, format=RGB。必须设置以确保应用能正确解析数据。
enable-last-sample	gboolean	true	是否维护 last-sample 属性（可用于随时查询最后一帧）。
last-sample	GstSample*	—	只读。返回最近接收到的一个 sample（包含 buffer、caps、pts/dts 等）。
eos	gboolean	true	只读。指示是否已收到 EOS（End-of-Stream）或尚未开始。

---

2. 缓冲与队列控制

属性	类型	默认值	说明
max-buffers	guint	0（无限制）	内部队列最多缓存多少个 buffer。设为 1 可实现“只保留最新帧”。
drop	gboolean	false	当队列满时是否丢弃旧 buffer。常用于实时流（如摄像头），防止延迟累积。
blocksize	guint	4096	每次拉取的字节数（仅在特定模式下有效，一般不用改）。
buffer-list	gboolean	false	是否使用 GstBufferList（批量 buffer），一般保持默认。

---

3. 同步与时序控制（Sync & QoS）

属性	类型	默认值	说明
sync	gboolean	true	是否根据 buffer 的 timestamp 进行时钟同步（即按播放时间等待）。 → 非实时处理（如 AI）应设为 false 以提升吞吐。
async	gboolean	true	是否异步进入 PAUSED 状态（通常保持默认）。
max-lateness	gint64	-1（无限）	buffer 超过 deadline 多少纳秒后被丢弃。设为 0 表示绝不容忍延迟。
processing-deadline	guint64	20,000,000ns (20ms）	最大允许的 buffer 处理时间，超时可能触发 drop。
render-delay	guint64	0	额外渲染延迟（调试用）。
ts-offset	gint64	0	对所有 buffer 时间戳增加偏移（单位：ns）。
throttle-time	guint64	0	强制在 buffer 之间插入最小间隔（单位：ns），用于限速。
qos	gboolean	false	是否向上游发送 QoS 事件，通知其调整速率（适用于自适应流）。

---

4. 性能与统计

属性	类型	说明
stats	GstStructure*	只读。包含： • rendered: 成功处理的 buffer 数 • dropped: 因延迟/队列满被丢弃的 buffer 数 • average-rate: 平均处理速率（buffers/sec）
max-bitrate	guint64	最大比特率限制（0 = 无限制），单位 bps。

---

5. 生命周期控制

属性	类型	默认值	说明
wait-on-eos	gboolean	true	收到 EOS 后是否等待所有 buffer 处理完毕再结束。

---

🔔 五、Element Signals（信号）

当 emit-signals=true 时，以下信号会被触发：

信号	回调签名	触发时机	用途
new-sample	GstFlowReturn (callback)(GstAppSink*, gpointer)	每当一个新 sample 到达	最常用！ 在回调中调用 pull-sample 获取数据
new-preroll	同上	preroll 阶段（如 PAUSED 状态第一帧）	初始化或预览
eos	void (callback)(GstAppSink*, gpointer)	收到 EOS	通知应用流已结束

✅ 使用流程：

g_object_set(appsink, "emit-signals", TRUE, NULL);
g_signal_connect(appsink, "new-sample", G_CALLBACK(on_new_sample), user_data);

---

🛠️ 六、Element Actions（主动拉取方法）

即使不使用信号，也可主动拉取数据（通过 GObject action signals）：

动作	参数	返回值	说明
pull-sample	—	GstSample*	阻塞式拉取下一个 sample（无数据时等待）
try-pull-sample	timeout (ns)	GstSample*	非阻塞式拉取，超时返回 NULL
pull-preroll	—	GstSample*	拉取 preroll sample（启动时第一帧）
try-pull-preroll	timeout (ns)	GstSample*	非阻塞版 preroll 拉取

💡 在 Python 中通常直接调用：

sample = appsink.emit("pull-sample")

---

🎯 七、典型使用模式对比

模式	适用场景	关键设置
事件驱动（推荐）	实时流、响应式处理	emit-signals=true + 连接 new-sample
轮询拉取	批处理、简单脚本	直接调用 pull-sample()
仅取最新帧	摄像头预览、AI推理	max-buffers=1, drop=true, sync=false

---

✅ 八、最佳实践建议

1. 务必设置 caps：明确指定输出格式（如 video/x-raw, format=BGR）
2. 实时流：drop=true, max-buffers=1, sync=false
3. 非实时处理（如 AI）：关闭 sync 和 qos，提升吞吐
4. 内存管理：GstSample 和 GstBuffer 使用后需 unref
5. 错误处理：检查 pull-sample 返回值是否为 NULL

---

📚 九、参考命令

gst-inspect-1.0 appsink

查看本地安装的 appsink 详细信息。