From 4ae436c4993a602ab8d73b66018782754134aa24 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Matej=20Kozlovsk=C3=BD?=
 <100806068+MatejKozlovsky@users.noreply.github.com>
Date: Sun, 11 Oct 2026 04:42:05 +0200
Subject: [PATCH 01/10] Render: an accelerator reports its adapter, takes
 memory budgets and can convert an export frame to 8-bit YUV 4:2:0 with an
 asynchronous readback (#897)

Defaulted Accelerator hooks for the export: adapter_info, set_memory_budgets, comp_frame_yuv420 (declines by default, so the caller renders on the CPU) and poll_readbacks. gpu_flags carries the export's switches (resident precomps, unified memory) and the reason the accelerator last declined a frame on this thread, so the GPU crate reads no environment.
---
 crates/render/src/gpu_flags.rs | 50 ++++++++++++++++++++++++++++++++++
 crates/render/src/lib.rs       | 39 ++++++++++++++++++++++++++
 2 files changed, 89 insertions(+)
 create mode 100644 crates/render/src/gpu_flags.rs

diff --git a/crates/render/src/gpu_flags.rs b/crates/render/src/gpu_flags.rs
new file mode 100644
index 0000000000..574d1d908f
--- /dev/null
+++ b/crates/render/src/gpu_flags.rs
@@ -0,0 +1,50 @@
+//! Process-wide switches the export tuning (`effectcraft_export::tuning`) hands to the GPU
+//! compositor before a render, so the GPU crate reads no environment of its own, plus the
+//! reason the accelerator last declined a frame on this thread (logged by the export).
+//!
+//! Defaults are the compositor's normal behaviour; the export only turns them off when asked.
+
+use std::cell::RefCell;
+use std::sync::atomic::{AtomicBool, Ordering};
+
+static PRECOMP_RESIDENT: AtomicBool = AtomicBool::new(true);
+static UNIFIED: AtomicBool = AtomicBool::new(false);
+
+/// The switches (see the export's `TUNING.md`).
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct GpuFlags {
+    /// Render precomp layers' nested comps resident on the GPU.
+    pub precomp_resident: bool,
+    /// The GPU shares system memory (re-uploads are cheap copies: a full upload cache is not
+    /// worth a warning).
+    pub unified: bool,
+}
+
+impl Default for GpuFlags {
+    fn default() -> Self {
+        GpuFlags { precomp_resident: true, unified: false }
+    }
+}
+
+pub fn set(f: GpuFlags) {
+    PRECOMP_RESIDENT.store(f.precomp_resident, Ordering::Relaxed);
+    UNIFIED.store(f.unified, Ordering::Relaxed);
+}
+
+pub fn get() -> GpuFlags {
+    GpuFlags { precomp_resident: PRECOMP_RESIDENT.load(Ordering::Relaxed), unified: UNIFIED.load(Ordering::Relaxed) }
+}
+
+thread_local! {
+    static DECLINE: RefCell<Option<String>> = const { RefCell::new(None) };
+}
+
+/// The accelerator declined the frame this thread asked for, because `why`.
+pub fn note_decline(why: impl Into<String>) {
+    DECLINE.with(|d| *d.borrow_mut() = Some(why.into()));
+}
+
+/// The reason noted by [`note_decline`] since the last call.
+pub fn take_decline() -> Option<String> {
+    DECLINE.with(|d| d.borrow_mut().take())
+}
diff --git a/crates/render/src/lib.rs b/crates/render/src/lib.rs
index 41036fe6b7..25ef45b7e7 100644
--- a/crates/render/src/lib.rs
+++ b/crates/render/src/lib.rs
@@ -15,6 +15,7 @@ pub mod color;
 pub mod disk_cache;
 use color::Region;
 pub mod eval;
+pub mod gpu_flags;
 pub mod masks;
 pub mod passes;
 pub mod shapes;
@@ -430,6 +431,31 @@ pub trait Accelerator: Send + Sync {
     /// handled (the CPU renders it).
     fn comp_frame(&self, r: &Renderer, comp: ItemId, t: Tick) -> Option<Image>;
     /// The accelerator implements effect `id` with the CPU effect's semantics.
+    /// Render a top-level comp frame like [`Self::comp_frame`], composite it over `bg` and
+    /// convert it on the device to 8-bit BT.709 limited-range 4:2:0 (the H.264 export's
+    /// input: Y plane, then U and V at half size), delivered to `done` from a later
+    /// [`Self::poll_readbacks`] (`None`: the readback failed). `Err(done)` = not handled.
+    #[allow(clippy::type_complexity)]
+    fn comp_frame_yuv420(
+        &self,
+        _r: &Renderer,
+        _comp: ItemId,
+        _t: Tick,
+        _bg: [f32; 3],
+        done: Box<dyn FnOnce(Option<Vec<u8>>) + Send>,
+    ) -> Result<(), Box<dyn FnOnce(Option<Vec<u8>>) + Send>> {
+        Err(done)
+    }
+    /// Deliver finished asynchronous readbacks ([`Self::comp_frame_yuv420`]); `wait`: block
+    /// briefly for the device.
+    fn poll_readbacks(&self, _wait: bool) {}
+    /// The device behind the accelerator (for export tuning); `None` = unknown.
+    fn adapter_info(&self) -> Option<AdapterInfo> {
+        None
+    }
+    /// Bytes the accelerator may keep in uploaded layer textures and in free working textures
+    /// (export tuning); the default keeps its own.
+    fn set_memory_budgets(&self, _upload: usize, _pool: usize) {}
     fn supports_effect(&self, id: &str) -> bool;
     /// Run a chain of supported effects on `buf`, clamping and quantising to `levels` after
     /// every effect when set (8/16 bpc). `None` = not handled.
@@ -2395,3 +2421,16 @@ mod tests_nested;
 mod tests_paint;
 #[cfg(test)]
 mod tests_time;
+
+/// What an [`Accelerator`] runs on (export tuning).
+#[derive(Clone, Debug, Default, PartialEq, Eq)]
+pub struct AdapterInfo {
+    pub name: String,
+    /// PCI vendor id (0x10de NVIDIA, 0x1002 AMD, 0x8086 Intel).
+    pub vendor: u32,
+    /// "DiscreteGpu", "IntegratedGpu", "Cpu" (software adapter), ...
+    pub device_type: String,
+    pub backend: String,
+    pub max_texture_dim: u32,
+    pub max_buffer_bytes: u64,
+}

From 13066d9e31ae98c614ac84ecd81886e32592332e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Matej=20Kozlovsk=C3=BD?=
 <100806068+MatejKozlovsky@users.noreply.github.com>
Date: Sun, 11 Oct 2026 04:42:05 +0200
Subject: [PATCH 02/10] GPU: export frames convert to YUV 4:2:0 on the GPU and
 read back asynchronously through a staging ring (#897)

A compute kernel does the export's to_rgba8_over + rgba_to_yuv420 (byte-identical to the CPU, tested), so a 4K frame reads back 12 MB of 8-bit 4:2:0 instead of 133 MB of RGBA f32, through the context's bounded readbacks. The context reports its adapter and takes upload and pool budgets (set_upload_budget / set_pool_budget; defaults unchanged); resident precomps follow the export's switch (on by default).
---
 crates/gpu/src/context.rs       |  44 +++++-
 crates/gpu/src/lib.rs           |  95 ++++++++++++-
 crates/gpu/src/readback.rs      | 119 +++++++++++++++-
 crates/gpu/src/shaders/yuv.wgsl |  85 ++++++++++++
 crates/gpu/src/walk.rs          |   2 +-
 crates/gpu/src/yuv.rs           | 231 ++++++++++++++++++++++++++++++++
 6 files changed, 571 insertions(+), 5 deletions(-)
 create mode 100644 crates/gpu/src/shaders/yuv.wgsl
 create mode 100644 crates/gpu/src/yuv.rs

diff --git a/crates/gpu/src/context.rs b/crates/gpu/src/context.rs
index 51221abc37..ab967ce56f 100644
--- a/crates/gpu/src/context.rs
+++ b/crates/gpu/src/context.rs
@@ -117,6 +117,8 @@ pub(crate) struct Pool {
     /// working texture of another `Enc` before it is gone.
     owned: HashMap<u64, HashMap<(u32, u32), Vec<wgpu::Texture>>>,
     next_owner: u64,
+    /// Bytes of free textures kept ([`GpuContext::set_pool_budget`]; default [`POOL_BUDGET`]).
+    budget: Option<usize>,
 }
 
 /// In-`Enc` texture reuse ([`Pool::owned`]); tests turn it off to compare.
@@ -163,7 +165,7 @@ impl Pool {
 
     fn make_free(&mut self, t: wgpu::Texture) {
         let b = tex_bytes(&t);
-        if self.bytes + b > POOL_BUDGET {
+        if self.bytes + b > self.budget.unwrap_or(POOL_BUDGET) {
             return;
         }
         self.bytes += b;
@@ -315,6 +317,10 @@ pub struct GpuContext {
     pub(crate) particle_states: crate::particles::StatesCell,
     /// Deferred readbacks (a browser worker's WebGPU device), see [`crate::deferred`].
     pub(crate) deferred: Option<Arc<crate::deferred::Deferred>>,
+    /// Export frame → YUV 4:2:0 conversion (built on first use).
+    pub(crate) yuv: std::sync::OnceLock<crate::yuv::YuvPipe>,
+    /// The adapter (export tuning).
+    pub(crate) info: effectcraft_render::AdapterInfo,
     readbacks: Arc<crate::readback::Readbacks>,
 }
 
@@ -627,7 +633,18 @@ impl GpuContext {
             init_resource(&device, "dummy storage buffer", || buffer_init(&device, &queue, Some("dummy"), &[0u8; 16], wgpu::BufferUsages::STORAGE))?;
         let dummy_tex = init_resource(&device, "dummy texture view", || dummy.create_view(&Default::default()))?;
         let max_dim = device.limits().max_texture_dimension_2d;
+        let ai = adapter.get_info();
+        let adapter_info = effectcraft_render::AdapterInfo {
+            name: ai.name.clone(),
+            vendor: ai.vendor,
+            device_type: format!("{:?}", ai.device_type),
+            backend: format!("{:?}", ai.backend),
+            max_texture_dim: max_dim,
+            max_buffer_bytes: device.limits().max_buffer_size,
+        };
         Ok(GpuContext {
+            info: adapter_info,
+            yuv: Default::default(),
             device,
             queue,
             name,
@@ -665,6 +682,24 @@ impl GpuContext {
         self.readbacks.check()
     }
 
+    /// Treat failed allocations as declining the frame being recorded, until the guard drops
+    /// (see [`crate::readback::Oom`]).
+    pub(crate) fn arm_oom(&self) -> crate::readback::Armed<'_> {
+        self.readbacks.1.arm()
+    }
+
+    /// Failed allocations reported so far (see [`crate::readback::Oom`]).
+    pub(crate) fn oom_count(&self) -> u64 {
+        self.readbacks.1.count()
+    }
+
+    /// A frame invalidated by a failed allocation was declined: drop the cached uploads and
+    /// let validation errors retire the context again.
+    pub(crate) fn settle_oom(&self) {
+        self.clear_uploads();
+        self.readbacks.1.settle();
+    }
+
     /// A notification hook for the owner of a shared device's error/loss handlers.
     /// Invoke it with diagnostic context when the host observes a device failure.
     /// It retires this context and settles pending readbacks without replacing any
@@ -880,6 +915,13 @@ impl GpuContext {
         self.upload_budget.store(bytes.max(1 << 20), std::sync::atomic::Ordering::Relaxed);
     }
 
+    /// Bytes of free working textures kept for reuse (default 768 MB).
+    pub fn set_pool_budget(&self, bytes: usize) {
+        if let Ok(mut p) = self.pool.lock() {
+            p.budget = Some(bytes);
+        }
+    }
+
     pub fn upload_budget(&self) -> usize {
         self.upload_budget.load(std::sync::atomic::Ordering::Relaxed)
     }
diff --git a/crates/gpu/src/lib.rs b/crates/gpu/src/lib.rs
index 252145c14c..0adccc3cb9 100644
--- a/crates/gpu/src/lib.rs
+++ b/crates/gpu/src/lib.rs
@@ -83,6 +83,7 @@ mod ops;
 mod particles;
 mod readback;
 mod walk;
+mod yuv;
 
 use std::sync::Arc;
 
@@ -318,13 +319,23 @@ impl Accelerator for Gpu {
     }
 
     fn comp_frame(&self, r: &Renderer, comp: ItemId, t: Tick) -> Option<Image> {
-        let img = self.render(r, comp, t);
+        let armed = self.ctx.arm_oom();
+        let before = self.ctx.oom_count();
+        let mut img = self.render(r, comp, t);
+        drop(armed);
+        let oom = self.ctx.oom_count() != before;
+        if oom {
+            // A failed allocation invalidated the frame: decline it, keep the device.
+            self.ctx.settle_oom();
+            img = None;
+        }
         if img.is_none() {
             // The caller renders the frame on the CPU; say so and why, or an export that falls
             // back frame after frame is only mysteriously slow. Once per comp and reason as a
             // warning (the log keeps only the last few hundred, for the System Report), then at
             // debug level.
-            let reason = self.decline_reason();
+            let reason = if oom { format!("{OUT_OF_MEMORY}: a GPU allocation failed while the frame recorded") } else { self.decline_reason() };
+            effectcraft_render::gpu_flags::note_decline(reason.clone());
             let first = self.declined.lock().map(|mut seen| seen.len() < 256 && seen.insert((comp.0, reason.clone()))).unwrap_or(false);
             if first {
                 log::warn!(target: "effectcraft_gpu", "GPU declined the frame at {:.3} s, the CPU renders it: {reason}", t.seconds());
@@ -335,6 +346,82 @@ impl Accelerator for Gpu {
         img
     }
 
+    fn adapter_info(&self) -> Option<effectcraft_render::AdapterInfo> {
+        Some(self.ctx.info.clone())
+    }
+
+    fn set_memory_budgets(&self, upload: usize, pool: usize) {
+        self.ctx.set_upload_budget(upload);
+        self.ctx.set_pool_budget(pool);
+    }
+
+    fn comp_frame_yuv420(
+        &self,
+        r: &Renderer,
+        comp: ItemId,
+        t: Tick,
+        bg: [f32; 3],
+        done: Box<dyn FnOnce(Option<Vec<u8>>) + Send>,
+    ) -> Result<(), Box<dyn FnOnce(Option<Vec<u8>>) + Send>> {
+        if let Err(e) = self.ctx.check_health() {
+            effectcraft_render::gpu_flags::note_decline(format!("device unhealthy: {e}"));
+            return Err(done);
+        }
+        if !self.ctx.can_readback() || self.ctx.deferred.is_some() {
+            effectcraft_render::gpu_flags::note_decline("no synchronous readback on this device");
+            return Err(done);
+        }
+        let yp = self.ctx.yuv.get_or_init(|| yuv::YuvPipe::new(&self.ctx.device));
+        // An allocation that fails while the frame records is caught here instead of retiring
+        // the device, so the caller can lower its frames in flight and retry the frame on the
+        // GPU. `done` stays reclaimable until the readback takes it.
+        let slot = Arc::new(std::sync::Mutex::new(Some(done)));
+        let armed = self.ctx.arm_oom();
+        let before = self.ctx.oom_count();
+        let mut e = Enc::new(&self.ctx);
+        let img = walk::render(&mut e, r, comp, t).filter(|i| i.width % 8 == 0 && i.height % 2 == 0);
+        let rendered = img.is_some();
+        if let Some(img) = &img
+            && self.ctx.oom_count() == before
+        {
+            let s2 = slot.clone();
+            yuv::convert(
+                &mut e,
+                yp,
+                img,
+                bg,
+                Box::new(move |b| {
+                    if let Some(d) = s2.lock().ok().and_then(|mut d| d.take()) {
+                        d(b);
+                    }
+                }),
+            );
+        }
+        drop(e);
+        drop(img);
+        drop(armed);
+        let reclaim = || slot.lock().ok().and_then(|mut d| d.take());
+        if self.ctx.oom_count() != before {
+            self.ctx.settle_oom();
+            effectcraft_render::gpu_flags::note_decline(format!("{OUT_OF_MEMORY}: a GPU allocation failed while the frame recorded"));
+            // The readback already reported the failure if it took `done`.
+            return reclaim().map_or(Ok(()), Err);
+        }
+        if !rendered {
+            effectcraft_render::gpu_flags::note_decline(self.decline_reason());
+            return reclaim().map_or(Ok(()), Err);
+        }
+        Ok(())
+    }
+
+    fn poll_readbacks(&self, wait: bool) {
+        let kind =
+            if wait { wgpu::PollType::Wait { submission_index: None, timeout: Some(std::time::Duration::from_millis(50)) } } else { wgpu::PollType::Poll };
+        // Straight to the device: a wait that times out (the queue is still busy) is normal
+        // here and must not retire the context's readbacks.
+        let _ = self.ctx.device.poll(kind);
+    }
+
     fn supports_effect(&self, id: &str) -> bool {
         self.ctx.check_health().is_ok() && self.ctx.can_readback() && effects::supports(id)
     }
@@ -457,3 +544,7 @@ mod tests_fx_warp;
 mod tests_init;
 #[cfg(test)]
 mod tests_particles;
+
+/// The prefix of a decline reason that a failed GPU allocation caused: the export scheduler
+/// lowers its frames in flight and retries the frame on the GPU when it sees it.
+pub const OUT_OF_MEMORY: &str = "out of memory";
diff --git a/crates/gpu/src/readback.rs b/crates/gpu/src/readback.rs
index 0ca0113501..8a289a70eb 100644
--- a/crates/gpu/src/readback.rs
+++ b/crates/gpu/src/readback.rs
@@ -22,7 +22,87 @@ struct State {
     timer_armed: bool,
 }
 #[derive(Default)]
-pub(crate) struct Readbacks(Mutex<State>);
+pub(crate) struct Readbacks(Mutex<State>, pub(crate) Oom);
+
+/// A failed allocation reported through the device's uncaptured-error handler.
+///
+/// wgpu reports a failed allocation (out-of-memory, or an internal error on drivers that
+/// report it that way) to the uncaptured-error handler of the thread-independent device,
+/// whichever thread allocated: the export renders a frame's layers on several threads, so
+/// thread-local error scopes miss most of them. Such an error does not lose the device; only
+/// the frame being recorded is invalid. The handler counts it instead of retiring the
+/// context, and the validation errors that the frame's invalid resources cause afterwards
+/// are absorbed until the frame is declined ([`Oom::settle`]). This applies only while a
+/// caller that checks [`Oom::count`] records a frame ([`Oom::arm`]); any other error, and
+/// any error outside such a frame (the viewer, the app's preview), still retires the context
+/// as before.
+#[derive(Default)]
+pub(crate) struct Oom {
+    count: std::sync::atomic::AtomicU64,
+    tainted: std::sync::atomic::AtomicBool,
+    armed: std::sync::atomic::AtomicUsize,
+}
+
+/// Keeps [`Oom`] armed while a checked frame records.
+pub(crate) struct Armed<'a>(&'a Oom);
+
+impl Drop for Armed<'_> {
+    fn drop(&mut self) {
+        self.0.armed.fetch_sub(1, std::sync::atomic::Ordering::SeqCst);
+    }
+}
+
+/// The kind of an uncaptured device error.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) enum ErrorKind {
+    OutOfMemory,
+    Internal,
+    Validation,
+}
+
+/// What the handler does with an uncaptured device error.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) enum OnError {
+    /// Counted against the frame being recorded; the device stays in use.
+    Absorb,
+    /// Retire the context (as before).
+    Retire,
+}
+
+impl Oom {
+    /// A frame whose caller checks [`Oom::count`] records until the guard drops.
+    pub(crate) fn arm(&self) -> Armed<'_> {
+        self.armed.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
+        Armed(self)
+    }
+
+    pub(crate) fn on_error(&self, kind: ErrorKind) -> OnError {
+        use std::sync::atomic::Ordering::SeqCst;
+        if self.armed.load(SeqCst) == 0 {
+            return OnError::Retire;
+        }
+        match kind {
+            ErrorKind::OutOfMemory | ErrorKind::Internal => {
+                self.count.fetch_add(1, SeqCst);
+                self.tainted.store(true, SeqCst);
+                OnError::Absorb
+            }
+            ErrorKind::Validation if self.tainted.load(SeqCst) => OnError::Absorb,
+            ErrorKind::Validation => OnError::Retire,
+        }
+    }
+
+    /// Failed allocations so far: a frame whose count changed while it recorded is invalid.
+    pub(crate) fn count(&self) -> u64 {
+        self.count.load(std::sync::atomic::Ordering::SeqCst)
+    }
+
+    /// The invalid frame was declined and its resources dropped: validation errors retire
+    /// the context again.
+    pub(crate) fn settle(&self) {
+        self.tainted.store(false, std::sync::atomic::Ordering::SeqCst);
+    }
+}
 pub(crate) struct Ticket {
     owner: Weak<Readbacks>,
     id: u64,
@@ -264,8 +344,18 @@ pub(crate) fn install(device: &wgpu::Device, me: &Arc<Readbacks>) {
     let fail = Arc::new(failure_notifier(me));
     let lost = fail.clone();
     device.set_device_lost_callback(move |reason, message| lost(format!("GPU device lost ({reason:?}): {message}")));
+    let weak = Arc::downgrade(me);
     device.on_uncaptured_error(Arc::new(move |e| {
         let message = format!("uncaptured GPU error: {e}");
+        let kind = match &e {
+            wgpu::Error::OutOfMemory { .. } => ErrorKind::OutOfMemory,
+            wgpu::Error::Validation { .. } => ErrorKind::Validation,
+            _ => ErrorKind::Internal,
+        };
+        if weak.upgrade().is_some_and(|me| me.1.on_error(kind) == OnError::Absorb) {
+            log::warn!("{message} (the frame being recorded is declined; the device stays in use)");
+            return;
+        }
         fail(message.clone());
         #[cfg(test)]
         #[allow(clippy::panic)]
@@ -527,3 +617,30 @@ mod tests {
         assert_eq!(packed(&[1, 2, 0, 0, 3, 4], 2, 4, 2).unwrap(), vec![1, 2, 3, 4]);
     }
 }
+
+#[cfg(test)]
+mod oom_tests {
+    use super::{ErrorKind, OnError, Oom};
+
+    #[test]
+    fn a_failed_allocation_does_not_retire_the_device() {
+        let o = Oom::default();
+        // Outside a checked frame (the viewer, the app's preview): retire, as before.
+        assert_eq!(o.on_error(ErrorKind::OutOfMemory), OnError::Retire);
+        let armed = o.arm();
+        assert_eq!(o.on_error(ErrorKind::Validation), OnError::Retire);
+        let before = o.count();
+        assert_eq!(o.on_error(ErrorKind::OutOfMemory), OnError::Absorb);
+        // The invalid resources it left fail validation: absorbed until the frame is declined.
+        assert_eq!(o.on_error(ErrorKind::Validation), OnError::Absorb);
+        assert_eq!(o.count(), before + 1);
+        o.settle();
+        assert_eq!(o.on_error(ErrorKind::Validation), OnError::Retire);
+        // Drivers that report a failed allocation as an internal error count too.
+        assert_eq!(o.on_error(ErrorKind::Internal), OnError::Absorb);
+        assert_eq!(o.count(), before + 2);
+        drop(armed);
+        assert_eq!(o.on_error(ErrorKind::OutOfMemory), OnError::Retire);
+        assert_eq!(o.count(), before + 2);
+    }
+}
diff --git a/crates/gpu/src/shaders/yuv.wgsl b/crates/gpu/src/shaders/yuv.wgsl
new file mode 100644
index 0000000000..00b2612689
--- /dev/null
+++ b/crates/gpu/src/shaders/yuv.wgsl
@@ -0,0 +1,85 @@
+// Finished frame → 8-bit BT.709 limited-range 4:2:0 (Y, U, V planes packed 4 bytes per word),
+// composited over the comp background: the GPU twin of `Image::to_rgba8_over` followed by
+// export's `rgba_to_yuv420`, operation for operation (same order of float operations, the same
+// rounding: `as u8` truncation of `x * 255 + 0.5`, `f32::round` half away from zero).
+
+struct YP {
+    // width, height, chroma width, Y words
+    size: vec4<u32>,
+    bg: vec4<f32>,
+}
+
+@group(0) @binding(0) var<uniform> Y: YP;
+@group(0) @binding(1) var frame: texture_2d<f32>;
+@group(0) @binding(2) var<storage, read_write> outw: array<u32>;
+
+fn q8(c: f32) -> f32 {
+    return floor(clamp(c, 0.0, 1.0) * 255.0 + 0.5);
+}
+
+// f32::round for x >= 0 (half away from zero).
+fn round_pos(x: f32) -> f32 {
+    let f = floor(x);
+    return select(f, f + 1.0, x - f >= 0.5);
+}
+
+fn px(x: u32, y: u32) -> vec3<f32> {
+    let p = textureLoad(frame, vec2<i32>(i32(x), i32(y)), 0);
+    let k = 1.0 - clamp(p.w, 0.0, 1.0);
+    let c = vec3<f32>(q8(p.x + Y.bg.x * k), q8(p.y + Y.bg.y * k), q8(p.z + Y.bg.z * k));
+    return c / 255.0;
+}
+
+fn luma(c: vec3<f32>) -> f32 {
+    return 0.2126 * c.x + 0.7152 * c.y + 0.0722 * c.z;
+}
+
+fn y8(l: f32) -> u32 {
+    return u32(clamp(round_pos(16.0 + 219.0 * l), 1.0, 254.0));
+}
+
+// One invocation: 4 chroma samples = 8 × 2 pixels.
+@compute @workgroup_size(8, 8)
+fn yuv420(@builtin(global_invocation_id) gid: vec3<u32>) {
+    let w = Y.size.x;
+    let h = Y.size.y;
+    let cw = Y.size.z;
+    if (gid.x * 4u >= cw || gid.y * 2u >= h) {
+        return;
+    }
+    let x0 = gid.x * 8u;
+    let cy = gid.y;
+    var uw = 0u;
+    var vw = 0u;
+    var yw = array<u32, 4>(0u, 0u, 0u, 0u);
+    for (var q = 0u; q < 4u; q++) {
+        // Accumulate in the CPU's order: row 0 left, right; row 1 left, right.
+        var a0 = 0.0;
+        var a1 = 0.0;
+        for (var dy = 0u; dy < 2u; dy++) {
+            for (var dx = 0u; dx < 2u; dx++) {
+                let x = x0 + q * 2u + dx;
+                let c = px(x, cy * 2u + dy);
+                let l = luma(c);
+                let byte = q * 2u + dx;
+                yw[dy * 2u + byte / 4u] |= y8(l) << (8u * (byte % 4u));
+                a0 += (c.z - l) / 1.8556;
+                a1 += (c.x - l) / 1.5748;
+            }
+        }
+        let u = u32(clamp(round_pos(128.0 + 224.0 * a0 / 4.0), 1.0, 254.0));
+        let v = u32(clamp(round_pos(128.0 + 224.0 * a1 / 4.0), 1.0, 254.0));
+        uw |= u << (8u * q);
+        vw |= v << (8u * q);
+    }
+    let r0 = (cy * 2u * w + x0) / 4u;
+    let r1 = ((cy * 2u + 1u) * w + x0) / 4u;
+    outw[r0] = yw[0];
+    outw[r0 + 1u] = yw[1];
+    outw[r1] = yw[2];
+    outw[r1 + 1u] = yw[3];
+    let cwords = cw / 4u * (h / 2u);
+    let ci = (cy * cw) / 4u + gid.x;
+    outw[Y.size.w + ci] = uw;
+    outw[Y.size.w + cwords + ci] = vw;
+}
diff --git a/crates/gpu/src/walk.rs b/crates/gpu/src/walk.rs
index e954122927..c23af19b48 100644
--- a/crates/gpu/src/walk.rs
+++ b/crates/gpu/src/walk.rs
@@ -295,7 +295,7 @@ fn draw_resident_fx(e: &mut Enc, r: &Renderer, ctx: &EvalCtx, layer: &Layer, can
 /// overrides, frame blending, nested motion-blur sampling; see `Renderer::precomp_source`);
 /// `Some(None)`: the GPU failed.
 fn draw_precomp(e: &mut Enc, r: &Renderer, ctx: &EvalCtx, layer: &Layer, canvas: &mut GpuImage, opacity: f32) -> Option<Option<()>> {
-    if layer.masks().is_some_and(|m| !m.children.is_empty()) || styles::active(ctx, layer) {
+    if !effectcraft_render::gpu_flags::get().precomp_resident || layer.masks().is_some_and(|m| !m.children.is_empty()) || styles::active(ctx, layer) {
         return None;
     }
     let (sub, item, lt, bs) = r.precomp_source(ctx, layer)?;
diff --git a/crates/gpu/src/yuv.rs b/crates/gpu/src/yuv.rs
new file mode 100644
index 0000000000..9676a2a031
--- /dev/null
+++ b/crates/gpu/src/yuv.rs
@@ -0,0 +1,231 @@
+//! Export frames converted on the device to the H.264 encoder's input (8-bit BT.709 limited
+//! range 4:2:0, see `shaders/yuv.wgsl`) and read back asynchronously: 12 MB per 4K frame
+//! instead of 133 MB of RGBA f32, and the worker records the next frame while the copy runs.
+
+use std::sync::{Arc, Mutex};
+
+use wgpu::util::DeviceExt;
+
+use crate::context::{Enc, GpuContext, GpuImage};
+
+pub(crate) struct YuvPipe {
+    bgl: wgpu::BindGroupLayout,
+    pipe: wgpu::ComputePipeline,
+    /// Storage buffers the kernel writes, by size.
+    outs: Mutex<Vec<wgpu::Buffer>>,
+    /// Mappable staging buffers, returned by the map callbacks.
+    staging: Arc<Mutex<Vec<wgpu::Buffer>>>,
+}
+
+/// Buffers kept for reuse (each ring).
+const RING: usize = 8;
+
+impl YuvPipe {
+    pub(crate) fn new(device: &wgpu::Device) -> YuvPipe {
+        let module = device.create_shader_module(wgpu::ShaderModuleDescriptor {
+            label: Some("yuv420"),
+            source: wgpu::ShaderSource::Wgsl(include_str!("shaders/yuv.wgsl").into()),
+        });
+        let bgl = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
+            label: Some("yuv420"),
+            entries: &[
+                wgpu::BindGroupLayoutEntry {
+                    binding: 0,
+                    visibility: wgpu::ShaderStages::COMPUTE,
+                    ty: wgpu::BindingType::Buffer { ty: wgpu::BufferBindingType::Uniform, has_dynamic_offset: false, min_binding_size: None },
+                    count: None,
+                },
+                wgpu::BindGroupLayoutEntry {
+                    binding: 1,
+                    visibility: wgpu::ShaderStages::COMPUTE,
+                    ty: wgpu::BindingType::Texture {
+                        sample_type: wgpu::TextureSampleType::Float { filterable: false },
+                        view_dimension: wgpu::TextureViewDimension::D2,
+                        multisampled: false,
+                    },
+                    count: None,
+                },
+                wgpu::BindGroupLayoutEntry {
+                    binding: 2,
+                    visibility: wgpu::ShaderStages::COMPUTE,
+                    ty: wgpu::BindingType::Buffer {
+                        ty: wgpu::BufferBindingType::Storage { read_only: false },
+                        has_dynamic_offset: false,
+                        min_binding_size: None,
+                    },
+                    count: None,
+                },
+            ],
+        });
+        let layout =
+            device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor { label: Some("yuv420"), bind_group_layouts: &[Some(&bgl)], immediate_size: 0 });
+        let pipe = device.create_compute_pipeline(&wgpu::ComputePipelineDescriptor {
+            label: Some("yuv420"),
+            layout: Some(&layout),
+            module: &module,
+            entry_point: Some("yuv420"),
+            compilation_options: Default::default(),
+            cache: None,
+        });
+        YuvPipe { bgl, pipe, outs: Mutex::new(vec![]), staging: Arc::new(Mutex::new(vec![])) }
+    }
+}
+
+fn take(ring: &Mutex<Vec<wgpu::Buffer>>, size: u64, make: impl FnOnce() -> wgpu::Buffer) -> wgpu::Buffer {
+    let found = ring.lock().ok().and_then(|mut r| r.iter().position(|b| b.size() == size).map(|i| r.swap_remove(i)));
+    found.unwrap_or_else(make)
+}
+
+fn give(ring: &Mutex<Vec<wgpu::Buffer>>, b: wgpu::Buffer) {
+    if let Ok(mut r) = ring.lock()
+        && r.len() < RING
+    {
+        r.push(b);
+    }
+}
+
+/// Convert `img` (`w` a multiple of 8, `h` even) over `bg`, submit, and hand the planes
+/// (Y `w×h`, then U and V `w/2 × h/2`) to `done` from a later device poll.
+pub(crate) fn convert(e: &mut Enc, yp: &YuvPipe, img: &GpuImage, bg: [f32; 3], done: Box<dyn FnOnce(Option<Vec<u8>>) + Send>) {
+    let g: &GpuContext = e.g;
+    let (w, h) = (img.width, img.height);
+    let cw = w / 2;
+    let ywords = w * h / 4;
+    let size = (w as u64 * h as u64) + 2 * (cw as u64 * (h / 2) as u64);
+    let out = take(&yp.outs, size, || {
+        g.device.create_buffer(&wgpu::BufferDescriptor {
+            label: Some("yuv420 out"),
+            size,
+            usage: wgpu::BufferUsages::STORAGE | wgpu::BufferUsages::COPY_SRC,
+            mapped_at_creation: false,
+        })
+    });
+    let stg = take(&yp.staging, size, || {
+        g.device.create_buffer(&wgpu::BufferDescriptor {
+            label: Some("yuv420 staging"),
+            size,
+            usage: wgpu::BufferUsages::MAP_READ | wgpu::BufferUsages::COPY_DST,
+            mapped_at_creation: false,
+        })
+    });
+    let mut params = [0u8; 32];
+    for (i, v) in [w, h, cw, ywords].into_iter().enumerate() {
+        params[i * 4..i * 4 + 4].copy_from_slice(&v.to_le_bytes());
+    }
+    for (i, v) in [bg[0], bg[1], bg[2], 1.0].into_iter().enumerate() {
+        params[16 + i * 4..16 + i * 4 + 4].copy_from_slice(&v.to_le_bytes());
+    }
+    let ub =
+        g.device.create_buffer_init(&wgpu::util::BufferInitDescriptor { label: Some("yuv420 params"), contents: &params, usage: wgpu::BufferUsages::UNIFORM });
+    let view = img.texture.create_view(&Default::default());
+    let bg_ = g.device.create_bind_group(&wgpu::BindGroupDescriptor {
+        label: Some("yuv420"),
+        layout: &yp.bgl,
+        entries: &[
+            wgpu::BindGroupEntry { binding: 0, resource: ub.as_entire_binding() },
+            wgpu::BindGroupEntry { binding: 1, resource: wgpu::BindingResource::TextureView(&view) },
+            wgpu::BindGroupEntry { binding: 2, resource: out.as_entire_binding() },
+        ],
+    });
+    {
+        let enc = e.encoder();
+        {
+            let mut pass = enc.begin_compute_pass(&wgpu::ComputePassDescriptor { label: Some("yuv420"), timestamp_writes: None });
+            pass.set_pipeline(&yp.pipe);
+            pass.set_bind_group(0, &bg_, &[]);
+            pass.dispatch_workgroups((w / 8).div_ceil(8), (h / 2).div_ceil(8), 1);
+        }
+        enc.copy_buffer_to_buffer(&out, 0, &stg, 0, size);
+    }
+    e.submit();
+    // Later work on the queue runs after this copy: the storage buffer is free to reuse.
+    give(&yp.outs, out);
+    let ring = yp.staging.clone();
+    let b = stg.clone();
+    // Through the context's bounded readbacks (deadline, retirement on device loss).
+    g.map_readback(&stg, size as usize, size as usize, 1, move |r| {
+        give(&ring, b);
+        done(r.map_err(|e| log::error!(target: "effectcraft_gpu", "yuv420 readback: {e}")).ok());
+    });
+}
+
+#[cfg(test)]
+mod tests {
+    use effectcraft_raster::Image;
+
+    /// export's `to_rgba8_over` + `rgba_to_yuv420` (crates/export/src/encode.rs), verbatim.
+    fn cpu(img: &Image, bg: [f32; 3]) -> Vec<u8> {
+        let rgba = img.to_rgba8_over(bg);
+        let (w, h) = (img.width as usize, img.height as usize);
+        let cw = w / 2;
+        let mut y = vec![0u8; w * h];
+        let mut u = vec![0u8; cw * (h / 2)];
+        let mut v = vec![0u8; cw * (h / 2)];
+        for cy in 0..h / 2 {
+            let mut acc = vec![(0f32, 0f32, 0f32); cw];
+            for dy in 0..2 {
+                let src = &rgba[(cy * 2 + dy) * w * 4..][..w * 4];
+                for x in 0..w {
+                    let (r, g, b) = (src[x * 4] as f32 / 255.0, src[x * 4 + 1] as f32 / 255.0, src[x * 4 + 2] as f32 / 255.0);
+                    let l = 0.2126 * r + 0.7152 * g + 0.0722 * b;
+                    y[(cy * 2 + dy) * w + x] = (16.0 + 219.0 * l).round().clamp(1.0, 254.0) as u8;
+                    let a = &mut acc[x / 2];
+                    a.0 += (b - l) / 1.8556;
+                    a.1 += (r - l) / 1.5748;
+                    a.2 += 1.0;
+                }
+            }
+            for (cx, a) in acc.iter().enumerate() {
+                u[cy * cw + cx] = (128.0 + 224.0 * a.0 / a.2).round().clamp(1.0, 254.0) as u8;
+                v[cy * cw + cx] = (128.0 + 224.0 * a.1 / a.2).round().clamp(1.0, 254.0) as u8;
+            }
+        }
+        [y, u, v].concat()
+    }
+
+    #[test]
+    fn yuv420_matches_cpu() {
+        let Some(g) = crate::tests::gpu() else { return };
+        let (w, h) = (264u32, 150u32);
+        let mut img = Image::new(w, h);
+        let mut s = 0x9e3779b9u32;
+        let mut rnd = || {
+            s ^= s << 13;
+            s ^= s >> 17;
+            s ^= s << 5;
+            s as f32 / u32::MAX as f32
+        };
+        for (i, p) in img.data.iter_mut().enumerate() {
+            let a = if i % 7 == 0 { 1.0 } else { rnd() };
+            // premultiplied, a few out of range, plus exact 8-bit levels (rounding ties)
+            *p = if i % 5 == 0 {
+                let q = (i % 256) as f32 / 255.0;
+                [q, 1.0 - q, q * 0.5, 1.0]
+            } else {
+                [rnd() * a * 1.1 - 0.02, rnd() * a, rnd() * a, a]
+            };
+        }
+        let bg = [0.05, 0.1, 0.2];
+        let want = cpu(&img, bg);
+        let src = g.ctx.upload_image(&img).expect("upload");
+        let yp = g.ctx.yuv.get_or_init(|| super::YuvPipe::new(&g.ctx.device));
+        let got = std::sync::Arc::new(std::sync::Mutex::new(None));
+        let got2 = got.clone();
+        let mut e = crate::context::Enc::new(&g.ctx);
+        super::convert(&mut e, yp, &src, bg, Box::new(move |b| *got2.lock().unwrap() = Some(b)));
+        drop(e);
+        for _ in 0..200 {
+            // Straight to the device: a short wait timing out is normal and must not retire the context.
+            let _ = g.ctx.device.poll(wgpu::PollType::Wait { submission_index: None, timeout: Some(std::time::Duration::from_millis(50)) });
+            if got.lock().unwrap().is_some() {
+                break;
+            }
+        }
+        let got = got.lock().unwrap().take().flatten().expect("readback");
+        assert_eq!(got.len(), want.len());
+        let diff: Vec<usize> = (0..got.len()).filter(|&i| got[i] != want[i]).collect();
+        let max = diff.iter().map(|&i| (got[i] as i32 - want[i] as i32).abs()).max().unwrap_or(0);
+        eprintln!("yuv420: {} of {} bytes differ (max {max}) on {}", diff.len(), got.len(), g.ctx.name);
+        assert!(diff.is_empty(), "first diffs at {:?}", &diff[..diff.len().min(10)]);
+    }
+}

From 4299ee987893c5b9000f2f135f88cd35f6cb0bcb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Matej=20Kozlovsk=C3=BD?=
 <100806068+MatejKozlovsky@users.noreply.github.com>
Date: Sun, 11 Oct 2026 04:42:37 +0200
Subject: [PATCH 03/10] Export: render --gpu streams frames through a shared
 CPU/GPU work queue with a bounded reorder buffer, adaptive CPU workers and
 hardware-adaptive tuning, instead of handing the GPU a batch of frames at
 once (#897)

The batch-parallel export sent a whole batch (up to 16 frames) to the GPU at once; the frames filled VRAM and fell back to the CPU without a word. A tuned plan now keeps gpu-frames on the GPU, adds CPU workers only while measured throughput improves (and never ones slow enough to stall the in-order encoder), and logs why the GPU declined a frame. H.264/HEVC/AV1/WebM take the GPU's YUV 4:2:0 frames, read back asynchronously so the GPU worker records the next frame during the copy.

Every option is set independently: CLI > EFFECTCRAFT_EXPORT_<OPTION> > config file > auto. Auto reads the GPU (VRAM, vendor, unified memory) and CPU (threads, performance/efficiency cores, RAM). The tuned pipeline is automatic only on NVIDIA discrete and Apple GPUs; other vendors keep the stock behaviour unless enabled. The RAM budget caps the CPU path's batch. CPU-only exports are unchanged. See crates/export/TUNING.md.
---
 Cargo.lock                       |  15 +
 crates/export/Cargo.toml         |   3 +
 crates/export/TUNING.md          |  91 +++
 crates/export/src/encode.rs      |  91 ++-
 crates/export/src/hw.rs          | 128 +++++
 crates/export/src/lib.rs         |  27 +-
 crates/export/src/pipeline.rs    | 540 +++++++++++++++++-
 crates/export/src/stream.rs      | 462 +++++++++++++++
 crates/export/src/tuning.rs      | 940 +++++++++++++++++++++++++++++++
 crates/export/src/webm.rs        |   2 +-
 crates/export/src/webm_av1.rs    |   2 +-
 crates/export/tests/scheduler.rs | 225 ++++++++
 12 files changed, 2495 insertions(+), 31 deletions(-)
 create mode 100644 crates/export/TUNING.md
 create mode 100644 crates/export/src/hw.rs
 create mode 100644 crates/export/src/stream.rs
 create mode 100644 crates/export/src/tuning.rs
 create mode 100644 crates/export/tests/scheduler.rs

diff --git a/Cargo.lock b/Cargo.lock
index 38999ed0c0..9bc7b360a7 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1286,6 +1286,7 @@ dependencies = [
  "log",
  "rayon",
  "thiserror 2.0.21",
+ "thread-priority",
  "web-time",
 ]
 
@@ -5074,6 +5075,20 @@ dependencies = [
  "syn 3.0.6",
 ]
 
+[[package]]
+name = "thread-priority"
+version = "3.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8d2e834949be5111506bb252643498af1514f600d9e1dceedaa42afae155b67f"
+dependencies = [
+ "bitflags 2.13.2",
+ "cfg-if",
+ "libc",
+ "log",
+ "rustversion",
+ "windows 0.62.2",
+]
+
 [[package]]
 name = "tiff"
 version = "0.11.3"
diff --git a/crates/export/Cargo.toml b/crates/export/Cargo.toml
index 2ef6f5ad8e..32687e307b 100644
--- a/crates/export/Cargo.toml
+++ b/crates/export/Cargo.toml
@@ -29,6 +29,9 @@ web-time = { workspace = true }
 thiserror = { workspace = true }
 log = { workspace = true }
 
+[target.'cfg(not(target_arch = "wasm32"))'.dependencies]
+thread-priority = "3"
+
 [dev-dependencies]
 effectcraft-media = { workspace = true }
 effectcraft-effects = { workspace = true }
diff --git a/crates/export/TUNING.md b/crates/export/TUNING.md
new file mode 100644
index 0000000000..5b63a29d85
--- /dev/null
+++ b/crates/export/TUNING.md
@@ -0,0 +1,91 @@
+# Export tuning
+
+Every pipeline improvement of the GPU export is an independent option. Each has three
+spellings, resolved per export with precedence **CLI > environment > config file > auto**:
+
+| CLI (`render`)        | environment                          | config file          |
+|-----------------------|--------------------------------------|----------------------|
+| `--gpu-inflight 3`    | `EFFECTCRAFT_EXPORT_GPU_INFLIGHT=3`  | `gpu-inflight = 3`   |
+
+Config file: `--tuning-config FILE` or `EFFECTCRAFT_EXPORT_CONFIG=FILE` (`key = value` lines,
+`#` comments). The value `auto` (or leaving an option out) lets the auto rules decide.
+`--print-tuning` prints every resolved value, where it came from and why, and renders nothing.
+`--threads N` / `EFFECTCRAFT_EXPORT_THREADS` sizes the rayon pool (simulates a smaller CPU).
+`RUST_LOG=effectcraft_export=info` logs the same table at the start of every export.
+
+## Options
+
+| option | values | auto |
+|---|---|---|
+| `backend` | auto, gpu, cpu | `auto` with a GPU (GPU workers + adaptive CPU workers); stock path without one; `cpu` if one frame does not fit the VRAM budget (warning logged) |
+| `gpu-frames` | N (0 = stock batches) | 1 GPU recording worker |
+| `gpu-inflight` | N ≥ 1 | 1 (below: room for up to 3 is reported, not used) |
+| `cpu-frames` | N, auto | adaptive: start GPU-only, add CPU workers while measured frames/s improves, max min(threads/2, 8); 0 with `backend gpu` |
+| `cpu-pool` | N (0 = global pool) | threads/2 when there are CPU workers |
+| `gpu-pool` | N (0 = global pool) | 0 |
+| `gpu-priority` | on, off | off |
+| `gpu-ideal-cpu` | N | unset (Windows only) |
+| `cache-mb` | MB (0 = off) | 4096: the job-wide layer cache, bounded (stock leaves it unbounded) |
+| `precomp-resident` | on, off | on with a GPU: precomp layers' nested comps render on the GPU (2D precomp layers without masks/styles/proxies/overrides/frame blending; others take the CPU path) |
+| `gpu-yuv` | on, off | on with a native GPU (H.264 only; byte-identical to the CPU conversion) |
+| `async-readback` | on, off | on when `gpu-yuv` is on (off = wait for each frame) |
+| `cpu-batch` | N | one CPU-compositor frame per thread, capped so ~8x the frame buffer each fits 60% of the RAM budget after the layer cache |
+| `ram-budget-mb` | MB | detected RAM: unified-memory GPUs plan from it; the layer cache is capped at 15% of it |
+| `vram-budget-mb` | MB | detected dedicated VRAM (amdgpu sysfs on Linux); unified memory: from RAM; else 2048 |
+| `upload-budget-mb` | MB | 25% of the VRAM budget, clamped to 256..1536 (a warning is logged once when it overflows) |
+| `pool-budget-mb` | MB | 5% of the VRAM budget, clamped to 128..768 |
+
+## Auto rules
+
+* **No GPU attached** (or `backend cpu`): the stock CPU path: parallel batches, the job layer cache,
+  software encoder, the project's renderer. The output is byte-identical to the stock export.
+* **VRAM plan**: the first frame in flight needs about 1,332 B per output pixel (≈ 10.3 GB at 4K,
+  2.6 GB at 1080p), calibrated from measured peaks without working-texture reuse (the GPU composites in
+  RGBA f32 whatever the project's bit depth); each further frame adds two RGBA f32 frames.
+  `free = 90% of budget − upload cache − texture pool − 384 MB`, and room for `clamp(frames that fit / gpu-frames, 1, 3)` frames in flight (`--print-tuning` shows it).
+  The default `gpu-inflight` is **1** all the same: with more, a frame that runs out of GPU memory is
+  retried, and the retry (plus a few frames after it) does not render exactly as it would have without
+  the failure, so the same export can differ between runs (Singularity at 1080p: frames 55-59 at ~30 dB).
+  Until that is fixed, set `gpu-inflight` above 1 only where a run-to-run difference is acceptable.
+  One frame in flight also measured no slower there (46.8 s vs 43-65 s with 3, which kept running out of memory).
+  Room at 4K: 24 GB → 3; 16 GB → 3; 8 GB and less → 0, so the backend becomes `cpu` up front and one warning says why
+  (GPU memory savings such as #688's texture reuse would let it render on the GPU). 1080p: 8 GB → 3, 4 GB and less → `cpu`.
+  A forced `backend gpu` that does not fit is kept but warned about.
+* **Out of memory while rendering**: a failed GPU allocation (reported to the device's error handler from
+  whichever thread allocated) invalidates only that frame: the device stays in use. The GPU worker waits for its frames in flight, keeps one fewer in flight from then on (at least 1, logged once)
+  and retries the frame on the GPU; only a frame that fails again is rendered on the CPU.
+* **CPU workers** stay adaptive by measured throughput. Before the first one is tried, a CPU frame is
+  estimated (frame rendered at quarter size, ×16). No worker is tried when a CPU frame would take more than
+  half the reorder buffer's worth of GPU frames (it would stall the in-order encoder) or add < 3%. Every frame the GPU declines is rendered on
+  the CPU and logged as a warning with the reason (device failure / out of memory, unsupported
+  content, frame larger than the texture limit), and the end summary counts these frames. So there
+  is no silent fallback.
+* **Encoder:** H.264 always uses the pure-Rust software encoder (no hardware encoder).
+
+## Unified memory (Apple silicon, integrated GPUs)
+
+* Detected from the adapter (integrated, or an Apple GPU). There is no separate VRAM: the GPU budget
+  (`vram-budget-mb`) is min(40% of RAM, 60% of the RAM available when the export starts); RAM and
+  availability come from `sysctl hw.memsize` + `vm_stat` (macOS) or `/proc/meminfo` (Linux).
+* The upload cache gets 256 MB plus what the frame slots leave of that budget (at most 1024 MB): an
+  upload is a copy within shared memory, so frame slots come first.
+* The CPU layer cache is capped at 15% of RAM (it competes with the GPU for the same memory).
+* Performance/efficiency cores (`hw.perflevel0/1`): adaptive CPU workers and their pool use at most
+  the efficiency cores; the performance cores stay with the GPU worker's CPU side and the encoder.
+  With `--threads N` the split is scaled to N.
+* If a frame does not fit the budget (little free memory, small `ram-budget-mb`), the export renders
+  on the CPU and logs a warning saying so.
+
+## Which GPUs get the tuned pipeline automatically
+
+`auto` applies the tuned GPU pipeline (scheduler, resident precomps,
+GPU YUV, budgets) only on GPUs it was verified on: **NVIDIA discrete** (RTX 3090, Windows) and
+**Apple silicon** (M4, macOS). On AMD, Intel, NVIDIA integrated and unknown adapters, `auto` keeps
+the stock path and `--print-tuning` / the export log say why. Users opt in with
+`--backend gpu` (the whole tuned pipeline) or with individual options (e.g. `--precomp-resident on`).
+
+## Memory limits on the CPU path
+
+With a RAM budget (detected, or `ram-budget-mb`), the CPU compositor renders at most `cpu-batch`
+frames at once, so a constrained machine (or a GPU-less fallback) does not run out of memory.
+The layer cache is capped at 15% of the budget.
diff --git a/crates/export/src/encode.rs b/crates/export/src/encode.rs
index e4a45561d9..f2c56434b9 100644
--- a/crates/export/src/encode.rs
+++ b/crates/export/src/encode.rs
@@ -30,6 +30,11 @@ pub(crate) trait VideoEncoder {
     fn sample_entry(&self) -> SampleEntry;
     fn encode(&mut self, rgba: &[u8], index: u64) -> Result<Vec<Packet>>;
     fn flush(&mut self) -> Result<Vec<Packet>>;
+    /// Encode a frame already in the encoder's 8-bit 4:2:0 layout (Y, then U and V planes at
+    /// half size; [`rgba_to_yuv420`]'s output). Only H.264 takes it.
+    fn encode_yuv(&mut self, _yuv: &[u8], _index: u64) -> Result<Vec<Packet>> {
+        Err(ExportError::Unsupported("YUV input".into()))
+    }
     /// Edit-list media start (B-frame delay) in the track timescale.
     fn media_start(&self) -> Option<i64> {
         None
@@ -83,6 +88,19 @@ impl VideoEncoder for H264 {
         let ps = self.enc.flush();
         Ok(self.packets(ps))
     }
+    fn encode_yuv(&mut self, yuv: &[u8], index: u64) -> Result<Vec<Packet>> {
+        let (w, h) = (self.w as usize, self.h as usize);
+        let cw = w.div_ceil(2);
+        let c = cw * h.div_ceil(2);
+        if yuv.len() != w * h + 2 * c {
+            return Err(ExportError::Unsupported(format!("YUV frame of {} bytes for {w}x{h}", yuv.len())));
+        }
+        let (y, uv) = yuv.split_at(w * h);
+        let (u, v) = uv.split_at(c);
+        let frame = filmcraft_h264enc::YuvFrame { y, u, v, y_stride: w, uv_stride: cw };
+        let ps = self.enc.try_encode(&frame, index as i64 * self.rate.den).map_err(enc)?;
+        Ok(self.packets(ps))
+    }
     fn media_start(&self) -> Option<i64> {
         (self.enc.delay() > 0).then_some(self.rate.den)
     }
@@ -257,22 +275,47 @@ pub(crate) async fn movie(job: &Cx<'_>, comp: &Comp, w: u32, h: u32, st: &mut St
         c => c,
     };
     let mut venc: Box<dyn VideoEncoder> = match fmt {
-        OutputFormat::H264 => Box::new(H264::new(w, h, rate, job.output.bitrate_kbps)?),
+        OutputFormat::H264 => {
+            log::info!(target: "effectcraft_export", "H.264 encoder: software");
+            Box::new(H264::new(w, h, rate, job.output.bitrate_kbps)?)
+        }
         OutputFormat::Hevc => Box::new(crate::hevc_av1::Hevc::new(w, h, rate, job.output)?),
         OutputFormat::Av1 => Box::new(crate::hevc_av1::Av1::new(w, h, rate, job.output)?),
         OutputFormat::Uncompressed => Box::new(crate::uncompressed::Raw::new(w, h, channels == Channels::Rgba)?),
         _ => Box::new(ProRes::new(w, h, job.output.prores_profile, if channels == Channels::Alpha { Channels::Rgb } else { channels })),
     };
     let brand = if matches!(fmt, OutputFormat::ProRes | OutputFormat::Uncompressed) { Brand::Mov } else { Brand::Mp4 };
-    let batch = batch_size();
-    let render = |_: u64, img: effectcraft_raster::Image| -> Vec<u8> { job.pixels(&img, comp, channels, w, h) };
+    let batch = batch_size(job);
+    // Frames reach the encoder as 8-bit RGBA, or (H.264 on a GPU worker) as 4:2:0 converted
+    // on the device.
+    enum Px {
+        Rgba(Vec<u8>),
+        Yuv(Vec<u8>),
+    }
+    let rendered = std::sync::Mutex::new(None);
+    let render = |_: u64, img: effectcraft_raster::Image| -> Px {
+        rendered.lock().unwrap_or_else(|e| e.into_inner()).get_or_insert((img.width, img.height));
+        Px::Rgba(job.pixels(&img, comp, channels, w, h))
+    };
+    let enc_s = std::cell::Cell::new(0f64);
+    let encode = |venc: &mut Box<dyn VideoEncoder>, px: &Px, k: u64| -> Result<Vec<Packet>> {
+        let t = std::time::Instant::now();
+        let r = match px {
+            Px::Rgba(b) => venc.encode(b, k),
+            Px::Yuv(b) => venc.encode_yuv(b, k),
+        };
+        enc_s.set(enc_s.get() + t.elapsed().as_secs_f64());
+        r
+    };
 
     // Encode the first batch before creating tracks: encoders finalise their config on frame 1.
-    let first_end = batch.min(st.total);
-    let first: Vec<Vec<u8>> = job.frames(comp, (0..first_end).collect(), render).await;
+    // A scheduled plan streams every frame after the first.
+    let streaming = matches!(job.plan, crate::tuning::Plan::Scheduled { .. });
+    let first_end = if streaming { 1 } else { batch }.min(st.total);
+    let first: Vec<Px> = job.frames(comp, (0..first_end).collect(), render).await;
     let mut pending = Vec::new();
     for (k, px) in first.iter().enumerate() {
-        pending.extend(venc.encode(px, k as u64)?);
+        pending.extend(encode(&mut venc, px, k as u64)?);
     }
     drop(first);
     st.advance(first_end)?;
@@ -356,11 +399,43 @@ pub(crate) async fn movie(job: &Cx<'_>, comp: &Comp, w: u32, h: u32, st: &mut St
     write_video(&mut mux, pending)?;
     write_audio_until(&mut mux, frame_end_time(first_end), &mut cursor)?;
     let mut i = first_end;
+    if streaming && i < total {
+        // Reorder buffer: up to 16 frames, at most ~2 GiB of 8-bit RGBA.
+        let cap = ((2usize << 30) / ((w as usize * h as usize * 4).max(1))).clamp(4, 16);
+        let ks: Vec<u64> = (i..total).collect();
+        let yuv = |_: u64, b: Vec<u8>| Px::Yuv(b);
+        let rendered = *rendered.lock().unwrap_or_else(|e| e.into_inner());
+        let direct_ok = fmt == OutputFormat::H264 && channels == Channels::Rgb && job.yuv_direct_ok(w, h, rendered);
+        let direct = crate::pipeline::Direct { bg: comp.background, map: &yuv };
+        log::info!(target: "effectcraft_export", "GPU-side YUV 4:2:0 + async readback: {}", if direct_ok { "on" } else { "off" });
+        let t_stream = std::time::Instant::now();
+        let (mut mux_s, mut n) = (0f64, 0u64);
+        job.stream(comp, &ks, &render, cap, direct_ok.then_some(&direct), |k, px| {
+            let ps = encode(&mut venc, &px, k)?;
+            drop(px);
+            let t = std::time::Instant::now();
+            write_video(&mut mux, ps)?;
+            write_audio_until(&mut mux, frame_end_time(k + 1), &mut cursor)?;
+            mux_s += t.elapsed().as_secs_f64();
+            n += 1;
+            st.advance(1)
+        })?;
+        let wall = t_stream.elapsed().as_secs_f64();
+        log::info!(
+            target: "effectcraft_export",
+            "encoder: {n} streamed frames, H.264 encode {:.1} ms/frame (total {:.1} s incl. frame 0), mux+audio {:.1} ms/frame; consumer busy {:.0}% of {wall:.1} s",
+            enc_s.get() * 1e3 / (n + 1) as f64,
+            enc_s.get(),
+            mux_s * 1e3 / n.max(1) as f64,
+            100.0 * (enc_s.get() + mux_s) / wall.max(1e-9)
+        );
+        i = total;
+    }
     while i < total {
         let end = (i + batch).min(total);
-        let frames: Vec<Vec<u8>> = job.frames(comp, (i..end).collect(), render).await;
+        let frames: Vec<Px> = job.frames(comp, (i..end).collect(), render).await;
         for (k, px) in frames.iter().enumerate() {
-            let ps = venc.encode(px, i + k as u64)?;
+            let ps = encode(&mut venc, px, i + k as u64)?;
             write_video(&mut mux, ps)?;
         }
         write_audio_until(&mut mux, frame_end_time(end), &mut cursor)?;
diff --git a/crates/export/src/hw.rs b/crates/export/src/hw.rs
new file mode 100644
index 0000000000..797f9d0242
--- /dev/null
+++ b/crates/export/src/hw.rs
@@ -0,0 +1,128 @@
+//! Hardware the export tuning plans for ([`crate::tuning::Hardware`]).
+
+use crate::tuning::{GpuHw, Hardware};
+
+/// The machine as seen by this export: rayon threads and the attached accelerator.
+pub(crate) fn detect(accel: Option<&dyn effectcraft_render::Accelerator>) -> Hardware {
+    let gpu = accel.map(|a| {
+        let info = a.adapter_info().unwrap_or_default();
+        let vram_bytes = dedicated_vram(info.vendor, &info.name);
+        // Apple silicon and integrated GPUs share system memory.
+        let unified = info.device_type == "IntegratedGpu" || info.name.starts_with("Apple");
+        GpuHw {
+            name: if info.name.is_empty() { a.name() } else { info.name },
+            vendor: info.vendor,
+            device_type: info.device_type,
+            vram_bytes,
+            unified,
+            max_texture_dim: if info.max_texture_dim == 0 { 8192 } else { info.max_texture_dim },
+            native: !effectcraft_render::passes::is_deferred(Some(a)),
+        }
+    });
+    let (ram_bytes, avail_ram_bytes) = memory();
+    Hardware { gpu, threads: rayon::current_num_threads(), ram_bytes, avail_ram_bytes, core_kinds: core_kinds() }
+}
+
+/// `sysctl -n NAME` (macOS), parsed.
+#[cfg(target_os = "macos")]
+fn sysctl(name: &str) -> Option<u64> {
+    let out = std::process::Command::new("/usr/sbin/sysctl").args(["-n", name]).output().ok()?;
+    String::from_utf8_lossy(&out.stdout).trim().parse().ok()
+}
+
+/// Physical memory and memory available now (free + inactive + speculative + purgeable pages on
+/// macOS, `MemAvailable` on Linux); `None` where not queried.
+fn memory() -> (Option<u64>, Option<u64>) {
+    #[cfg(target_os = "macos")]
+    {
+        let total = sysctl("hw.memsize");
+        let avail = std::process::Command::new("/usr/bin/vm_stat").output().ok().and_then(|o| {
+            let text = String::from_utf8_lossy(&o.stdout).into_owned();
+            let page = text.split("page size of ").nth(1)?.split_whitespace().next()?.parse::<u64>().ok()?;
+            let pages = |key: &str| {
+                text.lines()
+                    .find(|l| l.starts_with(key))
+                    .and_then(|l| l.rsplit(':').next())
+                    .and_then(|v| v.trim().trim_end_matches('.').parse::<u64>().ok())
+                    .unwrap_or(0)
+            };
+            let n = pages("Pages free") + pages("Pages inactive") + pages("Pages speculative") + pages("Pages purgeable");
+            Some(n.saturating_mul(page))
+        });
+        (total, avail)
+    }
+    #[cfg(target_os = "linux")]
+    {
+        let Ok(m) = std::fs::read_to_string("/proc/meminfo") else { return (None, None) };
+        let kb =
+            |key: &str| m.lines().find(|l| l.starts_with(key)).and_then(|l| l.split_whitespace().nth(1)).and_then(|v| v.parse::<u64>().ok()).map(|v| v * 1024);
+        (kb("MemTotal:"), kb("MemAvailable:"))
+    }
+    #[cfg(windows)]
+    {
+        // No platform calls (the workspace has no `unsafe`): ask CIM through PowerShell, in KB.
+        let out = std::process::Command::new("powershell.exe")
+            .args([
+                "-NoProfile",
+                "-NonInteractive",
+                "-Command",
+                "$o = Get-CimInstance Win32_OperatingSystem; \"$($o.TotalVisibleMemorySize) $($o.FreePhysicalMemory)\"",
+            ])
+            .output();
+        let Ok(out) = out else { return (None, None) };
+        let text = String::from_utf8_lossy(&out.stdout).into_owned();
+        let mut kb = text.split_whitespace().map(|v| v.parse::<u64>().ok().map(|v| v * 1024));
+        (kb.next().flatten(), kb.next().flatten())
+    }
+    #[cfg(not(any(target_os = "macos", target_os = "linux", windows)))]
+    {
+        (None, None)
+    }
+}
+
+/// Performance and efficiency cores (Apple silicon's `hw.perflevel0/1`); `None` elsewhere.
+fn core_kinds() -> Option<(usize, usize)> {
+    #[cfg(target_os = "macos")]
+    {
+        let p = sysctl("hw.perflevel0.logicalcpu")? as usize;
+        let e = sysctl("hw.perflevel1.logicalcpu").unwrap_or(0) as usize;
+        Some((p, e))
+    }
+    #[cfg(not(target_os = "macos"))]
+    {
+        None
+    }
+}
+
+/// Dedicated VRAM of the adapter; `None` = unknown (the tuning then plans with a conservative
+/// budget, or `vram-budget-mb`). Linux: sysfs (amdgpu reports it; NVIDIA's proprietary driver
+/// and Intel do not). NVIDIA (Windows and Linux): `nvidia-smi`, which ships with the driver.
+/// No platform calls: the workspace has no `unsafe`.
+fn dedicated_vram(vendor: u32, _name: &str) -> Option<u64> {
+    if vendor == 0x10de
+        && let Some(mb) = nvidia_smi_vram_mb()
+    {
+        return Some(mb << 20);
+    }
+    #[cfg(target_os = "linux")]
+    {
+        let dir = std::fs::read_dir("/sys/class/drm").ok()?;
+        dir.filter_map(|e| e.ok())
+            .filter_map(|e| std::fs::read_to_string(e.path().join("device/mem_info_vram_total")).ok())
+            .filter_map(|t| t.trim().parse::<u64>().ok())
+            .max()
+    }
+    #[cfg(not(target_os = "linux"))]
+    {
+        None
+    }
+}
+
+/// Total memory of the largest NVIDIA GPU in MB, from `nvidia-smi`; `None` without it.
+fn nvidia_smi_vram_mb() -> Option<u64> {
+    let out = std::process::Command::new("nvidia-smi").args(["--query-gpu=memory.total", "--format=csv,noheader,nounits"]).output().ok()?;
+    if !out.status.success() {
+        return None;
+    }
+    String::from_utf8_lossy(&out.stdout).lines().filter_map(|l| l.trim().parse::<u64>().ok()).max()
+}
diff --git a/crates/export/src/lib.rs b/crates/export/src/lib.rs
index eda9799588..66d87df548 100644
--- a/crates/export/src/lib.rs
+++ b/crates/export/src/lib.rs
@@ -34,8 +34,11 @@
 
 mod encode;
 mod hevc_av1;
+mod hw;
 mod out;
 mod pipeline;
+mod stream;
+pub mod tuning;
 mod uncompressed;
 mod webm;
 mod webm_av1;
@@ -174,12 +177,20 @@ pub fn export(job: &Job, progress: &mut dyn FnMut(&Progress) -> bool) -> Result<
 pub async fn export_async(job: &Job<'_>, progress: &mut dyn FnMut(&Progress) -> bool) -> Result<Report> {
     let t0 = Instant::now();
     let cx = Cx::new(job);
+    if tuning::request().print_only {
+        // `--print-tuning`: show the resolved options and render nothing.
+        println!("{}", cx.tuning.explain());
+        return Err(ExportError::Cancelled);
+    }
     let mut r = export_with(&cx, progress, t0).await;
     if matches!(r, Err(ExportError::Cancelled)) {
         cx.remove_cancelled_outputs()?;
         return r;
     }
     let log = cx.write_log(&r, t0.elapsed().as_secs_f64());
+    if let tuning::Plan::Scheduled { .. } = cx.plan {
+        log::info!(target: "effectcraft_export", "{}", cx.summary(t0.elapsed().as_secs_f64()));
+    }
     if let Ok(rep) = &mut r {
         rep.log = log;
         rep.overflow = cx.overflowed.lock().unwrap_or_else(|e| e.into_inner()).clone();
@@ -229,9 +240,15 @@ impl State<'_> {
     }
 }
 
-/// Frames per parallel batch.
-pub(crate) fn batch_size() -> u64 {
-    rayon::current_num_threads().clamp(2, 16) as u64
+/// Frames per parallel batch. A scheduled plan takes larger batches, so the GPU and CPU workers
+/// meet at a batch boundary less often.
+pub(crate) fn batch_size(cx: &Cx) -> u64 {
+    let n = rayon::current_num_threads().clamp(2, 16) as u64;
+    match cx.plan {
+        tuning::Plan::Scheduled { gpu, cpu } => n.max(8 * (gpu + cpu.max()) as u64).min(48),
+        // Stock: a frame per thread; fewer when the RAM budget says so (`cpu-batch`).
+        tuning::Plan::Parallel(_) => n.min(cx.tuning.cpu_batch.value.max(1) as u64),
+    }
 }
 
 /// Crop/pad 8-bit RGBA to `w`×`h` (codec rounding).
@@ -259,7 +276,7 @@ async fn sequence(cx: &Cx<'_>, comp: &Comp, w: u32, h: u32, st: &mut State<'_>)
         Channels::Rgba if !fmt.supports_alpha() => Channels::Rgb,
         c => c,
     };
-    let batch = batch_size();
+    let batch = batch_size(cx);
     let mut bytes = 0u64;
     let mut i = 0;
     while i < st.total {
@@ -369,7 +386,7 @@ async fn gif_export(job: &Cx<'_>, comp: &Comp, w: u32, h: u32, st: &mut State<'_
     let cs_per_frame = 100.0 * rate.den as f64 / rate.num as f64;
     let mut clock = 0.0f64;
     let mut emitted = 0u64;
-    let batch = batch_size();
+    let batch = batch_size(job);
     let mut i = 0;
     while i < st.total {
         let end = (i + batch).min(st.total);
diff --git a/crates/export/src/pipeline.rs b/crates/export/src/pipeline.rs
index a0093f4c71..df67a29dba 100644
--- a/crates/export/src/pipeline.rs
+++ b/crates/export/src/pipeline.rs
@@ -2,7 +2,9 @@
 //! guide layers, frame blending, motion blur), field rendering with 3:2 pulldown, colour depth,
 //! the Output Module's crop and resize, alpha handling, storage overflow and the render log.
 
+use std::cell::Cell;
 use std::sync::Mutex;
+use std::sync::atomic::{AtomicU64, AtomicUsize, Ordering};
 
 use effectcraft_project::render_queue::{
     AlphaMode, Channels, ColorDepth, CurrentOrOff, EffectsMode, FrameSample, RenderLog, ResizeQuality, SwitchOverride, log_path,
@@ -13,6 +15,8 @@ use effectcraft_render::{Backend, LayerCache, RenderOpts, Renderer};
 use effectcraft_time::Tick;
 use web_time::Instant;
 
+use crate::stream::{Adapt, Claim, Queue};
+use crate::tuning::{CpuWorkers, Plan};
 use crate::{Job, RenderQuality, out};
 
 /// GPU frames rendered at once by default: one, as the export scheduler's single GPU worker
@@ -39,6 +43,16 @@ pub(crate) fn gpu_inflight(var: Option<&str>) -> usize {
     }
 }
 
+/// Frames in flight per GPU worker of the scheduler: its tuned `per_worker`, capped by
+/// `EFFECTCRAFT_GPU_INFLIGHT` (#879/#1184) when set, which then bounds the GPU frames of all
+/// `workers` together (at least one per worker).
+pub(crate) fn scheduled_inflight(per_worker: usize, workers: usize, var: Option<&str>) -> usize {
+    match var {
+        None => per_worker.max(1),
+        v => per_worker.min((gpu_inflight(v) / workers.max(1)).max(1)).max(1),
+    }
+}
+
 /// `render` then `encode` over the frames `ks`, results in `ks` order.
 ///
 /// Without `cap` every frame renders and encodes in one parallel batch (the CPU path, as
@@ -78,12 +92,28 @@ pub(crate) struct Cx<'a> {
     /// Processed layer buffers shared by the job's frames, as the viewer's layer cache: static
     /// and transform-only layers render once per job (the GPU compositor then uploads them
     /// once). Dropped with the job.
-    cache: LayerCache,
+    cache: Option<LayerCache>,
     /// (output frame, seconds) of every rendered frame (Plus Per Frame Info logs).
     pub frame_times: Option<Mutex<Vec<(u64, f64)>>>,
     /// Files written to an overflow folder.
     pub overflowed: Mutex<Vec<String>>,
     written: Mutex<Vec<String>>,
+    /// How frames are spread over the compositors ([`crate::tuning`]).
+    pub plan: Plan,
+    /// Every export option, resolved for this job's hardware ([`crate::tuning`]).
+    pub tuning: crate::tuning::ExportTuning,
+    /// Frames of a scheduled plan by the compositor that actually rendered them: the GPU, the
+    /// CPU compositor (CPU workers), or the CPU after the GPU declined (GPU workers).
+    pub gpu_frames: AtomicU64,
+    pub cpu_frames: AtomicU64,
+    pub declined_frames: AtomicU64,
+    /// CPU workers the scheduler ended with.
+    pub cpu_workers: AtomicUsize,
+}
+
+thread_local! {
+    /// Set when the GPU declined a frame this thread asked it for (the CPU rendered it).
+    static DECLINED: Cell<bool> = const { Cell::new(false) };
 }
 
 impl<'a> std::ops::Deref for Cx<'a> {
@@ -128,24 +158,72 @@ impl<'a> Cx<'a> {
         let mut project = job.project.clone();
         apply_overrides(&mut project, job);
         let frame_times = (job.options.log == RenderLog::PlusPerFrameInfo).then(|| Mutex::new(Vec::new()));
-        let cache = LayerCache::default();
+        let tuning = resolve_tuning(job, &project);
+        // A job renders on the project's renderer; Software Only keeps every frame on the
+        // CPU unless the `backend` option forces the GPU.
+        let gpu_job = project.settings.gpu_acceleration || tuning.backend.value == Backend::Gpu;
+        let plan = tuning.plan(job.accel.is_some() && gpu_job);
+        effectcraft_render::gpu_flags::set(tuning.gpu_flags());
+        // The tuned budgets apply to the tuned pipeline, or when the user set them.
+        let budgets_given = tuning.upload_budget_mb.source != crate::tuning::Source::Auto || tuning.pool_budget_mb.source != crate::tuning::Source::Auto;
+        if let Some(a) = job.accel.filter(|_| budgets_given || matches!(plan, Plan::Scheduled { .. })) {
+            a.set_memory_budgets(tuning.upload_budget_mb.value << 20, tuning.pool_budget_mb.value << 20);
+        }
+        for w in &tuning.warnings {
+            log::warn!(target: "effectcraft_export", "{w}");
+        }
+        log::info!(target: "effectcraft_export", "export plan: {plan:?}\n{}", tuning.explain());
+        // the job-wide layer cache, bounded by `cache-mb` (0 = none).
+        let cache = export_cache(tuning.cache_mb.value);
         // With deferred readbacks, buffers computed from a missed pass's placeholders are not kept.
-        cache.set_gate(job.accel.and_then(|a| a.miss_gate()));
-        Cx { job, project, cache, frame_times, overflowed: Mutex::new(vec![]), written: Mutex::new(vec![]) }
+        if let Some(c) = &cache {
+            c.set_gate(job.accel.and_then(|a| a.miss_gate()));
+        }
+        Cx {
+            job,
+            project,
+            cache,
+            frame_times,
+            overflowed: Mutex::new(vec![]),
+            written: Mutex::new(vec![]),
+            plan,
+            tuning,
+            gpu_frames: AtomicU64::new(0),
+            cpu_frames: AtomicU64::new(0),
+            declined_frames: AtomicU64::new(0),
+            cpu_workers: AtomicUsize::new(0),
+        }
     }
 
     pub fn comp(&self) -> Option<&Comp> {
         self.project.comp(self.job.comp)
     }
 
+    /// The backend of frames not handed out by the scheduler.
+    fn backend(&self) -> Backend {
+        match self.plan {
+            Plan::Parallel(b) => b,
+            Plan::Scheduled { .. } => Backend::Auto,
+        }
+    }
+
     /// The renderer of the job's frames: the Render Settings' options, the job's accelerator
-    /// and layer cache.
-    fn renderer(&self) -> Renderer<'_> {
+    /// and layer cache; `backend` Auto = the project's renderer.
+    fn renderer(&self, backend: Backend) -> Renderer<'_> {
         let s = self.job.settings;
         // The whole job renders on the project's renderer (Mercury GPU Acceleration or Software
         // Only), not on whichever compositor Auto timed faster for each frame: the CPU and GPU
         // compositors differ slightly, so a per-frame choice made renders differ run to run.
-        let backend = if self.project.settings.gpu_acceleration { Backend::Gpu } else { Backend::Cpu };
+        let backend = match backend {
+            Backend::Auto => {
+                if self.project.settings.gpu_acceleration {
+                    Backend::Gpu
+                } else {
+                    Backend::Cpu
+                }
+            }
+            b => b,
+        };
         let opts = RenderOpts {
             scale: s.resolution.clamp(0.01, 4.0),
             motion_blur: s.motion_blur_override() != SwitchOverride::OffForAll,
@@ -162,13 +240,31 @@ impl<'a> Cx<'a> {
         let mut r = Renderer::new(&self.project, self.job.footage, opts);
         r.expr = self.job.expr;
         r.accel = self.job.accel;
-        r.cache = Some(&self.cache);
+        r.cache = self.cache.as_ref();
         r
     }
 
-    async fn render_at(&self, t: Tick) -> Image {
+    async fn render_at(&self, t: Tick, backend: Backend) -> Image {
+        let r = self.renderer(backend);
+        let backend = r.opts.backend;
+        // Forced GPU on a native accelerator: ask it directly, so a declined frame (out of
+        // memory, lost device, unsupported) is known; the CPU renders it then, as
+        // `Renderer::comp_frame` does.
+        if backend == Backend::Gpu
+            && self.plan != Plan::Parallel(Backend::Auto)
+            && !self.deferred()
+            && let Some(a) = r.accel
+        {
+            if let Some(img) = a.comp_frame(&r, self.job.comp, t) {
+                return img;
+            }
+            DECLINED.set(true);
+            let why = effectcraft_render::gpu_flags::take_decline().unwrap_or_else(|| "no reason given".into());
+            log::warn!(target: "effectcraft_export", "GPU declined the frame at {:.3} s, rendering it on the CPU: {why}", t.seconds());
+            return r.comp_frame_cpu(self.job.comp, t);
+        }
         // With deferred GPU readbacks (a browser worker) the frame renders in passes.
-        effectcraft_render::passes::comp_frame(&self.renderer(), self.job.comp, t).await
+        effectcraft_render::passes::comp_frame(&r, self.job.comp, t).await
     }
 
     /// Whether frames render in passes (an accelerator with deferred readbacks).
@@ -187,6 +283,15 @@ impl<'a> Cx<'a> {
             }
             return out;
         }
+        if let Plan::Scheduled { .. } = self.plan {
+            let mut out = Vec::with_capacity(ks.len());
+            // Collecting cannot fail.
+            let _ = self.stream(comp, &ks, &f, ks.len(), None, |_, v| {
+                out.push(v);
+                Ok(())
+            });
+            return out;
+        }
         map_frames(ks, self.gpu_cap(), |k| self.frame(comp, k), f)
     }
 
@@ -198,6 +303,282 @@ impl<'a> Cx<'a> {
         (self.job.accel.is_some() && self.project.settings.gpu_acceleration).then(|| gpu_inflight(std::env::var(GPU_INFLIGHT_ENV).ok().as_deref()))
     }
 
+    /// Render output frames `ks` with a [`Plan::Scheduled`] plan, map each with `f` on the
+    /// worker and hand the results to `consume` in order, on this thread, as soon as the next
+    /// one is ready (see [`crate::stream`]). At most `cap` frames are in flight or buffered.
+    /// `consume` failing stops the workers and returns its error.
+    pub fn stream<T: Send>(
+        &self,
+        comp: &Comp,
+        ks: &[u64],
+        f: &(impl Fn(u64, Image) -> T + Sync),
+        cap: usize,
+        direct: Option<&Direct<'_, T>>,
+        mut consume: impl FnMut(u64, T) -> crate::Result<()>,
+    ) -> crate::Result<()> {
+        let Plan::Scheduled { gpu, cpu } = self.plan else { return Err(crate::ExportError::Unsupported("stream without a scheduled plan".into())) };
+        let n = ks.len();
+        let t0 = Instant::now();
+        let (start_cpu, mut adapt) = match cpu {
+            CpuWorkers::Fixed(c) => (c, None),
+            CpuWorkers::Adaptive { max } => {
+                let mut a = Adapt::new(if gpu == 0 { 0 } else { max }, 0.0);
+                if gpu > 0 && max > 0 && n > 16 {
+                    let ms = self.cpu_frame_estimate(comp, ks[0]);
+                    log::info!(target: "effectcraft_export", "adaptive: CPU frame estimate {ms:.0} ms (quarter-size probe x 16)");
+                    a = a.with_cpu_estimate(ms, cap);
+                }
+                (if gpu == 0 { 1 } else { 0 }, Some(a))
+            }
+        };
+        let queue = Queue::<T>::new(n, cap, gpu + cpu.max(), start_cpu);
+        self.cpu_workers.store(start_cpu, Ordering::Relaxed);
+        let q = &queue;
+        // CPU workers share a pool (`cpu-pool`, auto: half the threads): on the whole rayon pool
+        // their intra-frame jobs saturate every core and the memory bus, and the GPU worker's own
+        // CPU stages run 2-4x slower.
+        let knobs = Knobs::from_tuning(&self.tuning);
+        let (gpu_pool, cpu_pool) = (knobs.pool(knobs.gpu_pool, "gpu"), knobs.pool(knobs.cpu_pool, "cpu"));
+        let (gpu_pool, cpu_pool, knobs) = (&gpu_pool, &cpu_pool, &knobs);
+        log::info!(target: "effectcraft_export", "scheduler knobs: {knobs:?}");
+        std::thread::scope(|s| {
+            for w in 0..gpu + cpu.max() {
+                let worker = if w < gpu { None } else { Some(w - gpu) };
+                s.spawn(move || {
+                    let _alive = q.alive();
+                    if worker.is_none() {
+                        knobs.tune_gpu_thread(w);
+                    }
+                    let pool = if worker.is_none() { gpu_pool } else { cpu_pool };
+                    // Runs on a pool thread when the worker has a pool (its rayon jobs stay in that pool).
+                    let in_pool = |job: &mut (dyn FnMut() + Send)| match pool {
+                        Some(p) => p.install(job),
+                        None => job(),
+                    };
+                    // Render frame `i` the usual way (an Image, mapped by `f`); false: stop.
+                    let normal = |i: usize| -> bool {
+                        let Some(&k) = ks.get(i) else { return false };
+                        let t = Instant::now();
+                        let backend = if worker.is_none() { Backend::Gpu } else { Backend::Cpu };
+                        let mut out = None;
+                        in_pool(&mut || {
+                            DECLINED.set(false);
+                            let img = effectcraft_render::passes::block_on(self.frame_with(comp, k, backend));
+                            out = Some((img, DECLINED.get()));
+                        });
+                        let Some((img, declined)) = out else { return false };
+                        let rendered = t.elapsed().as_secs_f64() * 1e3;
+                        let (what, counter) = match (worker, declined) {
+                            (None, false) => ("gpu", &self.gpu_frames),
+                            (None, true) => ("cpu (gpu declined)", &self.declined_frames),
+                            (Some(_), _) => ("cpu", &self.cpu_frames),
+                        };
+                        counter.fetch_add(1, Ordering::Relaxed);
+                        let who = match worker {
+                            None => format!("gpu worker {w}"),
+                            Some(c) => format!("cpu worker {c}"),
+                        };
+                        let t1 = Instant::now();
+                        let mut v = None;
+                        let mut img = Some(img);
+                        in_pool(&mut || v = img.take().map(|img| f(k, img)));
+                        let Some(v) = v else { return false };
+                        log::info!(target: "effectcraft_export", "frame {k}: {what} ({who}) {rendered:.0} ms + convert {:.0} ms", t1.elapsed().as_secs_f64() * 1e3);
+                        q.put(i, v);
+                                            true
+                    };
+                    let accel = if worker.is_none() { direct.zip(self.job.accel) } else { None };
+                    let Some((d, a)) = accel else {
+                        while let Some(i) = q.claim(worker, gpu) {
+                            if !normal(i) {
+                                break;
+                            }
+                        }
+                        return;
+                    };
+                    // GPU worker with device-side YUV and async readback: submit a frame, claim
+                    // the next while the device renders and copies it; finished frames come
+                    // back through the map callbacks (delivered on device polls).
+                    type Done = (usize, u64, Instant, f64, Option<Vec<u8>>);
+                    let (tx, rx) = std::sync::mpsc::channel::<Done>();
+                    let mut pending = 0usize;
+                    // Frames submitted but not read back yet: each holds its uploads and
+                    // transient textures on the device until it completes (unbounded, 1 worker
+                    // queued 16 frames and 23.7 GB of VRAM).
+                    let async_rb = self.tuning.async_readback.value;
+                    let mut inflight = crate::stream::Inflight::new(if async_rb { scheduled_inflight(self.tuning.gpu_inflight.value, gpu, std::env::var(GPU_INFLIGHT_ENV).ok().as_deref()) } else { 1 });
+                    let deliver = |(i, k, t, rec, bytes): Done| match bytes {
+                        Some(b) => {
+                            let t1 = Instant::now();
+                            let v = (d.map)(k, b);
+                            self.gpu_frames.fetch_add(1, Ordering::Relaxed);
+                            log::info!(target: "effectcraft_export", "frame {k}: gpu yuv420 (gpu worker {w}) record {rec:.0} ms, ready {:.0} ms after start + {:.1} ms", t1.duration_since(t).as_secs_f64() * 1e3, t1.elapsed().as_secs_f64() * 1e3);
+                            q.put(i, v);
+                        }
+                        None => {
+                            log::warn!(target: "effectcraft_export", "frame {k}: GPU readback failed, rendering it again");
+                            let mut out = None;
+                            in_pool(&mut || out = Some(f(k, effectcraft_render::passes::block_on(self.frame_with(comp, k, Backend::Cpu)))));
+                            self.declined_frames.fetch_add(1, Ordering::Relaxed);
+                            if let Some(v) = out {
+                                q.put(i, v);
+                            }
+                        }
+                    };
+                    loop {
+                        while let Ok(done) = rx.try_recv() {
+                            pending -= 1;
+                            deliver(done);
+                        }
+                        if pending >= inflight.limit {
+                            a.poll_readbacks(true);
+                            continue;
+                        }
+                        let c = if pending == 0 { q.claim(worker, gpu).map_or(Claim::Done, Claim::Got) } else { q.try_claim(worker, gpu) };
+                        let i = match c {
+                            Claim::Done => break,
+                            Claim::Full => {
+                                a.poll_readbacks(true);
+                                continue;
+                            }
+                            Claim::Got(i) => i,
+                        };
+                        let Some(&k) = ks.get(i) else { break };
+                        let t = Instant::now();
+                        let mut retried = false;
+                        let started = loop {
+                            let mut started = false;
+                            // The decline reason is thread-local: take it on the thread that recorded.
+                            let mut why = None;
+                            if let FrameSample::Progressive(at) = self.job.settings.sample(comp, k) {
+                                let tx = tx.clone();
+                                in_pool(&mut || {
+                                    let r = self.renderer(Backend::Gpu);
+                                    let rec = t;
+                                    let tx = tx.clone();
+                                    let cb: Box<dyn FnOnce(Option<Vec<u8>>) + Send> = Box::new(move |b| {
+                                        let _ = tx.send((i, k, rec, 0.0, b));
+                                    });
+                                    started = a.comp_frame_yuv420(&r, self.job.comp, at, d.bg, cb).is_ok();
+                                    if !started {
+                                        why = effectcraft_render::gpu_flags::take_decline();
+                                    }
+                                });
+                            }
+                            if started {
+                                break true;
+                            }
+                            match inflight.declined(why.as_deref(), retried) {
+                                crate::stream::OnDecline::Retry { lowered } => {
+                                    if let Some((was, now)) = lowered {
+                                        log::warn!(target: "effectcraft_export", "frame {k}: the GPU ran out of memory with {was} frame(s) in flight; keeping {now} in flight from now on and retrying the frame on the GPU");
+                                    } else {
+                                        log::info!(target: "effectcraft_export", "frame {k}: the GPU ran out of memory; retrying it on the GPU once the frames in flight finish");
+                                    }
+                                    // Let the frames in flight finish and free their memory.
+                                    let t_wait = Instant::now();
+                                    while pending > 0 && t_wait.elapsed().as_secs() < 120 {
+                                        a.poll_readbacks(true);
+                                        while let Ok(done) = rx.try_recv() {
+                                            pending -= 1;
+                                            deliver(done);
+                                        }
+                                    }
+                                    retried = true;
+                                }
+                                crate::stream::OnDecline::Cpu => {
+                                    if let Some(why) = why {
+                                        log::warn!(target: "effectcraft_export", "frame {k}: GPU 4:2:0 path declined ({why}); rendering it the usual way");
+                                    }
+                                    break false;
+                                }
+                            }
+                        };
+                        if started {
+                            pending += 1;
+                            log::debug!(target: "effectcraft_export", "frame {k}: recorded in {:.0} ms", t.elapsed().as_secs_f64() * 1e3);
+                            a.poll_readbacks(false);
+                            // Synchronous readback (`async-readback off`): wait for this frame.
+                            while !async_rb && pending > 0 {
+                                a.poll_readbacks(true);
+                                while let Ok(done) = rx.try_recv() {
+                                    pending -= 1;
+                                    deliver(done);
+                                }
+                            }
+                        } else if retried {
+                            // Still out of memory with nothing else in flight: the CPU renders
+                            // it (another GPU attempt outside the error scopes would retire the
+                            // device).
+                            log::warn!(target: "effectcraft_export", "frame {k}: the GPU is still out of memory after the retry; rendering it on the CPU");
+                            let mut out = None;
+                            in_pool(&mut || out = Some(f(k, effectcraft_render::passes::block_on(self.frame_with(comp, k, Backend::Cpu)))));
+                            self.declined_frames.fetch_add(1, Ordering::Relaxed);
+                            let Some(v) = out else { break };
+                            q.put(i, v);
+                        } else if !normal(i) {
+                            break;
+                        }
+                    }
+                    let t_end = Instant::now();
+                    while pending > 0 && t_end.elapsed().as_secs() < 120 {
+                        a.poll_readbacks(true);
+                        while let Ok(done) = rx.try_recv() {
+                            pending -= 1;
+                            deliver(done);
+                        }
+                    }
+                });
+            }
+            let mut result = Ok(());
+            let mut got = 0;
+            while let Some((i, v)) = q.next() {
+                got += 1;
+                if let Some(a) = adapt.as_mut() {
+                    let was = a.active;
+                    if let Some((c, fps)) = a.frame(t0.elapsed().as_secs_f64()) {
+                        log::info!(
+                            target: "effectcraft_export",
+                            "adaptive: {fps:.3} frames/s measured with {was} CPU worker(s) -> {c} CPU worker(s){}",
+                            if a.settled { " (settled on the fastest measured)" } else { "" }
+                        );
+                        q.set_cpu_active(c);
+                        self.cpu_workers.store(c, Ordering::Relaxed);
+                    }
+                }
+                if let Some(note) = adapt.as_mut().and_then(Adapt::take_note) {
+                    log::info!(target: "effectcraft_export", "adaptive: {note}");
+                }
+                if let Err(e) = consume(ks.get(i).copied().unwrap_or_default(), v) {
+                    result = Err(e);
+                    break;
+                }
+                if i + 1 == n {
+                    break;
+                }
+            }
+            q.stop();
+            if result.is_ok() && got < n {
+                result = Err(crate::ExportError::Unsupported("a render worker stopped".into()));
+            }
+            result
+        })
+    }
+
+    /// The end-of-render summary of a scheduled plan.
+    pub fn summary(&self, seconds: f64) -> String {
+        let g = self.gpu_frames.load(Ordering::Relaxed);
+        let c = self.cpu_frames.load(Ordering::Relaxed);
+        let d = self.declined_frames.load(Ordering::Relaxed);
+        let n = g + c + d;
+        format!(
+            "render summary: {n} frames in {seconds:.1} s ({:.3} fps): {g} on the GPU, {c} on the CPU compositor, {d} on the CPU after the GPU declined; {} CPU worker(s) at the end ({:?})",
+            n as f64 / seconds.max(1e-9),
+            self.cpu_workers.load(Ordering::Relaxed),
+            self.plan
+        )
+    }
+
     /// Output frame `i`: sampled (fields, pulldown), at the colour depth, cropped and resized.
     pub fn frame(&self, comp: &Comp, i: u64) -> Image {
         effectcraft_render::passes::block_on(self.frame_async(comp, i))
@@ -205,12 +586,33 @@ impl<'a> Cx<'a> {
 
     /// [`Cx::frame`] as a future (deferred readbacks: the frame renders in passes).
     pub async fn frame_async(&self, comp: &Comp, i: u64) -> Image {
+        self.frame_with(comp, i, self.backend()).await
+    }
+
+    /// [`Cx::frame_async`] on `backend`.
+    /// Estimated ms for one CPU-compositor frame: frame `k` rendered at a quarter of the size
+    /// (1/16 of the pixels), times 16.
+    fn cpu_frame_estimate(&self, comp: &Comp, k: u64) -> f64 {
+        let t = match self.job.settings.sample(comp, k) {
+            FrameSample::Progressive(t) => t,
+            FrameSample::Fields { first, .. } => first,
+        };
+        let mut r = self.renderer(Backend::Cpu);
+        r.cache = None;
+        r.accel = None;
+        r.opts.scale *= 0.25;
+        let t0 = Instant::now();
+        let _ = r.comp_frame_cpu(self.job.comp, t);
+        t0.elapsed().as_secs_f64() * 1e3 * 16.0
+    }
+
+    async fn frame_with(&self, comp: &Comp, i: u64, backend: Backend) -> Image {
         let t0 = Instant::now();
         let img = match self.job.settings.sample(comp, i) {
-            FrameSample::Progressive(t) => self.render_at(t).await,
+            FrameSample::Progressive(t) => self.render_at(t, backend).await,
             FrameSample::Fields { first, second, upper_first } => {
-                let a = self.render_at(first).await;
-                if second == first { a } else { interleave(&a, &self.render_at(second).await, upper_first) }
+                let a = self.render_at(first, backend).await;
+                if second == first { a } else { interleave(&a, &self.render_at(second, backend).await, upper_first) }
             }
         };
         let mut img = img;
@@ -592,6 +994,17 @@ mod tests {
         assert_eq!(Cx::new(&job).gpu_cap(), None, "no accelerator");
     }
 
+    #[test]
+    fn the_inflight_cap_bounds_the_scheduler_too() {
+        assert_eq!(scheduled_inflight(3, 1, None), 3);
+        assert_eq!(scheduled_inflight(3, 1, Some("1")), 1);
+        assert_eq!(scheduled_inflight(3, 1, Some("2")), 2);
+        assert_eq!(scheduled_inflight(2, 1, Some("8")), 2, "never above the tuned value");
+        assert_eq!(scheduled_inflight(3, 2, Some("4")), 2);
+        assert_eq!(scheduled_inflight(3, 4, Some("2")), 1, "at least one per worker");
+        assert_eq!(scheduled_inflight(3, 1, Some("junk")), 1, "bad values mean the default (1)");
+    }
+
     #[test]
     fn gpu_inflight_override_is_a_positive_number_or_the_default() {
         assert_eq!(gpu_inflight(None), GPU_INFLIGHT_DEFAULT);
@@ -637,17 +1050,17 @@ mod tests {
         let cx = Cx::new(&job);
         let comp = cx.comp().unwrap();
         cx.frame(comp, 0);
-        let renders = cx.cache.stats().misses;
+        let renders = cx.cache.as_ref().unwrap().stats().misses;
         assert!(renders > 0);
         for i in 1..10 {
             let img = cx.frame(comp, i);
             // The frames are the ones rendered without a cache.
             let t = settings.frame_time(comp, i);
-            let mut uncached = cx.renderer();
+            let mut uncached = cx.renderer(Backend::Auto);
             uncached.cache = None;
             assert_eq!(img.data, uncached.comp_frame(cid, t).data, "frame {i}");
         }
-        let stats = cx.cache.stats();
+        let stats = cx.cache.as_ref().unwrap().stats();
         assert_eq!(stats.misses, renders, "the solid rendered on the first frame only");
         assert!(stats.hits >= 9, "{stats:?}");
     }
@@ -680,3 +1093,98 @@ mod tests {
         assert_eq!(p.data[5][0], 1.0);
     }
 }
+
+/// The scheduler's thread options (`gpu-pool`, `cpu-pool`, `gpu-priority`, `gpu-ideal-cpu`).
+#[derive(Debug, Default)]
+pub(crate) struct Knobs {
+    pub gpu_pool: Option<usize>,
+    pub cpu_pool: Option<usize>,
+    #[cfg_attr(target_arch = "wasm32", allow(dead_code))]
+    pub gpu_priority: bool,
+    #[cfg_attr(not(windows), allow(dead_code))]
+    pub gpu_ideal_cpu: Option<u32>,
+}
+
+impl Knobs {
+    pub fn from_tuning(t: &crate::tuning::ExportTuning) -> Knobs {
+        let nz = |n: usize| (n > 0).then_some(n);
+        Knobs {
+            gpu_pool: nz(t.gpu_pool.value),
+            cpu_pool: if t.cpu_frames.value.max() > 0 { nz(t.cpu_pool.value) } else { None },
+            gpu_priority: t.gpu_priority.value,
+            gpu_ideal_cpu: t.gpu_ideal_cpu.value,
+        }
+    }
+
+    fn pool(&self, n: Option<usize>, name: &'static str) -> Option<rayon::ThreadPool> {
+        let n = n?;
+        rayon::ThreadPoolBuilder::new()
+            .num_threads(n)
+            .thread_name(move |i| format!("export-{name}-{i}"))
+            .build()
+            .map_err(|e| log::warn!(target: "effectcraft_export", "{name} pool: {e}"))
+            .ok()
+    }
+
+    fn tune_gpu_thread(&self, _w: usize) {
+        #[cfg(not(target_arch = "wasm32"))]
+        if self.gpu_priority
+            && let Err(e) = thread_priority::set_current_thread_priority(thread_priority::ThreadPriority::Max)
+        {
+            log::warn!(target: "effectcraft_export", "gpu worker priority: {e:?}");
+        }
+        #[cfg(windows)]
+        if let Some(n) = self.gpu_ideal_cpu
+            && let Err(e) = thread_priority::windows::set_current_thread_ideal_processor(n)
+        {
+            log::warn!(target: "effectcraft_export", "gpu worker ideal processor: {e:?}");
+        }
+    }
+}
+
+/// The export's layer cache ([`Cx::cache`]), `mb` megabytes (0 = none).
+fn export_cache(mb: usize) -> Option<effectcraft_render::LayerCache> {
+    (mb > 0).then(|| effectcraft_render::LayerCache::new(mb << 20))
+}
+
+/// Resolve the export options for `job` (CLI > environment > config > auto, see [`crate::tuning`]).
+fn resolve_tuning(job: &Job, project: &Project) -> crate::tuning::ExportTuning {
+    use crate::tuning::{Overrides, Source, request, resolve};
+    let hw = crate::hw::detect(job.accel);
+    let frame = project.comp(job.comp).map(|c| crate::output_size(c, job.settings, job.output)).unwrap_or((1920, 1080));
+    let req = request();
+    let env = Overrides::from_env();
+    let cfg = req.config.clone().unwrap_or_default();
+    resolve(&hw, frame, [(&req.cli, Source::Cli), (&env, Source::Env), (&cfg, Source::Config)])
+}
+
+/// Device-side H.264 input for a GPU worker ([`Cx::stream`]): the accelerator renders the frame,
+/// composites it over `bg` and converts it to 8-bit 4:2:0, read back asynchronously; `map`
+/// turns the planes into the stream's item.
+pub struct Direct<'d, T> {
+    pub bg: [f32; 3],
+    #[allow(clippy::type_complexity)]
+    pub map: &'d (dyn Fn(u64, Vec<u8>) -> T + Sync),
+}
+
+impl Cx<'_> {
+    /// Whether frames of `comp` can take the [`Direct`] path at output size `w`×`h`: a GPU
+    /// worker, a native accelerator, no depth quantising, crop or resize (the rendered frame
+    /// is the encoded one), even sizes the kernel covers. `rendered`: frame 0's size.
+    pub fn yuv_direct_ok(&self, w: u32, h: u32, rendered: Option<(u32, u32)>) -> bool {
+        let Plan::Scheduled { gpu, .. } = self.plan else { return false };
+        let s = self.job.settings;
+        let om = self.job.output;
+        let quantised = s.color_depth != ColorDepth::Current && s.color_depth.resolve(self.project.settings.bit_depth).levels().is_some();
+        gpu > 0
+            && self.job.accel.is_some()
+            && !self.deferred()
+            && !quantised
+            && !om.resize.enabled
+            && om.crop.edges(w, h, s.resolution.clamp(0.01, 4.0)) == (0, 0, 0, 0)
+            && rendered == Some((w, h))
+            && w.is_multiple_of(8)
+            && h.is_multiple_of(2)
+            && self.tuning.gpu_yuv.value
+    }
+}
diff --git a/crates/export/src/stream.rs b/crates/export/src/stream.rs
new file mode 100644
index 0000000000..3da32a3825
--- /dev/null
+++ b/crates/export/src/stream.rs
@@ -0,0 +1,462 @@
+//! The streaming frame scheduler of a [`Plan::Scheduled`](crate::tuning::Plan) export.
+//!
+//! Workers (GPU and CPU compositor) take output frames one at a time from a shared [`Queue`]
+//! and hand the results back; the encoder takes them in frame order as soon as the next one is
+//! ready. At most `cap` frames are claimed ahead of the encoder (in flight or waiting in the
+//! reorder buffer), so memory stays bounded and workers block while the window is full.
+//!
+//! The number of CPU workers is either fixed or chosen by [`Adapt`]: start GPU-only, measure
+//! frames/s over a window, add one CPU worker at a time while throughput improves, and drop
+//! back to the best count (then stop adapting) once it doesn't.
+
+use std::collections::BTreeMap;
+use std::sync::{Condvar, Mutex, MutexGuard};
+use std::time::Duration;
+
+struct Q<T> {
+    next_claim: usize,
+    next_out: usize,
+    ready: BTreeMap<usize, T>,
+    /// CPU workers allowed to take frames (ids `0..cpu_active`).
+    cpu_active: usize,
+    /// Workers still running (a worker that panics counts down too).
+    alive: usize,
+    stop: bool,
+}
+
+/// [`Queue::try_claim`]'s answer.
+#[derive(Debug, PartialEq, Eq)]
+pub(crate) enum Claim {
+    Got(usize),
+    /// The window is full (a frame before it is not done).
+    Full,
+    /// Nothing left for this worker.
+    Done,
+}
+
+/// Work queue + bounded reorder buffer for `n` frames.
+pub(crate) struct Queue<T> {
+    q: Mutex<Q<T>>,
+    cv: Condvar,
+    n: usize,
+    cap: usize,
+}
+
+/// Counts a worker out of [`Queue`] when dropped (also on panic).
+pub(crate) struct Alive<'q, T>(&'q Queue<T>);
+
+impl<T> Drop for Alive<'_, T> {
+    fn drop(&mut self) {
+        let mut q = self.0.lock();
+        q.alive = q.alive.saturating_sub(1);
+        self.0.cv.notify_all();
+    }
+}
+
+impl<T> Queue<T> {
+    pub fn new(n: usize, cap: usize, workers: usize, cpu_active: usize) -> Queue<T> {
+        let q = Q { next_claim: 0, next_out: 0, ready: BTreeMap::new(), cpu_active, alive: workers, stop: false };
+        Queue { q: Mutex::new(q), cv: Condvar::new(), n, cap: cap.max(1) }
+    }
+
+    fn lock(&self) -> MutexGuard<'_, Q<T>> {
+        self.q.lock().unwrap_or_else(|e| e.into_inner())
+    }
+
+    /// The guard a worker holds while it runs.
+    pub fn alive(&self) -> Alive<'_, T> {
+        Alive(self)
+    }
+
+    /// The next frame for a worker: a GPU worker (`cpu: None`) or CPU worker `cpu: Some(id)`.
+    /// Blocks while the window is full or (CPU) the worker is not active. A CPU worker leaves
+    /// the last `cpu_active` frames to the GPU when `gpu_workers` > 0. `None`: nothing left.
+    pub fn claim(&self, cpu: Option<usize>, gpu_workers: usize) -> Option<usize> {
+        match self.claim_with(cpu, gpu_workers, true) {
+            Claim::Got(i) => Some(i),
+            _ => None,
+        }
+    }
+
+    /// [`Queue::claim`] that returns [`Claim::Full`] instead of blocking.
+    pub fn try_claim(&self, cpu: Option<usize>, gpu_workers: usize) -> Claim {
+        self.claim_with(cpu, gpu_workers, false)
+    }
+
+    fn claim_with(&self, cpu: Option<usize>, gpu_workers: usize, block: bool) -> Claim {
+        let mut q = self.lock();
+        loop {
+            if q.stop || q.next_claim >= self.n {
+                return Claim::Done;
+            }
+            let mut may = q.next_claim < q.next_out + self.cap;
+            if let Some(id) = cpu {
+                if gpu_workers > 0 && self.n - q.next_claim <= q.cpu_active {
+                    return Claim::Done;
+                }
+                may &= id < q.cpu_active;
+            }
+            if may {
+                q.next_claim += 1;
+                return Claim::Got(q.next_claim - 1);
+            }
+            if !block {
+                return Claim::Full;
+            }
+            q = self.cv.wait_timeout(q, Duration::from_millis(200)).map(|(g, _)| g).unwrap_or_else(|e| e.into_inner().0);
+        }
+    }
+
+    /// Frame `i` is done.
+    pub fn put(&self, i: usize, v: T) {
+        self.lock().ready.insert(i, v);
+        self.cv.notify_all();
+    }
+
+    /// The next frame in order, waiting for it; `None` when all were taken, on [`Queue::stop`],
+    /// or when every worker has exited without producing it.
+    pub fn next(&self) -> Option<(usize, T)> {
+        let mut q = self.lock();
+        loop {
+            let i = q.next_out;
+            if let Some(v) = q.ready.remove(&i) {
+                q.next_out += 1;
+                self.cv.notify_all();
+                return Some((i, v));
+            }
+            if i >= self.n || q.stop || q.alive == 0 {
+                return None;
+            }
+            q = self.cv.wait(q).unwrap_or_else(|e| e.into_inner());
+        }
+    }
+
+    pub fn set_cpu_active(&self, n: usize) {
+        self.lock().cpu_active = n;
+        self.cv.notify_all();
+    }
+
+    /// Stop handing out frames (the encoder failed or was cancelled).
+    pub fn stop(&self) {
+        self.lock().stop = true;
+        self.cv.notify_all();
+    }
+
+    /// Frames waiting in the reorder buffer.
+    #[cfg(test)]
+    fn buffered(&self) -> usize {
+        self.lock().ready.len()
+    }
+}
+
+/// Adaptive CPU worker count from measured throughput.
+#[derive(Debug)]
+pub(crate) struct Adapt {
+    cpu_ms: Option<f64>,
+    cap: usize,
+    note: Option<String>,
+    max: usize,
+    pub active: usize,
+    best: (f64, usize),
+    start: f64,
+    frames: usize,
+    warm: bool,
+    pub settled: bool,
+}
+
+impl Adapt {
+    /// Improvement needed to count as faster.
+    const GAIN: f64 = 1.03;
+
+    pub fn new(max: usize, now: f64) -> Adapt {
+        Adapt { max, active: 0, best: (0.0, 0), start: now, frames: 0, warm: false, settled: max == 0, cpu_ms: None, cap: 0, note: None }
+    }
+
+    /// An estimate of one CPU frame (ms) and the reorder buffer's capacity: a CPU worker is
+    /// not even tried when it cannot pay off. Its frames must be ready before the GPU fills the
+    /// reorder buffer (else the in-order encoder and then the GPU wait for it), and it must add
+    /// more than [`Adapt::GAIN`].
+    pub fn with_cpu_estimate(mut self, cpu_ms: f64, cap: usize) -> Adapt {
+        self.cpu_ms = Some(cpu_ms);
+        self.cap = cap;
+        self
+    }
+
+    /// Why the adaptation stopped without trying a worker (taken once).
+    pub fn take_note(&mut self) -> Option<String> {
+        self.note.take()
+    }
+
+    /// Frames measured at `active` CPU workers (more workers: longer, their frames are slower).
+    fn window(&self) -> usize {
+        8 + 4 * self.active
+    }
+
+    /// A frame reached the encoder at `now` (seconds). Returns the new CPU worker count when it
+    /// changes, with the measured frames/s.
+    pub fn frame(&mut self, now: f64) -> Option<(usize, f64)> {
+        if self.settled {
+            return None;
+        }
+        self.frames += 1;
+        // The first window warms up (shader compiles, caches) and is not measured; so are the
+        // first frames after a change (the new worker's first frame is still in flight).
+        let need = if self.warm { self.window() } else { 4 };
+        if self.frames < need {
+            return None;
+        }
+        let fps = self.frames as f64 / (now - self.start).max(1e-9);
+        self.start = now;
+        self.frames = 0;
+        if !self.warm {
+            self.warm = true;
+            return None;
+        }
+        if fps > self.best.0 * Self::GAIN {
+            self.best = (fps, self.active);
+            if self.active == 0
+                && let Some(c) = self.cpu_ms
+            {
+                let gpu_ms = 1000.0 / fps.max(1e-9);
+                let gain = gpu_ms / c;
+                let stall = c > 0.5 * self.cap as f64 * gpu_ms;
+                if gain < Self::GAIN - 1.0 || stall {
+                    self.settled = true;
+                    self.note = Some(format!(
+                        "no CPU workers: a CPU frame takes ~{c:.0} ms vs {gpu_ms:.0} ms per GPU frame ({}), so a CPU worker would {}",
+                        if stall { format!("over half the {}-frame reorder buffer", self.cap) } else { format!("+{:.1}% at best", gain * 100.0) },
+                        if stall { "stall the in-order encoder" } else { "not help" }
+                    ));
+                    return None;
+                }
+            }
+            if self.active < self.max {
+                self.active += 1;
+                return Some((self.active, fps));
+            }
+            self.settled = true;
+            return None;
+        }
+        self.settled = true;
+        self.active = self.best.1;
+        Some((self.active, fps))
+    }
+}
+
+/// Frames a GPU worker keeps in flight, lowered when the GPU runs out of memory.
+///
+/// The GPU crate prefixes a decline caused by a failed allocation with
+/// [`OUT_OF_MEMORY`]; the device stays usable, so the worker lets its in-flight frames finish,
+/// keeps one frame fewer in flight from then on (never below 1) and retries the frame on the
+/// GPU once before the CPU renders it.
+#[derive(Debug)]
+pub(crate) struct Inflight {
+    pub(crate) limit: usize,
+    lowered: bool,
+}
+
+/// How a GPU decline caused by a failed allocation starts (see `effectcraft_gpu::OUT_OF_MEMORY`).
+pub(crate) const OUT_OF_MEMORY: &str = "out of memory";
+
+/// What to do with a frame the GPU declined.
+#[derive(Debug, PartialEq, Eq)]
+pub(crate) enum OnDecline {
+    /// Out of memory: wait for the frames in flight, then retry on the GPU. `lowered` is the
+    /// new limit the first time it drops (log it once), `None` afterwards.
+    Retry { lowered: Option<(usize, usize)> },
+    /// Render it on the CPU.
+    Cpu,
+}
+
+impl Inflight {
+    pub(crate) fn new(limit: usize) -> Self {
+        Self { limit: limit.max(1), lowered: false }
+    }
+
+    /// A frame was declined because `why`; `retried`: this frame was already retried.
+    pub(crate) fn declined(&mut self, why: Option<&str>, retried: bool) -> OnDecline {
+        if retried || !why.is_some_and(|w| w.starts_with(OUT_OF_MEMORY)) {
+            return OnDecline::Cpu;
+        }
+        let was = self.limit;
+        self.limit = (was - 1).max(1);
+        let first = self.limit < was && !self.lowered;
+        self.lowered |= self.limit < was;
+        OnDecline::Retry { lowered: first.then_some((was, self.limit)) }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::atomic::{AtomicUsize, Ordering};
+
+    /// Workers finishing out of order still stream in order, and never more than `cap`
+    /// frames are claimed ahead of the consumer.
+    #[test]
+    fn ordered_and_bounded() {
+        let (n, cap) = (200, 6);
+        let q = Queue::<usize>::new(n, cap, 4, 3);
+        let max_ahead = AtomicUsize::new(0);
+        let out = std::thread::scope(|s| {
+            for w in 0..4usize {
+                let (q, max_ahead) = (&q, &max_ahead);
+                s.spawn(move || {
+                    let _a = q.alive();
+                    let cpu = w.checked_sub(1);
+                    while let Some(i) = q.claim(cpu, 1) {
+                        std::thread::sleep(Duration::from_micros(((i * 7919 + w * 31) % 13) as u64 * 50));
+                        max_ahead.fetch_max(q.buffered() + 1, Ordering::Relaxed);
+                        q.put(i, i * 10);
+                    }
+                });
+            }
+            let mut out = vec![];
+            while let Some((i, v)) = q.next() {
+                std::thread::sleep(Duration::from_micros(30));
+                out.push((i, v));
+            }
+            out
+        });
+        assert_eq!(out.len(), n);
+        assert!(out.iter().enumerate().all(|(k, &(i, v))| i == k && v == k * 10));
+        assert!(max_ahead.load(Ordering::Relaxed) <= cap, "buffer exceeded cap");
+    }
+
+    /// A slow consumer blocks the workers (backpressure).
+    #[test]
+    fn backpressure() {
+        let q = Queue::<usize>::new(100, 4, 1, 0);
+        std::thread::scope(|s| {
+            s.spawn(|| {
+                let _a = q.alive();
+                while let Some(i) = q.claim(None, 1) {
+                    q.put(i, i);
+                }
+            });
+            std::thread::sleep(Duration::from_millis(100));
+            assert_eq!(q.buffered(), 4);
+            for k in 0..100 {
+                assert_eq!(q.next().map(|p| p.0), Some(k));
+            }
+            assert!(q.next().is_none());
+        });
+    }
+
+    /// Inactive CPU workers wait; stop() and a dead worker pool release everyone.
+    #[test]
+    fn cpu_gate_stop_and_dead_workers() {
+        let q = Queue::<usize>::new(50, 8, 1, 0);
+        std::thread::scope(|s| {
+            let h = s.spawn(|| {
+                let _a = q.alive();
+                q.claim(Some(0), 0)
+            });
+            std::thread::sleep(Duration::from_millis(50));
+            assert!(!h.is_finished(), "inactive CPU worker took a frame");
+            q.set_cpu_active(1);
+            assert_eq!(h.join().ok().flatten(), Some(0));
+        });
+        // The only worker exited without frame 1: next() gives up instead of hanging.
+        q.put(0, 0);
+        assert_eq!(q.next().map(|p| p.0), Some(0));
+        assert!(q.next().is_none());
+        let q2 = Queue::<usize>::new(10, 2, 1, 0);
+        q2.stop();
+        assert!(q2.claim(None, 1).is_none());
+    }
+
+    /// CPU workers leave the tail to the GPU.
+    #[test]
+    fn tail_left_to_gpu() {
+        let q = Queue::<usize>::new(5, 8, 2, 2);
+        assert_eq!(q.claim(Some(0), 1), Some(0));
+        assert_eq!(q.claim(Some(1), 1), Some(1));
+        assert_eq!(q.claim(Some(0), 1), Some(2));
+        assert_eq!(q.claim(Some(0), 1), None);
+        assert_eq!(q.claim(None, 1), Some(3));
+        assert_eq!(q.claim(Some(0), 0), Some(4));
+    }
+
+    /// Simulated throughput: adds workers while it helps, drops back when it hurts.
+    fn run(max: usize, fps_at: impl Fn(usize) -> f64) -> Adapt {
+        let mut a = Adapt::new(max, 0.0);
+        let mut t = 0.0;
+        for _ in 0..400 {
+            t += 1.0 / fps_at(a.active);
+            a.frame(t);
+        }
+        a
+    }
+
+    #[test]
+    fn adapt_choices() {
+        let a = run(4, |n| [0.76, 0.9, 0.98, 0.97, 0.8][n]);
+        assert_eq!((a.active, a.settled), (2, true));
+        let a = run(4, |n| [0.76, 0.6, 0.5, 0.4, 0.3][n]);
+        assert_eq!((a.active, a.settled), (0, true));
+        let a = run(3, |n| 0.5 + n as f64 * 0.2);
+        assert_eq!((a.active, a.settled), (3, true));
+        let a = run(0, |_| 1.0);
+        assert_eq!(a.active, 0);
+    }
+}
+
+#[cfg(test)]
+mod estimate_tests {
+    use super::Adapt;
+
+    fn feed(mut a: Adapt, fps: f64) -> Adapt {
+        let mut t = 0.0;
+        for _ in 0..40 {
+            t += 1.0 / fps;
+            a.frame(t);
+            if a.settled {
+                break;
+            }
+        }
+        a
+    }
+
+    #[test]
+    fn slow_cpu_frames_are_not_tried() {
+        // An RTX 3090 at 4K: GPU ~9.5 fps, CPU frame ~2.4 s, 16-frame buffer: skip.
+        let mut a = feed(Adapt::new(8, 0.0).with_cpu_estimate(2400.0, 16), 9.5);
+        assert!(a.settled && a.active == 0);
+        assert!(a.take_note().unwrap().contains("stall"));
+        // A slow GPU next to a fast CPU: a worker is tried (no skip note).
+        let mut a = feed(Adapt::new(8, 0.0).with_cpu_estimate(300.0, 16), 1.0);
+        assert!(a.take_note().is_none());
+    }
+}
+
+#[cfg(test)]
+mod inflight_tests {
+    use super::{Inflight, OnDecline};
+
+    #[test]
+    fn out_of_memory_lowers_inflight_once_and_retries_on_the_gpu() {
+        let mut f = Inflight::new(3);
+        let oom = Some("out of memory: Not enough memory left");
+        assert_eq!(f.declined(oom, false), OnDecline::Retry { lowered: Some((3, 2)) });
+        assert_eq!(f.limit, 2);
+        // Lowered again, but logged only the first time.
+        assert_eq!(f.declined(oom, false), OnDecline::Retry { lowered: None });
+        assert_eq!(f.limit, 1);
+        // Never below 1; still retried once.
+        assert_eq!(f.declined(oom, false), OnDecline::Retry { lowered: None });
+        assert_eq!(f.limit, 1);
+        // A retried frame that fails again goes to the CPU.
+        assert_eq!(f.declined(oom, true), OnDecline::Cpu);
+    }
+
+    #[test]
+    fn other_declines_go_to_the_cpu() {
+        let mut f = Inflight::new(2);
+        assert_eq!(f.declined(Some("device unhealthy: GPU device lost"), false), OnDecline::Cpu);
+        assert_eq!(f.declined(Some("device failure / out of memory: uncaptured GPU error"), false), OnDecline::Cpu);
+        assert_eq!(f.declined(None, false), OnDecline::Cpu);
+        assert_eq!(f.limit, 2);
+        assert_eq!(Inflight::new(0).limit, 1);
+    }
+}
diff --git a/crates/export/src/tuning.rs b/crates/export/src/tuning.rs
new file mode 100644
index 0000000000..265e23d48e
--- /dev/null
+++ b/crates/export/src/tuning.rs
@@ -0,0 +1,940 @@
+//! Export tuning: every pipeline improvement as an independent option, resolved once per
+//! export from the command line, the environment, a config file and the hardware.
+//!
+//! Precedence per option: **CLI > environment > config file > auto**. Every option has the
+//! same three spellings (see `TUNING.md`):
+//!
+//! | CLI                | environment                          | config key        |
+//! |--------------------|--------------------------------------|-------------------|
+//! | `--gpu-inflight 3` | `EFFECTCRAFT_EXPORT_GPU_INFLIGHT=3`  | `gpu-inflight = 3`|
+//!
+//! The config file is `--tuning-config FILE` or `EFFECTCRAFT_EXPORT_CONFIG=FILE` (`key = value`
+//! lines, `#` comments). `auto` (or no value anywhere) lets [`resolve`] decide from the
+//! [`Hardware`]: GPU presence, adapter limits, VRAM (or a conservative guess), core count;
+//! [`ExportTuning::explain`] says what it chose and why (`--print-tuning`).
+//!
+//! Without a GPU attached (or with `backend = cpu`) the export is the stock CPU path.
+
+use std::fmt::Write as _;
+use std::sync::Mutex;
+
+use effectcraft_render::Backend;
+
+/// Values given for the options (one layer: CLI, environment or config). `None` = not given
+/// (or `auto`).
+#[derive(Clone, Debug, Default, PartialEq)]
+pub struct Overrides {
+    pub backend: Option<Backend>,
+    pub gpu_frames: Option<usize>,
+    pub gpu_inflight: Option<usize>,
+    pub cpu_frames: Option<usize>,
+    pub cpu_pool: Option<usize>,
+    pub gpu_pool: Option<usize>,
+    pub gpu_priority: Option<bool>,
+    pub gpu_ideal_cpu: Option<u32>,
+    pub cache_mb: Option<usize>,
+    pub precomp_resident: Option<bool>,
+    pub gpu_yuv: Option<bool>,
+    pub async_readback: Option<bool>,
+    pub vram_budget_mb: Option<usize>,
+    pub ram_budget_mb: Option<usize>,
+    pub cpu_batch: Option<usize>,
+    pub upload_budget_mb: Option<usize>,
+    pub pool_budget_mb: Option<usize>,
+}
+
+/// Every option: (key, help). The CLI flag is `--key`, the environment variable
+/// `EFFECTCRAFT_EXPORT_KEY` (upper case, `-` → `_`), the config key `key`.
+pub const OPTIONS: &[(&str, &str)] = &[
+    ("backend", "auto|gpu|cpu: compositor for exported frames"),
+    ("gpu-frames", "N: GPU worker threads recording frames (0 = the stock parallel batches)"),
+    ("gpu-inflight", "N: frames per GPU worker submitted and not read back yet"),
+    ("cpu-frames", "N|auto: CPU compositor workers next to the GPU (auto: adaptive by throughput)"),
+    ("cpu-pool", "N: threads shared by the CPU workers' intra-frame work (0 = the whole pool)"),
+    ("gpu-pool", "N: a rayon pool of its own for the GPU workers (0 = the global pool)"),
+    ("gpu-priority", "on|off: raise the GPU worker threads' priority"),
+    ("gpu-ideal-cpu", "N: preferred logical CPU of the GPU worker (Windows)"),
+    ("cache-mb", "MB: export layer cache (static layers render and upload once; 0 = off)"),
+    ("precomp-resident", "on|off: render precomp layers' nested comps resident on the GPU (not on the CPU + upload)"),
+    ("gpu-yuv", "on|off: convert H.264 frames to 4:2:0 on the GPU (12 MB readback at 4K)"),
+    ("async-readback", "on|off: read GPU frames back asynchronously (record the next meanwhile)"),
+    ("vram-budget-mb", "MB: VRAM to plan with (default: detected; unified memory: from RAM; else a conservative 2048)"),
+    ("cpu-batch", "N: CPU-compositor frames rendered at once (default: one per thread, capped by the RAM budget)"),
+    ("ram-budget-mb", "MB: system RAM the export may use (default: detected); unified-memory GPUs plan their budget from it"),
+    ("upload-budget-mb", "MB: uploaded layer textures kept on the GPU"),
+    ("pool-budget-mb", "MB: free working textures kept on the GPU"),
+];
+
+fn parse_bool(v: &str) -> Option<bool> {
+    match v.trim().to_ascii_lowercase().as_str() {
+        "1" | "on" | "true" | "yes" => Some(true),
+        "0" | "off" | "false" | "no" => Some(false),
+        _ => None,
+    }
+}
+
+impl Overrides {
+    /// Set option `key` from text; `auto` clears it. `Err` says what was expected.
+    pub fn set(&mut self, key: &str, value: &str) -> Result<(), String> {
+        let key = key.trim().trim_start_matches("--").replace('_', "-").to_ascii_lowercase();
+        let v = value.trim();
+        let auto = v.eq_ignore_ascii_case("auto") || v.is_empty();
+        let num = || v.parse::<usize>().map_err(|_| format!("{key} {v}: expected a number or auto"));
+        let flag = || parse_bool(v).ok_or_else(|| format!("{key} {v}: expected on or off"));
+        macro_rules! put {
+            ($f:ident, $e:expr) => {
+                self.$f = if auto { None } else { Some($e?) }
+            };
+        }
+        match key.as_str() {
+            "backend" => put!(backend, Backend::parse(v).ok_or_else(|| format!("backend {v}: expected auto, gpu or cpu"))),
+            "gpu-frames" => put!(gpu_frames, num()),
+            "gpu-inflight" => put!(gpu_inflight, num().map(|n| n.max(1))),
+            "cpu-frames" => put!(cpu_frames, num()),
+            "cpu-pool" => put!(cpu_pool, num()),
+            "gpu-pool" => put!(gpu_pool, num()),
+            "gpu-priority" => put!(gpu_priority, flag()),
+            "gpu-ideal-cpu" => put!(gpu_ideal_cpu, num().map(|n| n as u32)),
+            "cache-mb" => put!(cache_mb, num()),
+            "precomp-resident" => put!(precomp_resident, flag()),
+            "gpu-yuv" => put!(gpu_yuv, flag()),
+            "async-readback" => put!(async_readback, flag()),
+            "vram-budget-mb" => put!(vram_budget_mb, num()),
+            "ram-budget-mb" => put!(ram_budget_mb, num()),
+            "cpu-batch" => put!(cpu_batch, num().map(|n| n.max(1))),
+            "upload-budget-mb" => put!(upload_budget_mb, num()),
+            "pool-budget-mb" => put!(pool_budget_mb, num()),
+            _ => return Err(format!("unknown export tuning option {key}")),
+        }
+        Ok(())
+    }
+
+    /// The `EFFECTCRAFT_EXPORT_*` variables (invalid values are logged and ignored).
+    pub fn from_env() -> Overrides {
+        Overrides::from_lookup(|k| std::env::var(k).ok())
+    }
+
+    pub fn from_lookup(get: impl Fn(&str) -> Option<String>) -> Overrides {
+        let mut o = Overrides::default();
+        for (key, _) in OPTIONS {
+            if let Some(v) = get(&env_name(key))
+                && let Err(e) = o.set(key, &v)
+            {
+                log::warn!(target: "effectcraft_export", "{}: {e} (ignored)", env_name(key));
+            }
+        }
+        o
+    }
+
+    /// `key = value` lines (`#` comments).
+    pub fn from_config(text: &str) -> Result<Overrides, String> {
+        let mut o = Overrides::default();
+        for (n, line) in text.lines().enumerate() {
+            let line = line.split('#').next().unwrap_or("").trim();
+            if line.is_empty() {
+                continue;
+            }
+            let (k, v) = line.split_once('=').or_else(|| line.split_once(':')).ok_or_else(|| format!("line {}: expected key = value", n + 1))?;
+            o.set(k, v).map_err(|e| format!("line {}: {e}", n + 1))?;
+        }
+        Ok(o)
+    }
+}
+
+/// `EFFECTCRAFT_EXPORT_GPU_INFLIGHT` for `gpu-inflight`.
+pub fn env_name(key: &str) -> String {
+    format!("EFFECTCRAFT_EXPORT_{}", key.replace('-', "_").to_ascii_uppercase())
+}
+
+/// What the export is set up from by the caller (the CLI): its options, a config file, and
+/// whether to only print the tuning.
+#[derive(Clone, Debug, Default)]
+pub struct Request {
+    pub cli: Overrides,
+    pub config: Option<Overrides>,
+    /// `--print-tuning`: resolve, print, render nothing.
+    pub print_only: bool,
+}
+
+static REQUEST: Mutex<Option<Request>> = Mutex::new(None);
+
+/// Use `r` for the exports that follow.
+pub fn set_request(r: Request) {
+    *REQUEST.lock().unwrap_or_else(|e| e.into_inner()) = Some(r);
+}
+
+pub(crate) fn request() -> Request {
+    let mut r = REQUEST.lock().unwrap_or_else(|e| e.into_inner()).clone().unwrap_or_default();
+    if r.config.is_none()
+        && let Ok(path) = std::env::var("EFFECTCRAFT_EXPORT_CONFIG")
+    {
+        match std::fs::read_to_string(&path).map_err(|e| e.to_string()).and_then(|t| Overrides::from_config(&t)) {
+            Ok(c) => r.config = Some(c),
+            Err(e) => log::warn!(target: "effectcraft_export", "EFFECTCRAFT_EXPORT_CONFIG {path}: {e} (ignored)"),
+        }
+    }
+    r
+}
+
+/// The machine an export plans for.
+#[derive(Clone, Debug, Default, PartialEq)]
+pub struct Hardware {
+    /// The attached GPU; `None` = CPU only.
+    pub gpu: Option<GpuHw>,
+    /// Rayon threads.
+    pub threads: usize,
+    /// Physical memory and memory available now (free + reclaimable), when the platform says.
+    pub ram_bytes: Option<u64>,
+    pub avail_ram_bytes: Option<u64>,
+    /// Performance / efficiency cores (Apple silicon, hybrid CPUs), when the platform says.
+    pub core_kinds: Option<(usize, usize)>,
+}
+
+#[derive(Clone, Debug, Default, PartialEq)]
+pub struct GpuHw {
+    pub name: String,
+    pub vendor: u32,
+    pub device_type: String,
+    /// Dedicated VRAM when the platform reports it.
+    pub vram_bytes: Option<u64>,
+    /// The GPU shares system memory (Apple silicon, integrated GPUs): its budget comes from RAM.
+    pub unified: bool,
+    pub max_texture_dim: u32,
+    /// Readbacks complete asynchronously (false: a browser worker's deferred readbacks).
+    pub native: bool,
+}
+
+impl GpuHw {
+    /// GPUs the tuned GPU pipeline's auto settings were verified on: NVIDIA discrete (RTX 3090)
+    /// and Apple silicon (M4). Others keep the stock path unless the user opts in.
+    pub fn verified(&self) -> bool {
+        (self.vendor == 0x10de && self.device_type == "DiscreteGpu") || (self.unified && self.name.starts_with("Apple"))
+    }
+}
+
+/// Where a value came from.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum Source {
+    Cli,
+    Env,
+    Config,
+    Auto,
+}
+
+/// A resolved option: value, origin, reason.
+#[derive(Clone, Debug, PartialEq)]
+pub struct Setting<T> {
+    pub value: T,
+    pub source: Source,
+    pub why: String,
+}
+
+/// How a job renders its frames.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) enum Plan {
+    /// Every frame of a batch in parallel on the rayon pool, with this backend (the stock export).
+    Parallel(Backend),
+    /// `gpu` GPU workers and CPU workers taking frames one at a time from a shared queue.
+    Scheduled { gpu: usize, cpu: CpuWorkers },
+}
+
+/// CPU compositor workers next to the GPU workers.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum CpuWorkers {
+    Fixed(usize),
+    /// Start with none and add them while throughput improves, up to `max`.
+    Adaptive {
+        max: usize,
+    },
+}
+
+impl CpuWorkers {
+    /// Workers to spawn.
+    pub fn max(self) -> usize {
+        match self {
+            CpuWorkers::Fixed(n) | CpuWorkers::Adaptive { max: n } => n,
+        }
+    }
+}
+
+/// Every option resolved for one export ([`resolve`]).
+#[derive(Clone, Debug, PartialEq)]
+pub struct ExportTuning {
+    pub backend: Setting<Backend>,
+    pub gpu_frames: Setting<usize>,
+    pub gpu_inflight: Setting<usize>,
+    pub cpu_frames: Setting<CpuWorkers>,
+    pub cpu_pool: Setting<usize>,
+    pub gpu_pool: Setting<usize>,
+    pub gpu_priority: Setting<bool>,
+    pub gpu_ideal_cpu: Setting<Option<u32>>,
+    pub cache_mb: Setting<usize>,
+    pub cpu_batch: Setting<usize>,
+    pub precomp_resident: Setting<bool>,
+    pub gpu_yuv: Setting<bool>,
+    pub async_readback: Setting<bool>,
+    pub vram_budget_mb: Setting<usize>,
+    pub ram_budget_mb: Setting<usize>,
+    pub upload_budget_mb: Setting<usize>,
+    pub pool_budget_mb: Setting<usize>,
+    /// Hardware it was resolved for and the frame size, for [`ExportTuning::explain`].
+    pub hardware: Hardware,
+    pub frame: (u32, u32),
+    /// Warnings worth a `warn` log (low VRAM, a forced GPU that may not fit...).
+    pub warnings: Vec<String>,
+}
+
+/// VRAM assumed when the platform does not report it.
+pub const UNKNOWN_VRAM_MB: usize = 2048;
+/// Unified memory: the share of RAM the GPU side may plan with, and of what is available now.
+pub const UNIFIED_RAM_SHARE: (u64, u64) = (40, 60);
+/// Peak working VRAM of one GPU frame, in bytes per output pixel, calibrated from measured
+/// `nvidia-smi` peaks of the standalone scheduler (no working-texture reuse: every layer and
+/// effect allocates its own f32 textures) on the 3 s Bench4K test comp:
+///
+/// * RTX 3090, same build, budgets and 3 frames in flight: 17,609 MiB at 3840×2160 and
+///   9,709 MiB at 1920×1080. The fixed part (caches, pools, pipelines) cancels in the
+///   difference: 7,900 MiB / 6.22 Mpx ≈ 1,332 B per pixel (≈ 83 RGBA f32 textures).
+/// * GTX 1070 8 GB at 1080p: 4,948 MiB with 2 frames in flight and 4,982 MiB with 3, so a
+///   frame in flight beyond the first adds little (its canvas and 4:2:0 readback, see
+///   [`EXTRA_FRAME_TEXTURES`]); 4,948 MiB − 2,633 MiB for the frame ≈ 2,315 MiB fixed
+///   = the 1,536 MB upload cache + the 409 MB pool + ≈ [`GPU_BASE_MB`].
+/// * GTX 1070 at 4K: one frame needs ≈ 10.3 GB + the fixed part, over its 8 GB: every frame
+///   ran out of memory (measured), so auto picks the CPU there.
+///
+/// The GPU composites in RGBA f32 whatever the project's bit depth, so the estimate depends
+/// on the frame size only. #688's texture reuse and resident effects cut it severalfold.
+pub const GPU_FRAME_BYTES_PER_PIXEL: u64 = 1332;
+/// What each frame in flight beyond the first adds, in RGBA f32 frames (its canvas and
+/// readback).
+pub const EXTRA_FRAME_TEXTURES: u64 = 2;
+/// Device memory besides the frames and the upload/pool budgets (pipelines, staging ring,
+/// driver), measured ≈ 370 MB on the GTX 1070.
+pub const GPU_BASE_MB: u64 = 384;
+
+/// Estimated peak working VRAM, in MB, of the first GPU frame of `frame` pixels.
+pub fn frame_vram_mb(frame: (u32, u32)) -> u64 {
+    (frame.0 as u64 * frame.1 as u64 * GPU_FRAME_BYTES_PER_PIXEL).div_ceil(1 << 20).max(1)
+}
+
+/// Frames in flight that fit `avail_mb` of VRAM: 0 when even one does not.
+pub fn frames_that_fit(frame: (u32, u32), avail_mb: u64) -> u64 {
+    let first = frame_vram_mb(frame);
+    let extra = (frame.0 as u64 * frame.1 as u64 * 16 * EXTRA_FRAME_TEXTURES).div_ceil(1 << 20).max(1);
+    if avail_mb < first { 0 } else { 1 + (avail_mb - first) / extra }
+}
+/// Most frames in flight per GPU worker worth having (measured: 3 hides readback + recording).
+pub const MAX_INFLIGHT: usize = 3;
+
+fn set<T>(value: T, source: Source, why: &str) -> Setting<T> {
+    Setting { value, source, why: why.to_string() }
+}
+
+/// Resolve every option: `layers` in precedence order (CLI, env, config), then the auto rules.
+pub fn resolve(hw: &Hardware, frame: (u32, u32), layers: [(&Overrides, Source); 3]) -> ExportTuning {
+    macro_rules! given {
+        ($f:ident) => {
+            layers.iter().find_map(|(o, s)| o.$f.clone().map(|v| (v, *s)))
+        };
+    }
+    let mut warnings = vec![];
+    let threads = hw.threads.max(1);
+    let fb = frame.0 as u64 * frame.1 as u64 * 16;
+    let user = |s: Source| match s {
+        Source::Cli => "command line",
+        Source::Env => "environment",
+        Source::Config => "config file",
+        Source::Auto => "auto",
+    };
+
+    // VRAM budget and the GPU-side byte budgets.
+    let detected = hw.gpu.as_ref().and_then(|g| g.vram_bytes).map(|b| (b >> 20) as usize);
+    let unified = hw.gpu.as_ref().is_some_and(|g| g.unified);
+    let ram = match given!(ram_budget_mb) {
+        Some((v, s)) => set(v, s, &format!("set on the {}", user(s))),
+        None => match (hw.ram_bytes, hw.avail_ram_bytes) {
+            (Some(t), Some(a)) => set((t >> 20) as usize, Source::Auto, &format!("detected ({} MB available now)", a >> 20)),
+            (Some(t), None) => set((t >> 20) as usize, Source::Auto, "detected"),
+            _ => set(0, Source::Auto, "not reported (no RAM-based limits)"),
+        },
+    };
+    // Available now, capped by a user RAM budget.
+    let avail_ram_mb = match (hw.avail_ram_bytes, ram.source) {
+        (Some(a), Source::Auto) => (a >> 20) as usize,
+        (Some(a), _) => ((a >> 20) as usize).min(ram.value),
+        (None, _) => ram.value,
+    };
+    let vram = match given!(vram_budget_mb) {
+        Some((v, s)) => set(v, s, &format!("set on the {}", user(s))),
+        None => match (&hw.gpu, detected) {
+            (None, _) => set(0, Source::Auto, "no GPU"),
+            (Some(_), _) if unified && ram.value > 0 => {
+                let (share, now) = UNIFIED_RAM_SHARE;
+                let mb = (ram.value as u64 * share / 100).min(avail_ram_mb as u64 * now / 100) as usize;
+                set(mb, Source::Auto, &format!("unified memory: min({share}% of {} MB RAM, {now}% of {avail_ram_mb} MB available now)", ram.value))
+            }
+            (Some(_), Some(mb)) => set(mb, Source::Auto, "detected dedicated VRAM"),
+            (Some(_), None) => set(UNKNOWN_VRAM_MB, Source::Auto, "VRAM not reported by the platform: conservative guess"),
+        },
+    };
+    let vb = vram.value as u64;
+    let upload = match given!(upload_budget_mb) {
+        Some((v, s)) => set(v, s, &format!("set on the {}", user(s))),
+        None if unified => {
+            // What the frame slots leave of the budget (an upload is a copy within shared
+            // memory, so the cache only needs to hold the static layers, not more).
+            let per_frame = frame_vram_mb(frame);
+            let avail0 = (vb * 9 / 10).saturating_sub(256);
+            let fit = frames_that_fit(frame, avail0).min(MAX_INFLIGHT as u64);
+            let used = if fit == 0 { 0 } else { per_frame + (fit - 1) * (fb * EXTRA_FRAME_TEXTURES).div_ceil(1 << 20) };
+            let left = if fit == 0 { 0 } else { avail0.saturating_sub(used) };
+            set(
+                (256 + left).clamp(256, 1024) as usize,
+                Source::Auto,
+                &format!("unified memory: 256 MB + what {fit} frame slot(s) leave of the budget, at most 1024 MB (an upload is a copy within shared memory)"),
+            )
+        }
+        None => set(
+            (vb / 4).clamp(256, 1536) as usize,
+            Source::Auto,
+            "25% of the VRAM budget, 256..1536 MB: static layers upload once (a smaller cache re-uploads them every frame)",
+        ),
+    };
+    let pool = match given!(pool_budget_mb) {
+        Some((v, s)) => set(v, s, &format!("set on the {}", user(s))),
+        None => set((vb / 20).clamp(128, 768) as usize, Source::Auto, "5% of the VRAM budget, 128..768 MB"),
+    };
+    // Frames that fit: 90% of VRAM minus the upload cache, the texture pool and the fixed
+    // part, over the calibrated working set of a frame ([`GPU_FRAME_BYTES_PER_PIXEL`]).
+    let per_frame_mb = frame_vram_mb(frame);
+    let avail_mb = (vb * 9 / 10).saturating_sub(upload.value as u64 + pool.value as u64 + GPU_BASE_MB);
+    let slots = frames_that_fit(frame, avail_mb) as usize;
+    let gpu_ok = hw.gpu.is_some();
+    let verified = hw.gpu.as_ref().is_some_and(GpuHw::verified);
+
+    let backend = match given!(backend) {
+        Some((b, s)) => {
+            if b == Backend::Gpu && gpu_ok && slots == 0 {
+                warnings.push(format!(
+                    "backend gpu forced, but one {}x{} frame needs ~{per_frame_mb} MB of working VRAM and the budget leaves {avail_mb} MB: frames the GPU declines render on the CPU (each logged with the reason)",
+                    frame.0, frame.1
+                ));
+            }
+            set(b, s, &format!("set on the {}", user(s)))
+        }
+        None if !gpu_ok => set(Backend::Auto, Source::Auto, "no GPU attached: stock CPU path"),
+        None if !verified => {
+            let g = hw.gpu.as_ref();
+            set(
+                Backend::Auto,
+                Source::Auto,
+                &format!(
+                    "GPU {} (vendor 0x{:04x}, {}) is not one the tuned pipeline was verified on (NVIDIA discrete, Apple silicon): stock path; opt in with --backend gpu or individual options",
+                    g.map(|g| g.name.as_str()).unwrap_or("?"),
+                    g.map(|g| g.vendor).unwrap_or(0),
+                    g.map(|g| g.device_type.as_str()).unwrap_or("?")
+                ),
+            )
+        }
+        None if slots == 0 && vram.why.starts_with("VRAM not reported") => {
+            warnings.push(format!(
+                "GPU {}: VRAM not reported, so the tuned pipeline cannot size its frames: stock path (set vram-budget-mb to opt in)",
+                hw.gpu.as_ref().map(|g| g.name.as_str()).unwrap_or("?")
+            ));
+            set(Backend::Auto, Source::Auto, "VRAM unknown: stock path")
+        }
+        None if slots == 0 => {
+            warnings.push(format!(
+                "GPU {} has a {} MB {} budget; one {}x{} frame needs ~{per_frame_mb} MB of working memory and the budget leaves {avail_mb} MB after the {} MB upload cache, the texture pool and the device's fixed use: rendering on the CPU up front instead of failing on the GPU frame after frame (GPU memory savings such as working-texture reuse and GPU-resident effects, #688, would let it render on the GPU)",
+                hw.gpu.as_ref().map(|g| g.name.as_str()).unwrap_or("?"),
+                vb,
+                if unified { "unified-memory" } else { "VRAM" },
+                frame.0,
+                frame.1,
+                upload.value
+            ));
+            set(Backend::Cpu, Source::Auto, "a frame does not fit the VRAM budget")
+        }
+        None => set(Backend::Auto, Source::Auto, "GPU attached: GPU workers + adaptive CPU workers"),
+    };
+    // Unverified GPUs keep the stock path unless the user chose the backend.
+    // VRAM not reported and too small a guess for a frame: the stock path, as for unverified GPUs.
+    let vram_unknown = backend.source == Source::Auto && backend.why == "VRAM unknown: stock path";
+    let use_gpu = gpu_ok && backend.value != Backend::Cpu && !vram_unknown && (verified || backend.source != Source::Auto);
+
+    // P/E cores scaled to the threads in use (`--threads` simulates a smaller CPU).
+    let efficiency = hw.core_kinds.filter(|(p, e)| *p > 0 && *e > 0).map(|(p, e)| {
+        let total = p + e;
+        if threads >= total {
+            return (p, e);
+        }
+        let p2 = (p * threads).div_ceil(total).min(threads.saturating_sub(1)).max(1);
+        (p2, threads.saturating_sub(p2).max(1))
+    });
+    let gpu_frames = match given!(gpu_frames) {
+        Some((v, s)) => set(v, s, &format!("set on the {}", user(s))),
+        None if !use_gpu => set(0, Source::Auto, "no GPU in use"),
+        None => set(1, Source::Auto, "one recording worker: with async readback its CPU side (~15 ms/frame) is far below the GPU's; a second only adds VRAM"),
+    };
+    let gpu_inflight = match given!(gpu_inflight) {
+        Some((v, s)) => set(v.max(1), s, &format!("set on the {}", user(s))),
+        None if !use_gpu => set(1, Source::Auto, "no GPU in use"),
+        None => {
+            let per_worker = slots / gpu_frames.value.max(1);
+            // One frame in flight until the retry after a GPU out-of-memory is deterministic:
+            // with more, a frame that runs out of memory renders differently on its retry and
+            // so do a few after it (see TUNING.md). The VRAM plan below only reports the room.
+            set(
+                1,
+                Source::Auto,
+                &format!(
+                    "one frame: a retry after GPU out-of-memory is not deterministic yet (VRAM budget: {avail_mb} MB free after the upload cache, pool and fixed use; ~{per_frame_mb} MB for the first {}x{} frame = room for {} per worker, at most {MAX_INFLIGHT})",
+                    frame.0,
+                    frame.1,
+                    per_worker.clamp(1, MAX_INFLIGHT)
+                ),
+            )
+        }
+    };
+    let cpu_frames = match given!(cpu_frames) {
+        Some((v, s)) => set(CpuWorkers::Fixed(v), s, &format!("set on the {}", user(s))),
+        None if !use_gpu => set(CpuWorkers::Fixed(0), Source::Auto, "no GPU: every frame on the CPU compositor (stock parallel batches)"),
+        None if backend.value == Backend::Gpu => set(CpuWorkers::Fixed(0), Source::Auto, "backend gpu: GPU workers only"),
+        None => match efficiency {
+            Some((_, e)) => set(
+                CpuWorkers::Adaptive { max: e.clamp(1, 8) },
+                Source::Auto,
+                &format!("adaptive: start GPU-only, add CPU workers while measured frames/s improves (max the {e} efficiency core(s), ≤ 8)"),
+            ),
+            None => set(
+                CpuWorkers::Adaptive { max: (threads / 2).clamp(1, 8) },
+                Source::Auto,
+                "adaptive: start GPU-only, add CPU workers while measured frames/s improves (max half the threads, ≤ 8)",
+            ),
+        },
+    };
+    let cpu_pool = match given!(cpu_pool) {
+        Some((v, s)) => set(v, s, &format!("set on the {}", user(s))),
+        None if cpu_frames.value.max() == 0 => set(0, Source::Auto, "no CPU workers"),
+        None => match efficiency {
+            Some((p, e)) => set(
+                e.max(1),
+                Source::Auto,
+                &format!("the {e} efficiency core(s): the {p} performance core(s) stay with the GPU worker's CPU side and the encoder"),
+            ),
+            None => set((threads / 2).max(1), Source::Auto, "half the threads: CPU workers must not starve the GPU worker's CPU side"),
+        },
+    };
+    let gpu_pool = match given!(gpu_pool) {
+        Some((v, s)) => set(v, s, &format!("set on the {}", user(s))),
+        None => set(0, Source::Auto, "the global pool"),
+    };
+    let gpu_priority = match given!(gpu_priority) {
+        Some((v, s)) => set(v, s, &format!("set on the {}", user(s))),
+        None => set(false, Source::Auto, "normal priority (no measured gain)"),
+    };
+    let gpu_ideal_cpu = match given!(gpu_ideal_cpu) {
+        Some((v, s)) => set(Some(v), s, &format!("set on the {}", user(s))),
+        None => set(None, Source::Auto, "the OS schedules it"),
+    };
+    let cache_mb = match given!(cache_mb) {
+        Some((v, s)) => set(v, s, &format!("set on the {}", user(s))),
+        None if ram.value > 0 && ram.value * 15 / 100 < 4096 => {
+            set(ram.value * 15 / 100, Source::Auto, &format!("the job-wide layer cache, bounded to 15% of {} MB RAM", ram.value))
+        }
+        None if !use_gpu => set(4096, Source::Auto, "the job-wide layer cache (static layers render once), bounded"),
+        None => set(4096, Source::Auto, "the job-wide layer cache: static layers render and upload once"),
+    };
+    // CPU-compositor frames rendered at once (stock: one per thread), capped so their working
+    // memory (~8 × the frame's f32 buffer each) fits 60% of the RAM budget after the layer cache.
+    let cpu_frame_mb = (fb * 8).div_ceil(1 << 20).max(1) as usize;
+    let cpu_batch = match given!(cpu_batch) {
+        Some((v, s)) => set(v.max(1), s, &format!("set on the {}", user(s))),
+        None if ram.value == 0 => set(threads, Source::Auto, "one frame per thread (stock)"),
+        None => {
+            let room = (ram.value.min(avail_ram_mb.max(1)) * 6 / 10).saturating_sub(cache_mb.value);
+            let fit = (room / cpu_frame_mb).max(1);
+            if fit >= threads {
+                set(threads, Source::Auto, &format!("one frame per thread (stock): {threads} x ~{cpu_frame_mb} MB fit 60% of the RAM budget"))
+            } else {
+                set(
+                    fit,
+                    Source::Auto,
+                    &format!("{fit} frame(s) at once: ~{cpu_frame_mb} MB each must fit {room} MB (60% of the RAM budget after the layer cache)"),
+                )
+            }
+        }
+    };
+    let on_gpu = |given: Option<(bool, Source)>, why: &str| match given {
+        Some((v, s)) => set(v, s, &format!("set on the {}", user(s))),
+        // On by default in the GPU compositor either way; the export only turns it off when asked.
+        None if !use_gpu => set(true, Source::Auto, "the GPU compositor's default"),
+        None => set(true, Source::Auto, why),
+    };
+    let precomp_resident = on_gpu(given!(precomp_resident), "nested comps render on the GPU (no CPU render + upload per frame)");
+    let native = hw.gpu.as_ref().is_some_and(|g| g.native);
+    let gpu_yuv = match given!(gpu_yuv) {
+        Some((v, s)) => set(v, s, &format!("set on the {}", user(s))),
+        None if !use_gpu || !native => set(false, Source::Auto, "no native GPU in use"),
+        None => set(true, Source::Auto, "H.264: 12 MB 4:2:0 readback instead of 133 MB RGBA f32 at 4K (byte-identical conversion)"),
+    };
+    let async_readback = match given!(async_readback) {
+        Some((v, s)) => set(v, s, &format!("set on the {}", user(s))),
+        None if !gpu_yuv.value => set(false, Source::Auto, "only with gpu-yuv"),
+        None => set(true, Source::Auto, "the GPU worker records the next frame while the copy runs"),
+    };
+    if let Some(g) = &hw.gpu
+        && use_gpu
+        && (frame.0 > g.max_texture_dim || frame.1 > g.max_texture_dim)
+    {
+        warnings.push(format!("{}x{} exceeds the GPU's {} px texture limit: frames render on the CPU (logged)", frame.0, frame.1, g.max_texture_dim));
+    }
+    ExportTuning {
+        backend,
+        gpu_frames,
+        gpu_inflight,
+        cpu_frames,
+        cpu_pool,
+        gpu_pool,
+        gpu_priority,
+        gpu_ideal_cpu,
+        cache_mb,
+        cpu_batch,
+        precomp_resident,
+        gpu_yuv,
+        async_readback,
+        vram_budget_mb: vram,
+        ram_budget_mb: ram,
+        upload_budget_mb: upload,
+        pool_budget_mb: pool,
+        hardware: hw.clone(),
+        frame,
+        warnings,
+    }
+}
+
+impl ExportTuning {
+    /// The scheduling plan.
+    pub(crate) fn plan(&self, accel: bool) -> Plan {
+        let backend = self.backend.value;
+        let gpu = self.gpu_frames.value;
+        if !accel || backend == Backend::Cpu || gpu == 0 {
+            return Plan::Parallel(backend);
+        }
+        Plan::Scheduled { gpu, cpu: self.cpu_frames.value }
+    }
+
+    /// The flags the GPU compositor reads.
+    pub fn gpu_flags(&self) -> effectcraft_render::gpu_flags::GpuFlags {
+        effectcraft_render::gpu_flags::GpuFlags {
+            precomp_resident: self.precomp_resident.value,
+            unified: self.hardware.gpu.as_ref().is_some_and(|g| g.unified),
+        }
+    }
+
+    /// A table of every option: value, where it came from, why.
+    pub fn explain(&self) -> String {
+        let mut s = String::new();
+        let hw = &self.hardware;
+        let _ = writeln!(s, "export tuning for a {}x{} frame, {} thread(s)", self.frame.0, self.frame.1, hw.threads);
+        let _ = writeln!(
+            s,
+            "CPU cores: {}; RAM: {}",
+            hw.core_kinds.map(|(p, e)| format!("{p} performance + {e} efficiency")).unwrap_or("kinds not reported".into()),
+            match (hw.ram_bytes, hw.avail_ram_bytes) {
+                (Some(t), Some(a)) => format!("{} MB, {} MB available", t >> 20, a >> 20),
+                (Some(t), None) => format!("{} MB", t >> 20),
+                _ => "not reported".into(),
+            }
+        );
+        match &hw.gpu {
+            Some(g) => {
+                let _ = writeln!(
+                    s,
+                    "GPU: {} (vendor 0x{:04x}, {}), VRAM {}, max texture {} px",
+                    g.name,
+                    g.vendor,
+                    g.device_type,
+                    if g.unified { "unified (shares RAM)".into() } else { g.vram_bytes.map(|b| format!("{} MB", b >> 20)).unwrap_or("not reported".into()) },
+                    g.max_texture_dim
+                );
+            }
+            None => {
+                let _ = writeln!(s, "GPU: none attached");
+            }
+        }
+        macro_rules! row {
+            ($name:expr, $f:expr) => {{
+                let v = &$f;
+                let _ = writeln!(s, "  {:<17} {:<22} [{:?}] {}", $name, format!("{:?}", v.value), v.source, v.why);
+            }};
+        }
+        row!("backend", self.backend);
+        row!("gpu-frames", self.gpu_frames);
+        row!("gpu-inflight", self.gpu_inflight);
+        row!("cpu-frames", self.cpu_frames);
+        row!("cpu-pool", self.cpu_pool);
+        row!("gpu-pool", self.gpu_pool);
+        row!("gpu-priority", self.gpu_priority);
+        row!("gpu-ideal-cpu", self.gpu_ideal_cpu);
+        row!("cache-mb", self.cache_mb);
+        row!("cpu-batch", self.cpu_batch);
+        row!("precomp-resident", self.precomp_resident);
+        row!("gpu-yuv", self.gpu_yuv);
+        row!("async-readback", self.async_readback);
+        row!("vram-budget-mb", self.vram_budget_mb);
+        row!("ram-budget-mb", self.ram_budget_mb);
+        row!("upload-budget-mb", self.upload_budget_mb);
+        row!("pool-budget-mb", self.pool_budget_mb);
+        for w in &self.warnings {
+            let _ = writeln!(s, "  warning: {w}");
+        }
+        s
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const UHD: (u32, u32) = (3840, 2160);
+
+    fn hw(vram_gb: Option<u64>, threads: usize) -> Hardware {
+        Hardware {
+            gpu: vram_gb.map(|g| GpuHw {
+                name: "Test GPU".into(),
+                vendor: 0x10de,
+                device_type: "DiscreteGpu".into(),
+                vram_bytes: if g == 0 { None } else { Some(g << 30) },
+                unified: false,
+                max_texture_dim: 16384,
+                native: true,
+            }),
+            threads,
+            ..Default::default()
+        }
+    }
+
+    /// A verified GPU whose VRAM the platform does not report keeps the stock path at 4K
+    /// (never the CPU backend), and a user VRAM budget opts it back in.
+    #[test]
+    fn unknown_vram_keeps_the_stock_gpu_path() {
+        let t = auto(&hw(Some(0), 16), UHD);
+        assert_eq!(t.backend.value, Backend::Auto);
+        assert!(matches!(t.plan(true), Plan::Parallel(Backend::Auto)));
+        let cli = Overrides { vram_budget_mb: Some(24576), ..Default::default() };
+        let t = resolve(&hw(Some(0), 16), UHD, [(&cli, Source::Cli), (&Overrides::default(), Source::Env), (&Overrides::default(), Source::Config)]);
+        assert!(matches!(t.plan(true), Plan::Scheduled { .. }));
+    }
+
+    /// Apple M4-like: 16 GB unified memory, `avail_gb` available, 4P + 6E cores.
+    fn m4(avail_gb: u64, threads: usize) -> Hardware {
+        Hardware {
+            gpu: Some(GpuHw {
+                name: "Apple M4".into(),
+                device_type: "IntegratedGpu".into(),
+                unified: true,
+                max_texture_dim: 16384,
+                native: true,
+                ..Default::default()
+            }),
+            threads,
+            ram_bytes: Some(16 << 30),
+            avail_ram_bytes: Some(avail_gb << 30),
+            core_kinds: Some((4, 6)),
+        }
+    }
+
+    fn vendor(vendor: u32, device_type: &str, name: &str, unified: bool) -> Hardware {
+        let mut h = hw(Some(16), 16);
+        if let Some(g) = &mut h.gpu {
+            (g.vendor, g.device_type, g.name, g.unified) = (vendor, device_type.into(), name.into(), unified);
+        }
+        h
+    }
+
+    #[test]
+    fn auto_tunes_only_verified_gpus() {
+        // Verified: NVIDIA discrete, Apple silicon.
+        assert!(matches!(auto(&hw(Some(24), 16), UHD).plan(true), Plan::Scheduled { .. }));
+        assert!(matches!(auto(&m4(11, 10), (1920, 1080)).plan(true), Plan::Scheduled { .. }));
+        // AMD, Intel, NVIDIA integrated, unknown: the stock path, saying why.
+        for h in [
+            vendor(0x1002, "DiscreteGpu", "AMD Radeon RX 7900", false),
+            vendor(0x8086, "IntegratedGpu", "Intel Arc", true),
+            vendor(0x10de, "IntegratedGpu", "NVIDIA Tegra", true),
+            vendor(0x1234, "Other", "Mystery GPU", false),
+        ] {
+            let t = auto(&h, UHD);
+            assert_eq!(t.plan(true), Plan::Parallel(Backend::Auto), "{:?}", h.gpu);
+            assert!(t.backend.why.contains("not one the tuned pipeline was verified on"));
+            assert!(!t.gpu_yuv.value && !t.async_readback.value);
+            // Opting in: the backend, or an individual option.
+            let mut cli = Overrides::default();
+            cli.set("backend", "gpu").unwrap();
+            let n = Overrides::default();
+            let t = resolve(&h, UHD, [(&cli, Source::Cli), (&n, Source::Env), (&n, Source::Config)]);
+            assert!(matches!(t.plan(true), Plan::Scheduled { .. }) && t.precomp_resident.value);
+            let mut cli = Overrides::default();
+            cli.set("precomp-resident", "on").unwrap();
+            let t = resolve(&h, UHD, [(&cli, Source::Cli), (&n, Source::Env), (&n, Source::Config)]);
+            assert!(t.precomp_resident.value);
+        }
+    }
+
+    #[test]
+    fn cpu_batch_fits_the_ram_budget() {
+        // No RAM reported: stock (a frame per thread).
+        assert_eq!(auto(&hw(None, 16), UHD).cpu_batch.value, 16);
+        // 4 GB budget at 4K: ~1013 MB per CPU frame, 60% of 4096 - 614 cache = 1843 MB: 1 frame.
+        let mut cli = Overrides::default();
+        cli.set("ram-budget-mb", "4096").unwrap();
+        let n = Overrides::default();
+        let t = resolve(&m4(11, 10), UHD, [(&cli, Source::Cli), (&n, Source::Env), (&n, Source::Config)]);
+        assert_eq!((t.backend.value, t.cpu_batch.value), (Backend::Cpu, 1));
+        assert!(t.warnings[0].contains("after the 256 MB upload cache"), "{}", t.warnings[0]);
+        // Plenty of RAM at 1080p: one per thread.
+        assert_eq!(auto(&m4(11, 10), (1920, 1080)).cpu_batch.value, 10);
+    }
+
+    #[test]
+    fn unified_memory_plans_from_ram() {
+        // 16 GB, 11 GB available: min(40% of 16384, 60% of 11264) = 6553 MB. A 4K frame needs
+        // ~10.3 GB without texture reuse: the CPU, with a warning; 1080p fits on the GPU.
+        let t = auto(&m4(11, 10), UHD);
+        assert_eq!(t.vram_budget_mb.value, 6553);
+        assert_eq!((t.backend.value, t.upload_budget_mb.value), (Backend::Cpu, 256));
+        assert_eq!(t.warnings.len(), 1);
+        let t = auto(&m4(11, 10), (1920, 1080));
+        assert_eq!((t.backend.value, t.gpu_inflight.value, t.upload_budget_mb.value), (Backend::Auto, 1, 1024));
+        assert_eq!((t.cpu_frames.value, t.cpu_pool.value), (CpuWorkers::Adaptive { max: 6 }, 6));
+        assert_eq!(t.cache_mb.value, 2457);
+        // Little available now: the budget shrinks and 1080p falls back to the CPU too.
+        let t = auto(&m4(3, 10), (1920, 1080));
+        assert_eq!(t.vram_budget_mb.value, 1843);
+        assert_eq!(t.backend.value, Backend::Cpu);
+        assert_eq!(t.warnings.len(), 1);
+        // 4 threads: 2P + 2E.
+        let t = auto(&m4(11, 4), (1920, 1080));
+        assert_eq!((t.cpu_frames.value, t.cpu_pool.value), (CpuWorkers::Adaptive { max: 2 }, 2));
+        // A user RAM budget caps it.
+        let mut cli = Overrides::default();
+        cli.set("ram-budget-mb", "4096").unwrap();
+        let n = Overrides::default();
+        let t = resolve(&m4(11, 10), UHD, [(&cli, Source::Cli), (&n, Source::Env), (&n, Source::Config)]);
+        assert_eq!((t.vram_budget_mb.value, t.backend.value), (1638, Backend::Cpu));
+    }
+
+    fn auto(h: &Hardware, frame: (u32, u32)) -> ExportTuning {
+        let n = Overrides::default();
+        resolve(h, frame, [(&n, Source::Cli), (&n, Source::Env), (&n, Source::Config)])
+    }
+
+    #[test]
+    fn no_gpu_is_stock() {
+        for threads in [4, 8, 16, 32] {
+            let t = auto(&hw(None, threads), UHD);
+            assert_eq!(t.plan(false), Plan::Parallel(Backend::Auto));
+            assert_eq!(t.cache_mb.value, 4096);
+            assert!(!t.gpu_yuv.value && !t.async_readback.value);
+            assert!(t.warnings.is_empty());
+        }
+    }
+
+    #[test]
+    fn vram_profiles_at_4k() {
+        // 24 GB: room for three frames in flight, one by default.
+        let t = auto(&hw(Some(24), 16), UHD);
+        assert_eq!((t.backend.value, t.gpu_frames.value, t.gpu_inflight.value), (Backend::Auto, 1, 1));
+        assert_eq!((t.upload_budget_mb.value, t.pool_budget_mb.value), (1536, 768));
+        // 8 GB (GTX 1070): 7372 - 1536 upload - 409 pool - 384 = 5043 MB left; a 4K frame needs
+        // ~10537 MB (measured: every frame ran out of memory), so the CPU up front, with one
+        // warning naming the GPU memory savings that would fit it. 1080p (~2635 MB) fits.
+        assert_eq!(frame_vram_mb(UHD), 10537);
+        assert_eq!(frame_vram_mb((1920, 1080)), 2635);
+        let t = auto(&hw(Some(8), 8), UHD);
+        assert_eq!((t.backend.value, t.plan(true)), (Backend::Cpu, Plan::Parallel(Backend::Cpu)));
+        assert_eq!((t.upload_budget_mb.value, t.pool_budget_mb.value), (1536, 409));
+        assert_eq!(t.warnings.len(), 1);
+        assert!(t.warnings[0].contains("rendering on the CPU up front") && t.warnings[0].contains("#688"), "{}", t.warnings[0]);
+        let t = auto(&hw(Some(8), 8), (1920, 1080));
+        assert_eq!((t.backend.value, t.gpu_inflight.value), (Backend::Auto, 1));
+        assert!(t.warnings.is_empty());
+        // 4 GB and 2 GB: neither size fits.
+        for gb in [4, 2] {
+            for frame in [UHD, (1920, 1080)] {
+                let t = auto(&hw(Some(gb), 4), frame);
+                assert_eq!(t.backend.value, Backend::Cpu, "{gb} GB {frame:?}");
+                assert_eq!(t.warnings.len(), 1);
+            }
+        }
+        assert_eq!(auto(&hw(Some(4), 4), UHD).upload_budget_mb.value, 1024);
+        // Unknown VRAM plans with a conservative 2 GB.
+        let t = auto(&hw(Some(0), 16), (1920, 1080));
+        assert_eq!(t.vram_budget_mb.value, UNKNOWN_VRAM_MB);
+    }
+
+    #[test]
+    fn frames_in_flight_from_the_calibrated_estimate() {
+        // The 24 GB GPU has room for three 4K frames in flight but keeps one (the default);
+        // one frame more than fits is never planned.
+        let t = auto(&hw(Some(24), 16), UHD);
+        assert_eq!((t.backend.value, t.gpu_inflight.value), (Backend::Auto, 1));
+        assert_eq!(frames_that_fit(UHD, 10536), 0);
+        assert_eq!(frames_that_fit(UHD, 10537), 1);
+        assert_eq!(frames_that_fit(UHD, 10537 + 254), 2);
+    }
+
+    #[test]
+    fn cores() {
+        for (threads, max, pool) in [(4, 2, 2), (8, 4, 4), (16, 8, 8), (32, 8, 16)] {
+            let t = auto(&hw(Some(24), threads), UHD);
+            assert_eq!(t.cpu_frames.value, CpuWorkers::Adaptive { max }, "{threads} threads");
+            assert_eq!(t.cpu_pool.value, pool);
+            assert_eq!(t.plan(true), Plan::Scheduled { gpu: 1, cpu: CpuWorkers::Adaptive { max } });
+        }
+    }
+
+    #[test]
+    fn precedence_cli_env_config_auto() {
+        let mut cli = Overrides::default();
+        let mut env = Overrides::default();
+        let mut cfg = Overrides::default();
+        cfg.set("gpu-inflight", "1").unwrap();
+        cfg.set("cache-mb", "512").unwrap();
+        env.set("gpu-inflight", "2").unwrap();
+        cli.set("--gpu-inflight", "3").unwrap();
+        env.set("precomp_resident", "off").unwrap();
+        let t = resolve(&hw(Some(4), 8), UHD, [(&cli, Source::Cli), (&env, Source::Env), (&cfg, Source::Config)]);
+        assert_eq!((t.gpu_inflight.value, t.gpu_inflight.source), (3, Source::Cli));
+        assert_eq!((t.precomp_resident.value, t.precomp_resident.source), (false, Source::Env));
+        assert_eq!((t.cache_mb.value, t.cache_mb.source), (512, Source::Config));
+        assert_eq!(t.gpu_yuv.source, Source::Auto);
+    }
+
+    #[test]
+    fn forced_gpu_on_small_vram_warns() {
+        let mut cli = Overrides::default();
+        cli.set("backend", "gpu").unwrap();
+        let n = Overrides::default();
+        let t = resolve(&hw(Some(2), 4), UHD, [(&cli, Source::Cli), (&n, Source::Env), (&n, Source::Config)]);
+        assert_eq!(t.backend.value, Backend::Gpu);
+        assert_eq!(t.warnings.len(), 1);
+        assert_eq!(t.cpu_frames.value, CpuWorkers::Fixed(0));
+    }
+
+    #[test]
+    fn parsing() {
+        let o = Overrides::from_lookup(|k| match k {
+            "EFFECTCRAFT_EXPORT_GPU_YUV" => Some("off".into()),
+            "EFFECTCRAFT_EXPORT_CPU_FRAMES" => Some("auto".into()),
+            _ => None,
+        });
+        assert_eq!((o.gpu_yuv, o.cpu_frames), (Some(false), None));
+        let c = Overrides::from_config("# x\nbackend = gpu\ngpu-frames: 2\n").unwrap();
+        assert_eq!((c.backend, c.gpu_frames), (Some(Backend::Gpu), Some(2)));
+        assert!(Overrides::from_config("nope = 1").is_err());
+        assert!(Overrides::default().set("gpu-yuv", "maybe").is_err());
+        assert_eq!(env_name("gpu-inflight"), "EFFECTCRAFT_EXPORT_GPU_INFLIGHT");
+    }
+}
diff --git a/crates/export/src/webm.rs b/crates/export/src/webm.rs
index a12bd4e1a6..d02536acef 100644
--- a/crates/export/src/webm.rs
+++ b/crates/export/src/webm.rs
@@ -252,7 +252,7 @@ pub(crate) async fn webm(job: &Cx<'_>, comp: &Comp, w: u32, h: u32, st: &mut Sta
         }
     };
 
-    let batch = batch_size();
+    let batch = batch_size(job);
     let mut i = 0;
     while i < total {
         let end = (i + batch).min(total);
diff --git a/crates/export/src/webm_av1.rs b/crates/export/src/webm_av1.rs
index ca06a3e512..b2c2acf8e6 100644
--- a/crates/export/src/webm_av1.rs
+++ b/crates/export/src/webm_av1.rs
@@ -132,7 +132,7 @@ pub(crate) async fn webm_av1(job: &Cx<'_>, comp: &Comp, w: u32, h: u32, st: &mut
         }
     };
 
-    let batch = batch_size();
+    let batch = batch_size(job);
     let mut i = 0;
     let flush_blocks = |blocks: &mut Vec<Block>, file: &mut crate::out::Out, seg_len: &mut u64| -> Result<()> {
         if !blocks.is_empty() {
diff --git a/crates/export/tests/scheduler.rs b/crates/export/tests/scheduler.rs
new file mode 100644
index 0000000000..0581b8c22c
--- /dev/null
+++ b/crates/export/tests/scheduler.rs
@@ -0,0 +1,225 @@
+//! The streaming scheduler (an export with an accelerator attached) produces the same movie as
+//! a CPU export, in frame order, whether the GPU renders frames or declines them.
+
+use std::path::Path;
+use std::sync::atomic::{AtomicU64, Ordering};
+
+use effectcraft_color::Label;
+use effectcraft_effects::Buf;
+use effectcraft_export::render_queue::{OutputFormat, OutputModule, RenderSettings, TimeSpan};
+use effectcraft_export::tuning::{Overrides, Request, set_request};
+use effectcraft_export::{Job, export};
+use effectcraft_project::{Comp, ItemId, ItemKind, LayerSource, Project, Solid, build};
+use effectcraft_raster::Image;
+use effectcraft_render::{Accelerator, FxStep, NoFootage, Renderer};
+use effectcraft_time::{FrameRate, Tick};
+
+/// A "GPU" that renders with the CPU compositor (`decline`: refuses every frame).
+struct Mock {
+    decline: bool,
+    asked: AtomicU64,
+}
+
+impl Accelerator for Mock {
+    fn name(&self) -> String {
+        "mock".into()
+    }
+    fn comp_frame(&self, r: &Renderer, comp: ItemId, t: Tick) -> Option<Image> {
+        self.asked.fetch_add(1, Ordering::Relaxed);
+        std::thread::sleep(std::time::Duration::from_millis(t.0.unsigned_abs() % 7));
+        (!self.decline).then(|| r.comp_frame_cpu(comp, t))
+    }
+    fn supports_effect(&self, _: &str) -> bool {
+        false
+    }
+    fn effects(&self, _: &[FxStep], _: &Buf, _: Option<f32>) -> Option<Buf> {
+        None
+    }
+}
+
+/// 40 frames; a solid of a different colour starts at each of several frames, so frames out of
+/// order change the movie.
+fn project() -> (Project, ItemId) {
+    project_with(None)
+}
+
+/// [`project`], with a sound layer playing `audio`.
+fn project_with(audio: Option<&Path>) -> (Project, ItemId) {
+    let mut p = Project::default();
+    let mut comp = Comp::new(64, 48, FrameRate::new(10, 1), Tick::from_seconds_f64(4.0));
+    for (i, start) in [3, 7, 11, 17, 23, 31].into_iter().enumerate() {
+        let c = [(i % 3 == 0) as u8 as f32, (i % 2) as f32, i as f32 / 6.0];
+        let sid = p.add_item(&format!("S{i}"), Label::Red, None, ItemKind::Solid(Solid { color: c, width: 10 + 8 * i as u32, height: 48, pixel_aspect: 1.0 }));
+        let mut l = build::layer(&mut p, &comp, &format!("S{i}"), LayerSource::Solid { item: sid }, (10 + 8 * i as u32, 48), None);
+        l.in_point = comp.frame_rate.tick_of(start);
+        comp.layers.push(l);
+    }
+    if let Some(path) = audio {
+        let f = effectcraft_media::probe(path).expect("probe wav");
+        let fid = p.add_item("tone.wav", Label::SeaFoam, None, ItemKind::Footage(f));
+        let l = build::layer(&mut p, &comp, "tone", LayerSource::Footage { item: fid }, (0, 0), None);
+        comp.layers.push(l);
+    }
+    let cid = p.add_item("Comp", Label::Sandstone, None, ItemKind::Comp(comp.into()));
+    (p, cid)
+}
+
+fn render(p: &Project, cid: ItemId, accel: Option<&dyn Accelerator>, name: &str) -> Vec<u8> {
+    let d = Path::new(env!("CARGO_MANIFEST_DIR")).join("../../target/test-out/export/scheduler");
+    std::fs::create_dir_all(&d).expect("mkdir");
+    let path = d.join(name).to_string_lossy().to_string();
+    let s = RenderSettings { time_span: TimeSpan::LengthOfComp, ..Default::default() };
+    let om = OutputModule { bitrate_kbps: 4000, ..OutputModule::for_format(OutputFormat::H264) };
+    let job = Job {
+        project: p,
+        footage: &NoFootage,
+        expr: None,
+        accel,
+        comp: cid,
+        settings: &s,
+        output: &om,
+        path: &path,
+        sink: None,
+        options: Default::default(),
+        nested_switches: true,
+    };
+    let mut last = 0;
+    let r = export(&job, &mut |pr| {
+        assert!(pr.done >= last);
+        last = pr.done;
+        true
+    })
+    .expect("export");
+    assert_eq!((r.frames, last), (40, 40));
+    std::fs::read(&path).expect("read")
+}
+
+#[test]
+fn streams_in_order_with_any_worker_mix() {
+    let (p, cid) = project();
+    let reference = render(&p, cid, None, "cpu.mp4");
+    for (k, (decline, cpu)) in [(false, Some(0)), (false, Some(2)), (true, Some(1)), (false, None)].into_iter().enumerate() {
+        let mut cli = Overrides { cpu_frames: cpu, ..Default::default() };
+        // The mock adapter is no verified vendor: opt in to the scheduler.
+        cli.set("gpu-frames", "1").unwrap();
+        set_request(Request { cli, ..Default::default() });
+        let gpu = Mock { decline, asked: AtomicU64::new(0) };
+        let movie = render(&p, cid, Some(&gpu), &format!("sched{k}.mp4"));
+        assert!(movie == reference, "decline {decline} cpu {cpu:?}: differs from the CPU export");
+        assert!(gpu.asked.load(Ordering::Relaxed) > 0, "the GPU worker rendered nothing");
+    }
+}
+
+/// A stereo 440 Hz tone, 16-bit PCM at 48 kHz.
+fn write_tone(path: &Path, secs: f64) {
+    let sr = 48_000u32;
+    let mut data = vec![];
+    for i in 0..(secs * sr as f64) as usize {
+        let s = (0.5 * (2.0 * std::f64::consts::PI * 440.0 * i as f64 / sr as f64).sin() * 32767.0).round() as i16;
+        data.extend_from_slice(&s.to_le_bytes());
+        data.extend_from_slice(&s.to_le_bytes());
+    }
+    let mut w = b"RIFF".to_vec();
+    w.extend_from_slice(&(36 + data.len() as u32).to_le_bytes());
+    w.extend_from_slice(b"WAVEfmt ");
+    for v in [16u32, 1 | (2 << 16), sr, sr * 4, 4 | (16 << 16)] {
+        w.extend_from_slice(&v.to_le_bytes());
+    }
+    w.extend_from_slice(b"data");
+    w.extend_from_slice(&(data.len() as u32).to_le_bytes());
+    w.extend_from_slice(&data);
+    std::fs::write(path, w).expect("write wav");
+}
+
+/// Every file `fmt` wrote for `path` (a movie, or each frame of an image sequence), in order.
+fn written(path: &Path) -> Vec<Vec<u8>> {
+    let dir = path.parent().expect("dir");
+    let stem = path.file_name().expect("name").to_string_lossy().split('[').next().unwrap_or_default().to_string();
+    let mut files: Vec<_> = std::fs::read_dir(dir)
+        .expect("read dir")
+        .flatten()
+        .map(|e| e.path())
+        .filter(|p| p.file_name().is_some_and(|n| n.to_string_lossy().starts_with(&stem)))
+        .collect();
+    files.sort();
+    files.iter().map(|p| std::fs::read(p).expect("read")).collect()
+}
+
+/// Decoded stereo samples of `path`'s audio track (empty when it has none).
+fn audio_of(path: &Path) -> Vec<f32> {
+    let f = effectcraft_media::probe(path).expect("probe");
+    if !f.has_audio {
+        return vec![];
+    }
+    effectcraft_media::MediaPool::new().audio_samples(&f, Tick::ZERO, 4 * 48_000, 48_000)
+}
+
+/// The scheduler changes how frames are rendered, not what the output holds. Without audio, a
+/// scheduled export (frames rendered by the "GPU" worker, or declined to the CPU) writes the same
+/// bytes as the CPU export in every container and image format. With audio, the scheduled export
+/// interleaves audio after every frame instead of after every batch, so the container bytes
+/// differ, but the video is the same and the decoded audio is sample-identical.
+#[test]
+fn other_formats_and_audio_match_the_cpu_export() {
+    let d = Path::new(env!("CARGO_MANIFEST_DIR")).join("../../target/test-out/export/scheduler-formats");
+    let _ = std::fs::remove_dir_all(&d);
+    std::fs::create_dir_all(&d).expect("mkdir");
+    let wav = d.join("tone.wav");
+    write_tone(&wav, 4.0);
+    let (p, cid) = project_with(Some(&wav));
+    let pool = effectcraft_media::MediaPool::new();
+    let mut cli = Overrides::default();
+    cli.set("gpu-frames", "1").unwrap();
+    set_request(Request { cli, ..Default::default() });
+    let s = RenderSettings { time_span: TimeSpan::LengthOfComp, ..Default::default() };
+    use effectcraft_export::render_queue::AudioOutput;
+    for (fmt, name, audio) in [
+        (OutputFormat::H264, "a.mp4", AudioOutput::Off),
+        (OutputFormat::H264, "b.mp4", AudioOutput::Auto),
+        (OutputFormat::ProRes, "a.mov", AudioOutput::Off),
+        (OutputFormat::ProRes, "b.mov", AudioOutput::Auto),
+        (OutputFormat::WebM, "a.webm", AudioOutput::Off),
+        (OutputFormat::Gif, "a.gif", AudioOutput::Auto),
+        (OutputFormat::PngSequence, "f_[#####].png", AudioOutput::Auto),
+        (OutputFormat::ExrSequence, "f_[#####].exr", AudioOutput::Auto),
+    ] {
+        let om = OutputModule { audio, ..OutputModule::for_format(fmt) };
+        let mut outs = vec![];
+        for (k, accel) in
+            [None, Some(Mock { decline: false, asked: AtomicU64::new(0) }), Some(Mock { decline: true, asked: AtomicU64::new(0) })].iter().enumerate()
+        {
+            let sub = d.join(format!("{k}"));
+            std::fs::create_dir_all(&sub).expect("mkdir");
+            let path = sub.join(name).to_string_lossy().to_string();
+            let job = Job {
+                project: &p,
+                footage: &pool,
+                expr: None,
+                accel: accel.as_ref().map(|a| a as &dyn Accelerator),
+                comp: cid,
+                settings: &s,
+                output: &om,
+                path: &path,
+                sink: None,
+                options: Default::default(),
+                nested_switches: true,
+            };
+            let r = export(&job, &mut |_| true).expect("export");
+            if let Some(a) = accel {
+                assert!(a.asked.load(Ordering::Relaxed) > 0, "{name}: the GPU worker rendered nothing");
+            }
+            outs.push((r.audio, written(Path::new(&path)), path));
+        }
+        assert!(!outs[0].1.is_empty(), "{name}: nothing written");
+        for o in &outs[1..] {
+            assert_eq!(o.0, outs[0].0, "{name}: audio on/off");
+            if outs[0].0 {
+                let want = audio_of(Path::new(&outs[0].2));
+                assert!(!want.is_empty(), "{name}: no audio decoded");
+                assert!(audio_of(Path::new(&o.2)) == want, "{name}: decoded audio differs from the CPU export");
+            } else {
+                assert!(o.1 == outs[0].1, "{name}: differs from the CPU export");
+            }
+        }
+    }
+}

From 0a5f133f6799d818e7a6ab22060f9158ff7f5bc0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Matej=20Kozlovsk=C3=BD?=
 <100806068+MatejKozlovsky@users.noreply.github.com>
Date: Sun, 11 Oct 2026 04:42:48 +0200
Subject: [PATCH 04/10] CLI: render takes --print-tuning, --tuning-config and
 the export options as flags (#897)

---
 Cargo.lock                       |  2 +
 apps/effectcraft-cli/Cargo.toml  |  2 +
 apps/effectcraft-cli/src/main.rs | 64 ++++++++++++++++++++++++++++++++
 3 files changed, 68 insertions(+)

diff --git a/Cargo.lock b/Cargo.lock
index 9bc7b360a7..4db3f18a40 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1192,12 +1192,14 @@ dependencies = [
  "cpu-time",
  "effectcraft-automation",
  "effectcraft-engine",
+ "effectcraft-export",
  "effectcraft-gpu",
  "effectcraft-host",
  "effectcraft-render",
  "effectcraft-time",
  "effectcraft-ui-egui",
  "image",
+ "rayon",
  "serde_json",
 ]
 
diff --git a/apps/effectcraft-cli/Cargo.toml b/apps/effectcraft-cli/Cargo.toml
index b5784f4ebf..f354efe673 100644
--- a/apps/effectcraft-cli/Cargo.toml
+++ b/apps/effectcraft-cli/Cargo.toml
@@ -13,12 +13,14 @@ name = "effectcraft-cli"
 path = "src/main.rs"
 
 [dependencies]
+rayon = { workspace = true }
 effectcraft-engine = { workspace = true }
 effectcraft-host = { workspace = true }
 effectcraft-automation = { workspace = true }
 effectcraft-ui-egui = { workspace = true }
 effectcraft-render = { workspace = true }
 effectcraft-gpu = { workspace = true }
+effectcraft-export = { workspace = true }
 effectcraft-time = { workspace = true }
 serde_json = { workspace = true }
 image = { workspace = true }
diff --git a/apps/effectcraft-cli/src/main.rs b/apps/effectcraft-cli/src/main.rs
index fe5238075e..4d6f3207b6 100644
--- a/apps/effectcraft-cli/src/main.rs
+++ b/apps/effectcraft-cli/src/main.rs
@@ -103,6 +103,10 @@ const USAGE: &str = "usage: effectcraft-cli <info|commands|exec|run|props|get|se
          [--jpeg-quality N] [--bitrate KBPS] [--prores PROFILE] [--audio auto|on|off]
          [--profile main|main10] [--level auto|4.1] [--rate-control bitrate|quality] [--video-quality N]
          [--keyint FRAMES] [--webm-codec vp9|av1] [--audio-bitrate KBPS] [--opus-app audio|voice] | --queue
+         [--gpu] [--print-tuning] [--threads N] [--tuning-config FILE] [--<export option> VALUE ...]
+         (export options: backend, gpu-frames, gpu-inflight, cpu-frames, cpu-pool, cache-mb,
+          precomp-resident, gpu-yuv, async-readback, vram-budget-mb, ...; see TUNING.md; each also
+          EFFECTCRAFT_EXPORT_<OPTION>; CLI > env > config > auto)
                                            (formats h264|hevc|av1|prores|webm|png|jpeg|tiff|exr|gif|wav|aiff;
                                            --profile..--keyint: HEVC / AV1, --audio-bitrate/--opus-app: WebM Opus)
                                            a relative --out is relative to the working directory
@@ -169,11 +173,31 @@ const VALUED: &[&str] = &[
     // mcp
     "--automation-read-root",
     "--automation-write-root",
+    "--backend",
+    "--gpu-frames",
+    "--gpu-inflight",
+    "--cpu-frames",
+    "--cpu-pool",
+    "--gpu-pool",
+    "--gpu-priority",
+    "--gpu-ideal-cpu",
+    "--cache-mb",
+    "--precomp-resident",
+    "--gpu-yuv",
+    "--async-readback",
+    "--vram-budget-mb",
+    "--ram-budget-mb",
+    "--cpu-batch",
+    "--upload-budget-mb",
+    "--pool-budget-mb",
+    "--tuning-config",
+    "--threads",
 ];
 
 /// Options without a value. Any other `--option` is a usage error.
 const FLAGS: &[&str] = &[
     "--json",
+    "--print-tuning",
     "--save",
     "--demo",
     "--empty",
@@ -361,6 +385,41 @@ fn session(args: &Args) -> Result<effectcraft_engine::Session, Failure> {
     Ok(s)
 }
 
+/// `render` export options (`effectcraft_export::tuning`): every `--<option> VALUE` of
+/// `tuning::OPTIONS`, `--tuning-config FILE`, `--print-tuning` (resolve and print, render
+/// nothing) and `--threads N` (rayon threads; simulates a smaller CPU). `RUST_LOG=info` logs
+/// the resolved table and which compositor rendered each frame.
+fn export_tuning(args: &Args) -> Result<(), Failure> {
+    use effectcraft_export::tuning::{OPTIONS, Overrides, Request, set_request};
+    if std::env::var_os("RUST_LOG").is_some() {
+        effectcraft_engine::logging::install();
+    }
+    let threads = match args.opt("--threads") {
+        Some(v) => Some(v.parse::<usize>().map_err(|_| Failure::Usage(format!("--threads {v}: expected a number")))?),
+        None => std::env::var("EFFECTCRAFT_EXPORT_THREADS").ok().and_then(|v| v.trim().parse().ok()),
+    };
+    if let Some(n) = threads.filter(|n| *n > 0) {
+        rayon::ThreadPoolBuilder::new().num_threads(n).build_global().map_err(|e| Failure::Error(format!("--threads: {e}")))?;
+    }
+    let mut cli = Overrides::default();
+    for (key, _) in OPTIONS {
+        if let Some(v) = args.opt(&format!("--{key}")) {
+            cli.set(key, v).map_err(Failure::Usage)?;
+        }
+    }
+    let config = match args.opt("--tuning-config") {
+        Some(p) => Some(
+            std::fs::read_to_string(p)
+                .map_err(|e| e.to_string())
+                .and_then(|t| Overrides::from_config(&t))
+                .map_err(|e| Failure::Usage(format!("--tuning-config {p}: {e}")))?,
+        ),
+        None => None,
+    };
+    set_request(Request { cli, config, print_only: args.flag("--print-tuning") });
+    Ok(())
+}
+
 /// `--save` / `--save-as` after a mutating command.
 fn maybe_save(b: &mut Backend, args: &Args) -> Result<Option<String>, Failure> {
     let r = if let Some(p) = args.opt("--save-as") {
@@ -657,6 +716,7 @@ fn render(args: &Args, json_out: bool) -> Result<(), Failure> {
     if args.opt("--bridge").is_some() {
         return usage_err("render runs headless; use `exec renderQueue.add` / `renderQueue.render` with --bridge");
     }
+    export_tuning(args)?;
     let mut s = session(args)?;
     if args.opt("--template").is_some() {
         template::prepare(&mut s, args)?;
@@ -763,6 +823,10 @@ fn render(args: &Args, json_out: bool) -> Result<(), Failure> {
     if tty {
         note!();
     }
+    if args.flag("--print-tuning") {
+        // The export printed its tuning and stopped before rendering.
+        return Ok(());
+    }
     let mut results = vec![];
     let mut failed = vec![];
     for it in s.project.render_queue.iter().filter(|i| i.render && i.started.is_some()) {

From 65bef8d4f289e6b5b2a991a64d08495f44a8b795 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Matej=20Kozlovsk=C3=BD?=
 <100806068+MatejKozlovsky@users.noreply.github.com>
Date: Sun, 11 Oct 2026 21:43:10 +0200
Subject: [PATCH 05/10] Export: the scheduler test compares WebM by its decoded
 frames, since its clusters follow the render batches (#897)

---
 crates/export/tests/scheduler.rs | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/crates/export/tests/scheduler.rs b/crates/export/tests/scheduler.rs
index 0581b8c22c..7493b6d052 100644
--- a/crates/export/tests/scheduler.rs
+++ b/crates/export/tests/scheduler.rs
@@ -154,9 +154,17 @@ fn audio_of(path: &Path) -> Vec<f32> {
     effectcraft_media::MediaPool::new().audio_samples(&f, Tick::ZERO, 4 * 48_000, 48_000)
 }
 
+/// Decoded frames of `path`'s 40-frame, 10 fps video track.
+fn video_of(path: &Path) -> Vec<effectcraft_raster::Image> {
+    let f = effectcraft_media::probe(path).expect("probe");
+    let pool = effectcraft_media::MediaPool::new();
+    (0..40).map(|k| (*pool.frame_at(&f, Tick::from_seconds_f64((k as f64 + 0.5) / 10.0)).expect("decode")).clone()).collect()
+}
+
 /// The scheduler changes how frames are rendered, not what the output holds. Without audio, a
 /// scheduled export (frames rendered by the "GPU" worker, or declined to the CPU) writes the same
-/// bytes as the CPU export in every container and image format. With audio, the scheduled export
+/// bytes as the CPU export in every container and image format, except WebM, whose clusters
+/// follow the render batches, so its decoded frames are compared instead. With audio, the scheduled export
 /// interleaves audio after every frame instead of after every batch, so the container bytes
 /// differ, but the video is the same and the decoded audio is sample-identical.
 #[test]
@@ -217,6 +225,10 @@ fn other_formats_and_audio_match_the_cpu_export() {
                 let want = audio_of(Path::new(&outs[0].2));
                 assert!(!want.is_empty(), "{name}: no audio decoded");
                 assert!(audio_of(Path::new(&o.2)) == want, "{name}: decoded audio differs from the CPU export");
+            } else if fmt == OutputFormat::WebM {
+                // Clusters follow the render batches, which differ with the scheduler and the
+                // thread count; the VP9 frames are the same.
+                assert!(video_of(Path::new(&o.2)) == video_of(Path::new(&outs[0].2)), "{name}: decoded video differs from the CPU export");
             } else {
                 assert!(o.1 == outs[0].1, "{name}: differs from the CPU export");
             }

From b4d69d6fad6766f2b2e7eee955e7783e996711d0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Matej=20Kozlovsk=C3=BD?=
 <100806068+MatejKozlovsky@users.noreply.github.com>
Date: Tue, 13 Oct 2026 12:29:24 +0200
Subject: [PATCH 06/10] Export: the layer cache stays at the stock 1 GiB unless
 cache-mb asks for more, and the GPU worker runs at normal priority (drops
 thread-priority and gpu-priority / gpu-ideal-cpu: off by default, no measured
 gain) (#897)

---
 Cargo.lock                       | 15 --------------
 apps/effectcraft-cli/src/main.rs |  2 --
 crates/export/Cargo.toml         |  3 ---
 crates/export/TUNING.md          |  4 +---
 crates/export/src/pipeline.rs    | 31 ++--------------------------
 crates/export/src/tuning.rs      | 35 +++++++-------------------------
 6 files changed, 10 insertions(+), 80 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 4db3f18a40..5493398d2d 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1288,7 +1288,6 @@ dependencies = [
  "log",
  "rayon",
  "thiserror 2.0.21",
- "thread-priority",
  "web-time",
 ]
 
@@ -5077,20 +5076,6 @@ dependencies = [
  "syn 3.0.6",
 ]
 
-[[package]]
-name = "thread-priority"
-version = "3.1.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8d2e834949be5111506bb252643498af1514f600d9e1dceedaa42afae155b67f"
-dependencies = [
- "bitflags 2.13.2",
- "cfg-if",
- "libc",
- "log",
- "rustversion",
- "windows 0.62.2",
-]
-
 [[package]]
 name = "tiff"
 version = "0.11.3"
diff --git a/apps/effectcraft-cli/src/main.rs b/apps/effectcraft-cli/src/main.rs
index 4d6f3207b6..8f9ffe5a38 100644
--- a/apps/effectcraft-cli/src/main.rs
+++ b/apps/effectcraft-cli/src/main.rs
@@ -179,8 +179,6 @@ const VALUED: &[&str] = &[
     "--cpu-frames",
     "--cpu-pool",
     "--gpu-pool",
-    "--gpu-priority",
-    "--gpu-ideal-cpu",
     "--cache-mb",
     "--precomp-resident",
     "--gpu-yuv",
diff --git a/crates/export/Cargo.toml b/crates/export/Cargo.toml
index 32687e307b..2ef6f5ad8e 100644
--- a/crates/export/Cargo.toml
+++ b/crates/export/Cargo.toml
@@ -29,9 +29,6 @@ web-time = { workspace = true }
 thiserror = { workspace = true }
 log = { workspace = true }
 
-[target.'cfg(not(target_arch = "wasm32"))'.dependencies]
-thread-priority = "3"
-
 [dev-dependencies]
 effectcraft-media = { workspace = true }
 effectcraft-effects = { workspace = true }
diff --git a/crates/export/TUNING.md b/crates/export/TUNING.md
index 5b63a29d85..8bca6754fd 100644
--- a/crates/export/TUNING.md
+++ b/crates/export/TUNING.md
@@ -23,9 +23,7 @@ Config file: `--tuning-config FILE` or `EFFECTCRAFT_EXPORT_CONFIG=FILE` (`key =
 | `cpu-frames` | N, auto | adaptive: start GPU-only, add CPU workers while measured frames/s improves, max min(threads/2, 8); 0 with `backend gpu` |
 | `cpu-pool` | N (0 = global pool) | threads/2 when there are CPU workers |
 | `gpu-pool` | N (0 = global pool) | 0 |
-| `gpu-priority` | on, off | off |
-| `gpu-ideal-cpu` | N | unset (Windows only) |
-| `cache-mb` | MB (0 = off) | 4096: the job-wide layer cache, bounded (stock leaves it unbounded) |
+| `cache-mb` | MB (0 = off) | 1024: the job-wide layer cache at the stock 1 GiB; a larger cache is opt-in |
 | `precomp-resident` | on, off | on with a GPU: precomp layers' nested comps render on the GPU (2D precomp layers without masks/styles/proxies/overrides/frame blending; others take the CPU path) |
 | `gpu-yuv` | on, off | on with a native GPU (H.264 only; byte-identical to the CPU conversion) |
 | `async-readback` | on, off | on when `gpu-yuv` is on (off = wait for each frame) |
diff --git a/crates/export/src/pipeline.rs b/crates/export/src/pipeline.rs
index df67a29dba..7a5a0374cd 100644
--- a/crates/export/src/pipeline.rs
+++ b/crates/export/src/pipeline.rs
@@ -346,9 +346,6 @@ impl<'a> Cx<'a> {
                 let worker = if w < gpu { None } else { Some(w - gpu) };
                 s.spawn(move || {
                     let _alive = q.alive();
-                    if worker.is_none() {
-                        knobs.tune_gpu_thread(w);
-                    }
                     let pool = if worker.is_none() { gpu_pool } else { cpu_pool };
                     // Runs on a pool thread when the worker has a pool (its rayon jobs stay in that pool).
                     let in_pool = |job: &mut (dyn FnMut() + Send)| match pool {
@@ -1094,26 +1091,17 @@ mod tests {
     }
 }
 
-/// The scheduler's thread options (`gpu-pool`, `cpu-pool`, `gpu-priority`, `gpu-ideal-cpu`).
+/// The scheduler's thread options (`gpu-pool`, `cpu-pool`).
 #[derive(Debug, Default)]
 pub(crate) struct Knobs {
     pub gpu_pool: Option<usize>,
     pub cpu_pool: Option<usize>,
-    #[cfg_attr(target_arch = "wasm32", allow(dead_code))]
-    pub gpu_priority: bool,
-    #[cfg_attr(not(windows), allow(dead_code))]
-    pub gpu_ideal_cpu: Option<u32>,
 }
 
 impl Knobs {
     pub fn from_tuning(t: &crate::tuning::ExportTuning) -> Knobs {
         let nz = |n: usize| (n > 0).then_some(n);
-        Knobs {
-            gpu_pool: nz(t.gpu_pool.value),
-            cpu_pool: if t.cpu_frames.value.max() > 0 { nz(t.cpu_pool.value) } else { None },
-            gpu_priority: t.gpu_priority.value,
-            gpu_ideal_cpu: t.gpu_ideal_cpu.value,
-        }
+        Knobs { gpu_pool: nz(t.gpu_pool.value), cpu_pool: if t.cpu_frames.value.max() > 0 { nz(t.cpu_pool.value) } else { None } }
     }
 
     fn pool(&self, n: Option<usize>, name: &'static str) -> Option<rayon::ThreadPool> {
@@ -1125,21 +1113,6 @@ impl Knobs {
             .map_err(|e| log::warn!(target: "effectcraft_export", "{name} pool: {e}"))
             .ok()
     }
-
-    fn tune_gpu_thread(&self, _w: usize) {
-        #[cfg(not(target_arch = "wasm32"))]
-        if self.gpu_priority
-            && let Err(e) = thread_priority::set_current_thread_priority(thread_priority::ThreadPriority::Max)
-        {
-            log::warn!(target: "effectcraft_export", "gpu worker priority: {e:?}");
-        }
-        #[cfg(windows)]
-        if let Some(n) = self.gpu_ideal_cpu
-            && let Err(e) = thread_priority::windows::set_current_thread_ideal_processor(n)
-        {
-            log::warn!(target: "effectcraft_export", "gpu worker ideal processor: {e:?}");
-        }
-    }
 }
 
 /// The export's layer cache ([`Cx::cache`]), `mb` megabytes (0 = none).
diff --git a/crates/export/src/tuning.rs b/crates/export/src/tuning.rs
index 265e23d48e..161dbdde51 100644
--- a/crates/export/src/tuning.rs
+++ b/crates/export/src/tuning.rs
@@ -30,8 +30,6 @@ pub struct Overrides {
     pub cpu_frames: Option<usize>,
     pub cpu_pool: Option<usize>,
     pub gpu_pool: Option<usize>,
-    pub gpu_priority: Option<bool>,
-    pub gpu_ideal_cpu: Option<u32>,
     pub cache_mb: Option<usize>,
     pub precomp_resident: Option<bool>,
     pub gpu_yuv: Option<bool>,
@@ -52,8 +50,6 @@ pub const OPTIONS: &[(&str, &str)] = &[
     ("cpu-frames", "N|auto: CPU compositor workers next to the GPU (auto: adaptive by throughput)"),
     ("cpu-pool", "N: threads shared by the CPU workers' intra-frame work (0 = the whole pool)"),
     ("gpu-pool", "N: a rayon pool of its own for the GPU workers (0 = the global pool)"),
-    ("gpu-priority", "on|off: raise the GPU worker threads' priority"),
-    ("gpu-ideal-cpu", "N: preferred logical CPU of the GPU worker (Windows)"),
     ("cache-mb", "MB: export layer cache (static layers render and upload once; 0 = off)"),
     ("precomp-resident", "on|off: render precomp layers' nested comps resident on the GPU (not on the CPU + upload)"),
     ("gpu-yuv", "on|off: convert H.264 frames to 4:2:0 on the GPU (12 MB readback at 4K)"),
@@ -93,8 +89,6 @@ impl Overrides {
             "cpu-frames" => put!(cpu_frames, num()),
             "cpu-pool" => put!(cpu_pool, num()),
             "gpu-pool" => put!(gpu_pool, num()),
-            "gpu-priority" => put!(gpu_priority, flag()),
-            "gpu-ideal-cpu" => put!(gpu_ideal_cpu, num().map(|n| n as u32)),
             "cache-mb" => put!(cache_mb, num()),
             "precomp-resident" => put!(precomp_resident, flag()),
             "gpu-yuv" => put!(gpu_yuv, flag()),
@@ -266,8 +260,6 @@ pub struct ExportTuning {
     pub cpu_frames: Setting<CpuWorkers>,
     pub cpu_pool: Setting<usize>,
     pub gpu_pool: Setting<usize>,
-    pub gpu_priority: Setting<bool>,
-    pub gpu_ideal_cpu: Setting<Option<u32>>,
     pub cache_mb: Setting<usize>,
     pub cpu_batch: Setting<usize>,
     pub precomp_resident: Setting<bool>,
@@ -331,6 +323,9 @@ fn set<T>(value: T, source: Source, why: &str) -> Setting<T> {
 }
 
 /// Resolve every option: `layers` in precedence order (CLI, env, config), then the auto rules.
+/// The stock export layer cache (`LayerCache::default()`): 1 GiB.
+pub const STOCK_CACHE_MB: usize = 1024;
+
 pub fn resolve(hw: &Hardware, frame: (u32, u32), layers: [(&Overrides, Source); 3]) -> ExportTuning {
     macro_rules! given {
         ($f:ident) => {
@@ -529,21 +524,9 @@ pub fn resolve(hw: &Hardware, frame: (u32, u32), layers: [(&Overrides, Source);
         Some((v, s)) => set(v, s, &format!("set on the {}", user(s))),
         None => set(0, Source::Auto, "the global pool"),
     };
-    let gpu_priority = match given!(gpu_priority) {
-        Some((v, s)) => set(v, s, &format!("set on the {}", user(s))),
-        None => set(false, Source::Auto, "normal priority (no measured gain)"),
-    };
-    let gpu_ideal_cpu = match given!(gpu_ideal_cpu) {
-        Some((v, s)) => set(Some(v), s, &format!("set on the {}", user(s))),
-        None => set(None, Source::Auto, "the OS schedules it"),
-    };
     let cache_mb = match given!(cache_mb) {
         Some((v, s)) => set(v, s, &format!("set on the {}", user(s))),
-        None if ram.value > 0 && ram.value * 15 / 100 < 4096 => {
-            set(ram.value * 15 / 100, Source::Auto, &format!("the job-wide layer cache, bounded to 15% of {} MB RAM", ram.value))
-        }
-        None if !use_gpu => set(4096, Source::Auto, "the job-wide layer cache (static layers render once), bounded"),
-        None => set(4096, Source::Auto, "the job-wide layer cache: static layers render and upload once"),
+        None => set(STOCK_CACHE_MB, Source::Auto, "the job-wide layer cache at the stock 1 GiB (a larger one is opt-in)"),
     };
     // CPU-compositor frames rendered at once (stock: one per thread), capped so their working
     // memory (~8 × the frame's f32 buffer each) fits 60% of the RAM budget after the layer cache.
@@ -596,8 +579,6 @@ pub fn resolve(hw: &Hardware, frame: (u32, u32), layers: [(&Overrides, Source);
         cpu_frames,
         cpu_pool,
         gpu_pool,
-        gpu_priority,
-        gpu_ideal_cpu,
         cache_mb,
         cpu_batch,
         precomp_resident,
@@ -675,8 +656,6 @@ impl ExportTuning {
         row!("cpu-frames", self.cpu_frames);
         row!("cpu-pool", self.cpu_pool);
         row!("gpu-pool", self.gpu_pool);
-        row!("gpu-priority", self.gpu_priority);
-        row!("gpu-ideal-cpu", self.gpu_ideal_cpu);
         row!("cache-mb", self.cache_mb);
         row!("cpu-batch", self.cpu_batch);
         row!("precomp-resident", self.precomp_resident);
@@ -786,7 +765,7 @@ mod tests {
     fn cpu_batch_fits_the_ram_budget() {
         // No RAM reported: stock (a frame per thread).
         assert_eq!(auto(&hw(None, 16), UHD).cpu_batch.value, 16);
-        // 4 GB budget at 4K: ~1013 MB per CPU frame, 60% of 4096 - 614 cache = 1843 MB: 1 frame.
+        // 4 GB budget at 4K: ~1013 MB per CPU frame, 60% of 4096 - 1024 cache = 1433 MB: 1 frame.
         let mut cli = Overrides::default();
         cli.set("ram-budget-mb", "4096").unwrap();
         let n = Overrides::default();
@@ -808,7 +787,7 @@ mod tests {
         let t = auto(&m4(11, 10), (1920, 1080));
         assert_eq!((t.backend.value, t.gpu_inflight.value, t.upload_budget_mb.value), (Backend::Auto, 1, 1024));
         assert_eq!((t.cpu_frames.value, t.cpu_pool.value), (CpuWorkers::Adaptive { max: 6 }, 6));
-        assert_eq!(t.cache_mb.value, 2457);
+        assert_eq!(t.cache_mb.value, STOCK_CACHE_MB);
         // Little available now: the budget shrinks and 1080p falls back to the CPU too.
         let t = auto(&m4(3, 10), (1920, 1080));
         assert_eq!(t.vram_budget_mb.value, 1843);
@@ -835,7 +814,7 @@ mod tests {
         for threads in [4, 8, 16, 32] {
             let t = auto(&hw(None, threads), UHD);
             assert_eq!(t.plan(false), Plan::Parallel(Backend::Auto));
-            assert_eq!(t.cache_mb.value, 4096);
+            assert_eq!(t.cache_mb.value, STOCK_CACHE_MB);
             assert!(!t.gpu_yuv.value && !t.async_readback.value);
             assert!(t.warnings.is_empty());
         }

From 5aa3db07a43281536e6a3940d277968c335c847f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Matej=20Kozlovsk=C3=BD?=
 <100806068+MatejKozlovsky@users.noreply.github.com>
Date: Tue, 13 Oct 2026 12:30:35 +0200
Subject: [PATCH 07/10] Export: the CLI probes the host (RAM, core kinds,
 VRAM), reads the EFFECTCRAFT_EXPORT_* variables and the tuning config file,
 and passes them in; the export library spawns no processes and reads no
 system files (#897)

---
 apps/effectcraft-cli/src/export_host.rs | 109 +++++++++++++++++++++
 apps/effectcraft-cli/src/main.rs        |  16 ++--
 crates/export/TUNING.md                 |  10 +-
 crates/export/src/hw.rs                 | 120 ++----------------------
 crates/export/src/pipeline.rs           |   9 +-
 crates/export/src/tuning.rs             |  40 ++++----
 6 files changed, 160 insertions(+), 144 deletions(-)
 create mode 100644 apps/effectcraft-cli/src/export_host.rs

diff --git a/apps/effectcraft-cli/src/export_host.rs b/apps/effectcraft-cli/src/export_host.rs
new file mode 100644
index 0000000000..8364ecf992
--- /dev/null
+++ b/apps/effectcraft-cli/src/export_host.rs
@@ -0,0 +1,109 @@
+//! Host facts for the export tuning (`effectcraft_export::tuning::Host`): the export library
+//! probes nothing itself, so the CLI measures RAM, core kinds and VRAM here (process spawns
+//! and system files) and passes them in.
+
+use effectcraft_export::tuning::Host;
+
+/// RAM, core kinds and dedicated VRAM of this machine; unknown values stay `None`.
+pub fn probe() -> Host {
+    let (ram_bytes, avail_ram_bytes) = memory();
+    Host { ram_bytes, avail_ram_bytes, core_kinds: core_kinds(), nvidia_vram_bytes: nvidia_smi_vram_mb().map(|mb| mb << 20), other_vram_bytes: sysfs_vram() }
+}
+
+/// `sysctl -n NAME` (macOS), parsed.
+#[cfg(target_os = "macos")]
+fn sysctl(name: &str) -> Option<u64> {
+    let out = std::process::Command::new("/usr/sbin/sysctl").args(["-n", name]).output().ok()?;
+    String::from_utf8_lossy(&out.stdout).trim().parse().ok()
+}
+
+/// Physical memory and memory available now (free + inactive + speculative + purgeable pages on
+/// macOS, `MemAvailable` on Linux); `None` where not queried.
+fn memory() -> (Option<u64>, Option<u64>) {
+    #[cfg(target_os = "macos")]
+    {
+        let total = sysctl("hw.memsize");
+        let avail = std::process::Command::new("/usr/bin/vm_stat").output().ok().and_then(|o| {
+            let text = String::from_utf8_lossy(&o.stdout).into_owned();
+            let page = text.split("page size of ").nth(1)?.split_whitespace().next()?.parse::<u64>().ok()?;
+            let pages = |key: &str| {
+                text.lines()
+                    .find(|l| l.starts_with(key))
+                    .and_then(|l| l.rsplit(':').next())
+                    .and_then(|v| v.trim().trim_end_matches('.').parse::<u64>().ok())
+                    .unwrap_or(0)
+            };
+            let n = pages("Pages free") + pages("Pages inactive") + pages("Pages speculative") + pages("Pages purgeable");
+            Some(n.saturating_mul(page))
+        });
+        (total, avail)
+    }
+    #[cfg(target_os = "linux")]
+    {
+        let Ok(m) = std::fs::read_to_string("/proc/meminfo") else { return (None, None) };
+        let kb =
+            |key: &str| m.lines().find(|l| l.starts_with(key)).and_then(|l| l.split_whitespace().nth(1)).and_then(|v| v.parse::<u64>().ok()).map(|v| v * 1024);
+        (kb("MemTotal:"), kb("MemAvailable:"))
+    }
+    #[cfg(windows)]
+    {
+        // No platform calls (the workspace has no `unsafe`): ask CIM through PowerShell, in KB.
+        let out = std::process::Command::new("powershell.exe")
+            .args([
+                "-NoProfile",
+                "-NonInteractive",
+                "-Command",
+                "$o = Get-CimInstance Win32_OperatingSystem; \"$($o.TotalVisibleMemorySize) $($o.FreePhysicalMemory)\"",
+            ])
+            .output();
+        let Ok(out) = out else { return (None, None) };
+        let text = String::from_utf8_lossy(&out.stdout).into_owned();
+        let mut kb = text.split_whitespace().map(|v| v.parse::<u64>().ok().map(|v| v * 1024));
+        (kb.next().flatten(), kb.next().flatten())
+    }
+    #[cfg(not(any(target_os = "macos", target_os = "linux", windows)))]
+    {
+        (None, None)
+    }
+}
+
+/// Performance and efficiency cores (Apple silicon's `hw.perflevel0/1`); `None` elsewhere.
+fn core_kinds() -> Option<(usize, usize)> {
+    #[cfg(target_os = "macos")]
+    {
+        let p = sysctl("hw.perflevel0.logicalcpu")? as usize;
+        let e = sysctl("hw.perflevel1.logicalcpu").unwrap_or(0) as usize;
+        Some((p, e))
+    }
+    #[cfg(not(target_os = "macos"))]
+    {
+        None
+    }
+}
+
+/// Dedicated VRAM from Linux sysfs (amdgpu reports it; NVIDIA's proprietary driver and Intel do
+/// not); `None` elsewhere. NVIDIA (Windows and Linux): [`nvidia_smi_vram_mb`], which ships with
+/// the driver. No platform calls: the workspace has no `unsafe`.
+fn sysfs_vram() -> Option<u64> {
+    #[cfg(target_os = "linux")]
+    {
+        let dir = std::fs::read_dir("/sys/class/drm").ok()?;
+        dir.filter_map(|e| e.ok())
+            .filter_map(|e| std::fs::read_to_string(e.path().join("device/mem_info_vram_total")).ok())
+            .filter_map(|t| t.trim().parse::<u64>().ok())
+            .max()
+    }
+    #[cfg(not(target_os = "linux"))]
+    {
+        None
+    }
+}
+
+/// Total memory of the largest NVIDIA GPU in MB, from `nvidia-smi`; `None` without it.
+fn nvidia_smi_vram_mb() -> Option<u64> {
+    let out = std::process::Command::new("nvidia-smi").args(["--query-gpu=memory.total", "--format=csv,noheader,nounits"]).output().ok()?;
+    if !out.status.success() {
+        return None;
+    }
+    String::from_utf8_lossy(&out.stdout).lines().filter_map(|l| l.trim().parse::<u64>().ok()).max()
+}
diff --git a/apps/effectcraft-cli/src/main.rs b/apps/effectcraft-cli/src/main.rs
index 8f9ffe5a38..52ddebafae 100644
--- a/apps/effectcraft-cli/src/main.rs
+++ b/apps/effectcraft-cli/src/main.rs
@@ -41,6 +41,7 @@
 
 use std::io::Write;
 
+mod export_host;
 mod template;
 
 use effectcraft_automation::tools::{self, Reply};
@@ -405,16 +406,15 @@ fn export_tuning(args: &Args) -> Result<(), Failure> {
             cli.set(key, v).map_err(Failure::Usage)?;
         }
     }
+    let read = |p: &str| std::fs::read_to_string(p).map_err(|e| e.to_string()).and_then(|t| Overrides::from_config(&t));
     let config = match args.opt("--tuning-config") {
-        Some(p) => Some(
-            std::fs::read_to_string(p)
-                .map_err(|e| e.to_string())
-                .and_then(|t| Overrides::from_config(&t))
-                .map_err(|e| Failure::Usage(format!("--tuning-config {p}: {e}")))?,
-        ),
-        None => None,
+        Some(p) => Some(read(p).map_err(|e| Failure::Usage(format!("--tuning-config {p}: {e}")))?),
+        None => std::env::var("EFFECTCRAFT_EXPORT_CONFIG")
+            .ok()
+            .and_then(|p| read(&p).map_err(|e| eprintln!("warning: EFFECTCRAFT_EXPORT_CONFIG {p}: {e} (ignored)")).ok()),
     };
-    set_request(Request { cli, config, print_only: args.flag("--print-tuning") });
+    let env = Overrides::from_lookup(|k| std::env::var(k).ok());
+    set_request(Request { cli, env, config, host: export_host::probe(), print_only: args.flag("--print-tuning") });
     Ok(())
 }
 
diff --git a/crates/export/TUNING.md b/crates/export/TUNING.md
index 8bca6754fd..4d6e042646 100644
--- a/crates/export/TUNING.md
+++ b/crates/export/TUNING.md
@@ -8,7 +8,8 @@ spellings, resolved per export with precedence **CLI > environment > config file
 | `--gpu-inflight 3`    | `EFFECTCRAFT_EXPORT_GPU_INFLIGHT=3`  | `gpu-inflight = 3`   |
 
 Config file: `--tuning-config FILE` or `EFFECTCRAFT_EXPORT_CONFIG=FILE` (`key = value` lines,
-`#` comments). The value `auto` (or leaving an option out) lets the auto rules decide.
+`#` comments). The CLI reads the environment variables and the config file and passes them to the
+export library (`tuning::Request`); other callers pass their own values or none. The value `auto` (or leaving an option out) lets the auto rules decide.
 `--print-tuning` prints every resolved value, where it came from and why, and renders nothing.
 `--threads N` / `EFFECTCRAFT_EXPORT_THREADS` sizes the rayon pool (simulates a smaller CPU).
 `RUST_LOG=effectcraft_export=info` logs the same table at the start of every export.
@@ -29,7 +30,7 @@ Config file: `--tuning-config FILE` or `EFFECTCRAFT_EXPORT_CONFIG=FILE` (`key =
 | `async-readback` | on, off | on when `gpu-yuv` is on (off = wait for each frame) |
 | `cpu-batch` | N | one CPU-compositor frame per thread, capped so ~8x the frame buffer each fits 60% of the RAM budget after the layer cache |
 | `ram-budget-mb` | MB | detected RAM: unified-memory GPUs plan from it; the layer cache is capped at 15% of it |
-| `vram-budget-mb` | MB | detected dedicated VRAM (amdgpu sysfs on Linux); unified memory: from RAM; else 2048 |
+| `vram-budget-mb` | MB | dedicated VRAM measured by the CLI (`nvidia-smi`; amdgpu sysfs on Linux); unified memory: from RAM; else 2048 |
 | `upload-budget-mb` | MB | 25% of the VRAM budget, clamped to 256..1536 (a warning is logged once when it overflows) |
 | `pool-budget-mb` | MB | 5% of the VRAM budget, clamped to 128..768 |
 
@@ -64,10 +65,11 @@ Config file: `--tuning-config FILE` or `EFFECTCRAFT_EXPORT_CONFIG=FILE` (`key =
 
 * Detected from the adapter (integrated, or an Apple GPU). There is no separate VRAM: the GPU budget
   (`vram-budget-mb`) is min(40% of RAM, 60% of the RAM available when the export starts); RAM and
-  availability come from `sysctl hw.memsize` + `vm_stat` (macOS) or `/proc/meminfo` (Linux).
+  availability come from `sysctl hw.memsize` + `vm_stat` (macOS) or `/proc/meminfo` (Linux), measured by
+  the CLI and passed in (`tuning::Host`); the export library itself spawns no processes and reads no system files.
 * The upload cache gets 256 MB plus what the frame slots leave of that budget (at most 1024 MB): an
   upload is a copy within shared memory, so frame slots come first.
-* The CPU layer cache is capped at 15% of RAM (it competes with the GPU for the same memory).
+* The CPU layer cache stays at the stock 1 GiB unless `cache-mb` asks for more.
 * Performance/efficiency cores (`hw.perflevel0/1`): adaptive CPU workers and their pool use at most
   the efficiency cores; the performance cores stay with the GPU worker's CPU side and the encoder.
   With `--threads N` the split is scaled to N.
diff --git a/crates/export/src/hw.rs b/crates/export/src/hw.rs
index 797f9d0242..539cf26c91 100644
--- a/crates/export/src/hw.rs
+++ b/crates/export/src/hw.rs
@@ -1,12 +1,15 @@
-//! Hardware the export tuning plans for ([`crate::tuning::Hardware`]).
+//! Hardware the export tuning plans for ([`crate::tuning::Hardware`]). The library probes
+//! nothing itself (no process spawns, no system files): the adapter comes from the
+//! accelerator and the host facts (RAM, core kinds, VRAM) from the caller ([`Host`]).
 
-use crate::tuning::{GpuHw, Hardware};
+use crate::tuning::{GpuHw, Hardware, Host};
 
-/// The machine as seen by this export: rayon threads and the attached accelerator.
-pub(crate) fn detect(accel: Option<&dyn effectcraft_render::Accelerator>) -> Hardware {
+/// The machine as seen by this export: rayon threads, the attached accelerator and what the
+/// caller measured of the host.
+pub(crate) fn detect(accel: Option<&dyn effectcraft_render::Accelerator>, host: &Host) -> Hardware {
     let gpu = accel.map(|a| {
         let info = a.adapter_info().unwrap_or_default();
-        let vram_bytes = dedicated_vram(info.vendor, &info.name);
+        let vram_bytes = if info.vendor == 0x10de { host.nvidia_vram_bytes.or(host.other_vram_bytes) } else { host.other_vram_bytes };
         // Apple silicon and integrated GPUs share system memory.
         let unified = info.device_type == "IntegratedGpu" || info.name.starts_with("Apple");
         GpuHw {
@@ -19,110 +22,5 @@ pub(crate) fn detect(accel: Option<&dyn effectcraft_render::Accelerator>) -> Har
             native: !effectcraft_render::passes::is_deferred(Some(a)),
         }
     });
-    let (ram_bytes, avail_ram_bytes) = memory();
-    Hardware { gpu, threads: rayon::current_num_threads(), ram_bytes, avail_ram_bytes, core_kinds: core_kinds() }
-}
-
-/// `sysctl -n NAME` (macOS), parsed.
-#[cfg(target_os = "macos")]
-fn sysctl(name: &str) -> Option<u64> {
-    let out = std::process::Command::new("/usr/sbin/sysctl").args(["-n", name]).output().ok()?;
-    String::from_utf8_lossy(&out.stdout).trim().parse().ok()
-}
-
-/// Physical memory and memory available now (free + inactive + speculative + purgeable pages on
-/// macOS, `MemAvailable` on Linux); `None` where not queried.
-fn memory() -> (Option<u64>, Option<u64>) {
-    #[cfg(target_os = "macos")]
-    {
-        let total = sysctl("hw.memsize");
-        let avail = std::process::Command::new("/usr/bin/vm_stat").output().ok().and_then(|o| {
-            let text = String::from_utf8_lossy(&o.stdout).into_owned();
-            let page = text.split("page size of ").nth(1)?.split_whitespace().next()?.parse::<u64>().ok()?;
-            let pages = |key: &str| {
-                text.lines()
-                    .find(|l| l.starts_with(key))
-                    .and_then(|l| l.rsplit(':').next())
-                    .and_then(|v| v.trim().trim_end_matches('.').parse::<u64>().ok())
-                    .unwrap_or(0)
-            };
-            let n = pages("Pages free") + pages("Pages inactive") + pages("Pages speculative") + pages("Pages purgeable");
-            Some(n.saturating_mul(page))
-        });
-        (total, avail)
-    }
-    #[cfg(target_os = "linux")]
-    {
-        let Ok(m) = std::fs::read_to_string("/proc/meminfo") else { return (None, None) };
-        let kb =
-            |key: &str| m.lines().find(|l| l.starts_with(key)).and_then(|l| l.split_whitespace().nth(1)).and_then(|v| v.parse::<u64>().ok()).map(|v| v * 1024);
-        (kb("MemTotal:"), kb("MemAvailable:"))
-    }
-    #[cfg(windows)]
-    {
-        // No platform calls (the workspace has no `unsafe`): ask CIM through PowerShell, in KB.
-        let out = std::process::Command::new("powershell.exe")
-            .args([
-                "-NoProfile",
-                "-NonInteractive",
-                "-Command",
-                "$o = Get-CimInstance Win32_OperatingSystem; \"$($o.TotalVisibleMemorySize) $($o.FreePhysicalMemory)\"",
-            ])
-            .output();
-        let Ok(out) = out else { return (None, None) };
-        let text = String::from_utf8_lossy(&out.stdout).into_owned();
-        let mut kb = text.split_whitespace().map(|v| v.parse::<u64>().ok().map(|v| v * 1024));
-        (kb.next().flatten(), kb.next().flatten())
-    }
-    #[cfg(not(any(target_os = "macos", target_os = "linux", windows)))]
-    {
-        (None, None)
-    }
-}
-
-/// Performance and efficiency cores (Apple silicon's `hw.perflevel0/1`); `None` elsewhere.
-fn core_kinds() -> Option<(usize, usize)> {
-    #[cfg(target_os = "macos")]
-    {
-        let p = sysctl("hw.perflevel0.logicalcpu")? as usize;
-        let e = sysctl("hw.perflevel1.logicalcpu").unwrap_or(0) as usize;
-        Some((p, e))
-    }
-    #[cfg(not(target_os = "macos"))]
-    {
-        None
-    }
-}
-
-/// Dedicated VRAM of the adapter; `None` = unknown (the tuning then plans with a conservative
-/// budget, or `vram-budget-mb`). Linux: sysfs (amdgpu reports it; NVIDIA's proprietary driver
-/// and Intel do not). NVIDIA (Windows and Linux): `nvidia-smi`, which ships with the driver.
-/// No platform calls: the workspace has no `unsafe`.
-fn dedicated_vram(vendor: u32, _name: &str) -> Option<u64> {
-    if vendor == 0x10de
-        && let Some(mb) = nvidia_smi_vram_mb()
-    {
-        return Some(mb << 20);
-    }
-    #[cfg(target_os = "linux")]
-    {
-        let dir = std::fs::read_dir("/sys/class/drm").ok()?;
-        dir.filter_map(|e| e.ok())
-            .filter_map(|e| std::fs::read_to_string(e.path().join("device/mem_info_vram_total")).ok())
-            .filter_map(|t| t.trim().parse::<u64>().ok())
-            .max()
-    }
-    #[cfg(not(target_os = "linux"))]
-    {
-        None
-    }
-}
-
-/// Total memory of the largest NVIDIA GPU in MB, from `nvidia-smi`; `None` without it.
-fn nvidia_smi_vram_mb() -> Option<u64> {
-    let out = std::process::Command::new("nvidia-smi").args(["--query-gpu=memory.total", "--format=csv,noheader,nounits"]).output().ok()?;
-    if !out.status.success() {
-        return None;
-    }
-    String::from_utf8_lossy(&out.stdout).lines().filter_map(|l| l.trim().parse::<u64>().ok()).max()
+    Hardware { gpu, threads: rayon::current_num_threads(), ram_bytes: host.ram_bytes, avail_ram_bytes: host.avail_ram_bytes, core_kinds: host.core_kinds }
 }
diff --git a/crates/export/src/pipeline.rs b/crates/export/src/pipeline.rs
index 7a5a0374cd..b2e93077fb 100644
--- a/crates/export/src/pipeline.rs
+++ b/crates/export/src/pipeline.rs
@@ -1122,13 +1122,12 @@ fn export_cache(mb: usize) -> Option<effectcraft_render::LayerCache> {
 
 /// Resolve the export options for `job` (CLI > environment > config > auto, see [`crate::tuning`]).
 fn resolve_tuning(job: &Job, project: &Project) -> crate::tuning::ExportTuning {
-    use crate::tuning::{Overrides, Source, request, resolve};
-    let hw = crate::hw::detect(job.accel);
-    let frame = project.comp(job.comp).map(|c| crate::output_size(c, job.settings, job.output)).unwrap_or((1920, 1080));
+    use crate::tuning::{Source, request, resolve};
     let req = request();
-    let env = Overrides::from_env();
+    let hw = crate::hw::detect(job.accel, &req.host);
+    let frame = project.comp(job.comp).map(|c| crate::output_size(c, job.settings, job.output)).unwrap_or((1920, 1080));
     let cfg = req.config.clone().unwrap_or_default();
-    resolve(&hw, frame, [(&req.cli, Source::Cli), (&env, Source::Env), (&cfg, Source::Config)])
+    resolve(&hw, frame, [(&req.cli, Source::Cli), (&req.env, Source::Env), (&cfg, Source::Config)])
 }
 
 /// Device-side H.264 input for a GPU worker ([`Cx::stream`]): the accelerator renders the frame,
diff --git a/crates/export/src/tuning.rs b/crates/export/src/tuning.rs
index 161dbdde51..eb143f59bd 100644
--- a/crates/export/src/tuning.rs
+++ b/crates/export/src/tuning.rs
@@ -9,7 +9,8 @@
 //! | `--gpu-inflight 3` | `EFFECTCRAFT_EXPORT_GPU_INFLIGHT=3`  | `gpu-inflight = 3`|
 //!
 //! The config file is `--tuning-config FILE` or `EFFECTCRAFT_EXPORT_CONFIG=FILE` (`key = value`
-//! lines, `#` comments). `auto` (or no value anywhere) lets [`resolve`] decide from the
+//! lines, `#` comments). The caller (the CLI) reads the environment, the config file and the
+//! host facts and passes them in a [`Request`]; this crate probes and reads nothing itself. `auto` (or no value anywhere) lets [`resolve`] decide from the
 //! [`Hardware`]: GPU presence, adapter limits, VRAM (or a conservative guess), core count;
 //! [`ExportTuning::explain`] says what it chose and why (`--print-tuning`).
 //!
@@ -103,11 +104,8 @@ impl Overrides {
         Ok(())
     }
 
-    /// The `EFFECTCRAFT_EXPORT_*` variables (invalid values are logged and ignored).
-    pub fn from_env() -> Overrides {
-        Overrides::from_lookup(|k| std::env::var(k).ok())
-    }
-
+    /// The `EFFECTCRAFT_EXPORT_*` variables as `get` returns them (the CLI passes the process
+    /// environment; invalid values are logged and ignored).
     pub fn from_lookup(get: impl Fn(&str) -> Option<String>) -> Overrides {
         let mut o = Overrides::default();
         for (key, _) in OPTIONS {
@@ -145,7 +143,11 @@ pub fn env_name(key: &str) -> String {
 #[derive(Clone, Debug, Default)]
 pub struct Request {
     pub cli: Overrides,
+    /// The `EFFECTCRAFT_EXPORT_*` variables ([`Overrides::from_lookup`]).
+    pub env: Overrides,
     pub config: Option<Overrides>,
+    /// What the caller measured of the host; the library probes nothing itself.
+    pub host: Host,
     /// `--print-tuning`: resolve, print, render nothing.
     pub print_only: bool,
 }
@@ -158,16 +160,22 @@ pub fn set_request(r: Request) {
 }
 
 pub(crate) fn request() -> Request {
-    let mut r = REQUEST.lock().unwrap_or_else(|e| e.into_inner()).clone().unwrap_or_default();
-    if r.config.is_none()
-        && let Ok(path) = std::env::var("EFFECTCRAFT_EXPORT_CONFIG")
-    {
-        match std::fs::read_to_string(&path).map_err(|e| e.to_string()).and_then(|t| Overrides::from_config(&t)) {
-            Ok(c) => r.config = Some(c),
-            Err(e) => log::warn!(target: "effectcraft_export", "EFFECTCRAFT_EXPORT_CONFIG {path}: {e} (ignored)"),
-        }
-    }
-    r
+    REQUEST.lock().unwrap_or_else(|e| e.into_inner()).clone().unwrap_or_default()
+}
+
+/// Host facts the caller measured (the CLI: `/proc/meminfo`, `sysctl`/`vm_stat`, CIM,
+/// `nvidia-smi`, sysfs). `None` = unknown: the tuning then plans conservatively.
+#[derive(Clone, Debug, Default, PartialEq)]
+pub struct Host {
+    /// Physical memory and memory available now (free + reclaimable).
+    pub ram_bytes: Option<u64>,
+    pub avail_ram_bytes: Option<u64>,
+    /// Performance / efficiency logical cores (Apple silicon, hybrid CPUs).
+    pub core_kinds: Option<(usize, usize)>,
+    /// Dedicated VRAM of the largest NVIDIA GPU (`nvidia-smi`), used for an NVIDIA adapter.
+    pub nvidia_vram_bytes: Option<u64>,
+    /// Dedicated VRAM another way (Linux sysfs, amdgpu), used for other adapters.
+    pub other_vram_bytes: Option<u64>,
 }
 
 /// The machine an export plans for.

From 97bd5380f8b7ad97364c93de64196fd4e21d5de8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Matej=20Kozlovsk=C3=BD?=
 <100806068+MatejKozlovsky@users.noreply.github.com>
Date: Tue, 13 Oct 2026 23:26:01 +0200
Subject: [PATCH 08/10] gpu: discard texture readbacks recorded across an
 absorbed OOM (wrong-layers fix)

---
 crates/gpu/src/context.rs | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/crates/gpu/src/context.rs b/crates/gpu/src/context.rs
index ab967ce56f..249617f11d 100644
--- a/crates/gpu/src/context.rs
+++ b/crates/gpu/src/context.rs
@@ -1243,6 +1243,7 @@ impl<'g> Enc<'g> {
         if !self.g.can_wait() {
             return None;
         }
+        let oom = self.g.readbacks.1.count();
         self.g.transfers.count(false, out.len());
         let layout =
             crate::readback::Layout::new(w, h, bpp, self.g.device.limits().max_buffer_size).map_err(|e| log::error!("gpu texture readback: {e}")).ok()?;
@@ -1268,6 +1269,12 @@ impl<'g> Enc<'g> {
         );
         self.submit();
         let bytes = self.g.read_buffer(&buf, row, padded as usize, h as usize).map_err(|e| log::error!("gpu texture readback: {e}")).ok()?;
+        // An absorbed OOM means the copy above (or the work that filled `texture`) may not
+        // have run: a reused staging buffer then still holds an earlier readback's pixels.
+        if self.g.readbacks.1.count() != oom {
+            log::warn!("gpu texture readback discarded: device ran out of memory while it was recorded");
+            return None;
+        }
         if bytes.len() != out.len() {
             log::error!("gpu texture readback size mismatch");
             return None;

From 67fd447cb3ecfee54626593dd78ee8d7b3e63774 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Matej=20Kozlovsk=C3=BD?=
 <100806068+MatejKozlovsky@users.noreply.github.com>
Date: Tue, 13 Oct 2026 23:40:08 +0200
Subject: [PATCH 09/10] gpu: count validation errors absorbed while tainted, so
 the frame that hit them is declined

---
 crates/gpu/src/readback.rs | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/crates/gpu/src/readback.rs b/crates/gpu/src/readback.rs
index 8a289a70eb..ddf94f84e2 100644
--- a/crates/gpu/src/readback.rs
+++ b/crates/gpu/src/readback.rs
@@ -87,7 +87,12 @@ impl Oom {
                 self.tainted.store(true, SeqCst);
                 OnError::Absorb
             }
-            ErrorKind::Validation if self.tainted.load(SeqCst) => OnError::Absorb,
+            ErrorKind::Validation if self.tainted.load(SeqCst) => {
+                // Still invalidates whatever frame recorded it (it may be a frame that started
+                // after the failed allocation, on another thread): count it, or that frame is kept.
+                self.count.fetch_add(1, SeqCst);
+                OnError::Absorb
+            }
             ErrorKind::Validation => OnError::Retire,
         }
     }

From 94bb28b8dd3c5a28cfeb59d71afbf2aee2c3446d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Matej=20Kozlovsk=C3=BD?=
 <100806068+MatejKozlovsky@users.noreply.github.com>
Date: Tue, 13 Oct 2026 23:46:09 +0200
Subject: [PATCH 10/10] gpu: test that validation errors after an absorbed OOM
 invalidate later readbacks

---
 crates/gpu/src/readback.rs | 28 ++++++++++++++++++++++++----
 1 file changed, 24 insertions(+), 4 deletions(-)

diff --git a/crates/gpu/src/readback.rs b/crates/gpu/src/readback.rs
index ddf94f84e2..0e7a666752 100644
--- a/crates/gpu/src/readback.rs
+++ b/crates/gpu/src/readback.rs
@@ -636,16 +636,36 @@ mod oom_tests {
         assert_eq!(o.on_error(ErrorKind::Validation), OnError::Retire);
         let before = o.count();
         assert_eq!(o.on_error(ErrorKind::OutOfMemory), OnError::Absorb);
-        // The invalid resources it left fail validation: absorbed until the frame is declined.
+        // The invalid resources it left fail validation: absorbed until the frame is declined,
+        // and counted, so work recorded after the failed allocation sees it too.
         assert_eq!(o.on_error(ErrorKind::Validation), OnError::Absorb);
-        assert_eq!(o.count(), before + 1);
+        assert_eq!(o.count(), before + 2);
         o.settle();
         assert_eq!(o.on_error(ErrorKind::Validation), OnError::Retire);
         // Drivers that report a failed allocation as an internal error count too.
         assert_eq!(o.on_error(ErrorKind::Internal), OnError::Absorb);
-        assert_eq!(o.count(), before + 2);
+        assert_eq!(o.count(), before + 3);
         drop(armed);
         assert_eq!(o.on_error(ErrorKind::OutOfMemory), OnError::Retire);
-        assert_eq!(o.count(), before + 2);
+        assert_eq!(o.count(), before + 3);
+    }
+
+    /// The wrong-layers bug: a readback that starts after the failed allocation (a layer the
+    /// frame renders on the CPU, its effect chain run on the GPU) only sees the validation
+    /// errors of the invalid resources. They must change the count, or the readback returns a
+    /// reused staging buffer's earlier pixels and they reach the layer cache.
+    #[test]
+    fn validation_after_a_failed_allocation_invalidates_later_readbacks() {
+        let o = Oom::default();
+        let _armed = o.arm();
+        assert_eq!(o.on_error(ErrorKind::OutOfMemory), OnError::Absorb);
+        let readback_start = o.count();
+        assert_eq!(o.on_error(ErrorKind::Validation), OnError::Absorb);
+        assert_ne!(o.count(), readback_start, "the readback would be kept");
+        // Once the declined frame settled, validation errors retire the device and no longer count.
+        o.settle();
+        let after = o.count();
+        assert_eq!(o.on_error(ErrorKind::Validation), OnError::Retire);
+        assert_eq!(o.count(), after);
     }
 }