MP4 录制插件

MP4 插件提供流媒体录制和点播回放功能。支持标准 MP4 和 fMP4（Fragmented MP4）两种格式，可通过 HTTP API 控制录制的启停，并内置自动清理和损坏恢复机制。

启用插件

预编译二进制已内置该插件，在 config.yaml 中设置 enable: true 即可。

配置说明

在 config.yaml 中配置 MP4 插件：

mp4:
  enable: true
  record_path: "./recordings"        # 录制文件存储目录
  fragment: false                     # 是否启用 fMP4 格式
  fragment_duration: 5               # fMP4 分片时长（秒）
  max_file_size: 0                   # 单文件最大字节数（0 = 不限）
  max_duration: 0                    # 单次录制最大时长/秒（0 = 不限）
  before_duration: 10                # 事件录制：事件前缓冲时长（秒）
  after_duration: 10                 # 事件录制：事件后延续时长（秒）
  expire_days: 0                     # 自动删除 N 天前的录制（0 = 不删除）
  disk_max_percent: 0                # 磁盘占用上限百分比（0 = 不限）
  auto_recovery: true                # 自动恢复损坏的录制文件
  filename_pattern: "{stream}_{date}_{time}.mp4"  # 文件命名模板

文件命名模板

filename_pattern 支持以下变量：

变量	说明	示例
{stream}	流路径（/ 替换为 _）	live_camera01
{date}	日期	20260318
{time}	时间	143025
{timestamp}	Unix 时间戳	1742291425

API 接口

所有接口挂载在 /mp4/ 路由前缀下。

开始录制

POST /mp4/start/{stream_path}

开始录制指定流。如果该流已在录制中，返回 already_recording 状态。

请求示例：

curl -X POST http://localhost:8180/mp4/start/live/camera01

响应示例：

{
  "status": "started",
  "stream": "live/camera01"
}

停止录制

POST /mp4/stop/{stream_path}

停止指定流的录制。录制文件自动写入磁盘并（如配置了数据库）保存元信息到数据库。

请求示例：

curl -X POST http://localhost:8180/mp4/stop/live/camera01

响应示例：

{
  "status": "stopped",
  "stream": "live/camera01"
}

查询录制状态

GET /mp4/status/{stream_path}

查询指定流是否正在录制。

响应示例：

{
  "stream": "live/camera01",
  "recording": true
}

列出活跃录制

GET /mp4/list

返回当前所有正在进行的录制任务。

响应示例：

{
  "recordings": ["live/camera01", "live/camera02"],
  "count": 2
}

查询录制历史

GET /mp4/records

查询已完成的录制记录列表（需配置数据库支持）。

响应示例：

{
  "status": "success",
  "records": [],
  "count": 0
}

点播文件列表

GET /mp4/vod

列出可供点播的 MP4 文件。

点播播放

GET /mp4/vod/{filename}

直接播放指定的 MP4 录制文件，响应 Content-Type: video/mp4，支持 Accept-Ranges 头用于断点续传。

请求示例：

curl http://localhost:8180/mp4/vod/live_camera01_20260318_143025.mp4 -o output.mp4

插件信息

GET /mp4/

返回插件版本和可用接口列表。

逐接口详细说明

默认基地址：http://localhost:8180

1) 开始录制

POST /mp4/start/{streamPath}

参数	位置	类型	必填	说明
streamPath	path	string	是	流路径，如 live/camera01

成功响应：

{
  "status": "started",
  "stream": "live/camera01"
}

2) 停止录制

POST /mp4/stop/{streamPath}

参数	位置	类型	必填	说明
streamPath	path	string	是	目标流路径

成功响应：

{
  "status": "stopped",
  "stream": "live/camera01"
}

3) 录制状态

GET /mp4/status/{streamPath}

成功响应：

{
  "stream": "live/camera01",
  "recording": true
}

4) 活跃录制列表

GET /mp4/list

成功响应：

{
  "recordings": ["live/camera01", "live/camera02"],
  "count": 2
}

5) 录制配置

GET /mp4/config

成功响应（示例）：

{
  "enable": true,
  "record_path": "./recordings",
  "fragment": false,
  "fragment_duration": 5,
  "expire_days": 0
}

6) 录制文件列表（按流）

GET /mp4/api/list/{streamPath}

成功响应（示例）：

{
  "stream_path": "live/camera01",
  "files": [
    {
      "name": "live_camera01_20260318_143025.mp4",
      "size": 104857600,
      "created_at": "2026-03-18T14:30:25Z"
    }
  ],
  "count": 1
}

7) 录制目录

GET /mp4/api/catalog

成功响应（示例）：

{
  "roots": ["./recordings"],
  "total_files": 128
}

8) 删除录制文件

DELETE /mp4/api/delete/{streamPath}

成功响应（示例）：

{
  "deleted": true,
  "stream_path": "live/camera01"
}

9) 下载录制

GET /mp4/download/{streamPath}

响应为 video/mp4 二进制流，支持 Range。

错误响应

HTTP 状态码	场景
400	路径参数缺失或非法
404	录制文件或流不存在
409	状态冲突（例如重复开始）
500	FFmpeg/IO/内部错误

自动清理

当配置了 expire_days 或 disk_max_percent 后，MP4 插件会每小时自动执行一次清理任务：

• 按天过期：删除超过 expire_days 天的录制文件
• 按磁盘占比：当磁盘使用率超过 disk_max_percent 时，按时间从旧到新删除录制文件

数据库集成

MP4 插件通过 EngineContext 获取 DatabaseApi，支持将录制元信息（流路径、文件路径、时长、大小、起止时间）持久化到数据库。支持 SQLite、MySQL、PostgreSQL 后端。

与 Crontab 插件配合

结合 crontab 插件可实现定时录制：

crontab:
  jobs:
    - name: "每日录制"
      cron: "0 8 * * *"
      action: "record_start"
      stream: "live/camera01"
      duration: 28800  # 录制 8 小时