Studio playback diagnostics
Use the running Studio for the current worktree. To launch one, follow studio. Confirm the composition and reproduction range before recording. Do not modify the composition just to obtain a trace.
Capture through WebMCP
- Call
set_buffering_tracingwith{"enabled": true}before reproducing. Alternatively, enable Settings → Studio → Debug → Show diagnostics,Config.setShowDiagnostics(true), or--show-diagnostics. The floating panel enables tracing while mounted. Drag its header to move it; arrow keys also work when the header has keyboard focus. - Pause playback and call
clear_buffering_eventswith{}. This removes completed history, preserving any active episode. Readget_diagnosticsfor a counter baseline. Optionally callreset_buffering_handles_createdwith{}to reset that creation count without changing active handles or other counters. - Use
select_composition,seek_to_frame,play, andpauseto reproduce the reported range. Start early enough to include premounting and loading. - Call
get_buffering_eventswith{"limit": 20}andget_diagnosticswith{}. Inspect the recorded frames, durations, handle stacks, media sources, and owner locations.ownersruns from the nearest layer through its ancestors. - Call
reveal_buffering_handlewith the returnedeventIdandhandleId. This pauses, switches to the recorded composition, seeks to the event's start frame, and selects the owner in the timeline and Inspector. Checkget_selectionandget_playback_stateto confirm. The panel's Reveal button does the same. - When finished, call
set_buffering_tracingwith{"enabled": false}. Tracing remains enabled if the panel is still open. Report the composition, frame, source location, media URL, duration, and evidence for the cause.
See the WebMCP tool schemas for exact inputs, outputs, and availability. These tools work in regular, detached, deployed, and remotion.new. Reveal requires a selectable composition timeline; it reports an error if a record, composition, or matching layer no longer exists.
Interpret the evidence
audioIteratorsCreatedis cumulative; it is not the number of live iterators.mediabunnySinksOpenis the current number of registered sinks whose inputs have not been disposed. It is not a cumulative count.bufferingHandlesCreatedcounts calls that create playback blocks. A block can be cleared immediately and never enter buffering. Reset only affects this count.bufferingStatesTriggeredcounts transitions into the internal buffering state. Overlapping handles form one episode. A handle added and removed within the same React batch does not trigger an episode. Short episodes may not display the loading indicator, whose default delay is 300 ms.activeAtStart: trueidentifies handles present when the episode began. Other handles joined an already-buffering episode; they may prolong it or be a result of resynchronization. A recorded handle is evidence of a playback block, not by itself proof of the root cause.- Event
frameis the composition frame at buffering entry. HandleframeandreleasedFramedescribe creation and release. Times useperformance.now()milliseconds.endedAt: nullmeans ongoing;endReason: 'unmounted'means the buffering provider disappeared, not that media finished loading.
Capture starts when enabled, not retroactively. Handles created earlier are
included in omittedHandles if still blocking at event start. Detailed history
keeps at most 100 events and 50 handles per event; the panel shows the latest 20.
Check droppedEvents and omittedHandles before treating a trace as complete.
History and counters reset on page reload. Clearing history preserves active
records and does not reset counters. IDs are not reused when history is cleared.
Use afterId only to request newer episodes. To inspect updates or releases in an
existing episode, omit it. Source stacks remain available after layers unmount;
Reveal matches a current layer by identity or captured source information and may
fall back to an ancestor. Check the returned selection rather than assuming the
original layer survived edits or HMR.
Find the cause and verify a fix
Read the first blocking handles' source and owning JSX, then trace media waits to the underlying fetch, decoding, seeking, or synchronization path. Follow fix-root-cause. Distinguish an initial decoder wait from audio handles subsequently created to resynchronize playback.
Inspect the relevant Sequence's premountFor, its actual mount frame, and source
media properties. Premounting mounts early; it does not guarantee all upcoming
frames are decoded. The preview queue in
canvas-ahead-of-time.ts
holds three ahead-of-time slots; current/peeked frames and browser decoder buffers
are separate. Do not interpret this as decoding a full second during premount.
For suspected media bottlenecks, verify resolution, codec, file size, bitrate, and decode timing. Confirm an alternative file contains the same capture before proposing a replacement. Do not suppress buffering or silently substitute a different video to hide a stall.
Reproduce the same range after a change and compare event count/durations, resource counters, and visible output. For React render regressions use react-scan. Keep traces bounded and local; summarize relevant handles instead of returning every raw stack. Detailed stack capture is opt-in; leave it off outside diagnostics work.
Implementation references: trace store, buffer transitions, handle creation, and reveal and serialization.
