Module client 

LL-HLS playback client engine — a sans-IO Low-Latency HLS (RFC 8216bis) client (issue #717, slices 2-4; the client module of hls-runtime — see docs/superpowers/specs/2026-07-18-multimux-hub-design.md).

HlsClient is a driveable, caller-driven state machine — the same sans-IO shape as srt-runtime (issue #565): the core never opens a socket or reads a clock. The caller drains Actions (what to fetch, and how), performs the IO itself, and feeds the response back in via HlsClient::on_playlist / HlsClient::on_resource / HlsClient::on_error; decoded Outputs (the init segment, then ordered access units) drain out via HlsClient::next_output.

Reuse, not re-description

This module defines no playlist model of its own. Parsing is broadcast_hls::MediaPlaylist::parse (issue #717 slice 1 — the symmetric inverse of the LL-HLS origin’s own to_m3u8() renderer, so origin and client share one wire model); demuxing a fetched CMAF part or segment into access units is transmux::Fmp4Demux. client holds only the client engine: the reload scheduler, the fetch pipeline (prefetch/byte-range/dedup), and the output ordering — see HlsClient’s docs for the full behaviour.

Zero IO in the core

No tokio/reqwest/socket dependency in HlsClient itself, ever — it is driveable by hand (see the crate’s hls-runtime/tests/it/origin_loop.rs for a complete in-process example against a real transmux::ll_hls::LlHlsSegmenter origin) with zero IO dependencies at all (verified by the --no-default-features gate).

Example

use hls_runtime::client::{Action, HlsClient};

let mut client = HlsClient::new(hls_runtime::client::HlsClientConfig::new("http://origin/live/stream.m3u8"));
// The caller performs this GET; here we just inspect the first action.
match client.poll() {
    Some(Action::FetchPlaylist { url, blocking, .. }) => {
        assert_eq!(url, "http://origin/live/stream.m3u8");
        assert!(blocking.is_none()); // nothing fetched yet, so no LL info.
    }
    other => panic!("unexpected first action: {other:?}"),
}

Structs

BlockingReload

A pending blocking Playlist Reload request (RFC 8216bis §6.2.5.2): the client has consumed the playlist up to (and possibly including) a given Partial Segment and wants the server to hold the response until something newer exists.

HlsClient

A driveable, sans-IO Low-Latency HLS (RFC 8216bis) playback client.

HlsClientConfig

What an HlsClient is configured by: the playlist it follows and how it chooses variants.

KeyId

Identifies one decryption key resource, assigned by the client per distinct absolute key URI (RFC 8216 §4.3.2.4). Correlates an Action::FetchKey with the matching crate::client::HlsClient::on_key call.

MasterSelection

The result of selecting a variant from a master playlist.

RenditionInfo

Information about one #EXT-X-MEDIA rendition in a master playlist.

VariantInfo

Information about one variant stream in a master playlist.

VariantPolicy

Policy for choosing a variant from a multivariant (master) playlist.

Enums

Action

One unit of IO the caller must perform, in response to a crate::client::HlsClient::poll call. The client core never touches a socket or a clock itself — every Action names exactly what to fetch and, for a playlist reload, how to shape the request.

Error

Error variants crate::client::HlsClient can return.

Output

One unit of decoded output, drained in order via crate::client::HlsClient::next_output.

ResourceId

Identifies one fetchable resource: the initialisation segment, a Low-Latency HLS partial segment (“part”, RFC 8216bis §4.4.4.9), or a whole media segment. Used to correlate an Action::FetchResource with the matching crate::client::HlsClient::on_resource call.

Functions

choose_variant

Choose a variant index according to the policy: the highest-bandwidth variant the policy allows, else the lowest-bandwidth one when it allows none; 0 for an empty list.

Type Aliases

Result

Crate-wide result alias.