MP4 Recording Plugin

The MP4 plugin provides media stream recording and video-on-demand (VOD) playback. It supports both standard MP4 and fMP4 (Fragmented MP4) formats, allows controlling recording start/stop via HTTP API, and includes built-in auto-cleanup and corruption recovery mechanisms.

Enabling the Plugin

Cargo.toml

features = ["mp4"]

Configuration

Configure the MP4 plugin in config.yaml:

mp4:
  enable: true
  record_path: "./recordings"        # Recording file storage directory
  fragment: false                     # Enable fMP4 format
  fragment_duration: 5               # fMP4 fragment duration (seconds)
  max_file_size: 0                   # Maximum file size in bytes (0 = unlimited)
  max_duration: 0                    # Maximum recording duration in seconds (0 = unlimited)
  before_duration: 10                # Event recording: pre-event buffer duration (seconds)
  after_duration: 10                 # Event recording: post-event continuation duration (seconds)
  expire_days: 0                     # Auto-delete recordings older than N days (0 = no deletion)
  disk_max_percent: 0                # Maximum disk usage percentage (0 = unlimited)
  auto_recovery: true                # Auto-recover corrupted recording files
  filename_pattern: "{stream}_{date}_{time}.mp4"  # File naming template

File Naming Template

filename_pattern supports the following variables:

Variable	Description	Example
{stream}	Stream path (/ replaced with _)	live_camera01
{date}	Date	20260318
{time}	Time	143025
{timestamp}	Unix timestamp	1742291425

API Endpoints

All endpoints are mounted under the /mp4/ route prefix.

Start Recording

POST /mp4/start/{stream_path}

Start recording the specified stream. Returns already_recording status if the stream is already being recorded.

Request example:

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

Response example:

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

Stop Recording

POST /mp4/stop/{stream_path}

Stop recording the specified stream. The recording file is automatically written to disk and (if a database is configured) metadata is saved to the database.

Request example:

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

Response example:

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

Query Recording Status

GET /mp4/status/{stream_path}

Query whether the specified stream is currently being recorded.

Response example:

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

List Active Recordings

GET /mp4/list

Returns all currently active recording tasks.

Response example:

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

Query Recording History

GET /mp4/records

Query the list of completed recordings (requires database support).

Response example:

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

VOD File List

GET /mp4/vod

List available MP4 files for on-demand playback.

VOD Playback

GET /mp4/vod/{filename}

Play a specific MP4 recording file directly. Responds with Content-Type: video/mp4 and supports Accept-Ranges header for resumable downloads.

Request example:

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

Plugin Info

GET /mp4/

Returns plugin version and list of available endpoints.

Auto-Cleanup

When expire_days or disk_max_percent is configured, the MP4 plugin automatically runs a cleanup task every hour:

• Expiration-based: Deletes recording files older than expire_days days
• Disk usage-based: When disk usage exceeds disk_max_percent, deletes recording files from oldest to newest

Database Integration

The MP4 plugin obtains DatabaseApi through EngineContext, supporting persistence of recording metadata (stream path, file path, duration, size, start/end time) to a database. Supports SQLite, MySQL, and PostgreSQL backends.

Integration with the Crontab Plugin

Combined with the crontab plugin, scheduled recording can be achieved:

crontab:
  jobs:
    - name: "Daily recording"
      cron: "0 8 * * *"
      action: "record_start"
      stream: "live/camera01"
      duration: 28800  # Record for 8 hours