transmux 0.20.0

//! Low-Latency HLS — partial segments (CMAF chunks) + playlist directives.
//!
//! Reference: **RFC 8216bis** (HTTP Live Streaming 2nd Edition, draft-pantos-hls-rfc8216bis).
//!
//! Whole-segment CMAF ([`crate::segmenter::Segmenter`]) produces one
//! `styp`+`moof`+`mdat` per segment, so a client cannot begin a segment until the
//! whole thing exists — latency is at least one segment duration. **Low-Latency
//! HLS** cuts that by publishing each segment's **partial segments** ("parts",
//! RFC 8216bis §4.4.4.9) as they are produced: an independently addressable CMAF
//! chunk (a `moof`+`mdat` fragment) covering a sub-duration of the parent segment,
//! delivered before the parent segment finalizes.
//!
//! # Part structure (ISO/IEC 14496-12:2015)
//!
//! A part is the same fragment structure the batch builder
//! [`crate::build_media_segment`] emits, scoped to the samples of one sub-duration:
//! a bare `moof` (§8.8.4) + `mdat` (§8.1.1). Each part's `moof` carries its own
//! `mfhd.sequence_number` (§8.8.5) — contiguous and increasing across all parts —
//! and each track fragment's `tfdt.baseMediaDecodeTime` (§8.8.12) is the decode
//! time of that part's first sample. **Concatenating a segment's parts reproduces
//! exactly the coded samples, decode order, and per-track decode timeline of the
//! whole-segment [`crate::build_media_segment`] output** — parts split, they never
//! lose, duplicate, or reorder a sample. A part is marked
//! [`PartInfo::independent`] when its first sample is a sync sample
//! (`INDEPENDENT=YES` in the playlist, RFC 8216bis §4.4.4.9).
//!
//! Segment boundaries stay keyframe-aligned (each segment's first part begins on
//! the anchor track's sync sample), exactly as [`crate::segmenter::Segmenter`].
//!
//! # Playlist directives
//!
//! The playlist tags an LL-HLS client needs (`#EXT-X-SERVER-CONTROL`,
//! `#EXT-X-PART-INF`, `#EXT-X-PART`, `#EXT-X-PRELOAD-HINT`) are rendered by
//! [`crate::hls::MediaPlaylist`] when its
//! [`low_latency`](crate::hls::MediaPlaylist::low_latency) config is set; see
//! [`crate::hls`] for the exact RFC 8216bis syntax and sections.

use alloc::collections::VecDeque;
use alloc::vec::Vec;

use broadcast_common::{Demand, Stage, Timestamp};

use crate::error::{Error, Result};
use crate::ll_dash::build_chunk;
use crate::pipeline::{FragmentTrackData, Sample, TrackSpec, build_init_segment};
use crate::segmenter::{
    MAX_PENDING_SAMPLES_PER_TRACK, MediaClock, choose_anchor, no_sync_sample_error,
};

/// One finished LL-HLS **partial segment** ("part") — RFC 8216bis §4.4.4.9.
///
/// The `bytes` are an independent `moof`+`mdat` CMAF chunk; a caller writes them
/// to the part's own URI (`#EXT-X-PART:...,URI="<uri>"`) and can serve them
/// before the parent segment is complete.
#[derive(Debug, Clone)]
pub struct PartInfo {
    /// The part bytes: a bare `moof`+`mdat` fragment (no `styp`).
    pub bytes: Vec<u8>,
    /// Part duration in seconds (the anchor track's buffered duration for this
    /// part) — the `#EXT-X-PART:DURATION` value.
    pub duration: f64,
    /// `true` when this part's first anchor-track sample is a sync sample, so it
    /// begins with an independently decodable frame (`INDEPENDENT=YES`).
    pub independent: bool,
    /// 1-based sequence number of the parent segment this part belongs to.
    pub segment_seq: u32,
    /// 0-based index of this part within its parent segment.
    pub part_index: u32,
}

/// A finished full segment emitted by [`LlHlsSegmenter`] once its parts have all
/// been produced (the parent `styp`+`moof`+`mdat` covering the same samples).
#[derive(Debug, Clone)]
pub struct SegmentInfo {
    /// The whole-segment bytes (`styp`+`moof`+`mdat`), byte-identical to
    /// [`crate::build_media_segment`] for the segment's samples.
    pub bytes: Vec<u8>,
    /// Segment duration in seconds.
    pub duration: f64,
    /// 1-based sequence number of this segment.
    pub segment_seq: u32,
    /// Number of parts that made up this segment.
    pub part_count: u32,
}

/// Per-track accumulation state for the segment currently being built.
struct TrackState {
    spec: TrackSpec,
    /// Samples buffered for the current (not-yet-cut) segment, in decode order.
    /// These are the samples of the whole segment; they are only cleared at the
    /// segment boundary (parts drain a *view* via `part_start`, not the buffer).
    pending: Vec<Sample>,
    /// Index into `pending` of the first sample not yet emitted in a *part*.
    part_start: usize,
    /// `base_media_decode_time` (`tfdt`) of the next *part* for this track =
    /// decode time of `pending[part_start]`.
    part_base_decode: u64,
    /// `base_media_decode_time` of the whole current *segment* for this track =
    /// decode time of `pending[0]`.
    seg_base_decode: u64,
    /// Advances `part_base_decode` past each sample as it is drained into a
    /// part, under the same duration-then-dts-delta rule as the anchor
    /// accumulator (see [`MediaClock`]).
    ///
    /// Deliberately a *different* clock instance from `seg_clock`: the two
    /// accumulators cover the same samples at different granularities (parts
    /// walk `pending` in sub-ranges, the segment walks it once at the
    /// boundary), and a [`MediaClock`]'s dts-delta fallback is only correct
    /// if it sees each sample exactly once. A plain `duration` sum would pin
    /// both at 0 forever on a `duration: Some(0)` stream, collapsing every
    /// part's and segment's `tfdt` onto the same decode time.
    part_clock: MediaClock,
    /// Advances `seg_base_decode` past the whole segment at the boundary —
    /// see `part_clock` for why this is a second, independent clock.
    seg_clock: MediaClock,
}

/// A stateful **Low-Latency HLS** segmenter (RFC 8216bis).
///
/// Same segmentation state machine as [`crate::segmenter::Segmenter`] — segments
/// are cut on the anchor track's sync samples once the segment target is reached —
/// but each segment is additionally sub-divided into **parts**: whenever the
/// anchor track's buffered-since-last-part duration reaches the *part target*, a
/// part (`moof`+`mdat`) is flushed and made available via
/// [`take_ready_parts`](Self::take_ready_parts) before the parent segment closes.
/// When the segment is cut, its remaining tail becomes a final part and the whole
/// segment is emitted via [`take_ready_segments`](Self::take_ready_segments).
///
/// ```
/// use transmux::{CodecConfig, Sample, TrackSpec};
/// use transmux::ll_hls::LlHlsSegmenter;
/// # use transmux::{AVCConfigurationBox, AVCDecoderConfigurationRecord, AvcPps, AvcSps};
/// # fn spec() -> TrackSpec {
/// #     let record = AVCDecoderConfigurationRecord {
/// #         configuration_version: 1,
/// #         profile_indication: 66,
/// #         profile_compatibility: 0,
/// #         level_indication: 30,
/// #         length_size_minus_one: 3,
/// #         sps: vec![AvcSps(vec![0x67, 0x42, 0xc0, 0x1e, 0xd9, 0x00, 0x80, 0x1e, 0x24])],
/// #         pps: vec![AvcPps(vec![0x68, 0xce, 0x3c, 0x80])],
/// #         chroma_format: None,
/// #         bit_depth_luma_minus8: None,
/// #         bit_depth_chroma_minus8: None,
/// #         sps_ext: vec![],
/// #     };
/// #     TrackSpec::new(1, 90_000, CodecConfig::Avc {
/// #         config: AVCConfigurationBox::new(record),
/// #         width: 16,
/// #         height: 16,
/// #     })
/// # }
/// # fn au(sync: bool) -> Sample {
/// #     use std::sync::atomic::{AtomicI64, Ordering};
/// #     static NEXT_DTS: AtomicI64 = AtomicI64::new(0);
/// #     let dts = NEXT_DTS.fetch_add(1000, Ordering::Relaxed);
/// #     Sample::new(vec![0u8; 4], Some(dts), Some(dts), Some(1000), sync)
/// # }
/// // 1 s target segments, ~334 ms parts.
/// let mut seg = LlHlsSegmenter::with_part_target(vec![spec()], 1000, 1.0, 334).unwrap();
/// let init = seg.init_segment().unwrap();      // ftyp + moov
/// assert_eq!(&init[4..8], b"ftyp");
/// seg.push(1, au(true)).unwrap();              // keyframe
/// seg.push(1, au(false)).unwrap();
/// assert!(seg.take_ready_parts().is_empty());  // still buffering: below the part target
/// seg.flush().unwrap();                        // trailing part + segment
/// assert_eq!(seg.take_ready_parts().len(), 1);
/// assert_eq!(seg.take_ready_segments().len(), 1);
/// ```
pub struct LlHlsSegmenter {
    tracks: Vec<TrackState>,
    movie_timescale: u32,
    /// Index into `tracks` of the segmentation anchor (keyframe cut boundary).
    anchor: usize,
    /// Target segment duration in the *anchor track's* media timescale.
    target_ticks: u64,
    /// Target part duration in the *anchor track's* media timescale.
    part_target_ticks: u64,
    /// Buffered duration of the whole current segment on the anchor (ticks).
    anchor_seg_dur: u64,
    /// Buffered duration since the last part flush on the anchor (ticks).
    anchor_part_dur: u64,
    /// Anchor-progress clock: advances *both* accumulators above from each
    /// anchor sample's `duration`, or from its `dts` delta when `duration` is
    /// absent or zero (see [`MediaClock`]).
    anchor_clock: MediaClock,
    /// `mfhd.sequence_number` of the next part/segment `moof`, 1-based, contiguous.
    next_seq: u32,
    /// 1-based number of the segment currently being built.
    current_segment: u32,
    /// 0-based index of the next part within the current segment.
    next_part_index: u32,
    /// Parts and full segments finished but not yet taken by the caller, in
    /// the exact order they were cut. The single source of truth for the
    /// inherent [`take_ready_parts`](Self::take_ready_parts)/
    /// [`take_ready_segments`](Self::take_ready_segments) drains *and*
    /// [`Stage::poll`] — there is no separate staging copy. The inherent
    /// drains filter this queue by variant (each leaving the other kind's
    /// relative order undisturbed); `poll` pops the raw item. Whichever API
    /// (or mix of both) the caller uses, every part and segment is delivered
    /// exactly once.
    ready: VecDeque<LlHlsStageOutput>,
}

impl LlHlsSegmenter {
    /// Create an LL-HLS segmenter for `tracks`, cutting segments roughly every
    /// `target_duration_secs` on the anchor track's keyframes, and flushing a
    /// part whenever the anchor buffers `part_target_ms` milliseconds since the
    /// last part.
    ///
    /// The anchor is chosen by the shared
    /// [`crate::segmenter::choose_anchor`] — the first **video**
    /// track (any codec, not just AVC), falling back to the first
    /// anchor-capable track — exactly as [`crate::segmenter::Segmenter`].
    /// `movie_timescale` matches [`build_init_segment`].
    ///
    /// # Errors
    /// [`Error::InvalidInput`] if `tracks` is empty, has duplicate `track_id`s,
    /// `target_duration_secs` is not positive and finite, `part_target_ms` is 0,
    /// or no track is anchor-capable (every track is section-carried).
    pub fn with_part_target(
        tracks: Vec<TrackSpec>,
        movie_timescale: u32,
        target_duration_secs: f64,
        part_target_ms: u32,
    ) -> Result<Self> {
        if tracks.is_empty() {
            return Err(Error::InvalidInput(
                "ll-hls segmenter needs at least one track",
            ));
        }
        if !(target_duration_secs.is_finite() && target_duration_secs > 0.0) {
            return Err(Error::InvalidInput(
                "target_duration_secs must be positive and finite",
            ));
        }
        if part_target_ms == 0 {
            return Err(Error::InvalidInput("part_target_ms must be >= 1"));
        }
        for (i, a) in tracks.iter().enumerate() {
            if tracks[i + 1..].iter().any(|b| b.track_id == a.track_id) {
                return Err(Error::InvalidInput("duplicate track_id"));
            }
        }

        // MUX = strict but filterable (media plane step-2 fix wave 1,
        // B2-B4): a track `build_init_segment` cannot place into an ISOBMFF
        // `trak` (opaque `CodecConfig::Data` or `CodecConfig::Subtitle`) is
        // no longer silently omitted here — it surfaces the same named
        // error every other mux entry point does, the first time
        // `init_segment`/a part build actually needs the `trak`. The caller
        // must pre-filter first (e.g. with
        // `tracks.retain(|t| t.config.is_muxable_in_bmff())`) if it wants
        // to drop such tracks rather than fail.

        // Anchor = first **video** track (any `CodecConfig::is_video` codec),
        // else the first anchor-capable track — the shared rule
        // `Segmenter`/`ts_hls` use. This used to match only
        // `CodecConfig::Avc`, so an HEVC+AAC media with audio first anchored on
        // the *audio* track: segments did not begin on an IRAP and every part
        // was reported `independent` (audio is all sync samples), advertising
        // `INDEPENDENT=YES` on parts that actually start mid-GOP.
        let anchor = choose_anchor(tracks.iter().map(|t| &t.config))?;

        let anchor_timescale = tracks[anchor].timescale as f64;
        let target_ticks = ((target_duration_secs * anchor_timescale) as u64).max(1);
        // part_target_ms / 1000 * timescale, integer-safe.
        let part_target_ticks =
            ((part_target_ms as u64 * tracks[anchor].timescale as u64) / 1000).max(1);

        let tracks = tracks
            .into_iter()
            .map(|spec| TrackState {
                spec,
                pending: Vec::new(),
                part_start: 0,
                part_base_decode: 0,
                seg_base_decode: 0,
                part_clock: MediaClock::new(),
                seg_clock: MediaClock::new(),
            })
            .collect();

        Ok(Self {
            tracks,
            movie_timescale,
            anchor,
            target_ticks,
            part_target_ticks,
            anchor_seg_dur: 0,
            anchor_part_dur: 0,
            anchor_clock: MediaClock::new(),
            next_seq: 1,
            current_segment: 1,
            next_part_index: 0,
            ready: VecDeque::new(),
        })
    }

    /// The part-target duration in seconds — the `#EXT-X-PART-INF:PART-TARGET`
    /// value a caller should advertise (see [`crate::hls::LowLatencyConfig`]).
    pub fn part_target_secs(&self) -> f64 {
        self.part_target_ticks as f64 / self.tracks[self.anchor].spec.timescale as f64
    }

    /// The initialization segment (`ftyp` + fragmented-init `moov`). Stable for
    /// the life of the segmenter; write it once before any part or segment.
    pub fn init_segment(&self) -> Result<Vec<u8>> {
        let specs: Vec<TrackSpec> = self.tracks.iter().map(|t| t.spec.clone()).collect();
        build_init_segment(&specs, self.movie_timescale)
    }

    /// Push one coded sample for `track_id`, in decode order.
    ///
    /// When the anchor track reaches a sync sample past the segment target, the
    /// current segment is finalized (its trailing samples flushed as a final part,
    /// then the whole segment emitted) *before* this sample is buffered, so the
    /// new keyframe opens the next segment's first part on a random-access point.
    /// Otherwise, once the anchor buffers a part-target's worth of samples since
    /// the last part, a part is flushed.
    ///
    /// Both accumulators advance via [`MediaClock`]: each anchor sample's own
    /// `duration` when that is a real, non-zero span, else the `dts` delta from
    /// the previous anchor sample — `duration` alone stalls on the `Some(0)`
    /// durations live input legitimately produces (no part *and* no segment
    /// would ever be emitted).
    ///
    /// # Errors
    /// [`Error::InvalidInput`] if `track_id` matches no track, a part/segment
    /// build fails, or this track already holds
    /// [`MAX_PENDING_SAMPLES_PER_TRACK`] un-cut samples (no anchor sync sample
    /// to cut on — call [`flush`](Self::flush) to close a trailing partial
    /// segment).
    pub fn push(&mut self, track_id: u32, sample: Sample) -> Result<()> {
        let idx = self
            .tracks
            .iter()
            .position(|t| t.spec.track_id == track_id)
            .ok_or(Error::InvalidInput("push: unknown track_id"))?;

        // Segment boundary: anchor keyframe past target → finalize the segment.
        if idx == self.anchor
            && sample.flags.is_sync
            && self.anchor_seg_dur >= self.target_ticks
            && !self.tracks[self.anchor].pending.is_empty()
        {
            self.finish_segment()?;
        }

        if self.tracks[idx].pending.len() >= MAX_PENDING_SAMPLES_PER_TRACK {
            return Err(no_sync_sample_error());
        }

        if idx == self.anchor {
            let elapsed = self.anchor_clock.tick(&sample);
            self.anchor_seg_dur += elapsed;
            self.anchor_part_dur += elapsed;
        }
        self.tracks[idx].pending.push(sample);

        // Part boundary: the anchor buffered a full part's worth since the last
        // part, but the segment is not yet due to close. Hold the segment's final
        // part for the boundary/flush so trailing non-anchor samples ride it.
        if idx == self.anchor
            && self.anchor_part_dur >= self.part_target_ticks
            && self.anchor_seg_dur < self.target_ticks
        {
            self.emit_part(false)?;
        }
        Ok(())
    }

    /// Finalize the trailing segment at end-of-stream. A no-op if nothing is
    /// buffered. Emits the final part(s) and the whole segment.
    ///
    /// # Errors
    /// Propagates a part/segment build failure.
    pub fn flush(&mut self) -> Result<()> {
        if self.tracks.iter().any(|t| !t.pending.is_empty()) {
            self.finish_segment()?;
        }
        Ok(())
    }

    /// Remove and return every part finished since the last call, in order.
    /// Any not-yet-taken segments remain queued (retrievable via
    /// [`take_ready_segments`](Self::take_ready_segments) or `Stage::poll`),
    /// in their original relative order.
    pub fn take_ready_parts(&mut self) -> Vec<PartInfo> {
        let mut parts = Vec::new();
        let mut remaining = VecDeque::with_capacity(self.ready.len());
        for item in self.ready.drain(..) {
            match item {
                LlHlsStageOutput::Part(p) => parts.push(p),
                other => remaining.push_back(other),
            }
        }
        self.ready = remaining;
        parts
    }

    /// Remove and return every full segment finished since the last call, in
    /// order — distinct from the parts. Any not-yet-taken parts remain
    /// queued (retrievable via [`take_ready_parts`](Self::take_ready_parts)
    /// or `Stage::poll`), in their original relative order.
    pub fn take_ready_segments(&mut self) -> Vec<SegmentInfo> {
        let mut segments = Vec::new();
        let mut remaining = VecDeque::with_capacity(self.ready.len());
        for item in self.ready.drain(..) {
            match item {
                LlHlsStageOutput::Segment(s) => segments.push(s),
                other => remaining.push_back(other),
            }
        }
        self.ready = remaining;
        segments
    }

    /// Finalize the current segment: flush its remaining un-parted samples as a
    /// final part, emit the whole segment, then open the next segment.
    fn finish_segment(&mut self) -> Result<()> {
        // Any samples buffered since the last part become the segment's final
        // part (also carries trailing non-anchor samples).
        let has_tail = self.tracks.iter().any(|t| t.part_start < t.pending.len());
        if has_tail {
            self.emit_part(true)?;
        }

        // Emit the whole segment from all buffered samples (byte-identical to the
        // batch build for the same sample set).
        let seg_seq = self.next_seq;
        let seg_bytes = {
            let frags: Vec<FragmentTrackData<'_>> = self
                .tracks
                .iter()
                .filter(|t| !t.pending.is_empty())
                .map(|t| FragmentTrackData {
                    track_id: t.spec.track_id,
                    base_media_decode_time: t.seg_base_decode,
                    samples: &t.pending,
                })
                .collect();
            crate::pipeline::build_media_segment(seg_seq, &frags)?
        };
        self.next_seq += 1;

        let seg_duration =
            self.anchor_seg_dur as f64 / self.tracks[self.anchor].spec.timescale as f64;
        self.ready.push_back(LlHlsStageOutput::Segment(SegmentInfo {
            bytes: seg_bytes,
            duration: seg_duration,
            segment_seq: self.current_segment,
            part_count: self.next_part_index,
        }));

        // Advance per-track decode times past the whole segment and clear buffers.
        for t in &mut self.tracks {
            let clock = &mut t.seg_clock;
            let dur: u64 = t.pending.iter().map(|s| clock.tick(s)).sum();
            t.seg_base_decode += dur;
            t.part_base_decode = t.seg_base_decode;
            t.pending.clear();
            t.part_start = 0;
        }
        self.anchor_seg_dur = 0;
        self.anchor_part_dur = 0;
        self.current_segment += 1;
        self.next_part_index = 0;
        Ok(())
    }

    /// Emit one part covering the samples buffered since the last part. If
    /// `final_part`, drain every remaining sample of every track; otherwise drain
    /// only the anchor's samples since the last part (non-anchor samples ride the
    /// segment's final part, matching the whole-segment single per-track run).
    fn emit_part(&mut self, final_part: bool) -> Result<()> {
        let anchor = self.anchor;

        // Per track, the [part_start .. end) sample range this part drains.
        let take_ends: Vec<usize> = self
            .tracks
            .iter()
            .enumerate()
            .map(|(i, t)| {
                if final_part || i == anchor {
                    t.pending.len()
                } else {
                    t.part_start
                }
            })
            .collect();

        // Nothing new for any track → skip (keeps sequence numbers meaningful).
        if take_ends
            .iter()
            .zip(&self.tracks)
            .all(|(&end, t)| end == t.part_start)
        {
            return Ok(());
        }

        // Independence: the part's first anchor sample is a sync sample.
        let anchor_state = &self.tracks[anchor];
        let independent = anchor_state
            .pending
            .get(anchor_state.part_start)
            .map(|s| s.flags.is_sync)
            .unwrap_or(false);

        // Part duration = the anchor's buffered-since-last-part duration.
        let part_secs = self.anchor_part_dur as f64 / self.tracks[anchor].spec.timescale as f64;

        let seq = self.next_seq;
        let part_bytes = {
            let frags: Vec<FragmentTrackData<'_>> = self
                .tracks
                .iter()
                .zip(&take_ends)
                .filter(|&(t, &end)| end > t.part_start)
                .map(|(t, &end)| FragmentTrackData {
                    track_id: t.spec.track_id,
                    base_media_decode_time: t.part_base_decode,
                    samples: &t.pending[t.part_start..end],
                })
                .collect();
            // A part is a bare moof+mdat (no styp): with_styp = false.
            build_chunk(seq, &frags, false)?
        };
        self.next_seq += 1;

        // Advance per-track part cursors and part-base decode times. The
        // `[part_start..end)` ranges are contiguous and in decode order across
        // calls, so `part_clock` sees each sample exactly once.
        for (t, &end) in self.tracks.iter_mut().zip(&take_ends) {
            let clock = &mut t.part_clock;
            let dur: u64 = t.pending[t.part_start..end]
                .iter()
                .map(|s| clock.tick(s))
                .sum();
            t.part_base_decode += dur;
            t.part_start = end;
        }

        let part_index = self.next_part_index;
        self.next_part_index += 1;
        self.anchor_part_dur = 0;

        self.ready.push_back(LlHlsStageOutput::Part(PartInfo {
            bytes: part_bytes,
            duration: part_secs,
            independent,
            segment_seq: self.current_segment,
            part_index,
        }));
        Ok(())
    }
}

/// [`LlHlsSegmenter`]'s [`Stage::Out`] — this segmenter drains two distinct
/// kinds of ready output today ([`take_ready_parts`](LlHlsSegmenter::take_ready_parts)
/// / [`take_ready_segments`](LlHlsSegmenter::take_ready_segments)); `Stage`
/// needs one `Out` type, and an enum is the honest way to carry that
/// distinction through rather than silently merging or dropping one kind.
/// Deliberately not unified with any other segmenter's `Out` — see the
/// `stage` module docs on why each implementor states its own shape.
#[derive(Debug, Clone)]
#[non_exhaustive]
pub enum LlHlsStageOutput {
    /// A finished partial segment — see [`PartInfo`].
    Part(PartInfo),
    /// A finished full segment — see [`SegmentInfo`].
    Segment(SegmentInfo),
}

/// [`Stage`] adoption (media plane step 2e-2): `In = (u32, Sample)`, same
/// reasoning as [`crate::segmenter::Segmenter`]'s impl. `Out =
/// [`LlHlsStageOutput`]`, covering both parts and segments (see that type's
/// docs).
///
/// Every inherent method — [`push`](Self::push), [`take_ready_parts`
/// ](Self::take_ready_parts), [`take_ready_segments`](Self::take_ready_segments),
/// [`flush`](Self::flush) — keeps working unchanged; this impl is an
/// additional, uniform way to drive the same engine. [`Stage::poll`] and the
/// inherent `take_ready_parts`/`take_ready_segments` drains all read from the
/// *same* `ready` queue (there is no separate staging copy) — `poll` pops the
/// raw part-or-segment item in exact production order, while each inherent
/// drain filters out its own variant and leaves the other kind queued. So a
/// part or segment is delivered exactly once no matter which API — inherent,
/// `Stage`, or a mix of both on the same instance — the caller uses to
/// retrieve it.
impl Stage for LlHlsSegmenter {
    type In<'a> = (u32, Sample);
    type Out = LlHlsStageOutput;
    type Error = Error;

    fn feed(&mut self, (track_id, sample): Self::In<'_>, _now: Timestamp) -> Result<()> {
        self.push(track_id, sample)
    }

    fn poll(&mut self) -> Option<Self::Out> {
        self.ready.pop_front()
    }

    fn finish(&mut self) -> Result<()> {
        self.flush()
    }

    fn next_deadline(&self) -> Option<Timestamp> {
        // Parts/segments are only cut in reaction to `push`/`flush` — no
        // rate-scheduled or timeout work.
        None
    }

    fn on_deadline(&mut self, _now: Timestamp) {}

    /// `saturated` once any track holds [`MAX_PENDING_SAMPLES_PER_TRACK`]
    /// un-cut samples — the same bound (and reasoning) as
    /// [`Segmenter`](crate::segmenter::Segmenter)'s: past it
    /// [`feed`](Stage::feed) errors rather than buffering a stream that never
    /// produces the sync sample a segment must open on.
    ///
    /// This segmenter is the one with the sharpest need for the bound: past
    /// the segment target it *also* stops emitting parts (a part is only
    /// flushed while `anchor_seg_dur < target_ticks`, so the segment's tail
    /// is held for the boundary), so a single-IDR stream produces no part
    /// **and** no segment while `pending` grows.
    fn demand(&self) -> Demand {
        if self
            .tracks
            .iter()
            .any(|t| t.pending.len() >= MAX_PENDING_SAMPLES_PER_TRACK)
        {
            Demand::saturated()
        } else {
            Demand::default()
        }
    }
}