Struct HlsClient 

pub struct HlsClient { /* private fields */ }

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

HlsClient never touches a socket or a clock. The caller drives it:

1. HlsClient::new seeds the first Action::FetchPlaylist; drain it with HlsClient::poll and perform the GET.
2. Feed the response back with HlsClient::on_playlist (playlist) or HlsClient::on_resource (init/part/segment bytes) — Action::FetchResource’s id correlates the two.
3. Drain HlsClient::poll again for the next round of actions (a new reload, newly discoverable parts, a preload-hint prefetch, …) and HlsClient::next_output for newly available Outputs.

Behaviour

• Reload scheduling (issue #717 slice 2): once a playlist advertises EXT-X-SERVER-CONTROL/EXT-X-PART-INF and the origin’s CAN-BLOCK-RELOAD attribute is YES (broadcast_hls::LowLatencyConfig::can_block_reload is true — not merely broadcast_hls::MediaPlaylist::low_latency being Some, since an origin may carry parts/PART-INF while still advertising CAN-BLOCK-RELOAD=NO), every reload is a Blocking Playlist Reload (RFC 8216bis §6.2.5.2) naming the next not-yet-seen Partial Segment’s _HLS_msn/_HLS_part. Otherwise reloads are plain GETs paced by an Action::WaitMs hint derived from #EXT-X-TARGETDURATION. EXT-X-SKIP/CAN-SKIP-UNTIL Playlist Delta Updates (RFC 8216bis §4.4.5.2) are requested once a full-playlist baseline exists, and merged back into a full view before further processing — see merge_delta internally.
• Fetch pipeline (slice 3): the EXT-X-PRELOAD-HINTed part is fetched ahead of its own appearance as a numbered EXT-X-PART; BYTERANGE parts are supported, including the RFC 8216bis §4.4.4.9 “omitted offset means immediately after the previous sub-range of the same resource” rule (tracked per resource URL). The Media Initialization Section (EXT-X-MAP) is fetched once and reused for every following resource until the map changes.
• Dedup / coalescing: once any of a segment’s parts have been individually fetched, that segment is never re-fetched whole — when it later closes (#EXTINF+URI), the client only fetches whichever of its parts (if any) are still missing, and marks the segment “delivered” once every part is accounted for (fetched, or GAP=YES). A playlist whose segments carry no parts at all (a non-LL origin) falls back to fetching the whole segment resource — the two paths never overlap for a single segment, so a part’s samples are never double-counted against its parent’s.
• Output adapter (slice 4): exactly one Output::Init precedes any Output::Samples; parts/segments are demuxed via transmux::Fmp4Demux (by concatenating the cached init bytes with the fetched resource — this crate never re-implements ISOBMFF box parsing, only reuses transmux’s), so Output::Samples carries real access units, not opaque container bytes. #EXT-X-DISCONTINUITY on a segment surfaces as Output::Discontinuity immediately before that segment’s first samples. Known limitation: an in-progress (OpenSegment) segment carries no discontinuity flag of its own (only a closed MediaSegment does) — if every part of a segment was already delivered while it was still open, a discontinuity revealed only once it closes is signalled late (after those parts’ samples, not before). This is a gap in the current wire model (broadcast_hls::OpenSegment), not something this crate can fix locally.
• Classic MPEG-TS-segment HLS (issue #760): a playlist that never advertises an EXT-X-MAP (HLS v3, the dominant legacy/IPTV form — self-contained .ts segments carrying their own PAT/PMT/PES, no separate init resource) routes each fetched Part/Segment through transmux::TsDemux instead, content-sniffed by the MPEG-TS sync byte rather than blocked on an init fetch that will never come. The first successfully demuxed segment’s recovered TrackSpecs synthesize the one Output::Init this crate’s contract requires (via transmux::build_init_segment) so downstream callers (e.g. multimux’s HlsPull, which recovers track specs from Output::Init) need no TS-specific handling of their own. The fMP4/CMAF plus LL (parts/preload-hint) path above is entirely unchanged; the two never overlap for a single playlist.

Implementations

impl HlsClient

pub fn new(playlist_url: impl Into<String>) -> Self

Create a new client for the Media Playlist at playlist_url, seeding the first Action::FetchPlaylist (a plain, non-blocking GET — the client does not yet know whether the origin supports blocking reload).

Examples found in repository

examples/client_stepping.rs (line 93)

fn main() {
    let playlist = canned_playlist();
    println!("--- canned media.m3u8 ---\n{playlist}");

    let mut client = HlsClient::new(PLAYLIST_URL);

    // The client always seeds a plain (non-blocking) GET first — it hasn't
    // seen a playlist yet, so it doesn't know the origin supports blocking
    // reload.
    match client.poll() {
        Some(Action::FetchPlaylist {
            url,
            blocking,
            skip,
        }) => {
            assert_eq!(url, PLAYLIST_URL);
            assert!(blocking.is_none());
            assert!(!skip);
            println!("action: FetchPlaylist {{ url: {url:?}, blocking: None }}");
        }
        other => panic!("expected the seeded FetchPlaylist, got {other:?}"),
    }

    // Feed the canned playlist in response to that (imagined) GET — no HTTP
    // client is ever involved.
    client
        .on_playlist(playlist.as_bytes())
        .expect("the canned playlist parses");

    // Drain every action the client now wants performed: the closed
    // segment's bytes, the open segment's landed part, the init segment
    // (from `#EXT-X-MAP`), the preload-hinted next part, and finally a
    // Blocking Playlist Reload naming the next Media Sequence Number/part.
    let mut saw_blocking_reload = false;
    while let Some(action) = client.poll() {
        match &action {
            Action::FetchResource { id, url, .. } => {
                println!("action: FetchResource {{ id: {id:?}, url: {url:?} }}");
            }
            Action::FetchPlaylist {
                url,
                blocking: Some(b),
                ..
            } => {
                println!(
                    "action: FetchPlaylist {{ url: {url:?}, blocking: {b:?} }}  <- blocking reload"
                );
                saw_blocking_reload = true;
            }
            Action::FetchPlaylist {
                url,
                blocking: None,
                ..
            } => {
                println!("action: FetchPlaylist {{ url: {url:?}, blocking: None }}");
            }
            Action::WaitMs(ms) => println!("action: WaitMs({ms})"),
            // `Action` is `#[non_exhaustive]` — a future variant is simply
            // not printed by this demo, not a compile break.
            _ => {}
        }
    }
    assert!(
        saw_blocking_reload,
        "this crate's own origin renderer defaults CAN-BLOCK-RELOAD=YES, so the \
         next reload the client schedules must be a blocking one"
    );
}

pub fn playlist_url(&self) -> &str

The Media Playlist URL this client is following.

pub fn poll(&mut self) -> Option<Action>

Drain the next IO Action the caller must perform, if any.

Examples found in repository

examples/client_stepping.rs (line 98)

fn main() {
    let playlist = canned_playlist();
    println!("--- canned media.m3u8 ---\n{playlist}");

    let mut client = HlsClient::new(PLAYLIST_URL);

    // The client always seeds a plain (non-blocking) GET first — it hasn't
    // seen a playlist yet, so it doesn't know the origin supports blocking
    // reload.
    match client.poll() {
        Some(Action::FetchPlaylist {
            url,
            blocking,
            skip,
        }) => {
            assert_eq!(url, PLAYLIST_URL);
            assert!(blocking.is_none());
            assert!(!skip);
            println!("action: FetchPlaylist {{ url: {url:?}, blocking: None }}");
        }
        other => panic!("expected the seeded FetchPlaylist, got {other:?}"),
    }

    // Feed the canned playlist in response to that (imagined) GET — no HTTP
    // client is ever involved.
    client
        .on_playlist(playlist.as_bytes())
        .expect("the canned playlist parses");

    // Drain every action the client now wants performed: the closed
    // segment's bytes, the open segment's landed part, the init segment
    // (from `#EXT-X-MAP`), the preload-hinted next part, and finally a
    // Blocking Playlist Reload naming the next Media Sequence Number/part.
    let mut saw_blocking_reload = false;
    while let Some(action) = client.poll() {
        match &action {
            Action::FetchResource { id, url, .. } => {
                println!("action: FetchResource {{ id: {id:?}, url: {url:?} }}");
            }
            Action::FetchPlaylist {
                url,
                blocking: Some(b),
                ..
            } => {
                println!(
                    "action: FetchPlaylist {{ url: {url:?}, blocking: {b:?} }}  <- blocking reload"
                );
                saw_blocking_reload = true;
            }
            Action::FetchPlaylist {
                url,
                blocking: None,
                ..
            } => {
                println!("action: FetchPlaylist {{ url: {url:?}, blocking: None }}");
            }
            Action::WaitMs(ms) => println!("action: WaitMs({ms})"),
            // `Action` is `#[non_exhaustive]` — a future variant is simply
            // not printed by this demo, not a compile break.
            _ => {}
        }
    }
    assert!(
        saw_blocking_reload,
        "this crate's own origin renderer defaults CAN-BLOCK-RELOAD=YES, so the \
         next reload the client schedules must be a blocking one"
    );
}

pub fn next_output(&mut self) -> Option<Output>

Drain the next Output event, if any.

pub fn on_playlist(&mut self, bytes: &[u8]) -> Result<()>

Feed a freshly fetched Media Playlist response.

Errors

Error::PlaylistNotUtf8 / Error::PlaylistParse on malformed input.

Examples found in repository

examples/client_stepping.rs (line 115)

fn main() {
    let playlist = canned_playlist();
    println!("--- canned media.m3u8 ---\n{playlist}");

    let mut client = HlsClient::new(PLAYLIST_URL);

    // The client always seeds a plain (non-blocking) GET first — it hasn't
    // seen a playlist yet, so it doesn't know the origin supports blocking
    // reload.
    match client.poll() {
        Some(Action::FetchPlaylist {
            url,
            blocking,
            skip,
        }) => {
            assert_eq!(url, PLAYLIST_URL);
            assert!(blocking.is_none());
            assert!(!skip);
            println!("action: FetchPlaylist {{ url: {url:?}, blocking: None }}");
        }
        other => panic!("expected the seeded FetchPlaylist, got {other:?}"),
    }

    // Feed the canned playlist in response to that (imagined) GET — no HTTP
    // client is ever involved.
    client
        .on_playlist(playlist.as_bytes())
        .expect("the canned playlist parses");

    // Drain every action the client now wants performed: the closed
    // segment's bytes, the open segment's landed part, the init segment
    // (from `#EXT-X-MAP`), the preload-hinted next part, and finally a
    // Blocking Playlist Reload naming the next Media Sequence Number/part.
    let mut saw_blocking_reload = false;
    while let Some(action) = client.poll() {
        match &action {
            Action::FetchResource { id, url, .. } => {
                println!("action: FetchResource {{ id: {id:?}, url: {url:?} }}");
            }
            Action::FetchPlaylist {
                url,
                blocking: Some(b),
                ..
            } => {
                println!(
                    "action: FetchPlaylist {{ url: {url:?}, blocking: {b:?} }}  <- blocking reload"
                );
                saw_blocking_reload = true;
            }
            Action::FetchPlaylist {
                url,
                blocking: None,
                ..
            } => {
                println!("action: FetchPlaylist {{ url: {url:?}, blocking: None }}");
            }
            Action::WaitMs(ms) => println!("action: WaitMs({ms})"),
            // `Action` is `#[non_exhaustive]` — a future variant is simply
            // not printed by this demo, not a compile break.
            _ => {}
        }
    }
    assert!(
        saw_blocking_reload,
        "this crate's own origin renderer defaults CAN-BLOCK-RELOAD=YES, so the \
         next reload the client schedules must be a blocking one"
    );
}

pub fn on_resource(&mut self, id: ResourceId, bytes: &[u8]) -> Result<()>

Feed the bytes fetched for a previously requested ResourceId (init/part/segment). Part/Segment resources delivered before the init segment are buffered internally and demuxed once the init arrives — the caller’s fetches may complete in any order.

Errors

Error::UnrequestedResource if id was never requested (the requested bookkeeping — or, for Init, init_uri — has no record of it): a caller/driver bug, or a stale/duplicate delivery after the client already moved past this id. Error::Demux if transmux::Fmp4Demux rejects the concatenation of the cached init + bytes.

pub fn on_error(&mut self, id: Option<ResourceId>)

Report that a previously requested ResourceId (or the playlist itself, via None) failed. Clears the id’s “requested” bookkeeping so the next Self::on_playlist call naturally re-requests it (no automatic retry timer — the caller drives retry cadence).

Trait Implementations

impl Debug for HlsClient

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.