Skip to content

FILE

media.ingest.file

Description

The file input turns a local MP4 or Matroska file into a proper live stream: the file plays in a loop. This is a production tool for filler channels: a "we'll be right back" technical channel, a promo channel, and a fallback when sources go down.

Configuration

Configure the stream through the central API. Stream configuration fragment:

streams:
  - name: promo
    inputs:
    - file:
        path: /storage/promo.mp4
    dvr: {}

Parameters

Parameter Description
path MP4 or Matroska file path on the streamer. The Sapsan process must be able to read it.

Transport options

Local filesystem, MP4 or Matroska container. Playback loops; no network connection is required.

Supported codecs

  • H.264
  • HEVC / H.265
  • AV1
  • JPEG (MP4)
  • AAC
  • AC-3
  • E-AC-3
  • MPEG Audio (MP4: Layer II / III; Matroska: MP3)
  • Opus

MP4 and Matroska are containers. The Matroska reader handles .mkv and .webm files; other paths use the MP4 reader. Matroska video supports H.264, HEVC and AV1; JPEG applies to MP4. In MP4, AV1 requires av01/av1C, Opus requires Opus/dOps, and MPEG Audio is identified through esds or an MP3 sample entry. The mp4a sample entry alone does not mean AAC. Reading compressed file frames does not automatically transcode them.

Error handling

Input state and failure cause are available in stream statistics. Connection loss or missing frames uses the shared retry and failover mechanisms.

Applying changes

Apply changes through the central API. Changing the source address or format reopens capture and may interrupt ingest while connecting. Check input state and arriving frames afterwards.

Counters

The tables give exact protocol statistics field names, including event counters and current-value gauges. Zero fields may be omitted. API and Prometheus expose different projections; the full list is not necessarily present in one Admin API response. Detailed statistics depend on the counter license.

Common input totals: bytes, frames, errors, warnings. They aggregate protocol data and must not be added to protocol counters again.

FilePlay

Field Type
bytes counter
frames counter
memory_bytes gauge

Other details

Preparing the file with ffmpeg

For an MBR file to play seamlessly, all qualities must be perfectly aligned: identical timestamps and keyframes in the same places. This is achieved with a single ffmpeg run using the split filter:

ffmpeg -y -i source.mkv \
  -filter_complex "\
[0:v:0]split=3[vhi][vme][vlo]; \
[vhi]scale=1920:1080:force_original_aspect_ratio=decrease,pad=1920:1080:(ow-iw)/2:(oh-ih)/2,setsar=1,fps=25,setpts=PTS-STARTPTS[v1]; \
[vme]scale=1280:720:force_original_aspect_ratio=decrease,pad=1280:720:(ow-iw)/2:(oh-ih)/2,setsar=1,fps=25,setpts=PTS-STARTPTS[v2]; \
[vlo]scale=960:540:force_original_aspect_ratio=decrease,pad=960:540:(ow-iw)/2:(oh-ih)/2,setsar=1,fps=25,setpts=PTS-STARTPTS[v3]" \
  -map "[v1]" -c:v:0 libx264 -b:v:0 6000k -g:v:0 100 -keyint_min:v:0 100 \
    -sc_threshold:v:0 0 -x264-params:v:0 "scenecut=0:open_gop=0" \
  -map "[v2]" -c:v:1 libx264 -b:v:1 3000k -g:v:1 100 -keyint_min:v:1 100 \
    -sc_threshold:v:1 0 -x264-params:v:1 "scenecut=0:open_gop=0" \
  -map "[v3]" -c:v:2 libx264 -b:v:2 1200k -g:v:2 100 -keyint_min:v:2 100 \
    -sc_threshold:v:2 0 -x264-params:v:2 "scenecut=0:open_gop=0" \
  -map 0:a:0 -c:a:0 aac -b:a:0 192k -ac 2 -ar 48000 \
  -metadata:s:v:0 title="1080p" -metadata:s:v:1 title="720p" -metadata:s:v:2 title="540p" \
  -metadata:s:a:0 language=eng \
  -movflags +faststart \
  promo.mp4

What matters here:

  • one run, one source, split — all qualities get identical timestamps;
  • setpts=PTS-STARTPTS — each quality's timeline starts at zero;
  • the same fps in all qualities;
  • rigid GOP: -g = -keyint_min, -sc_threshold 0 and scenecut=0:open_gop=0 — keyframes strictly every N frames in the same places; the encoder may not insert them on scene changes;
  • AAC audio at 48 kHz stereo;
  • -movflags +faststart — the index at the front of the file;
  • -metadata:s:v title=... / language=... — quality labels and track languages end up in the playlists.

A complete working example with multiple audio tracks lives in the sapsan repository: storage/king.sh.

Verification

Open http://server/streaming/v/promo/index.m3u8 — the master playlist must list all qualities, and switching between them must not stutter.

Next steps