HLS Plugin ¶

Description ¶

The HLS output handler publishes frames from an RT instance as an in-memory HLS stream. In RT 2026.2.1, it produces an M3U8 playlist and MPEG-TS video segments through the instance webserver.

This guide describes the RT 2026.2.1 source contract. The HLS handler exposes one configuration setting; its codec, frame rate, retention, and dimensions are implementation behavior, not HLS configuration controls.

Requirements ¶

An RT runtime with the HLS and Output plugins loaded.
An active instance whose selected output sink supplies image frames.
The instance webserver enabled and reachable by the intended client.

Configuration ¶

HLS handler configuration ¶

Configure HLS under the instance's Output.handlers map. HLS-specific settings belong in the nested config object:

{
  "Output": {
    "handlers": {
      "hls": {
        "uri": "hls://",
        "sink": "output",
        "enabled": true,
        "config": {
          "segment_duration": 2
        }
      }
    }
  }
}

segment_duration must be nested below config. A value placed alongside uri, sink, or enabled is not passed to the HLS handler.

Configuration reference ¶

Parameter	Type	Default	Description
`uri`	string	required	An HLS URI such as `hls://`. Its path is not the published stream name.
`sink`	string	`output`	Name of the Output sink whose image data is published.
`enabled`	boolean	`true`	Enables or disables creation of this generic Output handler.
`config.segment_duration`	integer	`2`	HLS segment-duration value in seconds. Use a positive integer; RT does not expose a documented range validation for this field.

The configured duration is written to #EXT-X-TARGETDURATION and #EXTINF in the playlist. A segment closes after the output duration exceeds that value, so the media duration is not guaranteed to be exactly the configured integer.

Fixed behavior in RT 2026.2.1 ¶

The following behavior is built into the implementation and cannot be changed through HLS handler configuration:

The stream is named after the active instance ID, not the handler key or the hls:// URI path.
The playlist retains at most five in-memory segments. Only completed segments are listed, so a playlist can contain fewer than five entries.
Video is encoded as H.264 Baseline in MPEG-TS with a fixed 800000 bit/s encoder target. FFmpeg inspection reports the emitted profile as Constrained Baseline. The handler does not create an audio stream.
HLS output cadence is fixed at 10 FPS.
Width and height come from the input frame when a segment is opened; the HLS handler does not provide a resize control.
CORS response headers are provided by the implementation. The handler has no per-stream CORS or connection-limit settings.
Multiple handlers in one instance do not create configurable bitrate renditions or an adaptive-bitrate stream.

Do not add max_segments, codec, bitrate, fps, resolution, cors_enabled, cors_origins, or max_connections to the HLS handler configuration. They are not HLS settings consumed by RT 2026.2.1.

Stream access ¶

The built-in webserver exposes the playlist at:

http://<host>:<webserver-port>/hls/<instance-id>.m3u8

Segments referenced by the playlist use:

/hls/<instance-id>/<segment-id>.ts

<webserver-port> is the port of the instance webserver. It is not configured under Output or by the HLS handler. <segment-id> is generated when the segment completes and must be read from the current playlist.

Lua example ¶

The Output Lua binding can create the same handler programmatically:

local output = api.factory.output.create(instance, "Output")

local hls = output:addHandler(
  "hls",
  "hls://",
  "output",
  {
    segment_duration = 2
  }
)

The handler name (hls in this example) manages the Output handler only. Use the active instance ID, rather than that name, in the playback URL.

Verify a stream ¶

After the instance is producing frames, fetch the playlist and one referenced segment from the same webserver:

playlist_url="http://<host>:<webserver-port>/hls/<instance-id>.m3u8"
if ! curl -fsS "$playlist_url" -o playlist.m3u8; then
  echo "Could not fetch the HLS playlist; verify the instance and webserver, then retry." >&2
  exit 1
fi

segment=$(awk '/^\/hls\/.*\.ts$/ { value = $0 } END { print value }' playlist.m3u8)
if [[ -z "$segment" ]]; then
  echo "No completed HLS segment yet; wait for a segment to complete, then retry." >&2
  exit 1
fi

if ! curl -fsS "http://<host>:<webserver-port>${segment}" -o segment.ts; then
  echo "Could not fetch the completed HLS segment; refresh the playlist and retry." >&2
  exit 1
fi

ffprobe -v error -select_streams v:0 \
  -show_entries stream=codec_name,profile,width,height,r_frame_rate,avg_frame_rate \
  -of default=nw=1 segment.ts

The stream identity should match the instance ID. RT 2026.2.1 source behavior expects H.264 Baseline-compatible video (reported by FFmpeg as Constrained Baseline) at the input-frame dimensions and a 10 FPS output cadence. Verify the active playlist rather than assuming it already contains five completed segments.

Troubleshooting ¶

Playlist returns 404 ¶

Confirm that the instance is running and has produced output frames.
Use the active instance ID in the URL, not the handler key or URI path.
Confirm the webserver host and port used by the instance.

Playlist has no media segments ¶

Wait for a segment to complete; incomplete segments are not emitted in the playlist.
Confirm that the selected Output sink contains image data.
Check the runtime log for Output or HLS handler errors.

Output does not have the required size, frame rate, or bitrate ¶

Those properties are not HLS handler settings in RT 2026.2.1. Prepare frames at the required dimensions before they reach the Output sink; do not rely on unsupported HLS configuration fields.