截图服务插件

Snap 插件提供视频流截图服务，支持按需截图、MJPEG 单帧输出、历史快照查询以及水印叠加。底层使用 FFmpeg 从流中提取关键帧并编码为图片。

启用插件

Cargo.toml

features = ["snap"]

# 如果还需要 MJPEG 流式输出
features = ["mjpeg"]  # 自动启用 snap

配置说明

snap:
  enable: true
  ffmpeg_path: "ffmpeg"             # FFmpeg 二进制路径
  output_path: "./snapshots"        # 截图文件存储目录
  format: "jpg"                     # 默认格式：jpg / png / webp
  quality: 85                       # 默认质量（1-100）
  width: 0                          # 默认宽度（0 = 保持原始）
  height: 0                         # 默认高度（0 = 保持原始）
  query_time_delta: 60              # 快照查询时间容差（秒）
  # 水印配置
  watermark_enabled: false
  watermark_text: ""
  watermark_font: ""
  watermark_font_size: 24
  watermark_position: "bottom-right"  # top-left / top-right / bottom-left / bottom-right / center
  watermark_color: "white"

前置依赖

截图功能依赖系统安装的 FFmpeg。请确保 ffmpeg 命令可在 PATH 中找到，或通过 ffmpeg_path 配置完整路径。

API 接口

实时截图

GET /snap/api/{stream_path}?format=jpg&quality=85&width=1280&height=720

对指定流进行实时截图。支持通过查询参数覆盖默认配置。

参数	类型	默认值	说明
format	string	jpg	图片格式：jpg / png / webp
quality	int	85	图片质量（1-100）
width	int	0	输出宽度（0 = 原始）
height	int	0	输出高度（0 = 原始）

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "stream_path": "live/camera01",
    "snap_time": "2026-03-18T14:30:25Z",
    "format": "jpg",
    "quality": 85,
    "width": 1920,
    "height": 1080,
    "file_size": 245760,
    "file_path": "./snapshots/live_camera01_20260318143025.jpg",
    "file_name": "live_camera01_20260318143025.jpg",
    "download_url": "/snap/download/live_camera01_20260318143025.jpg"
  }
}

传统截图接口

GET /snap/take/{stream_path}
POST /snap/take/{stream_path}

兼容旧版的简化截图接口，使用默认参数截图。

响应示例：

{
  "status": "success",
  "file_path": "./snapshots/live_camera01_20260318143025.jpg",
  "stream_path": "live/camera01",
  "width": 1920,
  "height": 1080,
  "file_size": 245760,
  "format": "jpg"
}

查询快照历史

GET /snap/query/{stream_path}?start_time=...&end_time=...&page=1&page_size=20

按流路径和时间范围分页查询历史快照记录。

参数	类型	说明
start_time	RFC3339	起始时间
end_time	RFC3339	结束时间
page	int	页码（默认 1）
page_size	int	每页数量（默认 20，最大 100）

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "stream_path": "live/camera01",
    "total": 42,
    "page": 1,
    "page_size": 20,
    "list": [
      {
        "id": 1,
        "stream_path": "live/camera01",
        "timestamp": "2026-03-18T14:30:25Z",
        "file_path": "./snapshots/live_camera01_20260318143025.jpg",
        "file_name": "live_camera01_20260318143025.jpg",
        "mode": "Manual"
      }
    ]
  }
}

查看全部历史

GET /snap/history
GET /snap/history/{stream_path}

不带路径参数返回全部历史记录，带路径参数返回指定流的历史。

清除历史

DELETE /snap/history

清除所有快照历史记录。

JPEG 单帧输出

GET /snap/frame.jpeg?src={stream_path}&width=640&height=480&quality=75

直接返回 JPEG 图片二进制数据（Content-Type: image/jpeg），适用于嵌入到 <img> 标签实现低频刷新的监控预览。

参数	类型	说明
src	string	必填，流路径
width	int	输出宽度
height	int	输出高度
quality	int	JPEG 质量

MJPEG 流输出（预留）

GET /snap/stream.mjpeg?src={stream_path}&width=640&height=480&fps=15&quality=75

MJPEG 持续流输出接口，当前版本暂未完全支持，建议使用 /snap/frame.jpeg 配合前端定时刷新替代。

获取配置

GET /snap/config

返回当前插件运行配置。

水印功能

启用水印后，截图时自动通过 FFmpeg drawtext 滤镜叠加水印文字：

snap:
  watermark_enabled: true
  watermark_text: "Monibuca V6"
  watermark_font: "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf"
  watermark_font_size: 24
  watermark_position: "bottom-right"
  watermark_color: "white"

水印位置选项：top-left、top-right、bottom-left、bottom-right、center。