HLS Server - Monibuca Large-Scale Distribution

HLS (HTTP Live Streaming) is an HTTP-based streaming protocol developed by Apple. By segmenting live streams into TS segments and generating M3U8 playlists, HLS offers excellent CDN compatibility and device coverage, making it the preferred protocol for large-scale distribution.

Basic Information

Property	Value
Transport Layer	HTTP (shares the engine HTTP port)
Publish	❌ Not supported
Subscribe	✅ Supported
Latency	5-30 seconds (depends on segment duration)
Config section	hls

Configuration

Enable plugin

The plugin is included in official binaries; configure it in config.yaml:

Configuration File

hls:
  enable: true
  segment_duration: 6
  max_segments: 5
  output_dir: "./hls"
  write_to_disk: true

Option	Type	Default	Description
enable	bool	true	Whether to enable the HLS plugin
segment_duration	u64	6	TS segment duration (seconds)
max_segments	usize	5	Maximum number of segments retained in the playlist
output_dir	string	"./hls"	Segment file output directory
write_to_disk	bool	true	Whether to write segments to disk
dvr_window	u32	0	Duration-based DVR/rewind retention in seconds; 0 = off. Independent of max_segments (live tail)

Tip

Reducing segment_duration can lower latency but increases request frequency. Typically 2-6 seconds is recommended for live streaming, while 6-10 seconds can be used for VOD scenarios.

DVR / live rewind (opt-in)

With the default dvr_window: 0, behavior is unchanged: the live playlist keeps only max_segments segments.

When dvr_window (seconds) is set, completed segments are retained by accumulated duration on this node, without changing the normal live playlist. Clients select the rewind view via query string:

Query	Behavior
(absent) or _HLS_rewind=NO	Current live tail (byte-identical to DVR-off when rewind is not requested)
_HLS_rewind=YES	EXT-X-PLAYLIST-TYPE:EVENT over retained completed segments (correct MEDIA-SEQUENCE / discontinuities; LL-HLS completed PART lines when enabled)

hls:
  enable: true
  write_to_disk: true          # required for DVR; otherwise a warning is logged and DVR is treated as off
  max_segments: 5              # live tail (unchanged)
  dvr_window: 120              # retain ~2 minutes beyond the live tail

# Live
GET /hls/live/show/index.m3u8

# Rewind (EVENT)
GET /hls/live/show/index.m3u8?_HLS_rewind=YES

ABR: _HLS_rewind=YES on the master propagates to each rendition media URI; each rendition remuxer retains independently.

Caution

• Requires write_to_disk: true. Segment files are deleted only after they leave both the live and DVR windows.
• DVR is node-local and is not synchronized across Origin–Edge cluster nodes. Switching edges or a cold start may yield an empty rewind window.
• HLS DVR export produces an M3U8 + TS VoD snapshot; it is not labeled as MP4. MP4 remux/recording ingestion remains separate follow-up work.

Exporting a DVR Interval as VoD

Retained DVR segments can be atomically exported into a stable HLS VoD asset:

curl -X POST "http://localhost:8180/hls/api/dvr/export" \
  -H "Content-Type: application/json" \
  -d '{
    "stream_path": "live/show",
    "start": 120,
    "end": 135,
    "name": "show-highlight"
  }'

Request fields:

Field	Description
stream_path	Source live stream path
start / end	Inclusive HLS EXT-X-MEDIA-SEQUENCE range; both endpoints must still be retained in this node’s dvr_window
name	Optional asset name; omitted names are generated automatically

The response includes playlist_url, for example:

{
  "status": "ok",
  "playlist_url": "/hls/vod/show-highlight/index.m3u8",
  "segment_count": 16,
  "duration": 48.0
}

The exporter hard-links selected .ts segments into the recordings directory first, falling back to copy across filesystems. It writes index.m3u8.tmp and atomically renames it to index.m3u8; once export succeeds, live DVR eviction can no longer break the VoD asset. Playback still goes through HLS auth:

ffplay http://localhost:8180/hls/vod/show-highlight/index.m3u8

ABR multi-rendition (opt-in)

With the default empty abr: [] (or omitting abr), behavior stays single-rendition: one media playlist per stream path. When you configure hls.abr, Monibuca serves a multivariant master playlist for a logical master path, pointing at each rung’s media index.m3u8.

The HLS plugin only builds the master. Encode/publish each rendition as a separate child stream via the transcode plugin onpub outputs (or another publisher), then let HLS remux those paths.

Config shape

hls:
  enable: true
  abr:
    - master: live/show
      renditions:
        - path: live/show_720p
          bandwidth: 2500000
          resolution: "1280x720"
          codecs: "avc1.64001f,mp4a.40.2"   # optional
        - path: live/show_480p
          bandwidth: 1200000
          resolution: "854x480"

Field	Description
master	Logical master path used in the master URL
renditions	Ordered ladder (highest bitrate first recommended)
path	Stream path for that rung’s media playlist
bandwidth	#EXT-X-STREAM-INF:BANDWIDTH (bps, required, > 0)
resolution	Optional, e.g. 1280x720
codecs	Optional RFC 6381 string

Master URL

Canonical:

GET /hls/<master>/master.m3u8

Example: http://localhost:8180/hls/live/show/master.m3u8

When ABR is configured for that master, /hls/<master>/index.m3u8 and /hls/<master>.m3u8 also return the same multivariant playlist (compatibility shorthand). Prefer master.m3u8. Each rendition media playlist remains /hls/<rendition>/index.m3u8.

End-to-end example (RTMP → transcode → ABR)

1. Publish: ffmpeg -re -i input.mp4 -c copy -f flv rtmp://localhost:1935/live/show
2. Transcode onpub produces live/show_720p / live/show_480p (see Transcode)
3. Configure hls.abr as above
4. Open the master in a player:

ffplay http://localhost:8180/hls/live/show/master.m3u8

Full YAML snippet:

transcode:
  enable: true
  onpub:
    "^live/show$":
      outputs:
        - target: "rtmp://127.0.0.1/live/show_720p"
          options:
            video_codec: "libx264"
            resolution: "1280x720"
            video_bitrate: 2500
            audio_codec: "aac"
            audio_bitrate: 128
        - target: "rtmp://127.0.0.1/live/show_480p"
          options:
            video_codec: "libx264"
            resolution: "854x480"
            video_bitrate: 1200
            audio_codec: "aac"
            audio_bitrate: 96

hls:
  enable: true
  abr:
    - master: live/show
      renditions:
        - path: live/show_720p
          bandwidth: 2500000
          resolution: "1280x720"
          codecs: "avc1.64001f,mp4a.40.2"
        - path: live/show_480p
          bandwidth: 1200000
          resolution: "854x480"

Default unchanged

Empty / omitted abr leaves single-rendition HLS behavior unchanged.

Limitations

• You must configure both transcode (or another rendition publisher) and hls.abr today — no auto-wiring.
• The ABR master is standard HLS multivariant; each media playlist may still use LL-HLS independently. This MVP does not coordinate multivariant LL-HLS.
• abr is not hot-reloadable; restart after changes.

URL Format

M3U8 Playlist

http://host:port/hls/{streamPath}/index.m3u8

ABR master (when configured):

http://host:port/hls/{masterPath}/master.m3u8

TS Segments

http://host:port/hls/{streamPath}/{sequence}.ts

Examples:

http://localhost:8180/hls/live/test/index.m3u8
http://localhost:8180/hls/live/test/0.ts

Playback

Using FFplay

ffplay http://localhost:8180/hls/live/test/index.m3u8

Using VLC

1. Open VLC, select Media → Open Network Stream
2. Enter URL: http://localhost:8180/hls/live/test/index.m3u8
3. Click Play

Browser Playback

Use hls.js for browser playback:

<script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
<video id="player" controls></video>
<script>
  const video = document.getElementById('player');
  if (Hls.isSupported()) {
    const hls = new Hls();
    hls.loadSource('http://localhost:8180/hls/live/test/index.m3u8');
    hls.attachMedia(video);
    hls.on(Hls.Events.MANIFEST_PARSED, () => video.play());
  } else if (video.canPlayType('application/vnd.apple.mpegurl')) {
    // Safari native support
    video.src = 'http://localhost:8180/hls/live/test/index.m3u8';
    video.play();
  }
</script>

Note

Safari natively supports HLS without requiring hls.js.

HLS Recording

The HLS plugin provides a recording API to record streams in HLS format (M3U8 + TS files):

The recording playlist stays open while capture is active and receives EXT-X-ENDLIST only on stop. Completed recording segments are retained independently of the live max_segments window; plan and monitor disk capacity for long recordings.

# Start recording
curl -X POST http://localhost:8180/hls/record/start/live/test

# Stop recording
curl -X POST http://localhost:8180/hls/record/stop/live/test

# List recordings
curl http://localhost:8180/hls/record/list

# Check recording status
curl http://localhost:8180/hls/record/status/live/test

# Query historical recordings
curl http://localhost:8180/hls/record/records

How It Works

1. Stream subscription: When an HLS playlist is first requested, the plugin automatically subscribes to the corresponding stream
2. Segment generation: Continuously reads frame data from the stream and splits it into TS segments based on segment_duration
3. Playlist update: Automatically updates the M3U8 playlist each time a new segment is generated
4. Sliding window: Retains the most recent max_segments segments; older segments are automatically cleaned up
5. Storage strategy: Segments are stored in both memory and disk (depending on write_to_disk configuration)

Latency Optimization

HLS latency is primarily determined by the following factors:

Total latency ≈ segment_duration × (max_segments - 1) + player buffer

Optimization recommendations:

# Low-latency configuration
hls:
  segment_duration: 2
  max_segments: 3

With this configuration, the theoretical minimum latency is approximately 4-6 seconds.

Caution

Excessively short segment durations may cause players to make frequent requests, which can actually degrade the experience on lossy networks. Please balance based on your actual use case.

Typical Workflow

# 1. Publish via RTMP
ffmpeg -re -i input.mp4 -c copy -f flv rtmp://localhost:1935/live/test

# 2. Subscribe via HLS
ffplay http://localhost:8180/hls/live/test/index.m3u8

# 3. You can also subscribe via other protocols simultaneously
ffplay http://localhost:8180/flv/live/test.flv