HLS Protocol

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)
Feature Flag	`hls`

Configuration

Feature Activation

[features]
hls = ["dep:plugin-hls"]

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

URL Format

M3U8 Playlist

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

TS Segments

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

Examples:

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

Playback

Using FFplay

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

Using VLC

Open VLC, select Media → Open Network Stream
Enter URL: http://localhost:8080/hls/live/test/index.m3u8
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:8080/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:8080/hls/live/test/index.m3u8';
    video.play();
  }
</script>

HLS Recording

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

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

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

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

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

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

How It Works

Stream subscription: When an HLS playlist is first requested, the plugin automatically subscribes to the corresponding stream
Segment generation: Continuously reads frame data from the stream and splits it into TS segments based on segment_duration
Playlist update: Automatically updates the M3U8 playlist each time a new segment is generated
Sliding window: Retains the most recent max_segments segments; older segments are automatically cleaned up
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.

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:8080/hls/live/test/index.m3u8

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