EffectCraft: An open-source motion graphics and compositing tool written by scratch in pure Rust
Merge remote-tracking branch 'origin/main' into fix/947-preview-opening-audio
tylerjenningsw2dcd1b27a9b1
diff --cc crates/ui-egui/src/app/playback.rsindex 000000000,912a196f8..d40bc69ffmode 000000,100644..100644--- a/crates/ui-egui/src/app/playback.rs+++ b/crates/ui-egui/src/app/playback.rs@@@ -1,0 -1,186 +1,192 @@@+ use super::*;++ impl EffectcraftApp {+ // ---------------------------------------------------------------- playback++ pub fn play(&mut self, now: f64) {+ let sc = self.session.prefs.preview.current;+ self.play_with(now, sc);+ }++ /// Start the preview of a Preview panel shortcut (its range, play-from, rate, skip,+ /// resolution, loop, caching, full screen and include options).+ pub fn play_with(&mut self, now: f64, sc: effectcraft_engine::preview::PreviewShortcut) {+ let Some(c) = self.session.active_comp_arc() else { return };+ let preset = self.session.prefs.preview.get(sc).clone();+ let plan = effectcraft_engine::preview::plan(&preset, &c, self.session.time());+ let fr = c.frame_rate;+ if plan.video {+ self.session.set_time(fr.tick_of(plan.first));+ }+ let restore_max = preset.full_screen.then_some(self.ui.maximized);+ let viewer = panels::viewers::active_panel(self);+ if preset.full_screen && self.ui.dock.is_docked(viewer) {+ self.ui.maximized = Some(viewer);+ }+ self.playback = Playback {+ playing: true,+ start_wall: now,+ start_time: fr.tick_of(plan.first),+ start_frame: plan.first,+ shown: 0,+ waiting: false,+ fps: plan.fps,+ shortcut: sc,+ plan: Some(plan),+ caching: plan.cache_first && plan.video,+ res: preset.resolution.factor(preset.custom_resolution),+ overlays: preset.include_overlays,+ layer_controls: preset.include_layer_controls,+ restore_max,+ audio_frame: (!plan.video).then_some(plan.first),+ audio_held: false,++ starting: false,++ starting_since: now,++ first_cached: None,+ shown_at: Default::default(),+ };+ if !self.playback.caching {+ if plan.video {- self.playback.audio_held = self.audio_plays();++ let audible = self.audio_plays();++ self.playback.audio_held = audible;++ self.playback.starting = audible;+ } else {+ self.start_audio(fr.tick_of(plan.first));+ }+ }+ }++ /// The preview includes audio at the comp's frame rate and the comp has something audible.+ fn audio_plays(&self) -> bool {+ let (Some(pl), Some(cid)) = (self.playback.plan, self.session.active_comp_id()) else { return false };+ let Some(c) = self.session.project.comp(cid) else { return false };+ // A preview at another frame rate plays slower or faster than real time: silent.+ pl.audio && (pl.fps - c.frame_rate.as_f64()).abs() <= 0.01 && effectcraft_engine::render::audio::comp_has_audio(&self.session.project, cid)+ }++ /// Start audio preview from comp time `t` when [`Self::audio_plays`] and an output device+ /// opens.+ pub(super) fn start_audio(&mut self, t: Tick) {+ self.audio = None;+ self.meter.clipped = [false; 2];+ let (Some(pl), Some(cid)) = (self.playback.plan, self.session.active_comp_id()) else { return };+ let Some(c) = self.session.project.comp_arc(cid).filter(|_| self.audio_plays()) else { return };+ let out = audio::AudioOutput::from_prefs(&self.session.prefs);+ let Some(dev) = self.hooks.audio_device.as_ref().and_then(|f| f(&out)) else { return };+ let mix = self.session.prefs.audio.preview_sample_rate;+ let fr = c.frame_rate;+ match audio::AudioPlayback::start(dev, self.render_source(), cid, t, fr.tick_of(pl.start), fr.tick_of(pl.end + 1), pl.looping, mix) {+ Ok(a) => self.audio = Some(a),+ Err(e) => log::warn!("audio preview: {e}"),+ }+ }++ /// Audio scrubbing: play the frame of `comp` at `t` (see [`audio::AudioScrub`]), opening the+ /// output on first use. Silent comps and missing devices do nothing.+ pub fn scrub_audio(&mut self, comp: ItemId, t: Tick, now: f64) {+ if self.playback.playing || !effectcraft_engine::render::audio::comp_has_audio(&self.session.project, comp) {+ return;+ }+ if self.scrub.is_none() {+ let out = audio::AudioOutput::from_prefs(&self.session.prefs);+ let Some(dev) = self.hooks.audio_device.as_ref().and_then(|f| f(&out)) else { return };+ match audio::AudioScrub::open(dev, now) {+ Ok(s) => self.scrub = Some(s),+ Err(e) => {+ log::warn!("audio scrubbing: {e}");+ return;+ }+ }+ }+ let src = self.render_source();+ let mix = self.session.prefs.audio.preview_sample_rate;+ if let Some(s) = &mut self.scrub {+ s.play(&src, comp, t, mix, now);+ }+ }++ pub fn stop(&mut self) {+ let was = std::mem::replace(&mut self.playback.playing, false);+ self.audio = None;+ self.playback.caching = false;++ self.playback.starting = false;+ if !was {+ return;+ }+ if let Some(m) = self.playback.restore_max.take() {+ self.ui.maximized = m;+ }+ let Some(pl) = self.playback.plan else { return };+ let move_time = self.session.prefs.preview.get(self.playback.shortcut).move_time_to_preview_time;+ if !move_time {+ self.session.set_time(pl.origin);+ } else if let Some(f) = self.playback.audio_frame+ && let Some(c) = self.session.active_comp()+ {+ let t = c.frame_rate.tick_of(f);+ self.session.set_time(t);+ }+ }++ pub fn toggle_play(&mut self, now: f64) {+ let sc = self.session.prefs.preview.current;+ self.toggle_play_with(now, sc);+ }++ /// A preview shortcut pressed: start its preview, or stop the running one. While Cache+ /// Before Playback is still rendering, "If caching, play cached frames" plays what is+ /// cached so far instead of stopping.+ pub fn toggle_play_with(&mut self, now: f64, sc: effectcraft_engine::preview::PreviewShortcut) {+ if !self.playback.playing {+ self.play_with(now, sc);+ return;+ }+ if self.playback.caching && self.session.prefs.preview.get(self.playback.shortcut).play_cached_frames && self.play_cached(now) {+ return;+ }+ self.stop();+ }++ /// Cut the caching preview down to the frames cached from its first frame on and play them.+ fn play_cached(&mut self, now: f64) -> bool {+ let (Some(mut pl), Some(cid)) = (self.playback.plan, self.session.active_comp_id()) else { return false };+ let scale = self.viewer_shown.as_ref().map(|(_, k)| k.scale as f64 / 1000.0).unwrap_or(1.0);+ let series = self.frame_series(cid, scale);+ let mut last = None;+ let mut f = pl.first;+ while f <= pl.end && self.frames.is_cached(&FrameKey { frame: f, ..series }) {+ last = Some(f);+ f += pl.step;+ }+ let Some(last) = last else { return false };+ pl.end = last;+ pl.start = pl.first;+ self.playback.plan = Some(pl);+ self.playback.caching = false;+ self.playback.start_wall = now;+ self.playback.start_frame = pl.first;+ let t = self.session.active_comp().map(|c| c.frame_rate.tick_of(pl.first)).unwrap_or_default();+ self.start_audio(t);+ true+ }++ /// A preview plays with Video off in the Preview panel (audio only): the current time stays+ /// put, so the viewer and Timeline say so instead of looking stuck (#1118). The frame under+ /// the audible sample, when one is known.+ pub fn video_preview_off(&self) -> Option<Option<i64>> {+ let p = self.playback.plan.filter(|_| self.playback.playing)?;+ (!p.video).then_some(self.playback.audio_frame)+ }++ /// The viewer shows grids, guides and safe margins (hidden while a preview without+ /// Include Overlays plays).+ pub fn overlays_visible(&self) -> bool {+ !self.playback.playing || self.playback.overlays+ }++ /// The viewer shows layer handles and paths (View ▸ Show Layer Controls, and Include Layer+ /// Controls while a preview plays).+ pub fn layer_controls_visible(&self) -> bool {+ self.ui.viewer.show_layer_controls && (!self.playback.playing || self.playback.layer_controls)+ }+ }diff --cc crates/ui-egui/src/app/prefetch.rsindex 000000000,b55884117..aea6d14a6mode 000000,100644..100644--- a/crates/ui-egui/src/app/prefetch.rs+++ b/crates/ui-egui/src/app/prefetch.rs@@@ -1,0 -1,381 +1,482 @@@+ use super::*;++ /// Seconds without a project change before paused prefetch resumes (see+ /// [`EffectcraftApp::editing`]).+ const EDIT_QUIET: f64 = 0.3;+++/// Longest a preview with sound holds its first frame, once that frame is cached, waiting for the++/// frames ahead (seconds, #947). A frame ahead that never gets cached mustn't hold it for ever:++/// the sound starts from the first frame anyway, and the preview goes on as a stalled one does.++const STARTUP_WAIT: f64 = 2.0;++++/// Longest a preview with sound holds its first frame in all (seconds, #947). The first frame++/// itself can take a while (a heavy comp, a busy machine), and [`STARTUP_WAIT`] counts only from++/// when it is cached; but one that never gets cached (larger than the RAM preview, which the size++/// estimate can't always tell) mustn't hold it for ever. The preview then goes on as a stalled++/// one does: its sound starts once the frames are cached.++const STARTUP_LIMIT: f64 = 10.0;++++/// How many frames from the first a preview with sound waits for before it starts (#947): the++/// prefetch's `ahead`, but no more than its `window` requests from the current frame (offsets++/// `0..window`), and no more than fit in the RAM preview `budget` (90 %, as for the prefetch) at++/// `frame_bytes`, the size frames really render at; at least the current frame, which the viewer++/// always requests. Waiting for a frame that is never requested, or that can't stay cached with++/// the others, would hold the first frame for ever.++fn startup_frames(ahead: i64, window: i64, budget: usize, frame_bytes: usize) -> i64 {++ let fit = (budget as f64 * 0.9 / frame_bytes.max(1) as f64) as i64;++ ahead.min(window).min(fit).max(1)++}+++ impl EffectcraftApp {+ /// RAM preview: advance at the preview's frame rate when frames are cached; otherwise hold+ /// and keep rendering ahead (the green cache bar fills, then playback runs in real time).+ pub(super) fn advance_playback(&mut self, ctx: &egui::Context, scale: f64, now: f64, input_active: bool, cid: ItemId) {+ let Some(c) = self.session.project.comp_arc(cid) else { return };+ let fr = c.frame_rate;+ let plan = self.playback.plan.filter(|_| self.playback.playing);+ let (wa, wb) = match plan {+ Some(p) => (p.start, p.end),+ None => (fr.frame_at(c.work_area.0), fr.frame_at(c.work_area.1 - c.frame_duration())),+ };+ let looping = plan.is_none_or(|p| p.looping);+ let video = plan.is_none_or(|p| p.video);+ // Prefetch ahead.+ let cur = fr.frame_at(self.session.time());+ let ahead = self.prefetch_ahead(ctx, now);+ let queued = self.frames.inflight();+ let series = self.frame_series(cid, scale);+ // The preview's position orders prefetch and eviction (#595).+ let playhead = plan.filter(|p| p.video).map(|p| frames::Playhead { series, cur, start: p.start, end: p.end, step: p.step, looping: p.looping });+ self.frames.set_playhead(playhead);+ let pass = PlaybackPass {+ ctx,+ comp: &c,+ cid,+ scale,+ now,+ frame_rate: fr,+ series,+ plan,+ window: FrameWindow { first: wa, last: wb },+ cur,+ video,+ looping,+ ahead,+ queued,+ };+ if self.cache_preview(&pass) {+ return;+ }+ let step = plan.map_or(1, |p| p.step);+ let fit_ahead = self.frames_that_fit(&c, scale) - 1;+ self.prefetch_playback(&pass, fit_ahead);+ self.pump_meters(ctx, now);+ if !self.playback.playing {+ self.cache_when_idle(ctx, &c, &series, now, input_active, (wa, wb));+ return;+ }+ let fit = self.frames_that_fit(&c, scale);++ if self.hold_first_frame(&pass, fit) {++ return;++ }+ self.start_held_audio(&pass, fit);+ if self.advance_audio_clock(&pass, step) {+ return;+ }+ self.advance_frame_clock(&pass, step);+ }++ /// While paused (scrubbing, editing) the viewer's frame comes first: prefetch only a few+ /// frames, only once it is done, and not while edits keep coming (a layer dragged in the+ /// viewer): those frames would be stale at the next step and would hold the CPU and GPU+ /// the next viewer frame needs.+ fn prefetch_ahead(&mut self, ctx: &egui::Context, now: f64) -> i64 {+ if self.playback.playing {+ (self.frames_parallelism() * 2).max(4) as i64+ } else if self.frames.urgent_pending() {+ 0+ } else if let Some(wait) = self.editing(now) {+ ctx.request_repaint_after(std::time::Duration::from_secs_f64(wait));+ 0+ } else {+ // Keep workers available for a newly edited viewer frame. Running obsolete+ // background renders cannot be preempted by the priority queue.+ self.frames_parallelism().saturating_sub(1).min(2) as i64+ }+ }++ /// Cache Before Playback: the range in play order, then start the clock. A range larger than+ /// the RAM preview budget is cut to the frames that fit (caching more would evict the first+ /// ones and never finish). Returns true when this pass handled the preview.+ fn cache_preview(&mut self, pass: &PlaybackPass<'_>) -> bool {+ let PlaybackPass { ctx, comp, cid, scale, now, frame_rate: fr, series, plan, ahead, mut queued, .. } = *pass;+ if !self.playback.caching {+ return false;+ }+ let Some(p) = plan else { return false };+ let mut all = true;+ let n = (p.end - p.start) / p.step + 1;+ let fit = self.frames_that_fit(comp, scale);+ if n > fit {+ let mut cut = p;+ (cut.start, cut.end) = (p.first, (p.first + (fit - 1) * p.step).min(p.end));+ self.playback.plan = Some(cut);+ self.toast = Some((format!("Preview cut to {fit} of {n} frames: no more fit in the RAM preview (Settings ▸ Memory & CPU)"), now));+ ctx.request_repaint();+ return true;+ }+ let order: Vec<i64> = (0..n).filter_map(|k| p.frame_after(p.first, k)).collect();+ for f in order {+ if self.frames.is_cached(&FrameKey { frame: f, ..series }) {+ continue;+ }+ all = false;+ if queued < ahead as usize {+ self.request_frame(cid, f, scale);+ queued += 1;+ }+ }+ self.playback.waiting = !all;+ if all {+ self.playback.caching = false;+ self.playback.start_wall = now;+ self.playback.start_frame = p.first;+ self.session.set_time(fr.tick_of(p.first));+ self.start_audio(fr.tick_of(p.first));+ }+ ctx.request_repaint();+ true+ }++ /// Never further ahead than the RAM preview holds: those frames would evict the ones the+ /// preview shows first, or be evicted before it gets there (#595). The window starts at the+ /// first uncached frame ahead: after a loop or a restart the frames just ahead are cached,+ /// and a window from the playhead left the workers idle until it came near the end of the+ /// cached run. It stays ahead × 3 frames wide: workers spread over the whole preview render+ /// frames with different layers at once (on the GPU, an atlas each: #1812).+ fn prefetch_playback(&self, pass: &PlaybackPass<'_>, fit_ahead: i64) {+ let PlaybackPass { cid, scale, plan, cur, ahead, series, mut queued, video, .. } = *pass;+ let FrameWindow { first: wa, last: wb } = pass.window;+ let frame = |k: i64| match plan {+ Some(p) => p.frame_after(cur, k),+ None => {+ let f = cur + k;+ Some(if f > wb { wa + (f - wb - 1).rem_euclid((wb - wa + 1).max(1)) } else { f })+ }+ };+ let cached = self.frames.cached_frames(&series);+ let uncached = |f: i64| cached.binary_search(&f).is_err();+ let first = match plan.filter(|_| self.playback.playing) {+ Some(p) => (0..fit_ahead.min((p.end - p.start) / p.step.max(1) + 1))+ .map_while(|k| frame(k).map(|f| (k, f)))+ .find(|&(_, f)| uncached(f))+ .map_or(0, |(k, _)| k),+ None => 0,+ };+ for k in first..(first + ahead * 3).min(fit_ahead) {+ if queued >= ahead as usize || !video {+ break;+ }+ let Some(f) = frame(k) else { break };+ if uncached(f) {+ self.request_frame(cid, f, scale);+ queued += 1;+ }+ }+ }++ /// Advance the audio or scrub output and feed its latest peaks to the level meter; an idle scrub is closed after+ /// one second. With no source but an active meter, drive the meter to silence and request a repaint.+ fn pump_meters(&mut self, ctx: &egui::Context, now: f64) {+ if let Some(a) = &mut self.audio {+ a.pump();+ self.meter.update(a.feed.take_peaks(), now);+ } else if let Some(s) = &mut self.scrub {+ // Scrubbing: the meters follow the snippets; an idle second closes the output.+ s.pump();+ self.meter.update(s.feed.take_peaks(), now);+ if now - s.last_used > 1.0 {+ self.scrub = None;+ }+ ctx.request_repaint_after(std::time::Duration::from_millis(50));+ } else if self.meter.active() {+ self.meter.update([0.0; 2], now);+ ctx.request_repaint();+ }+ }+- /// Held sound starts once the frames ahead are cached (see `Playback::audio_held`): the- /// prefetch window when the silent preview keeps real time, else the rest of the preview.++ /// Starting a preview with sound: hold the first frame until the frames ahead are cached, then++ /// start the sound from that same frame (see `Playback::starting`). Without an output device++ /// the picture plays on its own clock from it. How many frames ahead: only ones++ /// `prefetch_playback` requests and that fit in the RAM preview at the size they really render++ /// (an Extended Viewer frame is larger than the comp), so the wait always ends. Returns true++ /// while it holds the first frame.++ fn hold_first_frame(&mut self, pass: &PlaybackPass<'_>, fit: i64) -> bool {++ let PlaybackPass { ctx, comp, scale, now, plan, series, cur, ahead, frame_rate: fr, .. } = *pass;++ if !self.playback.starting {++ return false;++ }++ let Some(p) = plan else { return false };++ self.playback.start_wall = now;++ self.playback.start_frame = cur;++ // `prefetch_playback` requests every uncached frame of offsets 0..window from here.++ let window = (ahead * 3).min(fit - 1);++ let need = self.frames.get(&FrameKey { frame: cur, ..series }).map(|img| {++ let [w, h] = img.size();++ startup_frames(ahead, window, self.frames.budget(), w.saturating_mul(h).saturating_mul(4))++ });++ if need.is_some() && self.playback.first_cached.is_none() {++ self.playback.first_cached = Some(now);++ }++ // Don't wait for frames the RAM preview can't hold (not even one frame fits), for the++ // frames ahead longer than STARTUP_WAIT once the first is in, nor longer than++ // STARTUP_LIMIT in all (a frame that never gets cached).++ let give_up = (self.frames.budget() as f64) < self.frame_bytes(comp, scale)++ || self.playback.first_cached.is_some_and(|t| now - t >= STARTUP_WAIT)++ || now - self.playback.starting_since >= STARTUP_LIMIT;++ if !give_up && !need.is_some_and(|n| self.cached_ahead(&p, &series, cur, n)) {++ self.playback.waiting = true;++ ctx.request_repaint();++ return true;++ }++ self.playback.starting = false;++ self.playback.waiting = false;++ // Not on a frame that isn't cached: the stall below would stop the sound at once. The++ // preview goes on as a stalled one does, and the sound starts once frames are cached.++ if need.is_some() {++ self.playback.audio_held = false;++ self.start_audio(fr.tick_of(cur));++ }++ false++ }++++ /// Held sound starts once the frames ahead are cached again after a stall (see++ /// `Playback::audio_held`): the prefetch window when the silent preview keeps real time, else++ /// the rest of the preview.+ fn start_held_audio(&mut self, pass: &PlaybackPass<'_>, fit: i64) {+ let PlaybackPass { now, plan, series, cur, ahead, frame_rate: fr, .. } = *pass;+ if !self.playback.audio_held {+ return;+ }+ let Some(p) = plan else { return };+ if (self.playback.keeps_up(now) && self.cached_ahead(&p, &series, cur, ahead.min(fit))) || self.cached_ahead(&p, &series, cur, fit) {+ self.playback.audio_held = false;+ self.playback.start_wall = now;+ self.playback.start_frame = cur;+ self.start_audio(fr.tick_of(cur));+ }+ }++ /// Audio clock drives playback: show the frame under the audible sample. Returns true when+ /// the audio path handled this pass (including stopping at the end).+ fn advance_audio_clock(&mut self, pass: &PlaybackPass<'_>, step: i64) -> bool {+ let PlaybackPass { ctx, now, series, video, frame_rate: fr, cur, .. } = *pass;+ let FrameWindow { first: wa, last: wb } = pass.window;+ let Some(a) = &self.audio else { return false };+ if a.finished() {+ if video {+ self.session.set_time(fr.tick_of(wb));+ } else {+ self.playback.audio_frame = Some(wb);+ }+ self.stop();+ return true;+ }+ let snap = |f: i64| wa + (f - wa).div_euclid(step) * step;+ let target = snap(audio::frame_of_sample(a.clock(), a.rate, fr).clamp(wa, wb));+ if !video {+ self.playback.audio_frame = Some(target);+ } else if self.frames.is_cached(&FrameKey { frame: target, ..series }) {+ self.playback.waiting = false;+ if target != cur {+ self.session.set_time(fr.tick_of(target));+ self.playback.frame_shown(now);+ }+ } else {+ // Rendering can't keep up: rather than skip frames, the sound stops and every+ // frame shows as it renders until the frames ahead are cached again.+ self.audio = None;+ self.playback.audio_held = true;+ self.playback.waiting = true;+ // The rate measured before the stall no longer says it keeps up.+ self.playback.shown_at.clear();+ self.playback.start_wall = now;+ self.playback.start_frame = cur;+ }+ ctx.request_repaint();+ true+ }++ /// The wall clock advances the preview when no audio device drives it, and shows the target+ /// frame (or holds when it is not cached yet).+ fn advance_frame_clock(&mut self, pass: &PlaybackPass<'_>, step: i64) {+ let PlaybackPass { ctx, now, plan, video, looping, frame_rate: fr, cur, series, .. } = *pass;+ let FrameWindow { first: wa, last: wb } = pass.window;+ let elapsed = now - self.playback.start_wall;+ // The plan carries the rate the preview was started with (and `play_with` copies it to+ // `Playback::fps`). Deriving the frame from the plan keeps a logic-only tick correct even+ // when a host/test supplies only the plan; a stale duplicate cannot hold playback open.+ let fps = plan.map_or(self.playback.fps, |p| p.fps);+ let n = ((elapsed * fps) / step as f64).floor() as i64;+ let target = match plan {+ Some(p) => p.frame_after(self.playback.start_frame, n),+ None => {+ let t = self.playback.start_frame + n;+ if t <= wb {+ Some(t)+ } else if looping {+ Some(wa + (t - wa).rem_euclid((wb - wa + 1).max(1)))+ } else {+ None+ }+ }+ };+ let Some(target) = target else {+ if video {+ self.session.set_time(fr.tick_of(wb));+ } else {+ self.playback.audio_frame = Some(wb);+ }+ self.stop();+ return;+ };+ if !video {+ // Audio-only preview without an audio device: the clock runs, the time stays.+ self.playback.audio_frame = Some(target);+ ctx.request_repaint();+ return;+ }+ if self.frames.is_cached(&FrameKey { frame: target, ..series }) {+ self.playback.waiting = false;+ if target != cur {+ self.session.set_time(fr.tick_of(target));+ self.playback.frame_shown(now);+ }+ } else {+ // Not cached yet: hold the clock at the current frame (cache first, then play).+ self.playback.waiting = true;+ let next = plan.and_then(|p| p.frame_after(cur, 1)).unwrap_or(if cur + 1 > wb { wa } else { cur + 1 });+ if self.frames.is_cached(&FrameKey { frame: next, ..series }) {+ self.session.set_time(fr.tick_of(next));+ }+ self.playback.start_wall = now;+ self.playback.start_frame = fr.frame_at(self.session.time());+ }+ ctx.request_repaint();+ }++ /// While the project keeps changing (an edit within [`EDIT_QUIET`] seconds), how long until+ /// it counts as settled.+ fn editing(&mut self, now: f64) -> Option<f64> {+ if self.last_edit.1 != self.session.revision {+ self.last_edit = (now, self.session.revision);+ }+ let left = EDIT_QUIET - (now - self.last_edit.0);+ (left > 0.0).then_some(left)+ }++ /// Composition ▸ Preview ▸ Cache Frames When Idle: after a second without input or edits,+ /// render the work area's frames (from the current time on, then from its start) in the+ /// background, a few at a time, until it is cached or the RAM preview budget is full.+ fn cache_when_idle(+ &mut self,+ ctx: &egui::Context,+ comp: &effectcraft_engine::project::Comp,+ series: &FrameKey,+ now: f64,+ input_active: bool,+ (wa, wb): (i64, i64),+ ) {+ let active = input_active;+ if active || self.last_activity.1 != self.session.revision {+ self.last_activity = (now, self.session.revision);+ }+ if !self.ui.cache_when_idle || self.frames.urgent_pending() {+ return;+ }+ let quiet = now - self.last_activity.0;+ if quiet < 1.0 {+ ctx.request_repaint_after(std::time::Duration::from_secs_f64(1.0 - quiet));+ return;+ }+ // An empty work area has nothing to cache.+ let n = wb - wa + 1;+ if n < 1 {+ return;+ }+ let cur = comp.frame_rate.frame_at(self.session.time()).clamp(wa, wb);+ let fit = self.frames_that_fit(comp, series.scale as f64 / 1000.0).min(n);+ let slots = (self.frames_parallelism() / 2).max(1);+ let mut queued = self.frames.inflight();+ let scale = series.scale as f64 / 1000.0;+ let mut pending = false;+ for k in 0..fit {+ let f = wa + (cur - wa + k).rem_euclid(n);+ if self.frames.is_cached(&FrameKey { frame: f, ..*series }) {+ continue;+ }+ pending = true;+ if queued >= slots {+ break;+ }+ self.request_frame(ItemId(series.comp), f, scale);+ queued += 1;+ }+ if pending {+ ctx.request_repaint_after(std::time::Duration::from_millis(100));+ }+ }++ /// How many viewer frames of `comp` at `scale` the RAM preview budget holds (90 % of it,+ /// at least one).+ /// The frames of `plan` from `cur` to its end, or as many as fit in the RAM preview, are+ /// cached: sound can play from `cur` in real time.+ fn cached_ahead(&self, plan: &effectcraft_engine::preview::PreviewPlan, series: &FrameKey, cur: i64, fit: i64) -> bool {+ let cached = self.frames.cached_frames(series);+ (0..fit).map_while(|k| plan.frame_after(cur, k)).take_while(|f| *f >= cur).all(|f| cached.binary_search(&f).is_ok())+ }++ fn frames_that_fit(&self, comp: &effectcraft_engine::project::Comp, scale: f64) -> i64 {++ ((self.frames.budget() as f64 * 0.9 / self.frame_bytes(comp, scale)) as i64).max(1)++ }++++ /// Bytes of one comp-sized viewer frame at `scale` (Extended Viewer frames are larger).++ fn frame_bytes(&self, comp: &effectcraft_engine::project::Comp, scale: f64) -> f64 {+ let side = |n: u32| (n as f64 * scale).ceil().max(1.0);- let frame = side(comp.width) * side(comp.height) * 4.0;- ((self.frames.budget() as f64 * 0.9 / frame) as i64).max(1)++ side(comp.width) * side(comp.height) * 4.0+ }++ fn frames_parallelism(&self) -> usize {+ if cfg!(target_arch = "wasm32") {+ // frame workers render one frame each; without them frames render one at a time+ // on the UI thread (`Frames::pump`)+ return self.frames.remote_slots().max(1);+ }+ self.frames.parallelism()+ }+ }++++#[cfg(test)]++mod startup_tests {++ use super::startup_frames;++++ /// The frames a preview with sound waits for are always requested and fit together (#947).++ #[test]++ fn startup_waits_only_for_frames_it_requests_and_can_keep() {++ // A 64×36 frame: 9216 bytes. A 46 080-byte budget fits 4 of them (90 %); the prefetch++ // window then requests offsets 0..3, so the start needs those 3, not 4 it never asks for.++ let frame = 64 * 36 * 4;++ let fit = 4;++ let window = (32i64 * 3).min(fit - 1);++ assert_eq!(startup_frames(32, window, 46_080, frame), 3);++ // A roomy budget: the prefetch's `ahead` frames.++ assert_eq!(startup_frames(8, 24, 100_000_000, frame), 8);++ // Extended Viewer: a 160×120 comp renders 320×248 frames. 952 320 bytes fit 11 comp-sized++ // frames but only 2 real ones (90 %): wait for 2, not 4.++ assert_eq!(startup_frames(4, 11, 952_320, 320 * 248 * 4), 2);++ // Nothing fits, or no window: still the current frame, never 0.++ assert_eq!(startup_frames(8, 0, 0, frame), 1);++ // A zero frame size counts as 1 byte: no division by zero.++ assert_eq!(startup_frames(8, 24, 10, 0), 8);++ }++}diff --cc crates/ui-egui/src/lib.rsindex 6f610390d,fcbfd49bf..0b259bfde--- a/crates/ui-egui/src/lib.rs+++ b/crates/ui-egui/src/lib.rs@@@ -381,17 -184,6 +184,17 @@@ pub struct Playback/// fits in the RAM preview) is cached, so it never plays over skipped frames (#103), or/// sooner once the silent preview keeps real time with the frames ahead cached (#208).pub audio_held: bool,+ /// Starting a preview with sound (#947): the playhead stays on the first frame while the+ /// frames ahead render (the prefetch window, at most what fits in the RAM preview), then+ /// sound and picture start together from it. Without this the picture played on silently+ /// while they rendered and the sound started at the later frame, so the opening was lost.+ /// A stall later on still falls back to [`Playback::audio_held`].+ pub starting: bool,- /// When the preview started (seconds): [`Playback::starting`] gives up after [`STARTUP_LIMIT`].++ /// When the preview started (seconds): [`Playback::starting`] gives up after `STARTUP_LIMIT`.+ pub starting_since: f64,+ /// When the first frame was cached while [`Playback::starting`] (seconds): the wait for the- /// frames ahead gives up [`STARTUP_WAIT`] after it.++ /// frames ahead gives up `STARTUP_WAIT` after it.+ pub first_cached: Option<f64>,/// When the last frames were shown (seconds, the last second's worth): the achieved rate.pub shown_at: std::collections::VecDeque<f64>,}