HLS for browsers and apps ​

HLS (HTTP Live Streaming) splits audio into small files plus a playlist. Browsers and phone apps handle it well, and it passes through CDNs and strict networks that block long-lived connections. Your normal mount stream keeps working alongside it.

Looking to relay someone else's HLS stream?

This page is about serving HLS from Quikcast. To pull an existing HLS station into one of your mounts as a normal stream, see Relay an HLS stream.

HLS needs a producer

Quikcast serves HLS but does not create it. Something else must encode the segments and either write them to a directory Quikcast serves, or upload them through the private ingest API (FFmpeg plus a small script, or your own application). Quikcast validates uploads, keeps them in memory, writes the playlists and serves them. It never re-encodes.

1. Turn HLS on ​

toml
[hls]
username = "hls"
secret_file = "secrets/hls-ingest"
cors_origin = "https://player.example.com"
  • The ingest password must be different from every mount password.
  • cors_origin lets a website on that exact origin play your HLS in a browser. Leave it out if you only serve apps.

Everything else has defaults. See [hls] in the reference for capacity settings.

2. Publish a stream ​

A producer makes these calls with HTTP Basic authentication (the HLS username and password) to the private admin address (admin_listen, default 127.0.0.1:9090) under /internal/v1/hls/. Players use the public address. Run the producer on the same machine, or reach the admin port through an SSH tunnel; never expose it to the internet.

StepRequest
Create the streamPUT /internal/v1/hls/streams/radio
Create a rendition (one quality level)PUT /internal/v1/hls/streams/radio/renditions/aac with a JSON description
Upload each segmentPUT .../renditions/aac/segments/0, .../1, and so on
Publish the playlistPUT .../renditions/aac/publication
Publish the master playlistPUT /internal/v1/hls/streams/radio/master

A complete example you can run ​

This bash and curl script makes three 2-second AAC segments with FFmpeg, uploads them and publishes the playlists.

sh
HLS=http://127.0.0.1:9090/internal/v1/hls/streams
PW=$(cat secrets/hls-ingest)
c() { curl -s -u "hls:$PW" "$@"; }                       # authenticated curl
gen() { sed -E 's/.*"generation":"([0-9]+)".*/\1/'; }     # pull the generation out of a reply

# Make three test segments (replace with your real encoder output)
for n in 0 1 2; do
  ffmpeg -loglevel error -y -f lavfi -i "sine=frequency=$((440 + n * 220)):duration=2" \
    -c:a aac -b:a 128k -f mpegts seg$n.ts
done

# 1. Create the stream. Keep the generation it returns.
SG=$(c -X PUT $HLS/radio | gen)

# 2. Create a rendition (one quality level).
RG=$(c -X PUT $HLS/radio/renditions/aac \
  -H 'Content-Type: application/json' -H "X-HLS-Generation: $SG" \
  -d '{"target_duration":2,"window_segments":6,"bandwidth":128000,"codecs":"mp4a.40.2"}' | gen)

# 3. Upload the segments.
for n in 0 1 2; do
  c -X PUT $HLS/radio/renditions/aac/segments/$n \
    -H "X-HLS-Generation: $SG" -H "X-HLS-Rendition-Generation: $RG" \
    -H "X-HLS-Duration-Ms: 2000" -H "Content-Type: video/mp2t" --data-binary @seg$n.ts
done

# 4. Publish the media playlist, then the master playlist.
c -X PUT $HLS/radio/renditions/aac/publication \
  -H 'Content-Type: application/json' -H "X-HLS-Generation: $SG" -H "X-HLS-Rendition-Generation: $RG" \
  -d '{"expected_revision":0,"segments":[{"sequence":0,"duration_ms":2000},{"sequence":1,"duration_ms":2000},{"sequence":2,"duration_ms":2000}],"end":false}'

c -X PUT $HLS/radio/master \
  -H 'Content-Type: application/json' -H "X-HLS-Generation: $SG" \
  -d '{"expected_revision":0,"renditions":["aac"]}'

Generations are numbers Quikcast gives you

Creating a stream or rendition returns a long number such as 7832260401770470567. Send it back unchanged on later calls; it proves you mean the stream you created, not an older one with the same name.

A real producer keeps uploading new segments and publishing a sliding window (for example the latest six). Every call, header and error is documented in the HLS ingest API reference.

3. Play it ​

text
http://your-server:8000/hls/radio/master.m3u8

Open it in Safari, VLC, or a web player such as hls.js.

Serve HLS from a directory ​

If another program already writes HLS to disk (Liquidsoap's output.file.hls, FFmpeg's hls muxer, any tool that makes .m3u8 playlists and segments), Quikcast can serve that directory directly, with no ingest API or producer password.

toml
[hls]
directory = "/var/lib/radio/hls"
cors_origin = "https://player.example.com"

Every subdirectory is one stream, served at the same public address as ingested HLS:

text
/var/lib/radio/hls/radio/radio.m3u8       ->  /hls/radio/radio.m3u8
/var/lib/radio/hls/radio/radio_12.ts      ->  /hls/radio/radio_12.ts
/var/lib/radio/hls/radio/hq/index.m3u8    ->  /hls/radio/hq/index.m3u8

/hls/radio/master.m3u8 (the name used for ingested streams) also works: it returns master.m3u8 if the directory has one, and otherwise the muxer's own radio.m3u8. Player URLs inside playlists stay relative, so they keep working.

What is served:

  • Only regular files with an HLS extension: .m3u8, .ts, .m4s, .mp4, .aac, .mp3. Everything else is a 404, including .state_*.json files and any other file or directory whose name starts with a dot.
  • Paths that try to leave the stream (.., encoded slashes) are refused. A symlink is followed only if it stays inside the same stream directory, and a stream directory that links outside the root is not served.
  • Playlists are read fresh on every request with Cache-Control: no-cache. Writing a temporary file and renaming it is safe: a request sees the old file or the new one, never a mix. A file rewritten in place while read is retried, and an empty playlist counts as missing.
  • Segments get Cache-Control: public, max-age=3600 (not immutable, since a muxer may reuse a name after a restart). HEAD, single byte Range requests and If-None-Match work as for ingested HLS.
  • Files larger than 16 MiB are not served.

The directory must exist and be readable when Quikcast starts, and --check reports a problem. Changing directory while HLS is on needs a restart (adding or removing [hls] itself applies on reload); files and subdirectories can appear and disappear at any time.

Directory streams share everything else with ingested HLS: cors_origin, signed links ([hls.listener_auth."/hls/NAME"]), the [access] rules and the hls_* metrics. A stream registered through the ingest API takes precedence over a directory with the same name. When directory is set, the ingest secret or secret_file becomes optional: leave both out and the ingest API is switched off.

Counting listeners ​

HLS has no connection to count, so Quikcast reports unique client IPs that fetched a playlist or segment in the last directory_listener_window_secs seconds (default 60; set it to a few segment lengths). These are estimates, not connections: a viewer who closes the tab still counts until the window passes, and several people behind one address count once. Counts reset on restart.

They appear in the console's Listeners total, the Listeners page, its HLS page and the listener history, and in active_listeners of GET /api/stats. The Prometheus active_listeners gauge counts connections only.

GET /api/hls on the admin address lists each directory stream, and GET /api/hls/radio/listeners lists its listener sessions. Fields and session rules are in the management API. Behind a proxy, configure [trusted_proxies] so clients are identified by their real address.

Supported formats ​

AAC (LC, HE-AAC, HE-AACv2) in MPEG-TS, packed .aac or fragmented MP4; packed MP3; and FLAC in fragmented MP4. The exact format and codecs combinations are in the HLS ingest API reference.

Not supported: Ogg or native FLAC in HLS, encryption, video, low-latency HLS and DASH.

Good to know ​

  • Ingested HLS lives in memory. (Directory HLS stays on disk.) Restarting Quikcast clears all HLS content. Your producer must register and upload again.
  • Public URLs are generated for you. Players only need the master playlist address. Everything else comes from it.
  • Protect a stream with signed links if it should not be public.
  • Caching is already tuned. Playlists are no-cache; ingested segments are immutable and cached for a year, which is what CDNs want.