Open source Loom alternative. Beautiful, shareable screen recordings.
Rust appcapcossloommacnextjsnextjs15open-sourceossreactrecordrustscreen-capturescreen-recorderscreenshotsolidjstauritauri-apptypescriptvite
use cap_project::{
ClipOffsets, ClipTransitionType, ProjectConfiguration, TimelineFrameMapping, XY,
};
use cap_rendering::{
DecodedFrame, DecodedSegmentFrames, PrecomputedCursorTimeline, ProjectUniforms,
RecordingSegmentDecoders, RenderVideoConstants, ZoomTransformTimeline,
spring_mass_damper::SpringMassDamperSimulationConfig,
};
use cap_utils::operation_diagnostics::{Field, Operation};
use futures::stream::{FuturesUnordered, StreamExt};
use lru::LruCache;
use std::{
collections::{HashSet, VecDeque},
num::NonZeroUsize,
sync::{
Arc, RwLock,
atomic::{AtomicBool, AtomicU64, AtomicUsize, Ordering},
mpsc as std_mpsc,
},
time::{Duration, Instant},
};
use tokio::sync::{Notify, watch};
use tracing::{info, warn};
use crate::{
audio_output::{AudioOutput, PlaySpec},
editor,
editor_instance::{SegmentMedia, cursor_timeline_settings},
segments::get_audio_segments,
telemetry::{
PlaybackFrameSource, PlaybackSkipReason, PlaybackTelemetry, PlaybackTelemetryEvent,
},
};
const INITIAL_PREFETCH_BUFFER_SIZE: usize = 10;
const MAX_PREFETCH_BUFFER_SIZE: usize = 90;
const PREFETCH_CHANNEL_SIZE: usize = 4;
const MAX_PREFETCH_BUFFER_BYTES: usize = 128 * 1024 * 1024;
// Starvation boost: when the playback loop skips because decode fell behind,
// the runway temporarily widens (2x frames, byte budget below) and decays back
// after BOOST_CLEAN_WINDOW without another starvation skip. Steady-state
// memory is unchanged; the boost only spends memory while it is earning
// smoothness back.
const BOOSTED_PREFETCH_BUFFER_BYTES: usize = 192 * 1024 * 1024;
const BOOST_CLEAN_WINDOW: Duration = Duration::from_secs(6);
const PARALLEL_DECODE_TASKS: usize = 4;
const INITIAL_PARALLEL_DECODE_TASKS: usize = 4;
const FRAME_CACHE_SIZE: usize = 4;
const MAX_FRAME_CACHE_BYTES: usize = 64 * 1024 * 1024;
const RAMP_UP_FRAME_COUNT: u32 = 15;
fn clip_audio_changed(previous: &ProjectConfiguration, next: &ProjectConfiguration) -> bool {
let settings = |project: &ProjectConfiguration, segment: &cap_project::TimelineSegment| {
let offsets = project
.clips
.iter()
.find(|clip| clip.index == segment.recording_clip)
.map(|clip| clip.offsets)
.unwrap_or_default();
(
segment.recording_clip,
segment.start,
segment.end,
segment.timescale,
segment.speed_audio_mode,
segment.volume(),
offsets.mic,
offsets.system_audio,
)
};
match (&previous.timeline, &next.timeline) {
(Some(previous_timeline), Some(next_timeline)) => !previous_timeline
.segments
.iter()
.map(|segment| settings(previous, segment))
.eq(next_timeline
.segments
.iter()
.map(|segment| settings(next, segment))),
(None, None) => false,
_ => true,
}
}
#[cfg(target_os = "windows")]
struct WindowsTimerResolution;
#[cfg(target_os = "windows")]
impl WindowsTimerResolution {
fn set_high_precision() -> Self {
unsafe {
windows::Win32::Media::timeBeginPeriod(1);
}
Self
}
}
#[cfg(target_os = "windows")]
impl Drop for WindowsTimerResolution {
fn drop(&mut self) {
unsafe {
windows::Win32::Media::timeEndPeriod(1);
}
}
}
/// Above normal, so a wake preempts decode and render threads instead of
/// queueing behind them: at normal priority on a loaded machine the wake
/// landed up to 10 ms late, with or without the spin.
#[cfg(target_os = "windows")]
fn raise_playback_thread_priority() {
use windows::Win32::System::Threading::{
GetCurrentThread, SetThreadPriority, THREAD_PRIORITY_ABOVE_NORMAL,
};
unsafe {
let _ = SetThreadPriority(GetCurrentThread(), THREAD_PRIORITY_ABOVE_NORMAL);
}
}
#[cfg(target_os = "windows")]
struct WindowsWaitableTimer(windows::Win32::Foundation::HANDLE);
#[cfg(target_os = "windows")]
impl WindowsWaitableTimer {
/// How long before the deadline the timer wait ends and spinning starts.
/// The timer fires up to about 0.5 ms late.
const SPIN: Duration = Duration::from_micros(500);
/// `None` before Windows 10 1803, which rejects the high-resolution flag.
fn high_resolution() -> Option<Self> {
use windows::Win32::System::Threading::{
CREATE_WAITABLE_TIMER_HIGH_RESOLUTION, CreateWaitableTimerExW, TIMER_ALL_ACCESS,
};
unsafe {
CreateWaitableTimerExW(
None,
windows::core::PCWSTR::null(),
CREATE_WAITABLE_TIMER_HIGH_RESOLUTION,
TIMER_ALL_ACCESS.0,
)
}
.ok()
.map(Self)
}
fn sleep(&self, duration: Duration) -> bool {
use windows::Win32::{
Foundation::WAIT_OBJECT_0,
System::Threading::{INFINITE, SetWaitableTimer, WaitForSingleObject},
};
// Negative: relative, in 100 ns intervals.
let due = -i64::try_from(duration.as_nanos() / 100)
.unwrap_or(i64::MAX)
.max(1);
unsafe {
SetWaitableTimer(self.0, &due, 0, None, None, false).is_ok()
&& WaitForSingleObject(self.0, INFINITE) == WAIT_OBJECT_0
}
}
}
#[cfg(target_os = "windows")]
impl Drop for WindowsWaitableTimer {
fn drop(&mut self) {
unsafe {
let _ = windows::Win32::Foundation::CloseHandle(self.0);
}
}
}
fn precision_sleep_sync(deadline: Instant) {
let now = Instant::now();
if now >= deadline {
return;
}
let remaining = deadline.saturating_duration_since(now);
#[cfg(target_os = "windows")]
{
thread_local! {
static WAITABLE_TIMER: Option<WindowsWaitableTimer> =
WindowsWaitableTimer::high_resolution();
}
// A high-resolution timer wakes within a fraction of a millisecond,
// so only the last 500 us are spun. Without one, `thread::sleep` can
// wake a full 1 ms timer period late and the last 2 ms are spun.
let timed = WAITABLE_TIMER.with(|timer| {
timer.as_ref().is_some_and(|timer| {
remaining <= WindowsWaitableTimer::SPIN
|| timer.sleep(remaining.saturating_sub(WindowsWaitableTimer::SPIN))
})
});
if !timed {
let remaining = deadline.saturating_duration_since(Instant::now());
let spin_threshold = Duration::from_millis(2);
if remaining > spin_threshold {
std::thread::sleep(remaining.saturating_sub(spin_threshold));
}
}
while Instant::now() < deadline {
std::hint::spin_loop();
}
}
#[cfg(not(target_os = "windows"))]
{
std::thread::sleep(remaining);
}
}
fn valid_playback_duration(duration: f64) -> Option<f64> {
(duration.is_finite() && duration > 0.0).then_some(duration)
}
fn has_playback_audio(audio_segments: &[crate::audio::AudioSegment], has_music: bool) -> bool {
has_music
|| audio_segments
.iter()
.any(|segment| !segment.tracks.is_empty())
}
#[derive(Debug)]
pub enum PlaybackStartError {
InvalidFps,
PreparingCleanup,
PreparingCandidate,
}
pub struct Playback {
pub renderer: Arc<editor::RendererHandle>,
pub render_constants: Arc<RenderVideoConstants>,
pub start_frame_number: u32,
pub project: watch::Receiver<ProjectConfiguration>,
pub segment_medias: Arc<Vec<SegmentMedia>>,
pub music: crate::audio::MusicTracks,
pub audio_output: Arc<AudioOutput>,
pub telemetry: Option<PlaybackTelemetry>,
}
#[derive(Clone, Copy)]
pub enum PlaybackEvent {
Start,
Frame(u32),
Stop,
}
#[derive(Clone)]
pub struct PlaybackHandle {
preparing_audio_released: Arc<AtomicBool>,
stop_tx: watch::Sender<bool>,
event_rx: watch::Receiver<PlaybackEvent>,
seek_tx: Arc<watch::Sender<(u64, u32)>>,
seek_generation: Arc<AtomicU64>,
adopted: Option<crate::PreparingPlaybackAdoption>,
}
struct PrefetchedFrame {
seek_generation: u64,
frame_number: u32,
segment_frames: DecodedSegmentFrames,
segment_index: u32,
transition: Option<PrefetchedTransition>,
}
struct PrefetchedTransition {
segment_frames: DecodedSegmentFrames,
segment_index: u32,
kind: ClipTransitionType,
progress: f32,
}
impl PrefetchedFrame {
fn byte_len(&self) -> usize {
decoded_segment_frames_byte_len(&self.segment_frames).saturating_add(
self.transition
.as_ref()
.map(|transition| decoded_segment_frames_byte_len(&transition.segment_frames))
.unwrap_or(0),
)
}
fn into_cached(self) -> CachedFrame {
(
Arc::new(self.segment_frames),
self.segment_index,
self.transition.map(|transition| {
(
Arc::new(transition.segment_frames),
transition.segment_index,
transition.kind,
transition.progress,
)
}),
)
}
}
struct PrefetchReceiver {
frames: std_mpsc::Receiver<PrefetchedFrame>,
capacity: Arc<Notify>,
}
fn prefetch_channel(bound: usize) -> (std_mpsc::SyncSender<PrefetchedFrame>, PrefetchReceiver) {
let (sender, frames) = std_mpsc::sync_channel(bound);
(
sender,
PrefetchReceiver {
frames,
capacity: Arc::new(Notify::new()),
},
)
}
fn receive_prefetched_frame(
receiver: &PrefetchReceiver,
seek_generation: u64,
timeout: Duration,
) -> Result<PrefetchedFrame, std_mpsc::RecvTimeoutError> {
let deadline = Instant::now() + timeout;
loop {
let frame = receiver
.frames
.recv_timeout(deadline.saturating_duration_since(Instant::now()))?;
receiver.capacity.notify_one();
// A completed decode can already be queued when the producer observes a seek.
if frame.seek_generation == seek_generation {
return Ok(frame);
}
}
}
fn should_reset_prefetch(
seek_generation: u64,
next_frame: u32,
requested_generation: u64,
requested_frame: u32,
has_in_flight: bool,
) -> bool {
requested_generation != seek_generation
|| requested_frame > next_frame
|| (requested_frame < next_frame && !has_in_flight)
}
type CachedTransition = (Arc<DecodedSegmentFrames>, u32, ClipTransitionType, f32);
type CachedFrame = (Arc<DecodedSegmentFrames>, u32, Option<CachedTransition>);
fn decoded_frame_byte_len(frame: &DecodedFrame) -> usize {
frame.byte_len()
}
fn decoded_segment_frames_byte_len(frames: &DecodedSegmentFrames) -> usize {
frames
.screen_frame
.as_ref()
.map(decoded_frame_byte_len)
.unwrap_or(0)
.saturating_add(
frames
.camera_frame
.as_ref()
.map(decoded_frame_byte_len)
.unwrap_or(0),
)
}
fn cached_frame_byte_len(frame: &CachedFrame) -> usize {
decoded_segment_frames_byte_len(&frame.0).saturating_add(
frame
.2
.as_ref()
.map(|transition| decoded_segment_frames_byte_len(&transition.0))
.unwrap_or(0),
)
}
fn prefetch_frame_limit(frame_bytes: usize) -> usize {
if frame_bytes == 0 {
return MAX_PREFETCH_BUFFER_SIZE;
}
(MAX_PREFETCH_BUFFER_BYTES / frame_bytes)
.clamp(INITIAL_PREFETCH_BUFFER_SIZE, MAX_PREFETCH_BUFFER_SIZE)
}
// The boosted limit is capped both by 2x the base and by the boosted byte
// budget, but never drops below base: on Retina-sized frames the byte quotient
// alone would land under the base floor and silently disable the boost.
fn boosted_prefetch_frame_limit(frame_bytes: usize) -> usize {
let base = prefetch_frame_limit(frame_bytes);
if frame_bytes == 0 {
return base;
}
(base * 2)
.min((BOOSTED_PREFETCH_BUFFER_BYTES / frame_bytes).max(base + 6))
.clamp(base, MAX_PREFETCH_BUFFER_SIZE)
}
fn effective_prefetch_limit(frame_bytes: usize, boosted: bool) -> usize {
if boosted {
boosted_prefetch_frame_limit(frame_bytes)
} else {
prefetch_frame_limit(frame_bytes)
}
}
fn observe_prefetched_frame(frame: &PrefetchedFrame, largest_frame_bytes: &mut usize) {
let frame_bytes = frame.byte_len();
if frame_bytes > *largest_frame_bytes {
*largest_frame_bytes = frame_bytes;
}
}
// Until a frame has been observed the atomic keeps its INITIAL value; storing
// the zero-bytes result here would open the runway to MAX before the first
// frame's size is known.
fn refresh_prefetch_limit(
limit: &AtomicUsize,
largest_frame_bytes: usize,
boost_until: Option<Instant>,
) -> usize {
if largest_frame_bytes == 0 {
return limit.load(Ordering::Relaxed);
}
let boosted = boost_until.is_some_and(|until| Instant::now() < until);
let value = effective_prefetch_limit(largest_frame_bytes, boosted);
limit.store(value, Ordering::Relaxed);
value
}
struct FrameCache {
cache: LruCache<u32, CachedFrame>,
cache_bytes: usize,
max_bytes: usize,
}
impl FrameCache {
fn new(capacity: usize, max_bytes: usize) -> Self {
Self {
cache: LruCache::new(NonZeroUsize::new(capacity).unwrap()),
cache_bytes: 0,
max_bytes,
}
}
fn get(&mut self, frame_number: u32) -> Option<CachedFrame> {
self.cache
.get(&frame_number)
.map(|(frames, segment_index, transition)| {
(
Arc::clone(frames),
*segment_index,
transition.as_ref().map(
|(transition_frames, transition_index, kind, progress)| {
(
Arc::clone(transition_frames),
*transition_index,
*kind,
*progress,
)
},
),
)
})
}
fn insert(
&mut self,
frame_number: u32,
segment_frames: Arc<DecodedSegmentFrames>,
segment_index: u32,
transition: Option<CachedTransition>,
) {
let frame = (segment_frames, segment_index, transition);
let frame_bytes = cached_frame_byte_len(&frame);
if let Some((_, replaced)) = self.cache.push(frame_number, frame) {
self.cache_bytes = self
.cache_bytes
.saturating_sub(cached_frame_byte_len(&replaced));
}
self.cache_bytes = self.cache_bytes.saturating_add(frame_bytes);
while self.cache.len() > 1 && self.cache_bytes > self.max_bytes {
let Some((_, evicted)) = self.cache.pop_lru() else {
break;
};
self.cache_bytes = self
.cache_bytes
.saturating_sub(cached_frame_byte_len(&evicted));
}
}
fn evict_far_from(&mut self, current_frame: u32, max_distance: u32) {
let keys_to_remove: Vec<u32> = self
.cache
.iter()
.filter_map(|(k, _)| {
if (*k).abs_diff(current_frame) > max_distance {
Some(*k)
} else {
None
}
})
.collect();
for key in keys_to_remove {
if let Some(evicted) = self.cache.pop(&key) {
self.cache_bytes = self
.cache_bytes
.saturating_sub(cached_frame_byte_len(&evicted));
}
}
}
}
struct TransitionDecodeRequest {
decoders: RecordingSegmentDecoders,
segment_time: f64,
segment_index: u32,
offsets: ClipOffsets,
kind: ClipTransitionType,
progress: f32,
}
struct PrefetchDecodeRequest {
seek_generation: u64,
frame_number: u32,
decoders: RecordingSegmentDecoders,
segment_time: f64,
segment_index: u32,
offsets: ClipOffsets,
hide_camera: bool,
is_initial: bool,
transition: Option<TransitionDecodeRequest>,
}
type PrefetchDecodeResult = (
u64,
u32,
u32,
Option<DecodedSegmentFrames>,
Option<PrefetchedTransition>,
);
async fn decode_prefetched_frame(request: PrefetchDecodeRequest) -> PrefetchDecodeResult {
let PrefetchDecodeRequest {
seek_generation,
frame_number,
decoders,
segment_time,
segment_index,
offsets,
hide_camera,
is_initial,
transition,
} = request;
let primary = async {
if is_initial {
decoders
.get_frames_initial(segment_time as f32, !hide_camera, true, offsets)
.await
} else {
decoders
.get_frames(segment_time as f32, !hide_camera, true, offsets)
.await
}
};
let transition = async {
let transition = transition?;
let transition_decoders = if transition.segment_index == segment_index {
transition.decoders.transition_side().await
} else {
&transition.decoders
};
let segment_frames = if is_initial {
transition_decoders
.get_frames_initial(
transition.segment_time as f32,
!hide_camera,
true,
transition.offsets,
)
.await
} else {
transition_decoders
.get_frames(
transition.segment_time as f32,
!hide_camera,
true,
transition.offsets,
)
.await
}?;
Some(PrefetchedTransition {
segment_frames,
segment_index: transition.segment_index,
kind: transition.kind,
progress: transition.progress,
})
};
let (segment_frames, transition) = tokio::join!(primary, transition);
(
seek_generation,
frame_number,
segment_index,
segment_frames,
transition,
)
}
fn transition_decode_request(
project: &ProjectConfiguration,
segment_medias: &[SegmentMedia],
frame_time: f64,
) -> Option<TransitionDecodeRequest> {
let timeline = project.timeline.as_ref()?;
if timeline.transitions.is_empty() {
return None;
}
let TimelineFrameMapping::Transition {
outgoing,
kind,
progress,
..
} = timeline.get_frame_mapping(frame_time)?
else {
return None;
};
let segment_media = segment_medias.get(outgoing.segment.recording_clip as usize)?;
let offsets = project
.clips
.iter()
.find(|clip| clip.index == outgoing.segment.recording_clip)
.map(|clip| clip.offsets)
.unwrap_or_default();
Some(TransitionDecodeRequest {
decoders: segment_media.decoders.clone(),
segment_time: outgoing.source_time,
segment_index: outgoing.segment.recording_clip,
offsets,
kind,
progress: progress as f32,
})
}
impl Playback {
pub async fn start(
self,
fps: u32,
resolution_base: XY<u32>,
) -> Result<PlaybackHandle, PlaybackStartError> {
self.start_with_diagnostics(fps, resolution_base, None)
.await
}
pub async fn start_with_adopted_audio(
self,
fps: u32,
resolution_base: XY<u32>,
adoption: crate::PreparingPlaybackAdoption,
) -> Result<PlaybackHandle, PlaybackStartError> {
self.start_inner(fps, resolution_base, None, Some(adoption))
.await
}
pub async fn start_with_diagnostics(
self,
fps: u32,
resolution_base: XY<u32>,
resource: Option<u64>,
) -> Result<PlaybackHandle, PlaybackStartError> {
self.start_inner(fps, resolution_base, resource, None).await
}
async fn start_inner(
mut self,
fps: u32,
resolution_base: XY<u32>,
resource: Option<u64>,
adopted: Option<crate::PreparingPlaybackAdoption>,
) -> Result<PlaybackHandle, PlaybackStartError> {
let start_call = Instant::now();
let mut diagnostic = Operation::start(
"editor_playback",
&[
Field::number("requested_fps", fps as u64),
Field::number("requested_width", resolution_base.x as u64),
Field::number("requested_height", resolution_base.y as u64),
Field::number("start_frame", self.start_frame_number as u64),
Field::number("source_segments", self.segment_medias.len() as u64),
Field::flag("music", !self.music.is_empty()),
],
);
if let Some(resource) = resource {
diagnostic.field(Field::identifier("resource", resource));
}
let fps_f64 = fps as f64;
if !(fps_f64.is_finite() && fps_f64 > 0.0) {
warn!(fps, "Invalid FPS provided for playback start");
diagnostic.finish(false);
return Err(PlaybackStartError::InvalidFps);
}
let (stop_tx, mut stop_rx) = watch::channel(false);
stop_rx.borrow_and_update();
let (event_tx, mut event_rx) = watch::channel(PlaybackEvent::Start);
event_rx.borrow_and_update();
let (seek_tx, mut seek_rx) = watch::channel((0u64, self.start_frame_number));
seek_rx.borrow_and_update();
let preparing_audio_released = Arc::new(AtomicBool::new(false));
let runtime = tokio::runtime::Handle::current();
let handle = PlaybackHandle {
preparing_audio_released: preparing_audio_released.clone(),
stop_tx: stop_tx.clone(),
event_rx,
seek_tx: Arc::new(seek_tx),
seek_generation: Arc::new(AtomicU64::new(0)),
adopted: adopted.clone(),
};
let (prefetch_tx, prefetch_rx) = prefetch_channel(PREFETCH_CHANNEL_SIZE);
let prefetch_capacity = Arc::clone(&prefetch_rx.capacity);
let prefetch_fallback_wait = Duration::from_secs_f64(1.0 / fps_f64);
let (frame_request_tx, mut frame_request_rx) =
watch::channel((0u64, self.start_frame_number));
let (playback_position_tx, mut playback_position_rx) =
watch::channel(self.start_frame_number);
let prefetch_frame_limit = Arc::new(AtomicUsize::new(INITIAL_PREFETCH_BUFFER_SIZE));
let output_size = ProjectUniforms::get_output_size(
&self.render_constants.options,
&self.project.borrow(),
resolution_base,
);
self.renderer
.prepare_output_size(output_size.0, output_size.1);
let in_flight_frames: Arc<RwLock<HashSet<u32>>> = Arc::new(RwLock::new(HashSet::new()));
let prefetch_in_flight = in_flight_frames.clone();
let producer_prefetch_frame_limit = Arc::clone(&prefetch_frame_limit);
let _main_in_flight = in_flight_frames;
let mut prefetch_stop_rx = stop_rx.clone();
let mut prefetch_project = self.project.clone();
let prefetch_segment_medias = self.segment_medias.clone();
let (prefetch_duration, has_timeline) = self
.project
.borrow()
.timeline
.as_ref()
.and_then(|timeline| valid_playback_duration(timeline.duration()))
.map(|duration| (duration, true))
.unwrap_or((0.0, false));
let segment_media_count = self.segment_medias.len();
tokio::spawn(async move {
if !has_timeline {
warn!("Prefetch: No valid timeline duration found");
}
if segment_media_count == 0 {
warn!("Prefetch: No segment media available");
}
type PrefetchFuture =
std::pin::Pin<Box<dyn std::future::Future<Output = PrefetchDecodeResult> + Send>>;
let (mut seek_generation, mut next_prefetch_frame) =
*frame_request_rx.borrow_and_update();
let mut request_changed = false;
let mut in_flight: FuturesUnordered<PrefetchFuture> = FuturesUnordered::new();
let mut frames_decoded: u32 = 0;
let mut cached_project = prefetch_project.borrow().clone();
let mut pending_frame: Option<PrefetchedFrame> = None;
loop {
if *prefetch_stop_rx.borrow() {
break;
}
if prefetch_project.has_changed().unwrap_or(false) {
cached_project = prefetch_project.borrow_and_update().clone();
}
if request_changed || frame_request_rx.has_changed().unwrap_or(false) {
request_changed = false;
let (requested_generation, requested) = *frame_request_rx.borrow_and_update();
let generation_changed = requested_generation != seek_generation;
let reset = should_reset_prefetch(
seek_generation,
next_prefetch_frame,
requested_generation,
requested,
!in_flight.is_empty(),
);
seek_generation = requested_generation;
if reset {
let old_frame = next_prefetch_frame;
let is_backward_seek = requested < old_frame;
let seek_distance = if is_backward_seek {
old_frame - requested
} else {
requested - old_frame
};
next_prefetch_frame = requested;
frames_decoded = 0;
if let Ok(mut in_flight_guard) = prefetch_in_flight.write() {
in_flight_guard.clear();
}
let reset_distance =
producer_prefetch_frame_limit.load(Ordering::Relaxed).max(2) as u32 / 2;
if generation_changed || is_backward_seek || seek_distance > reset_distance
{
in_flight = FuturesUnordered::new();
}
if generation_changed {
pending_frame = None;
}
}
}
if let Some(frame) = pending_frame.take() {
match prefetch_tx.try_send(frame) {
Ok(()) => {}
Err(std_mpsc::TrySendError::Full(frame)) => {
pending_frame = Some(frame);
tokio::select! {
result = prefetch_stop_rx.changed() => {
if result.is_err() {
break;
}
}
result = frame_request_rx.changed() => {
if result.is_err() {
break;
}
request_changed = true;
}
_ = prefetch_capacity.notified() => {}
_ = tokio::time::sleep(prefetch_fallback_wait) => {}
}
continue;
}
Err(std_mpsc::TrySendError::Disconnected(_)) => break,
}
}
let current_playback_frame = *playback_position_rx.borrow_and_update();
let max_prefetch_ahead = producer_prefetch_frame_limit
.load(Ordering::Relaxed)
.clamp(INITIAL_PREFETCH_BUFFER_SIZE, MAX_PREFETCH_BUFFER_SIZE)
as u32;
let max_prefetch_frame = current_playback_frame + max_prefetch_ahead;
let initial_parallel_decode_tasks = INITIAL_PARALLEL_DECODE_TASKS;
let parallel_decode_tasks = PARALLEL_DECODE_TASKS;
let effective_parallel = if frames_decoded < RAMP_UP_FRAME_COUNT {
initial_parallel_decode_tasks
} else {
parallel_decode_tasks
};
while in_flight.len() < effective_parallel {
let frame_num = next_prefetch_frame;
if frame_num > max_prefetch_frame {
break;
}
let prefetch_time = frame_num as f64 / fps_f64;
if prefetch_time >= prefetch_duration {
next_prefetch_frame = next_prefetch_frame.saturating_add(1);
break;
}
let already_in_flight = prefetch_in_flight
.read()
.map(|guard| guard.contains(&frame_num))
.unwrap_or(false);
if already_in_flight {
next_prefetch_frame += 1;
continue;
}
if let Some((segment_time, segment)) =
cached_project.get_segment_time(prefetch_time)
&& let Some(segment_media) =
prefetch_segment_medias.get(segment.recording_clip as usize)
{
let clip_offsets = cached_project
.clips
.iter()
.find(|v| v.index == segment.recording_clip)
.map(|v| v.offsets)
.unwrap_or_default();
let decoders = segment_media.decoders.clone();
let hide_camera = !cached_project.requires_camera();
let segment_index = segment.recording_clip;
let is_initial = frames_decoded < 10;
let transition = transition_decode_request(
&cached_project,
&prefetch_segment_medias,
prefetch_time,
);
if let Ok(mut in_flight_guard) = prefetch_in_flight.write() {
in_flight_guard.insert(frame_num);
}
in_flight.push(Box::pin(decode_prefetched_frame(PrefetchDecodeRequest {
seek_generation,
frame_number: frame_num,
decoders,
segment_time,
segment_index,
offsets: clip_offsets,
hide_camera,
is_initial,
transition,
})));
}
next_prefetch_frame += 1;
}
tokio::select! {
biased;
result = prefetch_stop_rx.changed() => {
if result.is_err() {
break;
}
}
result = frame_request_rx.changed() => {
if result.is_err() {
break;
}
request_changed = true;
}
Some((generation, frame_num, segment_index, result, transition)) = in_flight.next() => {
if let Ok(mut in_flight_guard) = prefetch_in_flight.write() {
in_flight_guard.remove(&frame_num);
}
frames_decoded = frames_decoded.saturating_add(1);
if let Some(segment_frames) = result {
let frame = PrefetchedFrame {
seek_generation: generation,
frame_number: frame_num,
segment_frames,
segment_index,
transition,
};
match prefetch_tx.try_send(frame) {
Ok(()) => {}
Err(std_mpsc::TrySendError::Full(frame)) => {
pending_frame = Some(frame);
}
Err(std_mpsc::TrySendError::Disconnected(_)) => break,
}
} else if frames_decoded <= 5 {
warn!(
frame = frame_num,
segment = segment_index,
"Prefetch: decoder returned no frames"
);
}
}
result = playback_position_rx.changed(), if in_flight.is_empty() => {
if result.is_err() {
break;
}
}
_ = tokio::time::sleep(prefetch_fallback_wait), if in_flight.is_empty() => {}
}
}
});
// Resolve the background audio decodes before entering the sync
// playback thread. This only waits when playback starts before the
// decode kicked off at editor open has finished.
diagnostic.stage("waiting_for_audio_decode");
let audio_wait_start = Instant::now();
let audio_segments = get_audio_segments(&self.segment_medias).await;
if let Some(telemetry) = &self.telemetry {
telemetry.emit(PlaybackTelemetryEvent::AudioSegmentsResolved {
elapsed: audio_wait_start.elapsed(),
});
}
// Restarts an idle-paused output stream while the video warms up, so
// the play request after warmup finds it already running.
if adopted.is_none() && has_playback_audio(&audio_segments, !self.music.is_empty()) {
self.audio_output.prewarm();
}
diagnostic.field(Field::number(
"audio_decode_wait_ms",
audio_wait_start.elapsed().as_millis() as u64,
));
diagnostic.stage("preparing_playback");
let playback_body = move || {
let mut adopted_guard = AdoptedPlaybackGuard(adopted);
let adopted = &mut adopted_guard.0;
let duration = self
.project
.borrow()
.timeline
.as_ref()
.and_then(|timeline| valid_playback_duration(timeline.duration()));
let Some(duration) = duration else {
diagnostic.stage("invalid_timeline");
diagnostic.finish(false);
warn!("Playback: No valid timeline duration found");
stop_tx.send(true).ok();
event_tx.send(PlaybackEvent::Stop).ok();
return;
};
let (audio_playhead_tx, audio_playhead_rx) =
watch::channel(self.start_frame_number as f64 / fps as f64);
let frame_duration = Duration::from_secs_f64(1.0 / fps_f64);
let mut frame_number = self.start_frame_number;
let mut seek_generation = 0;
let mut prefetch_buffer: VecDeque<PrefetchedFrame> =
VecDeque::with_capacity(MAX_PREFETCH_BUFFER_SIZE + PREFETCH_CHANNEL_SIZE);
let mut frame_cache = FrameCache::new(FRAME_CACHE_SIZE, MAX_FRAME_CACHE_BYTES);
let mut largest_prefetched_frame_bytes = 0usize;
let mut total_frames_rendered = 0u64;
let mut total_frames_skipped = 0u64;
let mut cache_hits = 0u64;
let mut prefetch_hits = 0u64;
let sync_decodes = 0u64;
let mut last_stats_time = Instant::now();
let mut frames_at_last_stats = 0u64;
let stats_interval = Duration::from_secs(2);
let is_mid_start = self.start_frame_number > 0;
let warmup_target_frames = if is_mid_start { 30 } else { 10 };
let warmup_after_first_timeout = if is_mid_start {
Duration::from_millis(800)
} else {
Duration::from_millis(500)
};
let warmup_no_frames_timeout = Duration::from_secs(5);
let mut warmup_start = Instant::now();
let mut first_frame_time: Option<Instant> = None;
let mut boost_until: Option<Instant> = None;
let mut starvation_skips = 0u64;
while !*stop_rx.borrow() {
if adopted
.as_ref()
.is_some_and(|adoption| adoption.invalidated())
{
let _ = stop_tx.send(true);
break;
}
if let Some(snapshot) = adopted.as_ref().and_then(|adoption| adoption.snapshot()) {
let target = crate::preparing_handoff::presentation_frame(&snapshot, fps);
if target > frame_number {
frame_number = target;
prefetch_buffer.retain(|frame| frame.frame_number >= target);
let _ = frame_request_tx.send((seek_generation, target));
let _ = playback_position_tx.send(target);
}
}
refresh_prefetch_limit(
&prefetch_frame_limit,
largest_prefetched_frame_bytes,
boost_until,
);
if adopted.is_none() && seek_rx.has_changed().unwrap_or(false) {
(seek_generation, frame_number) = *seek_rx.borrow_and_update();
prefetch_buffer.clear();
first_frame_time = None;
warmup_start = Instant::now();
let _ = frame_request_tx.send((seek_generation, frame_number));
let _ = playback_position_tx.send(frame_number);
event_tx.send(PlaybackEvent::Frame(frame_number)).ok();
}
let should_start = if let Some(first_time) = first_frame_time {
prefetch_buffer
.iter()
.any(|p| p.frame_number == frame_number)
|| prefetch_buffer.len()
>= warmup_target_frames
.min(prefetch_frame_limit.load(Ordering::Relaxed))
|| first_time.elapsed() > warmup_after_first_timeout
} else {
false
};
if should_start {
break;
}
if first_frame_time.is_none() && warmup_start.elapsed() > warmup_no_frames_timeout {
warn!(
"Playback warmup timed out waiting for first frame after {:?}",
warmup_start.elapsed()
);
// Without the stop signal the prefetch producer task keeps
// decoding forever after an aborted warmup.
stop_tx.send(true).ok();
let _ = event_tx.send(PlaybackEvent::Stop);
return;
}
match receive_prefetched_frame(
&prefetch_rx,
seek_generation,
Duration::from_millis(50),
) {
Ok(prefetched) => {
if prefetched.frame_number >= frame_number {
observe_prefetched_frame(
&prefetched,
&mut largest_prefetched_frame_bytes,
);
prefetch_buffer.push_back(prefetched);
if first_frame_time.is_none() {
first_frame_time = Some(Instant::now());
}
}
while prefetch_buffer.len()
< warmup_target_frames.min(prefetch_frame_limit.load(Ordering::Relaxed))
{
match receive_prefetched_frame(
&prefetch_rx,
seek_generation,
Duration::ZERO,
) {
Ok(p) => {
if p.frame_number >= frame_number {
observe_prefetched_frame(
&p,
&mut largest_prefetched_frame_bytes,
);
prefetch_buffer.push_back(p);
}
}
Err(_) => break,
}
}
}
Err(std_mpsc::RecvTimeoutError::Timeout) => {}
Err(std_mpsc::RecvTimeoutError::Disconnected) => break,
}
}
prefetch_buffer
.make_contiguous()
.sort_by_key(|p| p.frame_number);
let playback_start_frame = frame_number;
let mut cached_project = Arc::new(self.project.borrow().clone());
let build_cursor_timelines =
|project: &ProjectConfiguration| -> Vec<Arc<PrecomputedCursorTimeline>> {
let cursor_smoothing =
(!project.cursor.raw).then_some(SpringMassDamperSimulationConfig {
tension: project.cursor.tension,
mass: project.cursor.mass,
friction: project.cursor.friction,
});
let click_spring = project.cursor.click_spring_config();
self.segment_medias
.iter()
.map(|seg| {
Arc::new(PrecomputedCursorTimeline::new(
&seg.cursor,
cursor_smoothing,
Some(click_spring),
))
})
.collect()
};
let build_zoom_timelines =
|project: &ProjectConfiguration| -> Vec<ZoomTransformTimeline> {
self.segment_medias
.iter()
.enumerate()
.map(|(recording_clip, seg)| {
ZoomTransformTimeline::from_project_for_clip(
project,
&seg.cursor,
duration,
self.render_constants.options.screen_size,
recording_clip as u32,
)
})
.collect()
};
let build_outgoing_zoom_timelines =
|project: &ProjectConfiguration| -> Vec<ZoomTransformTimeline> {
if project
.timeline
.as_ref()
.is_none_or(|timeline| timeline.transitions.is_empty())
{
return Vec::new();
}
self.segment_medias
.iter()
.enumerate()
.map(|(recording_clip, segment)| {
ZoomTransformTimeline::from_project_for_outgoing_clip(
project,
&segment.cursor,
duration,
self.render_constants.options.screen_size,
recording_clip as u32,
)
})
.collect()
};
let mut cursor_timelines = build_cursor_timelines(&cached_project);
let mut zoom_timelines = build_zoom_timelines(&cached_project);
let mut outgoing_zoom_timelines = build_outgoing_zoom_timelines(&cached_project);
if !*stop_rx.borrow()
&& let Some(prefetched_idx) = prefetch_buffer
.iter()
.position(|p| p.frame_number == frame_number)
{
let frame_acquire_start = Instant::now();
let prefetched = prefetch_buffer.remove(prefetched_idx).unwrap();
let frame_acquire_duration = frame_acquire_start.elapsed();
let (segment_frames, segment_index, transition) = prefetched.into_cached();
if let Some(segment_media) = self.segment_medias.get(segment_index as usize) {
let zoom_until = (frame_number as f32 + 1.0) / fps as f32;
if let Some(timeline) = zoom_timelines.get_mut(segment_index as usize) {
timeline.ensure_precomputed_until(zoom_until);
}
if let Some(timeline) = outgoing_zoom_timelines.get_mut(segment_index as usize)
{
timeline.ensure_precomputed_until(zoom_until);
}
let zoom_timeline = zoom_timelines.get(segment_index as usize);
let empty_timeline;
let zoom_ref = match zoom_timeline {
Some(timeline) => timeline,
None => {
empty_timeline = ZoomTransformTimeline::new(
&[],
None,
&segment_media.cursor,
cached_project.screen_movement_spring,
duration,
None,
);
&empty_timeline
}
};
let precomputed_cursor = &cursor_timelines[segment_index as usize];
let uniforms_start = Instant::now();
let uniforms = ProjectUniforms::new_with_precomputed_cursor(
&self.render_constants,
&cached_project,
frame_number,
fps,
resolution_base,
&segment_media.cursor,
&segment_frames,
duration,
zoom_ref,
precomputed_cursor,
);
let uniforms_duration = uniforms_start.elapsed();
let submit_start = Instant::now();
let submitted_frame_number = frame_number;
let rendered = if let Some((outgoing_frames, outgoing_index, kind, progress)) =
transition
{
let outgoing_media = &self.segment_medias[outgoing_index as usize];
if let Some(timeline) =
outgoing_zoom_timelines.get_mut(outgoing_index as usize)
{
timeline.ensure_precomputed_until(zoom_until);
}
let outgoing_zoom = &outgoing_zoom_timelines[outgoing_index as usize];
let outgoing_uniforms = ProjectUniforms::new_with_precomputed_cursor(
&self.render_constants,
&cached_project,
frame_number,
fps,
resolution_base,
&outgoing_media.cursor,
&outgoing_frames,
duration,
outgoing_zoom,
&cursor_timelines[outgoing_index as usize],
);
self.renderer.render_transition_frame_wait(
editor::RendererTransitionInput {
segment_frames: Arc::unwrap_or_clone(outgoing_frames),
uniforms: outgoing_uniforms,
cursor: outgoing_media.cursor.clone(),
},
editor::RendererTransitionInput {
segment_frames: Arc::unwrap_or_clone(segment_frames),
uniforms,
cursor: segment_media.cursor.clone(),
},
kind,
progress,
)
} else {
self.renderer.render_frame_wait(
Arc::unwrap_or_clone(segment_frames),
uniforms,
segment_media.cursor.clone(),
)
};
let submit_duration = submit_start.elapsed();
if rendered {
if let Some(telemetry) = &self.telemetry {
telemetry.emit(PlaybackTelemetryEvent::FrameSubmitted {
frame_number: submitted_frame_number,
source: PlaybackFrameSource::InitialPrerender,
schedule_overshoot: Duration::ZERO,
frame_acquire_duration,
uniforms_duration,
submit_duration,
prefetch_buffer_len: prefetch_buffer.len(),
total_frames_skipped,
});
}
total_frames_rendered += 1;
event_tx.send(PlaybackEvent::Frame(frame_number)).ok();
frame_number = frame_number.saturating_add(1);
let _ = playback_position_tx.send(frame_number);
}
}
}
while prefetch_buffer.len()
< warmup_target_frames.min(prefetch_frame_limit.load(Ordering::Relaxed))
{
match receive_prefetched_frame(&prefetch_rx, seek_generation, Duration::ZERO) {
Ok(prefetched) => {
if prefetched.frame_number >= frame_number {
observe_prefetched_frame(
&prefetched,
&mut largest_prefetched_frame_bytes,
);
prefetch_buffer.push_back(prefetched);
}
}
Err(_) => break,
}
}
prefetch_buffer
.make_contiguous()
.sort_by_key(|p| p.frame_number);
if let Some(telemetry) = &self.telemetry {
telemetry.emit(PlaybackTelemetryEvent::WarmupComplete {
elapsed: warmup_start.elapsed(),
buffered_frames: prefetch_buffer.len(),
target_frames: warmup_target_frames,
start_frame_number: playback_start_frame,
});
}
#[cfg(target_os = "windows")]
let _timer_guard = WindowsTimerResolution::set_high_precision();
#[cfg(target_os = "windows")]
raise_playback_thread_priority();
// Attach this playback's audio to the session's persistent output
// stream. Blocks until the live callback is consuming the source,
// so the clock below never runs ahead of audible audio.
diagnostic.field(Field::number(
"warmup_ms",
warmup_start.elapsed().as_millis() as u64,
));
diagnostic.stage("initializing_audio_output");
let audio_spawn_start = Instant::now();
let _ = audio_playhead_tx.send(playback_start_frame as f64 / fps_f64);
let mut audio_generation = if adopted.is_some() {
None
} else if !has_playback_audio(&audio_segments, !self.music.is_empty()) {
info!("No audio segments found, skipping audio playback.");
None
} else {
self.audio_output.play(PlaySpec {
segments: audio_segments.clone(),
music: self.music.clone(),
project: self.project.borrow().clone(),
duration_secs: duration,
start_playhead_secs: playback_start_frame as f64 / fps_f64,
playhead_rx: audio_playhead_rx.clone(),
})
};
let mut has_audio = audio_generation.is_some();
if let Some(telemetry) = &self.telemetry {
telemetry.emit(PlaybackTelemetryEvent::AudioPipelineReady {
elapsed: audio_spawn_start.elapsed(),
has_audio,
});
telemetry.emit(PlaybackTelemetryEvent::ClockStarted {
elapsed: start_call.elapsed(),
});
}
diagnostic.field(Field::number(
"audio_output_init_ms",
audio_spawn_start.elapsed().as_millis() as u64,
));
diagnostic.field(Field::number(
"clock_start_ms",
start_call.elapsed().as_millis() as u64,
));
diagnostic.field(Field::flag("audio_output_started", has_audio));
diagnostic.stage("playing");
let mut start = Instant::now();
let mut clock_anchor_frame = playback_start_frame;
let mut transitioned_audio = None;
let mut last_adopted_frame = None;
'playback: loop {
if *stop_rx.borrow() {
break;
}
if adopted.as_ref().is_some_and(|adoption| adoption.is_owner()) && {
let project = self.project.borrow();
project.audio.improve
|| project.audio != cached_project.audio
|| clip_audio_changed(&cached_project, &project)
} {
let adoption = adopted.as_ref().unwrap();
frame_number = adoption.frame_number(fps).unwrap_or(frame_number);
let cleaned = runtime.block_on(async {
tokio::select! {
biased;
_ = stop_rx.changed() => false,
result = tokio::time::timeout(Duration::from_secs(2), adoption.stop_and_wait()) => {
matches!(result, Ok(Some(exit)) if !exit.cleanup_failed)
}
}
});
if !cleaned || *stop_rx.borrow() {
break;
}
drop(adopted.take());
preparing_audio_released.store(true, Ordering::Release);
let project = self.project.borrow().clone();
Arc::make_mut(&mut cached_project).audio = project.audio.clone();
let ticket = self.audio_output.prepare_playback(PlaySpec {
segments: audio_segments.clone(),
music: self.music.clone(),
project,
duration_secs: duration,
start_playhead_secs: frame_number as f64 / fps_f64,
playhead_rx: audio_playhead_rx.clone(),
});
let started = runtime.block_on(async {
tokio::select! {
biased;
_ = stop_rx.changed() => false,
result = tokio::time::timeout(Duration::from_secs(2), ticket.wait_started()) => result.unwrap_or(false),
}
});
if !started || *stop_rx.borrow() {
break;
}
audio_generation = Some(ticket.generation());
transitioned_audio = Some(ticket);
has_audio = true;
clock_anchor_frame = frame_number;
start = Instant::now();
}
if let Some(adoption) = adopted {
let Some(snapshot) = adoption.snapshot() else {
break;
};
if snapshot.progress.phase == crate::PreparingEditorPhase::Unavailable {
break;
}
let target = crate::preparing_handoff::presentation_frame(&snapshot, fps);
if snapshot.playback.buffering || last_adopted_frame == Some(target) {
if !snapshot.playback.playing && adoption.is_owner() {
break;
}
std::thread::sleep(frame_duration);
continue;
}
frame_number = target;
let _ = playback_position_tx.send(target);
}
let limit_now = refresh_prefetch_limit(
&prefetch_frame_limit,
largest_prefetched_frame_bytes,
boost_until,
);
if adopted.is_none() && seek_rx.has_changed().unwrap_or(false) {
let (generation, target) = *seek_rx.borrow_and_update();
tracing::debug!(from = frame_number, to = target, "playback live seek");
seek_generation = generation;
frame_number = target;
clock_anchor_frame = target;
start = Instant::now();
prefetch_buffer.clear();
frame_cache.evict_far_from(target, limit_now as u32);
let _ = frame_request_tx.send((seek_generation, target));
let _ = playback_position_tx.send(target);
event_tx.send(PlaybackEvent::Frame(target)).ok();
if has_audio && audio_playhead_tx.send(target as f64 / fps_f64).is_err() {
break 'playback;
}
continue;
}
if self.project.has_changed().unwrap_or(false) {
let next_project = self.project.borrow_and_update().clone();
let audio_changed = cached_project.audio != next_project.audio
|| clip_audio_changed(&cached_project, &next_project);
let cursor_changed = cursor_timeline_settings(&cached_project.cursor)
!= cursor_timeline_settings(&next_project.cursor);
let zoom_changed = !ZoomTransformTimeline::project_inputs_match(
&cached_project,
&next_project,
self.render_constants.options.screen_size,
);
cached_project = Arc::new(next_project);
if adopted.is_none()
&& audio_changed
&& let Some(generation) = audio_generation
{
self.audio_output.refresh_playback(
PlaySpec {
segments: audio_segments.clone(),
music: self.music.clone(),
project: (*cached_project).clone(),
duration_secs: duration,
start_playhead_secs: frame_number as f64 / fps_f64,
playhead_rx: audio_playhead_rx.clone(),
},
generation,
);
}
if cursor_changed {
cursor_timelines = build_cursor_timelines(&cached_project);
}
if zoom_changed {
zoom_timelines = build_zoom_timelines(&cached_project);
outgoing_zoom_timelines = build_outgoing_zoom_timelines(&cached_project);
}
}
let frame_offset = frame_number.saturating_sub(clock_anchor_frame) as f64;
let next_deadline = start + frame_duration.mul_f64(frame_offset);
if adopted.is_none() {
precision_sleep_sync(next_deadline);
}
if *stop_rx.borrow() {
break;
}
let overshoot = if adopted.is_some() {
Duration::ZERO
} else {
Instant::now().saturating_duration_since(next_deadline)
};
if adopted.is_none() && overshoot > frame_duration + frame_duration / 2 {
let frames_behind = (overshoot.as_secs_f64() * fps_f64).floor() as u32;
let skip = frames_behind.max(1);
let skipped_from = frame_number;
frame_number += skip;
total_frames_skipped += skip as u64;
while prefetch_buffer
.front()
.is_some_and(|f| f.frame_number < frame_number)
{
prefetch_buffer.pop_front();
}
frame_cache.evict_far_from(
frame_number,
prefetch_frame_limit.load(Ordering::Relaxed) as u32,
);
let _ = frame_request_tx.send((seek_generation, frame_number));
let _ = playback_position_tx.send(frame_number);
if let Some(telemetry) = &self.telemetry {
telemetry.emit(PlaybackTelemetryEvent::FrameSkipped {
frame_number: skipped_from,
skipped: skip,
reason: PlaybackSkipReason::ScheduleOvershoot,
prefetch_buffer_len: prefetch_buffer.len(),
});
}
if has_audio
&& audio_playhead_tx
.send(frame_number as f64 / fps_f64)
.is_err()
{
break 'playback;
}
continue;
}
prefetch_buffer.retain(|p| p.frame_number >= frame_number);
let drain_budget = 16usize;
let mut drained = 0usize;
while prefetch_buffer.len() < prefetch_frame_limit.load(Ordering::Relaxed)
&& drained < drain_budget
{
match receive_prefetched_frame(&prefetch_rx, seek_generation, Duration::ZERO) {
Ok(prefetched) => {
drained += 1;
if prefetched.frame_number >= frame_number {
observe_prefetched_frame(
&prefetched,
&mut largest_prefetched_frame_bytes,
);
prefetch_buffer.push_back(prefetched);
}
}
Err(_) => break,
}
}
let playback_time = frame_number as f64 / fps_f64;
if playback_time >= duration {
break;
}
let mut was_cached = false;
let frame_acquire_start = Instant::now();
let mut frame_source = PlaybackFrameSource::Cache;
let segment_frames_opt = if let Some(cached) = frame_cache.get(frame_number) {
was_cached = true;
cache_hits += 1;
Some(cached)
} else if adopted.is_some() {
let mut exact = prefetch_buffer
.iter()
.position(|frame| frame.frame_number == frame_number)
.and_then(|index| prefetch_buffer.remove(index));
if exact.is_none() {
let _ = frame_request_tx.send((seek_generation, frame_number));
match receive_prefetched_frame(
&prefetch_rx,
seek_generation,
frame_duration,
) {
Ok(frame) if frame.frame_number == frame_number => exact = Some(frame),
Ok(frame) if frame.frame_number > frame_number => {
prefetch_buffer.push_back(frame)
}
Ok(_) | Err(std_mpsc::RecvTimeoutError::Timeout) => {}
Err(std_mpsc::RecvTimeoutError::Disconnected) => break 'playback,
}
}
let Some(frame) = exact else {
continue;
};
frame_source = PlaybackFrameSource::PrefetchWaitExact;
Some(frame.into_cached())
} else if prefetch_buffer
.front()
.is_some_and(|f| f.frame_number == frame_number)
{
frame_source = PlaybackFrameSource::PrefetchFront;
let prefetched = prefetch_buffer.pop_front().unwrap();
prefetch_hits += 1;
Some(prefetched.into_cached())
} else {
let prefetched_idx = prefetch_buffer
.iter()
.position(|p| p.frame_number == frame_number);
if let Some(idx) = prefetched_idx {
frame_source = PlaybackFrameSource::PrefetchSearch;
let prefetched = prefetch_buffer.remove(idx).unwrap();
prefetch_hits += 1;
Some(prefetched.into_cached())
} else if prefetch_buffer.is_empty() {
let _ = frame_request_tx.send((seek_generation, frame_number));
let wait_ms = if total_frames_rendered < 15 { 20 } else { 8 };
let prefetched_opt = match receive_prefetched_frame(
&prefetch_rx,
seek_generation,
Duration::from_millis(wait_ms),
) {
Ok(p) => Some(p),
Err(std_mpsc::RecvTimeoutError::Timeout) => receive_prefetched_frame(
&prefetch_rx,
seek_generation,
Duration::ZERO,
)
.ok(),
Err(std_mpsc::RecvTimeoutError::Disconnected) => {
break 'playback;
}
};
match prefetched_opt {
Some(prefetched) => {
observe_prefetched_frame(
&prefetched,
&mut largest_prefetched_frame_bytes,
);
if prefetched.frame_number == frame_number {
frame_source = PlaybackFrameSource::PrefetchWaitExact;
Some(prefetched.into_cached())
} else if prefetched.frame_number > frame_number {
frame_source = PlaybackFrameSource::PrefetchWaitFuture;
let skipped_from = frame_number;
frame_number = prefetched.frame_number;
total_frames_skipped += 1;
starvation_skips += 1;
boost_until = Some(Instant::now() + BOOST_CLEAN_WINDOW);
if let Some(telemetry) = &self.telemetry {
telemetry.emit(PlaybackTelemetryEvent::FrameSkipped {
frame_number: skipped_from,
skipped: 1,
reason: PlaybackSkipReason::PrefetchGap,
prefetch_buffer_len: prefetch_buffer.len(),
});
}
Some(prefetched.into_cached())
} else {
prefetch_buffer.push_back(prefetched);
let skipped_from = frame_number;
frame_number = frame_number.saturating_add(1);
total_frames_skipped += 1;
starvation_skips += 1;
boost_until = Some(Instant::now() + BOOST_CLEAN_WINDOW);
if let Some(telemetry) = &self.telemetry {
telemetry.emit(PlaybackTelemetryEvent::FrameSkipped {
frame_number: skipped_from,
skipped: 1,
reason: PlaybackSkipReason::PrefetchBehind,
prefetch_buffer_len: prefetch_buffer.len(),
});
}
continue;
}
}
None => {
let skipped_from = frame_number;
frame_number = frame_number.saturating_add(1);
total_frames_skipped += 1;
starvation_skips += 1;
boost_until = Some(Instant::now() + BOOST_CLEAN_WINDOW);
let _ = frame_request_tx.send((seek_generation, frame_number));
let _ = playback_position_tx.send(frame_number);
if let Some(telemetry) = &self.telemetry {
telemetry.emit(PlaybackTelemetryEvent::FrameSkipped {
frame_number: skipped_from,
skipped: 1,
reason: PlaybackSkipReason::PrefetchTimeout,
prefetch_buffer_len: prefetch_buffer.len(),
});
}
if has_audio
&& audio_playhead_tx
.send(frame_number as f64 / fps_f64)
.is_err()
{
break 'playback;
}
continue;
}
}
} else {
// IMPORTANT: Do NOT send frame_request_tx from these skip paths.
// frame_request_tx resets the prefetch pipeline's next_prefetch_frame
// via a watch channel. Since the prefetch is already decoding well ahead
// (e.g. next_prefetch_frame=119), sending a lower frame number here
// (e.g. 63) is interpreted as a backward seek, which clears ALL in-flight
// decode tasks via `in_flight = FuturesUnordered::new()`. This creates a
// cascading failure: dropped decode tasks create more gaps → more skips
// → more resets → progressively worse playback. The prefetch already
// tracks playback position via playback_position_tx/rx.
//
// Note: the overshoot skip (above) and clock-drift skip (below) DO still
// send frame_request_tx because those advance frame_number forward from
// the playback clock, which the prefetch correctly treats as demand for
// higher frames. These buffer-gap skips are different — the frame_number
// we'd send is always BEHIND the prefetch's next_prefetch_frame.
//
// Before jumping, drain all available frames from the rx channel. The
// regular drain budget of 16 per iteration can miss frames that arrived
// between the drain and the buffer check. This protects both the
// jump-to-min path and the +1 fallback path below.
let late_drain_limit = prefetch_frame_limit
.load(Ordering::Relaxed)
.saturating_add(PREFETCH_CHANNEL_SIZE);
while prefetch_buffer.len() < late_drain_limit {
match receive_prefetched_frame(
&prefetch_rx,
seek_generation,
Duration::ZERO,
) {
Ok(p) => {
if p.frame_number >= frame_number {
observe_prefetched_frame(
&p,
&mut largest_prefetched_frame_bytes,
);
prefetch_buffer.push_back(p);
}
}
Err(_) => break,
}
}
if let Some(late_idx) = prefetch_buffer
.iter()
.position(|p| p.frame_number == frame_number)
{
frame_source = PlaybackFrameSource::LateDrain;
let prefetched = prefetch_buffer.remove(late_idx).unwrap();
prefetch_hits += 1;
Some(prefetched.into_cached())
} else {
let min_buffered = prefetch_buffer.iter().map(|p| p.frame_number).min();
if let Some(next_available_frame) = min_buffered
&& next_available_frame > frame_number
{
let jumped = next_available_frame - frame_number;
let skipped_from = frame_number;
frame_number = next_available_frame;
total_frames_skipped += jumped as u64;
starvation_skips += jumped as u64;
boost_until = Some(Instant::now() + BOOST_CLEAN_WINDOW);
let _ = playback_position_tx.send(frame_number);
if let Some(telemetry) = &self.telemetry {
telemetry.emit(PlaybackTelemetryEvent::FrameSkipped {
frame_number: skipped_from,
skipped: jumped,
reason: PlaybackSkipReason::PrefetchGap,
prefetch_buffer_len: prefetch_buffer.len(),
});
}
if has_audio
&& audio_playhead_tx
.send(frame_number as f64 / fps_f64)
.is_err()
{
break 'playback;
}
continue;
}
let skipped_from = frame_number;
frame_number = frame_number.saturating_add(1);
total_frames_skipped += 1;
starvation_skips += 1;
boost_until = Some(Instant::now() + BOOST_CLEAN_WINDOW);
let _ = playback_position_tx.send(frame_number);
if let Some(telemetry) = &self.telemetry {
telemetry.emit(PlaybackTelemetryEvent::FrameSkipped {
frame_number: skipped_from,
skipped: 1,
reason: PlaybackSkipReason::PrefetchGap,
prefetch_buffer_len: prefetch_buffer.len(),
});
}
if has_audio
&& audio_playhead_tx
.send(frame_number as f64 / fps_f64)
.is_err()
{
break 'playback;
}
continue;
}
}
};
let frame_acquire_duration = frame_acquire_start.elapsed();
if let Some((segment_frames, segment_index, transition)) = segment_frames_opt {
let Some(segment_media) = self.segment_medias.get(segment_index as usize)
else {
if adopted.is_some() {
break;
}
frame_number = frame_number.saturating_add(1);
continue;
};
if !was_cached {
frame_cache.insert(
frame_number,
Arc::clone(&segment_frames),
segment_index,
transition.as_ref().map(
|(frames, transition_index, kind, progress)| {
(Arc::clone(frames), *transition_index, *kind, *progress)
},
),
);
}
let zoom_until = (frame_number as f32 + 1.0) / fps as f32;
if let Some(timeline) = zoom_timelines.get_mut(segment_index as usize) {
timeline.ensure_precomputed_until(zoom_until);
}
if let Some(timeline) = outgoing_zoom_timelines.get_mut(segment_index as usize)
{
timeline.ensure_precomputed_until(zoom_until);
}
let zoom_timeline = zoom_timelines.get(segment_index as usize);
let empty_timeline;
let zoom_ref = match zoom_timeline {
Some(timeline) => timeline,
None => {
empty_timeline = ZoomTransformTimeline::new(
&[],
None,
&segment_media.cursor,
cached_project.screen_movement_spring,
duration,
None,
);
&empty_timeline
}
};
let precomputed_cursor = &cursor_timelines[segment_index as usize];
let uniforms_start = Instant::now();
let uniforms = ProjectUniforms::new_with_precomputed_cursor(
&self.render_constants,
&cached_project,
frame_number,
fps,
resolution_base,
&segment_media.cursor,
&segment_frames,
duration,
zoom_ref,
precomputed_cursor,
);
let uniforms_duration = uniforms_start.elapsed();
let submit_start = Instant::now();
let submitted_frame_number = frame_number;
if let Some((outgoing_frames, outgoing_index, kind, progress)) = transition {
let outgoing_media = &self.segment_medias[outgoing_index as usize];
if let Some(timeline) =
outgoing_zoom_timelines.get_mut(outgoing_index as usize)
{
timeline.ensure_precomputed_until(zoom_until);
}
let outgoing_uniforms = ProjectUniforms::new_with_precomputed_cursor(
&self.render_constants,
&cached_project,
frame_number,
fps,
resolution_base,
&outgoing_media.cursor,
&outgoing_frames,
duration,
&outgoing_zoom_timelines[outgoing_index as usize],
&cursor_timelines[outgoing_index as usize],
);
self.renderer.render_transition_frame(
editor::RendererTransitionInput {
segment_frames: Arc::unwrap_or_clone(outgoing_frames),
uniforms: outgoing_uniforms,
cursor: outgoing_media.cursor.clone(),
},
editor::RendererTransitionInput {
segment_frames: Arc::unwrap_or_clone(segment_frames),
uniforms,
cursor: segment_media.cursor.clone(),
},
kind,
progress,
);
} else {
self.renderer.render_frame(
Arc::unwrap_or_clone(segment_frames),
uniforms,
segment_media.cursor.clone(),
);
}
let submit_duration = submit_start.elapsed();
if let Some(telemetry) = &self.telemetry {
telemetry.emit(PlaybackTelemetryEvent::FrameSubmitted {
frame_number: submitted_frame_number,
source: frame_source,
schedule_overshoot: overshoot,
frame_acquire_duration,
uniforms_duration,
submit_duration,
prefetch_buffer_len: prefetch_buffer.len(),
total_frames_skipped,
});
}
total_frames_rendered += 1;
}
if last_stats_time.elapsed() >= stats_interval {
// Rate over the reporting window, not since `start`: a live
// seek re-anchors `start`, so a lifetime average would read
// thousands of fps right after a scrub.
let window_secs = last_stats_time.elapsed().as_secs_f64().max(0.001);
let effective_fps = total_frames_rendered.saturating_sub(frames_at_last_stats)
as f64
/ window_secs;
frames_at_last_stats = total_frames_rendered;
let buffer_len = prefetch_buffer.len();
info!(
effective_fps = format!("{:.1}", effective_fps),
total_rendered = total_frames_rendered,
total_skipped = total_frames_skipped,
starved = starvation_skips,
cache_hits = cache_hits,
prefetch_hits = prefetch_hits,
sync_decodes = sync_decodes,
prefetch_buffer = buffer_len,
prefetch_limit = prefetch_frame_limit.load(Ordering::Relaxed),
"Playback stats"
);
last_stats_time = Instant::now();
}
event_tx.send(PlaybackEvent::Frame(frame_number)).ok();
if adopted.is_some() {
last_adopted_frame = Some(frame_number);
continue;
}
frame_number = frame_number.saturating_add(1);
let _ = playback_position_tx.send(frame_number);
if has_audio
&& audio_playhead_tx
.send(frame_number as f64 / fps_f64)
.is_err()
{
break 'playback;
}
let expected_frame =
clock_anchor_frame + (start.elapsed().as_secs_f64() * fps_f64).floor() as u32;
if frame_number < expected_frame {
let frames_behind = expected_frame - frame_number;
if frames_behind <= 2 {
continue;
}
let skipped = frames_behind;
let skipped_from = frame_number;
frame_number += skipped;
total_frames_skipped += skipped as u64;
while prefetch_buffer
.front()
.is_some_and(|f| f.frame_number < frame_number)
{
prefetch_buffer.pop_front();
}
frame_cache.evict_far_from(
frame_number,
prefetch_frame_limit.load(Ordering::Relaxed) as u32,
);
let _ = frame_request_tx.send((seek_generation, frame_number));
let _ = playback_position_tx.send(frame_number);
if let Some(telemetry) = &self.telemetry {
telemetry.emit(PlaybackTelemetryEvent::FrameSkipped {
frame_number: skipped_from,
skipped,
reason: PlaybackSkipReason::ClockDrift,
prefetch_buffer_len: prefetch_buffer.len(),
});
}
if has_audio
&& audio_playhead_tx
.send(frame_number as f64 / fps_f64)
.is_err()
{
break 'playback;
}
}
}
diagnostic.field(Field::number("frames_skipped", total_frames_skipped));
diagnostic.stage("loop_ended");
diagnostic.finish(true);
if let Some(generation) = audio_generation {
self.audio_output.stop_playback(generation);
}
drop(transitioned_audio);
stop_tx.send(true).ok();
event_tx.send(PlaybackEvent::Stop).ok();
};
std::thread::Builder::new()
.name("cap-playback".into())
.spawn(playback_body)
.expect("failed to spawn playback thread");
Ok(handle)
}
}
struct AdoptedPlaybackGuard(Option<crate::PreparingPlaybackAdoption>);
impl Drop for AdoptedPlaybackGuard {
fn drop(&mut self) {
if let Some(adoption) = &self.0 {
adoption.cancel();
}
}
}
impl PlaybackHandle {
pub(crate) fn preparing_audio_released(&self) -> bool {
self.preparing_audio_released.load(Ordering::Acquire)
}
pub fn stop(&self) {
if let Some(adoption) = &self.adopted {
adoption.cancel();
}
self.stop_tx.send(true).ok();
}
/// Seek the running playback in place: no teardown, no warmup, no audio
/// re-attach. Returns false once the playback thread is gone, which is the
/// caller's cue to fall back to a full restart.
pub fn seek(&self, frame: u32) -> bool {
if self.adopted.is_some() && !self.preparing_audio_released() {
return false;
}
let generation = self.seek_generation.fetch_add(1, Ordering::Relaxed) + 1;
self.seek_tx.send((generation, frame)).is_ok()
}
pub async fn receive_event(&mut self) -> watch::Ref<'_, PlaybackEvent> {
self.event_rx.changed().await.ok();
self.event_rx.borrow_and_update()
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn precision_sleep_returns_at_its_deadline() {
for micros in [0, 50, 250, 900, 2_100, 16_667, 33_333] {
let deadline = Instant::now() + Duration::from_micros(micros);
precision_sleep_sync(deadline);
let late = Instant::now()
.checked_duration_since(deadline)
.unwrap_or_else(|| panic!("{micros} us sleep returned early"));
assert!(
late < Duration::from_secs(1),
"{micros} us sleep returned {late:?} late"
);
}
let start = Instant::now();
precision_sleep_sync(start);
assert!(start.elapsed() < Duration::from_millis(100));
}
// Every supported runner is Windows 10 1803 or later; the spin fallback
// is for older builds.
#[cfg(target_os = "windows")]
#[test]
fn windows_has_a_high_resolution_waitable_timer() {
let timer = WindowsWaitableTimer::high_resolution().expect("high-resolution timer");
let start = Instant::now();
assert!(timer.sleep(Duration::from_millis(5)));
assert!(start.elapsed() >= Duration::from_millis(4));
}
/// Pacing cost and accuracy of the playback sleep at 30 and 60 fps:
/// `cargo test -p cap-editor --lib playback::tests::precision_sleep_pacing -- --ignored --nocapture`
#[cfg(target_os = "windows")]
#[test]
#[ignore]
fn precision_sleep_pacing() {
fn thread_cpu() -> Duration {
use windows::Win32::{
Foundation::FILETIME,
System::Threading::{GetCurrentThread, GetThreadTimes},
};
let [mut creation, mut exit, mut kernel, mut user] = [FILETIME::default(); 4];
unsafe {
GetThreadTimes(
GetCurrentThread(),
&mut creation,
&mut exit,
&mut kernel,
&mut user,
)
.unwrap();
}
let ticks =
|t: FILETIME| (u64::from(t.dwHighDateTime) << 32) | u64::from(t.dwLowDateTime);
Duration::from_nanos((ticks(kernel) + ticks(user)) * 100)
}
let _timer_guard = WindowsTimerResolution::set_high_precision();
raise_playback_thread_priority();
for fps in [30u32, 60] {
let frame = Duration::from_secs(1) / fps;
let frames = fps * 10;
let cpu_start = thread_cpu();
let start = Instant::now();
let mut late_us = Vec::with_capacity(frames as usize);
for n in 1..=frames {
let deadline = start + frame * n;
precision_sleep_sync(deadline);
late_us.push(Instant::now().duration_since(deadline).as_secs_f64() * 1e6);
}
let cpu = thread_cpu().saturating_sub(cpu_start).as_secs_f64()
/ start.elapsed().as_secs_f64();
late_us.sort_by(f64::total_cmp);
let at = |q: f64| late_us[((late_us.len() - 1) as f64 * q).round() as usize];
println!(
"pacing fps={fps} cpu={:.1}% late_us p50={:.0} p95={:.0} p99={:.0} max={:.0}",
cpu * 100.0,
at(0.5),
at(0.95),
at(0.99),
at(1.0)
);
}
}
#[test]
fn source_audio_offset_edits_refresh_playback_for_the_recording_clip() {
let project: ProjectConfiguration = serde_json::from_value(serde_json::json!({
"clips": [{ "index": 1 }, { "index": 0 }],
"timeline": { "zoomSegments": [], "segments": [
{ "recordingSegment": 0, "start": 0.0, "end": 2.0, "timescale": 1.0 },
{ "recordingSegment": 1, "start": 1.0, "end": 3.0, "timescale": 2.0 }
] }
}))
.unwrap();
for clip in 0..project.clips.len() {
for offset in [-0.1, 0.1] {
let mut next = project.clone();
next.clips[clip].offsets.mic = offset;
assert!(clip_audio_changed(&project, &next));
assert!(clip_audio_changed(&next, &project));
let mut next = project.clone();
next.clips[clip].offsets.system_audio = offset;
assert!(clip_audio_changed(&project, &next));
assert!(clip_audio_changed(&next, &project));
}
}
}
#[test]
fn visual_and_unused_clip_offsets_do_not_refresh_playback_audio() {
let project: ProjectConfiguration = serde_json::from_value(serde_json::json!({
"timeline": { "zoomSegments": [], "segments": [
{ "recordingSegment": 0, "start": 0.0, "end": 2.0, "timescale": 1.0 }
] }
}))
.unwrap();
let mut next = project.clone();
next.clips.push(cap_project::ClipConfiguration {
index: 0,
offsets_auto_calculated: true,
offsets: ClipOffsets {
camera: 0.1,
..Default::default()
},
});
next.clips.push(cap_project::ClipConfiguration {
index: 1,
offsets: ClipOffsets {
mic: 0.1,
system_audio: -0.1,
..Default::default()
},
..Default::default()
});
assert!(!clip_audio_changed(&project, &next));
next.clips.reverse();
assert!(!clip_audio_changed(&next, &project));
}
#[test]
fn clip_audio_changes_refresh_playback_without_refreshing_for_names() {
let project: ProjectConfiguration = serde_json::from_value(serde_json::json!({
"timeline": { "zoomSegments": [], "segments": [
{ "recordingSegment": 0, "start": 0.0, "end": 2.0, "timescale": 1.0 }
] }
}))
.unwrap();
let mut next = project.clone();
next.timeline.as_mut().unwrap().segments[0].name = Some("Renamed".into());
next.timeline.as_mut().unwrap().segments[0].volume = Some(1.0);
assert!(!clip_audio_changed(&project, &next));
next.timeline.as_mut().unwrap().segments[0].volume = Some(0.5);
assert!(clip_audio_changed(&project, &next));
next.timeline.as_mut().unwrap().segments[0].volume = None;
next.timeline.as_mut().unwrap().segments[0].speed_audio_mode =
Some(cap_project::ClipSpeedAudioMode::Mute);
assert!(clip_audio_changed(&project, &next));
next.timeline.as_mut().unwrap().segments.clear();
assert!(clip_audio_changed(&project, &next));
}
#[test]
fn late_handoff_stop_only_cancels_its_original_playback() {
let make_handle = || {
let (stop_tx, stop_rx) = watch::channel(false);
let (_, event_rx) = watch::channel(PlaybackEvent::Start);
let (seek_tx, _) = watch::channel((0, 0));
(
PlaybackHandle {
preparing_audio_released: Arc::new(AtomicBool::new(false)),
adopted: None,
stop_tx,
event_rx,
seek_tx: Arc::new(seek_tx),
seek_generation: Arc::new(AtomicU64::new(0)),
},
stop_rx,
)
};
let (first, first_stop) = make_handle();
let handoff_owner = first.clone();
let (replacement, replacement_stop) = make_handle();
let mut current_playback = Some(first);
current_playback.replace(replacement).unwrap().stop();
handoff_owner.stop();
assert!(*first_stop.borrow());
assert!(!*replacement_stop.borrow());
current_playback.take().unwrap().stop();
assert!(*replacement_stop.borrow());
}
fn decoded_frames(bytes: usize) -> DecodedSegmentFrames {
DecodedSegmentFrames {
screen_size: XY::new(1, 1),
screen_frame: Some(DecodedFrame::new(vec![0; bytes], 1, 1)),
camera_frame: None,
segment_time: 0.0,
recording_time: 0.0,
segment_has_camera: false,
}
}
fn prefetched_frame(seek_generation: u64, frame_number: u32) -> PrefetchedFrame {
PrefetchedFrame {
seek_generation,
frame_number,
segment_frames: decoded_frames(4),
segment_index: 0,
transition: None,
}
}
#[test]
fn backward_seek_discards_queued_frames_from_the_previous_generation() {
let (sender, receiver) = prefetch_channel(4);
for (generation, frame) in [(1, 3000), (1, 480), (2, 480), (2, 481)] {
assert!(sender.send(prefetched_frame(generation, frame)).is_ok());
}
let target = receive_prefetched_frame(&receiver, 2, Duration::ZERO).unwrap();
assert_eq!(target.frame_number, 480);
assert_eq!(target.seek_generation, 2);
let next = receive_prefetched_frame(&receiver, 2, Duration::ZERO).unwrap();
assert_eq!(next.frame_number, 481);
}
#[test]
fn repeated_seeks_to_the_same_frame_require_the_latest_generation() {
let (sender, receiver) = prefetch_channel(3);
for generation in 0..3 {
assert!(sender.send(prefetched_frame(generation, 480)).is_ok());
}
let target = receive_prefetched_frame(&receiver, 2, Duration::ZERO).unwrap();
assert_eq!(target.seek_generation, 2);
assert_eq!(target.frame_number, 480);
}
#[test]
fn stale_prefetch_frames_do_not_hide_timeout_or_disconnection() {
let (sender, receiver) = prefetch_channel(1);
assert!(sender.send(prefetched_frame(1, 3000)).is_ok());
assert!(matches!(
receive_prefetched_frame(&receiver, 2, Duration::ZERO),
Err(std_mpsc::RecvTimeoutError::Timeout)
));
assert!(sender.send(prefetched_frame(1, 3001)).is_ok());
drop(sender);
assert!(matches!(
receive_prefetched_frame(&receiver, 2, Duration::ZERO),
Err(std_mpsc::RecvTimeoutError::Disconnected)
));
}
#[tokio::test]
async fn draining_the_prefetch_channel_wakes_a_blocked_producer() {
let (sender, receiver) = prefetch_channel(1);
let capacity = Arc::clone(&receiver.capacity);
assert!(sender.try_send(prefetched_frame(1, 10)).is_ok());
assert!(matches!(
sender.try_send(prefetched_frame(1, 11)),
Err(std_mpsc::TrySendError::Full(_))
));
let consumer = std::thread::spawn(move || {
let frame = receive_prefetched_frame(&receiver, 1, Duration::from_secs(5));
(frame.map(|frame| frame.frame_number), receiver)
});
tokio::time::timeout(Duration::from_secs(5), capacity.notified())
.await
.expect("consumer drain should wake the producer");
assert!(sender.try_send(prefetched_frame(1, 11)).is_ok());
let (frame, _receiver) = consumer.join().unwrap();
assert_eq!(frame.ok(), Some(10));
}
#[test]
fn discarding_stale_prefetch_frames_signals_capacity() {
use futures::FutureExt;
let (sender, receiver) = prefetch_channel(1);
assert!(sender.try_send(prefetched_frame(1, 10)).is_ok());
assert!(receiver.capacity.notified().now_or_never().is_none());
assert!(matches!(
receive_prefetched_frame(&receiver, 2, Duration::ZERO),
Err(std_mpsc::RecvTimeoutError::Timeout)
));
assert!(receiver.capacity.notified().now_or_never().is_some());
assert!(sender.try_send(prefetched_frame(2, 10)).is_ok());
}
#[tokio::test]
async fn buffering_retries_preserve_in_flight_decodes() {
let (sender, receiver) = tokio::sync::oneshot::channel();
let mut in_flight = FuturesUnordered::new();
in_flight.push(async move { receiver.await.unwrap() });
for requested in [480, 481, 482] {
if should_reset_prefetch(2, 484, 2, requested, !in_flight.is_empty()) {
in_flight = FuturesUnordered::new();
}
}
assert!(sender.send(483).is_ok());
assert_eq!(in_flight.next().await, Some(483));
}
#[test]
fn prefetch_retries_recover_when_idle_and_new_seeks_always_reset() {
assert!(should_reset_prefetch(2, 484, 2, 480, false));
assert!(should_reset_prefetch(2, 484, 2, 600, true));
assert!(!should_reset_prefetch(2, 484, 2, 484, false));
for requested in [480, 484, 600] {
assert!(should_reset_prefetch(2, 484, 3, requested, true));
}
}
#[test]
fn timeline_music_enables_audio_playback_without_recorded_audio() {
assert!(has_playback_audio(&[], true));
assert!(!has_playback_audio(&[], false));
}
#[test]
fn prefetch_limit_tracks_decoded_frame_memory() {
assert_eq!(prefetch_frame_limit(0), MAX_PREFETCH_BUFFER_SIZE);
assert_eq!(
prefetch_frame_limit(4 * 1024 * 1024),
MAX_PREFETCH_BUFFER_BYTES / (4 * 1024 * 1024)
);
assert_eq!(
prefetch_frame_limit(MAX_PREFETCH_BUFFER_BYTES),
INITIAL_PREFETCH_BUFFER_SIZE
);
}
#[test]
fn frame_cache_evicts_oldest_frames_to_stay_within_byte_budget() {
let mut cache = FrameCache::new(10, 15);
cache.insert(1, Arc::new(decoded_frames(10)), 0, None);
cache.insert(2, Arc::new(decoded_frames(10)), 0, None);
assert_eq!(cache.cache.len(), 1);
assert_eq!(cache.cache_bytes, 10);
assert!(cache.get(1).is_none());
assert!(cache.get(2).is_some());
}
#[test]
fn frame_cache_keeps_one_oversized_frame() {
let mut cache = FrameCache::new(10, 4);
cache.insert(1, Arc::new(decoded_frames(10)), 0, None);
assert_eq!(cache.cache.len(), 1);
assert_eq!(cache.cache_bytes, 10);
assert!(cache.get(1).is_some());
}
#[test]
fn frame_cache_holds_multiple_frames_within_byte_budget() {
let retina_frame = 24 * 1024 * 1024;
let mut cache = FrameCache::new(FRAME_CACHE_SIZE, MAX_FRAME_CACHE_BYTES);
cache.insert(1, Arc::new(decoded_frames(retina_frame)), 0, None);
cache.insert(2, Arc::new(decoded_frames(retina_frame)), 0, None);
assert!(cache.get(1).is_some());
assert!(cache.get(2).is_some());
cache.insert(3, Arc::new(decoded_frames(retina_frame)), 0, None);
assert_eq!(cache.cache.len(), 2);
assert!(cache.cache_bytes <= MAX_FRAME_CACHE_BYTES);
assert!(cache.get(3).is_some());
}
#[test]
fn boosted_limit_widens_and_never_shrinks_below_base() {
let retina_frame = 24 * 1024 * 1024;
let base = prefetch_frame_limit(retina_frame);
let boosted = boosted_prefetch_frame_limit(retina_frame);
assert_eq!(base, INITIAL_PREFETCH_BUFFER_SIZE);
assert!(boosted > base);
assert!(boosted <= base * 2);
let small_frame = 2 * 1024 * 1024;
assert!(boosted_prefetch_frame_limit(small_frame) >= prefetch_frame_limit(small_frame));
assert!(boosted_prefetch_frame_limit(small_frame) <= MAX_PREFETCH_BUFFER_SIZE);
assert_eq!(boosted_prefetch_frame_limit(0), prefetch_frame_limit(0));
}
#[test]
fn frame_cache_accounts_for_count_based_eviction() {
let mut cache = FrameCache::new(2, usize::MAX);
cache.insert(1, Arc::new(decoded_frames(10)), 0, None);
cache.insert(2, Arc::new(decoded_frames(10)), 0, None);
cache.insert(3, Arc::new(decoded_frames(10)), 0, None);
assert_eq!(cache.cache.len(), 2);
assert_eq!(cache.cache_bytes, 20);
assert!(cache.get(1).is_none());
}
}