f67d38b35cc5
playback.rs
#[cfg(not(target_arch = "wasm32"))]
use super::play_ahead;
use super::{AUDIO_RETRY_S, AUDIO_STALL_S, FilmcraftApp, Tick, frames, json, panels, shuttle};
#[cfg(test)]
use filmcraft_engine::Session;
impl FilmcraftApp {
// ---------------------------------------------------------------- playback
pub fn toggle_play(&mut self, speed: f64) {
if self.playback.playing {
self.stop();
} else {
self.play(speed);
}
}
pub fn play(&mut self, speed: f64) {
self.stop_source();
if self.session.active_sequence().is_none() {
return;
}
// restart from the end → from the start (Settings ▸ Timeline ▸ "At playback end, return to
// beginning when restarting playback")
let dur = self.session.active_sequence().map(|q| q.duration()).unwrap_or_default();
// (not while a voice-over take starts: it was put exactly where the take must begin, e.g. on empty timeline past the end)
if speed > 0.0
&& self.session.prefs.timeline.return_to_beginning
&& !self.session.voiceover.recording()
&& self.session.playhead() >= dur - self.session.sequence_rate().frame_duration()
{
self.session.set_playhead(Tick::ZERO);
}
// A loop restart keeps counting into the same meter.
if !self.playback.playing || self.playback.speed != speed {
self.playback.meter.start(speed);
}
self.playback.playing = true;
self.playback.speed = speed;
self.playback.anchor_tick = self.session.playhead();
self.playback.anchor_time = -1.0; // set when the preroll ends
self.playback.smooth_playhead = None;
self.playback.preroll = Some(-1.0);
self.playback.preroll_ready = false;
if let Some(a) = self.audio.as_mut() {
a.stop();
}
self.playback.audio_clock = false;
self.playback.audio_retry_at = 0.0;
}
/// Start the clock (and audio) once the first frames are ready or the preroll timed out.
fn end_preroll(&mut self, now: f64) {
self.playback.preroll = None;
self.playback.anchor_time = now;
self.playback.anchor_tick = self.session.playhead();
self.playback.audio_seen = (0, now);
self.start_audio(now);
// Audio Track Mixer: an automation pass runs while playing forward in real time
if (self.playback.speed - 1.0).abs() < 1e-9 && !self.session.mixrec.active() {
let t = self.session.playhead();
let _ = self.session.execute("mixer.recordStart", json!({"time": t.0}));
}
// Multi-Camera view: playing records live cuts (keys 1–9 / clicking angles)
panels::multicam::on_play(self);
// voice-over: the capture starts with the audio clock
panels::voiceover::on_play(self);
}
/// Play the last Text to Speech preview (`Session::tts_preview`) on the audio output, stopping
/// timeline playback first. Starting playback again takes the output back.
pub fn play_tts_preview(&mut self) -> Result<f64, String> {
let audio = self.session.tts_preview.clone().ok_or("nothing to preview")?;
if self.playback.playing {
self.stop();
}
self.release_scrub_output();
let a = self.audio.as_mut().ok_or("no audio output (check Settings > Audio Hardware)")?;
let sr = a.sample_rate().max(1);
a.stop();
let step = f64::from(audio.sample_rate.max(1)) / f64::from(sr);
let seconds = audio.seconds();
let mut pos = 0.0f64;
let fill = Box::new(move |buf: &mut [f32], ch: usize| {
for frame in buf.chunks_mut(ch.max(1)) {
let i = pos as usize;
let f = (pos - i as f64) as f32;
let x0 = audio.samples.get(i).copied().unwrap_or(0.0);
let x1 = audio.samples.get(i + 1).copied().unwrap_or(0.0);
frame.fill(x0 + (x1 - x0) * f);
pos += step;
}
});
a.start(fill)?;
self.playback.audio_clock = false;
self.playback.tts_preview = true;
Ok(seconds)
}
/// Whether [`FilmcraftApp::stop`] has a transport to stop: Program or Source playback, a
/// preroll, or a recording that runs one. A press that only moves the playhead uses this so it
/// does not close an audio stream that is already open (#2633): dropping the output stream
/// makes the next scrub grain open the device again, and on WASAPI that open is slow.
pub fn transport_running(&self) -> bool {
self.playback.playing
// A panel that panicked clears `playing` but leaves the output playing, and the clock
// stays on: the press still has that stream to stop.
|| self.playback.audio_clock
|| self.source_playback.clock.playing
|| self.playback.preroll.is_some()
|| self.session.mixrec.active()
|| self.session.mcrec.active()
|| self.session.voiceover.recording()
}
pub fn stop(&mut self) {
self.playback.playing = false;
self.playback.tts_preview = false;
self.playback.stop_at = None;
self.playback.rest_at = None;
self.playback.preroll = None;
self.playback.meter.finish();
self.frames.stop_prefetch();
if let Some(a) = self.audio.as_mut() {
a.stop();
}
if let Some(out) = self.scrub_out.as_mut() {
out.stop();
}
self.scrub.device_stopped();
self.playback.audio_clock = false;
self.playback.audio_retry_at = 0.0;
if self.session.mixrec.active() {
let t = self.session.playhead();
if let Err(e) = self.session.execute("mixer.recordStop", json!({"time": t.0})) {
self.ui.status = e.to_string();
}
}
panels::multicam::on_stop(self);
panels::voiceover::on_stop(self);
}
/// [`stop`](Self::stop) for a press or drag that moves the playhead (a scrub bar, a ruler).
/// With nothing playing or recording there is nothing to stop, and stopping the output would
/// close the scrub stream (see `scrub.rs`) that the drag keeps open, once per move. A take
/// that records while stopped and a Text to Speech preview still end here, as they do in `stop`.
pub(crate) fn stop_for_scrub(&mut self) {
if self.transport_running() || self.playback.tts_preview {
self.stop();
}
}
/// Give the scrub output's device back before playback opens its own stream (#2633). The scrub
/// stream lingers for a few seconds after the last grain, and a device that takes one stream
/// at a time (a raw ALSA `hw:` device, an exclusive-mode output) would refuse playback's.
fn release_scrub_output(&mut self) {
if let Some(out) = self.scrub_out.as_mut() {
out.release();
self.scrub.device_stopped();
}
}
pub(super) fn start_audio(&mut self, now: f64) {
let Some(seq_id) = self.session.state.active_sequence else { return };
let start_tick = self.session.playhead();
self.release_scrub_output();
let Some(a) = self.audio.as_mut() else { return };
let sr = a.sample_rate();
// Output frames still follow the accelerated timeline. The pitch preference selects
// either the original rate conversion or pitch-corrected program audio.
let Some((mix_rate, mix)) = shuttle::mix(&self.session, seq_id, sr, self.playback.speed) else {
a.stop();
self.playback.audio_retry_at = 0.0;
return;
};
let cursor = start_tick.to_units_floor(i64::from(mix_rate));
// the old stream stops before the new mixer resets the underrun counters
a.stop();
// Desktop: mix ahead on a thread so the device callback never waits on decoding.
#[cfg(not(target_arch = "wasm32"))]
let fill = play_ahead::spawn(mix, cursor, sr, a.channels(), self.playback.audio_stats.clone());
#[cfg(target_arch = "wasm32")]
let fill = {
let (mut mix, mut cursor) = (mix, cursor);
Box::new(move |buf: &mut [f32], ch: usize| {
mix(cursor, buf, ch);
cursor += (buf.len() / ch.max(1)) as i64;
})
};
match a.start(fill) {
Ok(_) => {
self.playback.audio_clock = true;
self.playback.audio_retry_at = 0.0;
if let Some(note) = self.audio.as_ref().and_then(|audio| audio.note()) {
self.ui.status = note;
}
}
Err(e) => {
log::warn!("audio output unavailable: {e}");
self.playback.audio_clock = false;
self.playback.audio_retry_at = now + AUDIO_RETRY_S;
}
}
}
/// Where the Timeline draws the playhead: the smoothed playback clock while playing, else the
/// session playhead.
pub(crate) fn shown_playhead(&self) -> Tick {
match self.playback.smooth_playhead {
Some((t, _)) if self.playback.playing => t,
_ => self.session.playhead(),
}
}
/// The drawn playhead for a playback clock at `clock`: the last drawn one moved on by the wall
/// time since, plus a tenth of how far that is from the clock. It never steps back against
/// the direction of play; a jump (loop, seek) more than a quarter second away is taken at once.
fn smooth_playhead(&self, clock: Tick, now: f64) -> Tick {
let Some((drawn, at)) = self.playback.smooth_playhead else { return clock };
let speed = self.playback.speed;
let predicted = drawn.seconds() + (now - at).max(0.0) * speed;
let error = clock.seconds() - predicted;
if !predicted.is_finite() || error.abs() > 0.25 {
return clock;
}
let next = predicted + error * 0.1;
let next = if speed >= 0.0 { next.max(drawn.seconds()) } else { next.min(drawn.seconds()) };
Tick::from_seconds_f64(next)
}
/// Advance the Program playhead only while playing; owns preroll completion, audio-clock anchoring, output retry and the fallback to wall time when audio
/// is lost or stalls.
pub(super) fn advance_playback(&mut self, ctx: &egui::Context) {
if !self.playback.playing {
self.playback.smooth_playhead = None;
return;
}
let now = self.now();
if let Some(since) = self.playback.preroll {
let since = if since < 0.0 { now } else { since };
self.playback.preroll = Some(since);
if self.playback.preroll_ready || now - since >= frames::PREROLL_TIMEOUT_S {
self.end_preroll(now);
} else {
ctx.request_repaint();
return;
}
}
if self.playback.anchor_time < 0.0 {
self.playback.anchor_time = now;
}
if !self.playback.audio_clock && self.playback.audio_retry_at > 0.0 && now >= self.playback.audio_retry_at {
// The output failed mid-play: open it again where the wall clock got to (what
// pause/play does by hand), so a recovering device brings the sound back.
self.playback.audio_retry_at = now + AUDIO_RETRY_S;
self.playback.anchor_tick = self.session.playhead();
self.playback.anchor_time = now;
self.playback.audio_seen = (0, now);
self.start_audio(now);
}
let rate = self.session.sequence_rate();
if self.playback.audio_clock
&& let Some(audio) = self.audio.as_mut()
{
audio.recover();
}
let reading = if self.playback.audio_clock { self.audio.as_ref().and_then(|a| a.played_frames().map(|f| (f, a.sample_rate()))) } else { None };
if self.playback.audio_clock && reading.is_none() {
// A device error relinquishes its clock immediately. Resume from the displayed
// frame, rather than jumping to the old wall-clock anchor after buffered playback.
self.playback.anchor_tick = self.session.playhead();
self.playback.anchor_time = now;
self.playback.audio_clock = false;
self.playback.audio_retry_at = now + AUDIO_RETRY_S;
if let Some(audio) = self.audio.as_mut() {
audio.stop();
}
log::warn!("audio output lost its playback clock; playing without sound");
self.ui.status = tl!("Audio output failed: playing without sound (check Settings > Audio Hardware)").into();
}
if let Some((f, sr)) = reading {
if f != self.playback.audio_seen.0 {
self.playback.audio_seen = (f, now);
} else if now - self.playback.audio_seen.1 >= AUDIO_STALL_S {
// the device stopped consuming samples: continue from where the audio got to on
// the wall clock, without sound
let played = if sr > 0 { f as f64 / sr as f64 } else { 0.0 };
self.playback.anchor_tick += Tick::from_seconds_f64(played * self.playback.speed);
self.playback.anchor_time = now;
self.playback.audio_clock = false;
if let Some(a) = self.audio.as_mut() {
a.stop();
}
log::warn!("audio output stalled (no samples consumed for {AUDIO_STALL_S} s); playing without sound");
self.ui.status = tl!("Audio output is not responding: playing without sound (check Settings > Audio Hardware)").into();
}
}
let elapsed = match reading {
Some((f, sr)) if self.playback.audio_clock && sr > 0 => f as f64 / sr as f64,
_ => now - self.playback.anchor_time,
};
let t = self.playback.anchor_tick + Tick::from_seconds_f64(elapsed * self.playback.speed);
let seq = self.session.active_sequence();
let dur = seq.map(|q| q.duration()).unwrap_or_default();
let (lo, hi) = if self.playback.looping {
(seq.and_then(|q| q.mark_in).unwrap_or(Tick::ZERO), seq.and_then(|q| q.mark_out).map(|o| o + rate.frame_duration()).unwrap_or(dur))
} else {
(Tick::ZERO, dur)
};
if let Some(end) = self.playback.stop_at.filter(|e| t >= *e && self.playback.speed > 0.0 && !self.playback.looping) {
self.session.set_playhead(self.playback.rest_at.unwrap_or(end));
self.stop();
} else if t >= hi && self.playback.speed > 0.0 && (self.playback.looping || !self.session.voiceover.recording()) {
// a voice-over take keeps playing (and recording) into the empty timeline past the end
if self.playback.looping {
self.session.set_playhead(lo);
self.play(self.playback.speed);
} else {
self.session.set_playhead(hi - rate.frame_duration());
self.stop();
}
} else if t <= Tick::ZERO && self.playback.speed < 0.0 {
self.session.set_playhead(Tick::ZERO);
self.stop();
} else {
self.session.set_playhead(t);
self.playback.smooth_playhead = Some((self.smooth_playhead(t, now), now));
}
ctx.request_repaint();
}
}
#[cfg(test)]
mod clock_tests {
use super::*;
/// The egui clock starts at the integration's beginning, which can precede `clock_start`.
/// Applying the captured offset to host time keeps hidden logic moving instead of freezing at
/// the last UI time and then jumping when the next UI pass arrives.
#[test]
fn now_applies_the_ui_clock_offset_and_keeps_the_test_override_first() {
let mut app = FilmcraftApp::new(Session::default());
app.ui_clock = 123.0;
app.ui_clock_offset = Some(1_000.0);
assert!(app.now() >= 1_000.0, "the captured offset moves the host clock to egui time");
app.ui_clock = 2_000.0;
assert_eq!(app.now(), 2_000.0, "an egui clock ahead of host+offset still wins");
app.set_now_for_test(7.0);
assert_eq!(app.now(), 7.0, "the deterministic test override keeps precedence");
}
}
#[cfg(test)]
mod audio_recovery_tests;
#[cfg(test)]
mod voiceover_playback_tests {
use super::*;
/// A voice-over take into an empty timeline past the end keeps playing and recording.
#[test]
fn a_voice_over_take_records_into_the_empty_timeline_past_the_end() {
let mut session = Session::default();
session.execute("file.openDemoProject", json!({})).unwrap();
session.execute("audio.voiceover.settings", json!({"prerollSeconds": 0.0})).unwrap();
session.prefs.timeline.return_to_beginning = true;
let ctx = egui::Context::default();
let mut app = FilmcraftApp::new(session);
app.audio = None;
let dur = app.session.active_sequence().map(|q| q.duration()).unwrap();
let from = app.session.sequence_rate().snap(dur + Tick::from_seconds_f64(60.0));
app.session.set_playhead(from);
panels::voiceover::toggle(&mut app, None).unwrap();
// play() keeps the record point instead of returning to the beginning
assert!(app.playback.playing);
assert_eq!(app.session.playhead(), from);
app.end_preroll(0.0);
// and one second later the take is still playing and recording, not stopped at the end
app.set_now_for_test(1.0);
let mut output = ctx.run_ui(egui::RawInput { time: Some(1.0), ..Default::default() }, |ui| app.advance_playback(ui.ctx()));
output.textures_delta.clear();
assert!(app.playback.playing);
assert!(app.session.voiceover.recording());
assert!(app.session.playhead() > from, "{:?} <= {from:?}", app.session.playhead());
app.session.execute("audio.voiceover.stop", json!({"discard": true})).unwrap();
app.stop();
}
}
#[cfg(test)]
mod smooth_playhead_tests {
use super::*;
fn playing_at(now: f64) -> FilmcraftApp {
let mut session = Session::default();
session.execute("file.openDemoProject", json!({})).unwrap();
let mut app = FilmcraftApp::new(session);
app.playback.playing = true;
app.playback.speed = 1.0;
app.playback.anchor_tick = Tick::ZERO;
app.playback.anchor_time = 0.0;
app.set_now_for_test(now);
app.advance_playback(&egui::Context::default());
app
}
/// The playhead line follows the playback clock between frame boundaries, so it glides at the
/// display's refresh rate instead of jumping a whole frame at a time. The session playhead
/// still names the frame shown.
#[test]
fn the_drawn_playhead_moves_between_frames_while_playing() {
let frame = playing_at(0.0).session.sequence_rate().frame_duration().seconds();
let mid = frame * 1.5;
let app = playing_at(mid);
assert_eq!(app.session.playhead(), app.session.sequence_rate().tick_of(1), "the frame shown");
let drawn = app.shown_playhead().seconds();
assert!((drawn - mid).abs() < 1e-6, "drawn at the clock time {mid}, not the frame boundary: {drawn}");
let later = playing_at(mid + frame * 0.25).shown_playhead().seconds();
assert!(later > drawn, "it keeps moving inside the same frame: {drawn} -> {later}");
}
/// A device that reports its clock once per 1024-sample buffer.
struct BufferedDevice(std::sync::Arc<std::sync::atomic::AtomicU64>);
impl crate::AudioOut for BufferedDevice {
fn sample_rate(&self) -> u32 {
48_000
}
fn start(&mut self, _: Box<dyn FnMut(&mut [f32], usize) + Send>) -> Result<u32, String> {
Ok(48_000)
}
fn stop(&mut self) {}
fn played_frames(&self) -> Option<u64> {
Some(self.0.load(std::sync::atomic::Ordering::Relaxed))
}
}
/// Played on the audio clock and drawn at 60 Hz, the playhead only ever moves forward, by
/// about one display frame's worth of time each frame. It used to step back a few points and
/// then jump ahead every half second or so.
#[test]
fn on_the_audio_clock_the_drawn_playhead_never_steps_back() {
let mut session = Session::default();
session.execute("file.openDemoProject", json!({})).unwrap();
let mut app = FilmcraftApp::new(session);
let played = std::sync::Arc::new(std::sync::atomic::AtomicU64::new(0));
app.audio = Some(Box::new(BufferedDevice(played.clone())));
app.playback.playing = true;
app.playback.speed = 1.0;
app.playback.audio_clock = true;
app.playback.anchor_tick = Tick::ZERO;
let ctx = egui::Context::default();
let mut last: Option<f64> = None;
for frame in 0..240 {
let now = frame as f64 / 60.0;
played.store((now * 48_000.0 / 1024.0).floor() as u64 * 1024, std::sync::atomic::Ordering::Relaxed);
app.set_now_for_test(now);
app.advance_playback(&ctx);
let drawn = app.shown_playhead().seconds();
if let Some(prev) = last.filter(|_| frame > 30) {
let step = drawn - prev;
assert!(step >= 0.0, "frame {frame}: stepped back {:.4} s ({prev:.4} -> {drawn:.4})", -step);
assert!((0.5 / 60.0..1.5 / 60.0).contains(&step), "frame {frame}: uneven step {step:.4} s");
assert!((drawn - now).abs() < 0.05, "frame {frame}: drawn {drawn:.4} drifted from the clock {now:.4}");
}
last = Some(drawn);
}
}
/// Stopped, the drawn playhead is the session playhead.
#[test]
fn stopped_it_is_the_session_playhead() {
let mut app = playing_at(0.1);
app.stop();
assert_eq!(app.shown_playhead(), app.session.playhead());
}
}
No file is open. Choose one in the tree, or press Ctrl+O (⌘O on a Mac) to find one by name.
Syntax highlighting could not load. The unmodified read-only text remains available above.