SEI 注入插件

features = ["sei"]

适用于时间戳、水印、业务标记等随流元数据注入场景。

SEI 以视频基本流内 NAL（H.264 类型 6 / H.265 前缀 SEI 类型 39）的形式插入， 因此所有转封装完整 Annex-B 的下游协议都会原样携带 —— 包括 HLS / LL-HLS 的 MPEG-TS 切片。播放端需自行解析 SEI（如通过 WebRTC DataChannel 或自定义解析器）。

注入 API

POST /sei/api/inject
Content-Type: application/json

{
  "stream_path": "live/test",
  "payload": "hello",
  "payload_encoding": "utf8",
  "uuid": "00112233445566778899aabbccddeeff",
  "once": true,
  "target_path": "live/test_sei"
}

字段	必填	说明
stream_path	是	目标流路径；可为 SEI 转换任务的源路径或输出路径
payload	是	SEI 负载内容
payload_encoding	否	utf8（默认）或 base64
uuid	否	user-data-unregistered 的 16 字节 UUID（32 位十六进制）；缺省随机生成
once	否	true（默认）：下一个可插入帧插入一次；false：每个可插入帧重复插入，直到被替换
target_path	否	当该流尚无 SEI 转换任务时，用此路径创建 source → target 转换任务

SEI 默认在 IDR 帧插入；配置 sei.insert_on_every_frame: true 后每帧插入。

响应与错误

• 200：已入队，返回 job_id / target_path / pending 数量
• 400：缺少 stream_path、payload 为空、base64/uuid 非法
• 404：stream_path 对应的流不存在（无在线发布者）
• 409：流存在但没有 SEI 转换任务，且未提供 target_path

与 HLS 联动

转换任务将注入后的码流重新发布到 target_path，HLS/LL-HLS 对该路径的 TS 转封装会原样保留 SEI NAL。播放注入后的流请使用 target_path （如 /hls/live/test_sei.m3u8）。

当前边界

• 仅注入，不提供 SEI 提取/解析 API。
• 不生成 ID3 timed metadata、EXT-X-DATERANGE 或 CMAF emsg； 依赖 hls.js ID3 cue 的播放器无法消费 SEI，需自定义解析。