GitCorner

Code

ossartcraftfilmcraft🌐
f67d38b35cc5
//! Step-wise export of the encoded-video formats (H.264 MP4/MOV, ProRes / DNxHR / Motion-JPEG MOV).
//!
//! [`Exporter::step`] renders, encodes and muxes one batch of frames (plus the audio up to its
//! end) per call, so a host without threads (the web app) can run an export a slice at a time
//! between UI frames; [`crate::export`] simply loops it on a worker thread.
//!
//! Before the first batch, loudness normalization (when enabled) measures the export range. A
//! two-pass VBR H.264 export renders and analyses every frame once (first pass, nothing written),
//! then encodes for real with the first pass's statistics.
//!
//! When a source's bytes are not available yet (asynchronous web reads mark
//! [`filmcraft_media::pending`]), the video batch is rendered again on the next call: nothing is encoded
//! from frames with missing media. Known, pre-existing web issue (TODO, separate fix): the audio pull
//! has already advanced its position when it hits a pending source, so a retried group loses its audio.
//!
//! The file does not depend on how many frames a step renders (one per core natively, one on the
//! web): packets go to the muxer in fixed groups of [`INTERLEAVE`] output frames, each followed by
//! the audio up to its end, so the same project and settings give the same bytes on any machine.
//!
//! # Overlapping render and encode
//!
//! Rendering a batch is parallel (rayon); encoding, muxing and the audio are serial and own the
//! encoder, the container writer and the audio state. Run one after the other the wall time was
//! `render + encode + audio + mux`. A step now renders batch *k+1* on the rayon pool
//! ([`rayon::in_place_scope`] + `spawn`) while the *calling* thread encodes, muxes and mixes the
//! audio of batch *k*, and keeps the finished frames in `ahead` for the next step: the wall time
//! is about `max(render, encode + audio + mux)`. Design points:
//!
//! * **Bytes do not change.** Batches are cut exactly as before (`next .. next + batch`), frames
//!   are encoded in order, and the audio / mux interleave still follows [`INTERLEAVE`] groups, so
//!   the file is identical with or without overlap, on any core count and for any step size
//!   (`determinism_tests`).
//! * **The encode side stays on the thread that called [`Exporter::step`].** Encoders (hardware
//!   ones in particular) may be tied to a thread, and the exporter need not be `Send`; only the
//!   render of the next batch moves to the pool. It needs no `&mut` access to the exporter: it
//!   holds an `Arc<Pipeline>` and the source provider.
//! * **Pending media.** [`filmcraft_media::pending`] is a thread-local flag, set by web readers
//!   (whose export never overlaps: wasm has no threads, so [`Exporter::overlapping`] is false and
//!   every step is the sequential render-then-encode of before). The render of a batch takes the
//!   flag after every frame, on whatever thread drew it, and a batch that saw it is discarded:
//!   a prefetched batch that hit pending is dropped and rendered again by the next step, and
//!   nothing is ever encoded from it. The audio pull checks the flag on the encoding thread right
//!   after pulling, before a frame is encoded (the batch is then not encoded; its audio is not
//!   recovered, see the known issue above) and the prefetched batch is dropped too, because the step
//!   did not advance `next`.
//! * **Cancellation** is checked at the start of every step, which drops the prefetched frames;
//!   the prefetch is not started once it is set.
//! * **Panics.** The prefetch runs under `catch_unwind` and becomes an [`ExportError`]; a panic of
//!   the encode side unwinds the calling thread as before (the job guard turns it into an error).
//! * **Memory.** Two batches are in flight instead of one, so the batch is capped by
//!   [`IN_FLIGHT_BUDGET`]: `2 * batch * frame_bytes <= budget`, at least one frame
//!   ([`overlap_batch`]). A batch never grows over what it was without overlap, so the peak is the
//!   old peak plus at most the finished frames of the batch being encoded (half the budget,
//!   256 MiB); a 4K HDR export (100 MB a frame) runs 2-frame batches and 4K SDR 8-frame ones instead of 16. Frames are
//!   dropped as soon as they are encoded.
//! * **Two-pass** exports overlap in the analysis pass (encode only) and in the real pass; the
//!   prefetch never runs past the end of a pass.
//! * **Timers.** `Render` and `Encode` are wall times of work that now runs at the same time, so
//!   their sum may exceed the export's wall time; `Wait` is the time the encoding side then spent
//!   waiting for the render (large: render-bound; near zero: encode-bound).

use std::panic::{AssertUnwindSafe, catch_unwind};
use std::sync::Arc;
use std::sync::atomic::{AtomicBool, Ordering};

use filmcraft_isobmff::{Brand, Mp4Writer, PcmConfig, SampleEntry, TrackConfig, WriteSample, WriterOptions};
use filmcraft_project::{ItemId, Project};
use filmcraft_render::SourceProvider;
use filmcraft_time::FrameRate;
use rayon::prelude::*;

use crate::audio_out::AudioOut;
use crate::mxf_out::{MxfMux, MxfSetup};
use crate::pipeline::Pipeline;
use crate::settings::{AudioCodec, BitrateMode, HardwareEncoding};
use crate::{
    AudioEncoder, ColorSignal, EncodedPacket, EncoderFactory, EncoderFrame, ExportError, ExportSettings, Format, H264Pass, Out, PrepareAhead, Progress, Report,
    Result, Stage, VideoEncoder, audio_factories, export_range, frame_span, note_stage, take_hw_encode_decline, timed, video_factories,
};

/// Output frames per interleaved group: the video packets of these frames, then the audio up to
/// their end, form one chunk of each track. Fixed (not the batch size, which follows the core
/// count) so the file layout is the same on every machine.
pub const INTERLEAVE: i64 = 16;

/// Most bytes of rendered frames an overlapped export keeps in flight (the batch being encoded and
/// the one being rendered), see [`overlap_batch`].
pub const IN_FLIGHT_BUDGET: u64 = 1 << 29;

/// One rendered picture: straight RGBA8, or for HDR exports the encoded R'G'B' floats.
type Frame = (Vec<u8>, Vec<f32>);

/// Bytes of one [`Frame`] of a `w` x `h` export (RGBA8, or three f32 per pixel for HDR).
pub(crate) fn frame_bytes(w: u32, h: u32, hdr: bool) -> u64 {
    u64::from(w).saturating_mul(u64::from(h)).saturating_mul(if hdr { 12 } else { 4 })
}

/// Frames per batch when two batches are in flight: `batch` (what a sequential export would use),
/// lowered so that `2 * frames * frame_bytes` stays within `budget`, but never below one frame.
pub(crate) fn overlap_batch(batch: i64, frame_bytes: u64, budget: u64) -> i64 {
    let want = u64::try_from(batch.max(1)).unwrap_or(1);
    let fit = (budget / 2) / frame_bytes.max(1);
    i64::try_from(fit.min(want)).unwrap_or(1).max(1)
}

/// A batch rendered while the previous one was being encoded.
struct Ahead {
    /// First frame.
    first: i64,
    frames: Vec<Frame>,
}

/// Render frames `f..end` in parallel. `None` when a source was not ready for one of them (the
/// pending flag, taken after every frame because it is per thread): the batch is incomplete and
/// must be rendered again.
/// `prepare` (the encoder's [`VideoEncoder::prepare_ahead`]) then works on each frame, numbered
/// from `f0` like [`EncoderFrame::index`].
fn render_batch(pipe: &Pipeline, f: i64, end: i64, sources: &dyn SourceProvider, prepare: Option<&PrepareAhead>, f0: i64) -> Option<Vec<Frame>> {
    let pending = AtomicBool::new(false);
    let frames: Vec<Frame> = (f..end)
        .into_par_iter()
        .map(|fi| {
            let frame = pipe.frame(fi, sources);
            if filmcraft_media::pending::take() {
                pending.store(true, Ordering::Relaxed);
            }
            if let Some(prepare) = prepare {
                let index = u64::try_from(fi - f0).unwrap_or(u64::MAX);
                prepare(&EncoderFrame { width: pipe.w, height: pipe.h, rgba: &frame.0, hdr: pipe.hdr_out.then_some(frame.1.as_slice()), index });
            }
            frame
        })
        .collect();
    (!pending.load(Ordering::Relaxed)).then_some(frames)
}

/// What encoding a batch came to.
enum Encoded {
    Done,
    /// Audio media was not ready: nothing was encoded, run the batch again.
    Pending,
}

/// What one [`Exporter::step`] did.
#[derive(Debug)]
pub enum Step {
    /// A batch was encoded; call again.
    Progress,
    /// Media bytes are still loading: nothing was encoded, call again later.
    Pending,
    /// The file is complete.
    Done(Report),
}

/// An export of an encoded-video format, advanced one batch at a time.
pub struct Exporter {
    pipe: Arc<Pipeline>,
    settings: ExportSettings,
    f0: i64,
    f1: i64,
    /// Next frame to encode.
    next: i64,
    batch: i64,
    /// Render the next batch while this one is encoded (see the module docs).
    overlap: bool,
    /// Bytes of frames the overlap may keep in flight ([`IN_FLIGHT_BUDGET`]; tests lower it).
    budget: u64,
    /// The batch starting at `next`, already rendered.
    ahead: Option<Ahead>,
    /// Steps that rendered a batch alongside the encoding of the previous one.
    overlapped_steps: u64,
    brand: Brand,
    venc: Box<dyn VideoEncoder>,
    aenc: Option<Box<dyn AudioEncoder>>,
    audio: Option<AudioOut>,
    /// The loudness pass ran (or is not needed).
    measured: bool,
    /// The first pass of a two-pass encode is running.
    first_pass: bool,
    /// For the report: the software encoder ran where a hardware one was asked for ([`software_fallback`]).
    warnings: Vec<String>,
    /// Encoded video packets not written yet (the current [`INTERLEAVE`] group).
    queued: Vec<EncodedPacket>,
    /// Created after the first group was encoded (encoders may finalise their codec config then).
    mux: Option<Mp4Writer<Out>>,
    /// MXF exports write through this instead of `mux`.
    mxf: Option<MxfMux>,
    seq: ItemId,
    project: Arc<Project>,
    vt: usize,
    at: Option<usize>,
    t0: web_time::Instant,
}

/// Whether [`Exporter`] handles a format.
pub fn stepped(format: Format) -> bool {
    matches!(
        format,
        Format::H264 | Format::Hevc | Format::Av1 | Format::ProRes | Format::DnxHr | Format::Apv | Format::Mjpeg | Format::MxfOp1a | Format::MxfOpAtom
    )
}

/// Whether an export is HDR: an HDR working space, SDR not asked for, and a format whose encoder
/// writes HDR (`hdr_available` says so for H.265, which has no built-in encoder).
pub(crate) fn hdr_output(working_hdr: bool, sdr: bool, format: Format, hdr_available: impl Fn(Format) -> bool) -> bool {
    working_hdr
        && !sdr
        && match format {
            Format::H264 | Format::ProRes | Format::DnxHr | Format::Apv => true,
            Format::Hevc => hdr_available(Format::Hevc),
            _ => false,
        }
}

fn make_venc(settings: &ExportSettings, w: u32, h: u32, rate: FrameRate) -> Result<(Box<dyn VideoEncoder>, Option<String>)> {
    pick_encoder(&video_factories().read().unwrap_or_else(|e| e.into_inner()).clone(), settings.video_format(), w, h, rate, settings)
}

/// What the report says when FilmCraft's own encoder runs where a hardware one was asked for (H.264
/// with Hardware encoding Auto) or declined the export (`declined`: which one and why). `None` when
/// a hardware encoder runs, or none was asked for.
fn software_fallback(settings: &ExportSettings, venc: &dyn VideoEncoder, declined: Option<String>) -> Option<String> {
    if venc.hardware().is_some() {
        return None;
    }
    let format = settings.video_format();
    match declined {
        Some(why) => Some(format!("hardware encoding declined ({why}); the software {} encoder ran", format.label())),
        None if format == Format::H264 && settings.hardware_encoding == HardwareEncoding::Auto => {
            Some("hardware encoding is Auto, but no hardware H.264 encoder is available here; the software encoder ran".into())
        }
        None => None,
    }
}

/// Pick the encoder for an export: the first registered factory that takes it, and which hardware
/// encoder declined the export before it and why, if one did ([`crate::note_hw_encode_declined_by`]).
///
/// A factory answers in one of three ways: it takes the export (`Some(Ok(..))`), it is not its
/// job (`None`), or it is its job and it failed (`Some(Err(..))`). **A failure must not stop the
/// walk.** For H.264 the software encoder is the documented fallback ("Hardware encoding: Auto …
/// otherwise the software encoder"), and for H.265 there is no software encoder at all, so the
/// next factory may be the only one that can take the export. When no factory takes it, the
/// first failure is what the user is told — the same message as before.
fn pick_encoder(
    factories: &[EncoderFactory],
    format: Format,
    w: u32,
    h: u32,
    rate: FrameRate,
    settings: &ExportSettings,
) -> Result<(Box<dyn VideoEncoder>, Option<String>)> {
    // a reason left on this thread by an earlier request is not this export's
    let _ = take_hw_encode_decline();
    let mut first_failure: Option<ExportError> = None;
    for fac in factories {
        match fac(format, w, h, rate, settings) {
            Some(Ok(enc)) => return Ok((enc, take_hw_encode_decline())),
            Some(Err(e)) if first_failure.is_none() => first_failure = Some(e),
            Some(Err(_)) => {}
            None => {}
        }
    }
    Err(first_failure.unwrap_or_else(|| ExportError::Unsupported(format!("{} encoder not available yet", format.label()))))
}

impl Exporter {
    /// Set up an export (encoder, output size, colour signalling); sets `progress.total`.
    pub fn new(project: Arc<Project>, seq: ItemId, settings: &ExportSettings, progress: &Progress) -> Result<Self> {
        timed(Stage::Setup, || Self::set_up(project, seq, settings, progress))
    }

    fn set_up(project: Arc<Project>, seq: ItemId, settings: &ExportSettings, progress: &Progress) -> Result<Self> {
        if !stepped(settings.format) {
            return Err(ExportError::Unsupported(format!("{} is not a stepped export", settings.format.label())));
        }
        settings.validate()?;
        let q = project.sequence(seq).ok_or(ExportError::NoSequence)?;
        // HDR sequences export HDR (H.264 / ProRes / DNxHR / APV, and H.265 where a registered encoder
        // writes Main 10) unless SDR is asked for; elsewhere H.265 is tone-mapped 8-bit SDR
        let pipe = q.settings.color;
        let hdr_out = hdr_output(pipe.working.is_hdr(), settings.sdr, settings.video_format(), crate::hdr_available);
        let mut settings = settings.clone();
        settings.signal = match (hdr_out, pipe.working) {
            (true, filmcraft_color::WorkingSpace::Rec2100Pq) => ColorSignal::PQ,
            (true, _) => ColorSignal::HLG,
            _ => ColorSignal::default(),
        };
        // bake the derived bitrate / keyframe values in for the encoder factories
        let r = settings.resolve(q.settings.width, q.settings.height, q.settings.frame_rate, q.settings.sample_rate);
        settings.bitrate_kbps = r.target_kbps;
        settings.max_bitrate_kbps = Some(r.max_kbps);
        settings.keyframe_distance = Some(r.keyint);
        settings.adaptive_bitrate = None;
        let two_pass = settings.video_format() == Format::H264 && settings.bitrate_mode == BitrateMode::Vbr2Pass;
        settings.h264_pass = if two_pass { H264Pass::First } else { H264Pass::Single };
        let range = export_range(&project, seq, &settings)?;
        let pipe = Arc::new(Pipeline::new(project.clone(), seq, &settings, hdr_out)?);
        let (f0, f1) = frame_span(pipe.rate, range);
        let nframes = (f1 - f0) as u64;
        if !settings.part_of_batch {
            progress.total.store(nframes * if two_pass { 2 } else { 1 }, Ordering::Relaxed);
            progress.set_status(format!("Exporting {} frames ({})", nframes, settings.format.label()));
        }
        let (venc, declined) = make_venc(&settings, pipe.w, pipe.h, pipe.rate)?;
        log::info!("{} export: {} encoder", settings.video_format().label(), venc.hardware().unwrap_or("software"));
        let warnings: Vec<String> = software_fallback(&settings, venc.as_ref(), declined).into_iter().collect();
        for w in &warnings {
            log::warn!("{w}");
        }
        let brand = if settings.format.is_mp4_with(settings.multiplexer) { Brand::Mp4 } else { Brand::Mov };
        let audio = if settings.has_audio() { Some(AudioOut::new(project.clone(), seq, &settings, range)?) } else { None };
        let aenc: Option<Box<dyn AudioEncoder>> = match (&audio, settings.audio_codec()) {
            (Some(a), AudioCodec::Aac) => {
                let found =
                    audio_factories().read().unwrap_or_else(|e| e.into_inner()).iter().find_map(|f| f(settings.format, a.sr, a.channels as u32, &settings));
                Some(found.ok_or_else(|| ExportError::Unsupported("AAC encoder not available".into()))??)
            }
            (Some(a), AudioCodec::Flac) => Some(Box::new(crate::FlacAudio::new(a.sr, a.channels as u32, &settings)?)),
            _ => None,
        };
        let measured = !settings.effects.loudness.enabled || audio.is_none();
        Ok(Self {
            pipe,
            f0,
            f1,
            next: f0,
            batch: rayon::current_num_threads().clamp(2, 16) as i64,
            overlap: true,
            budget: IN_FLIGHT_BUDGET,
            ahead: None,
            overlapped_steps: 0,
            brand,
            venc,
            aenc,
            audio,
            measured,
            first_pass: two_pass,
            warnings,
            queued: Vec::new(),
            mux: None,
            mxf: None,
            seq,
            project: project.clone(),
            vt: 0,
            at: None,
            t0: web_time::Instant::now(),
            settings,
        })
    }

    /// Frames in the export.
    pub fn frames(&self) -> u64 {
        (self.f1 - self.f0).max(0) as u64
    }

    /// Requested frames per [`Self::step`] (default: one per core), capped by GPU renderer
    /// capacity and the overlap memory budget. 1 keeps web UI frames short.
    pub fn set_batch(&mut self, n: i64) {
        self.batch = n.max(1);
    }

    /// Render the next batch while encoding the current one (the default natively; the web, with
    /// no threads, never does). Off gives the sequential render-then-encode; the file is the same.
    pub fn set_overlap(&mut self, on: bool) {
        self.overlap = on;
        if !on {
            self.ahead = None;
        }
    }

    /// Lower the in-flight byte budget (tests make small frames hit the cap).
    #[cfg(test)]
    pub(crate) fn set_budget(&mut self, bytes: u64) {
        self.budget = bytes;
    }

    /// Whether steps overlap rendering with encoding now: switched on, a pool with more than one
    /// thread, and not on wasm.
    pub fn overlapping(&self) -> bool {
        self.overlap && !cfg!(target_arch = "wasm32") && rayon::current_num_threads() > 1
    }

    /// Steps so far that rendered the next batch alongside the encoding of the current one.
    pub fn overlapped_steps(&self) -> u64 {
        self.overlapped_steps
    }

    /// Frames rendered ahead of the encoder now (memory held by the overlap).
    pub fn frames_ahead(&self) -> usize {
        self.ahead.as_ref().map_or(0, |a| a.frames.len())
    }

    /// Frames in the next batch, bounded before Rayon can steal nested frame tasks.
    fn batch_len(&self) -> i64 {
        let batch = self.pipe.render_batch_limit(self.batch);
        if self.overlapping() { overlap_batch(batch, frame_bytes(self.pipe.w, self.pipe.h, self.pipe.hdr_out), self.budget) } else { batch }
    }

    fn sample_at_frame(&self, f: i64, sr: u32) -> i64 {
        self.pipe.rate.tick_of(f).to_units_floor(sr as i64)
    }

    fn write_audio(&mut self, planar: Option<Vec<Vec<f32>>>) -> Result<()> {
        if let Some(m) = self.mxf.as_mut() {
            return match planar {
                Some(buf) => m.write_audio(&buf),
                None => Ok(()),
            };
        }
        let (Some(at), Some(buf)) = (self.at, planar) else { return Ok(()) };
        let n = buf.first().map_or(0, Vec::len);
        if n == 0 {
            return Ok(());
        }
        let mux = self.mux.as_mut().ok_or_else(|| ExportError::Encode("internal: the container writer was not created".into()))?;
        match self.aenc.as_mut() {
            Some(a) => {
                for au in a.encode(&buf)? {
                    mux.write_sample(at, WriteSample { data: &au, duration: a.frame_size(), composition_offset: 0, is_sync: true })
                        .map_err(|e| ExportError::Io(e.to_string()))?;
                }
            }
            None => {
                // little-endian, like the track's `lpcm` / `sowt` description says
                let mut pcm = Vec::new();
                crate::pcm::encode(crate::pcm::PcmContainer::Wav, &crate::audio_out::interleave(&buf), self.settings.audio.sample_format(), &mut pcm);
                mux.write_sample(at, WriteSample { data: &pcm, duration: n as u32, composition_offset: 0, is_sync: true })
                    .map_err(|e| ExportError::Io(e.to_string()))?;
            }
        }
        Ok(())
    }

    fn write_video(&mut self, packets: Vec<EncodedPacket>) -> Result<()> {
        if let Some(m) = self.mxf.as_mut() {
            return m.write_video(packets);
        }
        let mux = self.mux.as_mut().ok_or_else(|| ExportError::Encode("internal: the container writer was not created".into()))?;
        for p in packets {
            mux.write_sample(self.vt, WriteSample { data: &p.data, duration: p.duration, composition_offset: p.composition_offset, is_sync: p.key })
                .map_err(|e| ExportError::Io(e.to_string()))?;
        }
        Ok(())
    }

    /// Create the muxer and its tracks (after the first batch was encoded).
    fn open_mux(&mut self) -> Result<()> {
        if self.settings.format.is_mxf() {
            let q = self.project.sequence(self.seq).ok_or(ExportError::NoSequence)?;
            // start timecode of the first exported frame, at the output rate
            let seq_rate = q.settings.frame_rate;
            let start = self.pipe.rate.frame_at(seq_rate.tick_of(q.start_timecode)) + self.f0;
            let name = self.project.item(self.seq).map(|i| i.name.clone()).unwrap_or_default();
            self.mxf = Some(MxfMux::new(MxfSetup {
                settings: &self.settings,
                name,
                width: self.pipe.w,
                height: self.pipe.h,
                rate: self.pipe.rate,
                audio: self.audio.as_ref().map(|a| (a.sr, a.channels)),
                timecode: (start, q.settings.drop_frame),
            })?);
            return Ok(());
        }
        let file = Out::create(&self.settings)?;
        let mut opts = WriterOptions::new(self.brand);
        opts.metadata = self.settings.metadata.udta();
        let mut mux = Mp4Writer::new(file, opts).map_err(|e| ExportError::Io(e.to_string()))?;
        let mut vcfg = TrackConfig::new(self.venc.sample_entry(), self.venc.timescale());
        vcfg.media_start = self.venc.media_start();
        self.vt = mux.add_track(vcfg).map_err(|e| ExportError::Io(e.to_string()))?;
        self.at = match (&self.audio, &self.aenc) {
            (None, _) => None,
            (Some(a), Some(enc)) => {
                let mut c = TrackConfig::new(enc.sample_entry(), a.sr);
                c.media_start = Some(enc.priming() as i64);
                Some(mux.add_track(c).map_err(|e| ExportError::Io(e.to_string()))?)
            }
            (Some(a), None) => {
                let f = self.settings.audio.sample_format();
                let pcm = PcmConfig {
                    bits: f.bits() as _,
                    float: f.is_float(),
                    big_endian: false,
                    signed: true,
                    channels: a.channels as _,
                    sample_rate: a.sr as f64,
                };
                Some(mux.add_track(TrackConfig::new(SampleEntry::pcm(pcm), a.sr)).map_err(|e| ExportError::Io(e.to_string()))?)
            }
        };
        self.mux = Some(mux);
        Ok(())
    }

    /// Render, encode and mux the next batch (or finish the file).
    pub fn step(&mut self, sources: &dyn SourceProvider, progress: &Progress) -> Result<Step> {
        if progress.cancel.load(Ordering::Relaxed) {
            self.ahead = None;
            return Err(ExportError::Cancelled);
        }
        let _ = filmcraft_media::pending::take();
        if !self.measured {
            if !self.settings.part_of_batch {
                progress.set_status("Measuring loudness");
            }
            let a = self.audio.as_mut().ok_or_else(|| ExportError::Encode("internal: the audio pipeline was not created".into()))?;
            let settings = &self.settings;
            timed(Stage::Loudness, || a.measure(settings, sources, &|| progress.cancel.load(Ordering::Relaxed)))?;
            if filmcraft_media::pending::take() {
                return Ok(Step::Pending);
            }
            *progress.loudness.lock().unwrap_or_else(|e| e.into_inner()) = a.loudness;
            self.measured = true;
            if !self.settings.part_of_batch {
                progress.set_status(format!("Exporting {} frames ({})", self.frames(), self.settings.format.label()));
            }
            return Ok(Step::Progress);
        }
        if self.next < self.f1 {
            return self.step_batch(sources, progress);
        }
        self.ahead = None;
        if self.first_pass {
            // end of the analysis pass: encode for real with its statistics
            let _ = self.venc.flush()?;
            let stats = self.venc.pass_stats().ok_or_else(|| ExportError::Encode("two-pass statistics missing".into()))?;
            self.settings.h264_pass = H264Pass::Second(stats);
            // the same request as the analysis pass's: a hardware encoder declines it again, already reported
            self.venc = make_venc(&self.settings, self.pipe.w, self.pipe.h, self.pipe.rate)?.0;
            self.first_pass = false;
            self.next = self.f0;
            return Ok(Step::Progress);
        }
        let finishing = web_time::Instant::now();
        let mixed = self.audio.as_mut().and_then(|a| a.rest(sources));
        if filmcraft_media::pending::take() {
            return Ok(Step::Pending);
        }
        if self.mux.is_none() && self.mxf.is_none() {
            self.open_mux()?;
        }
        let mut tail = std::mem::take(&mut self.queued);
        tail.extend(self.venc.flush()?);
        self.write_video(tail)?;
        self.write_audio(mixed)?;
        if let (Some(at), Some(a)) = (self.at, self.aenc.as_mut()) {
            let mux = self.mux.as_mut().ok_or_else(|| ExportError::Encode("internal: the container writer was not created".into()))?;
            for (au, duration) in a.flush_timed()? {
                mux.write_sample(at, WriteSample { data: &au, duration, composition_offset: 0, is_sync: true }).map_err(|e| ExportError::Io(e.to_string()))?;
            }
            if let Some(entry) = a.final_sample_entry() {
                mux.set_sample_entry(at, entry).map_err(|e| ExportError::Io(e.to_string()))?;
            }
        }
        let (bytes, extra_files) = match self.mxf.take() {
            Some(m) => m.finish(&self.settings)?,
            None => {
                let mux = self.mux.take().ok_or_else(|| ExportError::Encode("internal: the container writer was not created".into()))?;
                // Upload services and progressive players need the MP4 metadata before media.
                // The muxer relocates data in bounded chunks and adjusts every sample offset.
                let w = if self.brand == Brand::Mp4 { mux.finish_faststart() } else { mux.finish() }.map_err(|e| ExportError::Io(e.to_string()))?;
                (w.finish(&self.settings)?, Vec::new())
            }
        };
        note_stage(Stage::Finish, finishing.elapsed());
        let secs = self.t0.elapsed().as_secs_f64();
        let nframes = self.frames();
        if !self.settings.part_of_batch {
            progress.finished.store(true, Ordering::Relaxed);
            progress.set_status(format!("Done in {secs:.1}s"));
        }
        Ok(Step::Done(Report {
            path: self.settings.path.clone(),
            frames: nframes,
            seconds: secs,
            bytes,
            render_fps: nframes as f64 / secs.max(1e-6),
            extra_files,
            encoder: Some(self.venc.hardware().unwrap_or("software").to_string()),
            warnings: std::mem::take(&mut self.warnings),
        }))
    }

    /// Encode (and mux) the batch starting at `self.next`, rendering the one after it meanwhile.
    fn step_batch(&mut self, sources: &dyn SourceProvider, progress: &Progress) -> Result<Step> {
        let prepare = self.venc.prepare_ahead();
        let f0 = self.f0;
        let (f, frames) = match self.ahead.take() {
            Some(a) if a.first == self.next => (a.first, a.frames),
            _ => {
                let (f, end) = (self.next, self.next.saturating_add(self.batch_len()).min(self.f1));
                let pipe = &self.pipe;
                match timed(Stage::Render, || render_batch(pipe, f, end, sources, prepare.as_ref(), f0)) {
                    Some(frames) => (f, frames),
                    None => return Ok(Step::Pending),
                }
            }
        };
        let end = f.saturating_add(i64::try_from(frames.len()).unwrap_or(0));
        if end <= f {
            return Err(ExportError::Encode("internal: an empty batch was rendered".into()));
        }
        // the batch after this one, when the pool can render it while this one is encoded
        let plan =
            (end < self.f1 && self.overlapping() && !progress.cancel.load(Ordering::Relaxed)).then(|| (end, end.saturating_add(self.batch_len()).min(self.f1)));
        let Some((a, b)) = plan else {
            return match self.encode_batch(f, frames, sources)? {
                Encoded::Pending => Ok(Step::Pending),
                Encoded::Done => {
                    progress.done.fetch_add((end - f) as u64, Ordering::Relaxed);
                    self.next = end;
                    Ok(Step::Progress)
                }
            };
        };
        let pipe = self.pipe.clone();
        let mut slot: Option<std::thread::Result<Option<Vec<Frame>>>> = None;
        let mut encode_done: Option<web_time::Instant> = None;
        let encoded = rayon::in_place_scope(|s| {
            s.spawn(|_| {
                slot = Some(catch_unwind(AssertUnwindSafe(|| timed(Stage::Render, || render_batch(&pipe, a, b, sources, prepare.as_ref(), f0)))));
            });
            let r = self.encode_batch(f, frames, sources);
            encode_done = Some(web_time::Instant::now());
            r
        });
        // the scope returned only now: what is left since the encoding ended is waiting for the render
        if let Some(t) = encode_done {
            note_stage(Stage::Wait, t.elapsed());
        }
        match encoded? {
            Encoded::Pending => Ok(Step::Pending),
            Encoded::Done => {
                self.overlapped_steps += 1;
                progress.done.fetch_add((end - f) as u64, Ordering::Relaxed);
                self.next = end;
                match slot {
                    Some(Ok(Some(frames))) => self.ahead = Some(Ahead { first: a, frames }),
                    // a source was not ready: the next step renders this batch again
                    Some(Ok(None)) | None => {}
                    Some(Err(_)) => return Err(ExportError::Encode("internal error while rendering a frame (the panic was logged by the panic hook)".into())),
                }
                Ok(Step::Progress)
            }
        }
    }

    /// Encode the rendered frames `f..` (the analysis pass of a two-pass export only encodes), mux
    /// them with their audio, and drop each frame as soon as it is encoded.
    fn encode_batch(&mut self, f: i64, frames: Vec<Frame>, sources: &dyn SourceProvider) -> Result<Encoded> {
        if self.first_pass {
            for (k, frame) in frames.into_iter().enumerate() {
                timed(Stage::Encode, || self.encode(std::slice::from_ref(&frame), f + k as i64))?;
            }
            return Ok(Encoded::Done);
        }
        let end = f.saturating_add(i64::try_from(frames.len()).unwrap_or(0));
        // the audio of every interleave group that ends in this batch, mixed before encoding so a
        // pending source stops the step before any frame of the batch is encoded (the audio position has
        // already moved though: known web issue, see the module docs)
        let cuts: Vec<i64> = (f + 1..=end).filter(|&g| (g - self.f0) % INTERLEAVE == 0).collect();
        let mut mixed = Vec::with_capacity(cuts.len());
        if let Some(sr) = self.audio.as_ref().map(|a| a.sr) {
            let t = web_time::Instant::now();
            for &g in &cuts {
                let until = self.sample_at_frame(g, sr);
                mixed.push(self.audio.as_mut().and_then(|a| a.pull(until, sources)));
            }
            note_stage(Stage::Audio, t.elapsed());
        }
        // taken right here, on the thread that pulled, before other work can touch the flag
        if filmcraft_media::pending::take() {
            return Ok(Encoded::Pending);
        }
        let mut mixed = mixed.into_iter();
        for (k, frame) in frames.into_iter().enumerate() {
            let fi = f + k as i64;
            let packets = timed(Stage::Encode, || self.encode(std::slice::from_ref(&frame), fi))?;
            self.queued.extend(packets);
            if cuts.contains(&(fi + 1)) {
                timed(Stage::Mux, || -> Result<()> {
                    if self.mux.is_none() && self.mxf.is_none() {
                        self.open_mux()?;
                    }
                    let packets = std::mem::take(&mut self.queued);
                    self.write_video(packets)
                })?;
                let pcm = mixed.next().flatten();
                timed(Stage::Audio, || self.write_audio(pcm))?;
            }
        }
        Ok(Encoded::Done)
    }

    fn encode(&mut self, frames: &[(Vec<u8>, Vec<f32>)], f: i64) -> Result<Vec<EncodedPacket>> {
        let mut packets = Vec::new();
        for (k, (rgba, hdr)) in frames.iter().enumerate() {
            let fr = EncoderFrame {
                width: self.pipe.w,
                height: self.pipe.h,
                rgba,
                hdr: self.pipe.hdr_out.then_some(hdr.as_slice()),
                index: (f - self.f0) as u64 + k as u64,
            };
            packets.extend(self.venc.encode(&fr)?);
        }
        Ok(packets)
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    const MIB: u64 = 1 << 20;

    /// A factory that answers as it is told, so the walk can be exercised without a driver.
    fn factory(answer: fn(Format, u32, u32, FrameRate, &ExportSettings) -> Option<Result<Box<dyn VideoEncoder>>>) -> EncoderFactory {
        answer
    }

    fn never(_: Format, _: u32, _: u32, _: FrameRate, _: &ExportSettings) -> Option<Result<Box<dyn VideoEncoder>>> {
        None
    }

    fn fails(_: Format, _: u32, _: u32, _: FrameRate, _: &ExportSettings) -> Option<Result<Box<dyn VideoEncoder>>> {
        Some(Err(ExportError::Unsupported("the driver said no".into())))
    }

    fn fails_other(_: Format, _: u32, _: u32, _: FrameRate, _: &ExportSettings) -> Option<Result<Box<dyn VideoEncoder>>> {
        Some(Err(ExportError::Unsupported("the other driver said no".into())))
    }

    fn takes(_: Format, _: u32, _: u32, _: FrameRate, _: &ExportSettings) -> Option<Result<Box<dyn VideoEncoder>>> {
        Some(Ok(Box::new(Dummy(None))))
    }

    fn takes_in_hardware(_: Format, _: u32, _: u32, _: FrameRate, _: &ExportSettings) -> Option<Result<Box<dyn VideoEncoder>>> {
        Some(Ok(Box::new(Dummy(Some("NVENC")))))
    }

    /// A hardware encoder that does not take the export, as NVENC declines a two-pass one.
    fn declines(_: Format, _: u32, _: u32, _: FrameRate, _: &ExportSettings) -> Option<Result<Box<dyn VideoEncoder>>> {
        crate::note_hw_encode_declined_by("NVENC", "two-pass VBR");
        None
    }

    /// An encoder that writes nothing; the walk only needs something that can be handed back. It
    /// says it is the hardware encoder it names, if any.
    struct Dummy(Option<&'static str>);

    impl VideoEncoder for Dummy {
        fn sample_entry(&self) -> SampleEntry {
            SampleEntry::avc(filmcraft_isobmff::AvcConfig::default(), 0, 0)
        }
        fn timescale(&self) -> u32 {
            1
        }
        fn encode(&mut self, _frame: &EncoderFrame) -> Result<Vec<EncodedPacket>> {
            Ok(Vec::new())
        }
        fn flush(&mut self) -> Result<Vec<EncodedPacket>> {
            Ok(Vec::new())
        }
        fn hardware(&self) -> Option<&'static str> {
            self.0
        }
    }

    /// The encoder a walk took, and the decline it reported.
    fn taken(r: Result<(Box<dyn VideoEncoder>, Option<String>)>) -> (Box<dyn VideoEncoder>, Option<String>) {
        match r {
            Ok(t) => t,
            Err(e) => panic!("the walk took no encoder: {e}"),
        }
    }

    /// The error of a walk that took no encoder. `Box<dyn VideoEncoder>` is not `Debug`, so this
    /// is not `expect_err`.
    fn error_of(r: Result<(Box<dyn VideoEncoder>, Option<String>)>) -> ExportError {
        match r {
            Ok(_) => panic!("the walk took an encoder"),
            Err(e) => e,
        }
    }

    /// A factory that *fails* must not stop the walk: the next factory may be the one that can
    /// take the export. For H.264 that is FilmCraft's own encoder, and for H.265 it is a second
    /// hardware encoder, because there is no software H.265 encoder at all.
    #[test]
    fn a_failing_factory_does_not_stop_the_walk() {
        let s = ExportSettings { format: Format::Hevc, ..Default::default() };
        // the failing factory is asked first, the one that takes it second
        let taken = pick_encoder(&[factory(fails), factory(takes)], Format::Hevc, 64, 64, FrameRate::FPS_24, &s);
        assert!(taken.is_ok(), "the second factory takes it");
    }

    /// Nothing took the export: the first failure is what the user is told, and a factory that
    /// merely declined is not a failure.
    #[test]
    fn the_first_failure_is_reported_when_nothing_takes_the_export() {
        let s = ExportSettings { format: Format::Hevc, ..Default::default() };
        let e = error_of(pick_encoder(&[factory(fails), factory(fails_other)], Format::Hevc, 64, 64, FrameRate::FPS_24, &s));
        assert!(e.to_string().contains("the driver said no"), "{e}");
        assert!(!e.to_string().contains("the other driver said no"), "the first failure is the one reported: {e}");
        // a factory that declined is not a failure: the message is the "not available" one
        let e = error_of(pick_encoder(&[factory(never), factory(never)], Format::Hevc, 64, 64, FrameRate::FPS_24, &s));
        assert!(e.to_string().contains("encoder not available yet"), "{e}");
    }

    /// NVENC declined a two-pass H.264 export with Hardware encoding Auto and the software encoder
    /// took it: the export said nothing, so its file read as NVENC's. Now the walk hands back the
    /// reason, once, and the report says the software encoder ran and why.
    #[test]
    fn a_hardware_encoder_that_declines_is_reported_with_its_reason() {
        let auto = ExportSettings { format: Format::H264, hardware_encoding: HardwareEncoding::Auto, ..Default::default() };
        let (venc, declined) = taken(pick_encoder(&[factory(declines), factory(takes)], Format::H264, 64, 64, FrameRate::FPS_24, &auto));
        assert_eq!(venc.hardware(), None, "the software encoder took it");
        assert_eq!(declined.as_deref(), Some("NVENC: two-pass VBR"));
        let warning = software_fallback(&auto, venc.as_ref(), declined);
        assert_eq!(warning.as_deref(), Some("hardware encoding declined (NVENC: two-pass VBR); the software H.264 encoder ran"));
        // the reason belonged to that walk: the next one starts without it
        let (venc, declined) = taken(pick_encoder(&[factory(takes)], Format::H264, 64, 64, FrameRate::FPS_24, &auto));
        assert_eq!(declined, None);
        // and with no hardware encoder at all (no driver), Auto still says the software encoder ran
        let warning = software_fallback(&auto, venc.as_ref(), declined);
        assert_eq!(warning.as_deref(), Some("hardware encoding is Auto, but no hardware H.264 encoder is available here; the software encoder ran"));
    }

    /// A hardware encoder that runs, or an export that asked for none, has nothing to warn about.
    #[test]
    fn no_warning_when_hardware_runs_or_was_not_asked_for() {
        let auto = ExportSettings { format: Format::H264, hardware_encoding: HardwareEncoding::Auto, ..Default::default() };
        let (venc, declined) = taken(pick_encoder(&[factory(takes_in_hardware), factory(takes)], Format::H264, 64, 64, FrameRate::FPS_24, &auto));
        assert_eq!(venc.hardware(), Some("NVENC"));
        assert_eq!(software_fallback(&auto, venc.as_ref(), declined), None);
        // Hardware encoding Off (the default), or Auto on a format no hardware encoder takes
        let (venc, _) = taken(pick_encoder(&[factory(takes)], Format::H264, 64, 64, FrameRate::FPS_24, &auto));
        let off = ExportSettings { format: Format::H264, ..Default::default() };
        let prores = ExportSettings { format: Format::ProRes, hardware_encoding: HardwareEncoding::Auto, ..Default::default() };
        assert_eq!(software_fallback(&off, venc.as_ref(), None), None);
        assert_eq!(software_fallback(&prores, venc.as_ref(), None), None);
    }

    #[test]
    fn frame_bytes_by_format() {
        assert_eq!(frame_bytes(1920, 1080, false), 1920 * 1080 * 4);
        assert_eq!(frame_bytes(3840, 2160, true), 3840 * 2160 * 12);
        assert_eq!(frame_bytes(u32::MAX, u32::MAX, true), u64::MAX, "saturates");
        assert_eq!(frame_bytes(0, 1080, false), 0);
    }

    #[test]
    fn the_overlap_batch_fits_the_memory_budget() {
        let budget = IN_FLIGHT_BUDGET;
        // 1080p keeps the full 16 frames, 4K SDR (33 MB a frame) 8 + 8 in flight (2 x 8 x 33 MB = 512 MiB)
        assert_eq!(overlap_batch(16, frame_bytes(1920, 1080, false), budget), 16);
        assert_eq!(overlap_batch(16, frame_bytes(3840, 2160, false), budget), 8);
        // 4K HDR (100 MB a frame): 256 MiB per batch is 2 frames, not 16
        let hdr4k = frame_bytes(3840, 2160, true);
        let n = overlap_batch(16, hdr4k, budget);
        assert_eq!(n, 2);
        assert!(2 * n as u64 * hdr4k <= budget);
        // 8K HDR: one frame at a time, even though two do not fit (never fewer than one)
        assert_eq!(overlap_batch(16, frame_bytes(7680, 4320, true), budget), 1);
        // a smaller batch (web: 1) is never raised, a degenerate one is one frame
        assert_eq!(overlap_batch(1, 4, budget), 1);
        assert_eq!(overlap_batch(0, 4, budget), 1);
        assert_eq!(overlap_batch(-3, 4, budget), 1);
        assert_eq!(overlap_batch(8, 0, budget), 8, "no division by zero");
        assert_eq!(overlap_batch(8, u64::MAX, budget), 1);
        assert_eq!(overlap_batch(8, 100 * MIB, 0), 1);
        // two batches in flight never exceed the budget unless a single frame alone does
        for batch in 1..=16 {
            for fb in [MIB, 8 * MIB, 33 * MIB, 100 * MIB, 400 * MIB, 700 * MIB] {
                let n = overlap_batch(batch, fb, budget) as u64;
                assert!(n >= 1 && n <= batch as u64);
                assert!(n == 1 || 2 * n * fb <= budget, "batch {batch}, frame {fb}: {n}");
            }
        }
    }
}