Optional ReadonlyenabledPause playback while required artifacts are unprepared. A session turns
this on by default for playback. Its initial opening frame may appear
before annotations arrive. playbackGate: false on the session turns it
off. A renderer created directly leaves it off.
Optional ReadonlyqualityRaster quality required by an enabled gate. Default: "adaptive", which
accepts smaller previews during rapid movement. "fine" waits for the full
display-fitted raster and prepares its lead at that quality. An enabled
fine gate overrides maskFrame.previewScale during playback, scrubbing,
and seeking. This can increase CPU work and buffering.
maxWaitSeconds still bounds the wait; on expiry, playback may use a
preview or omit an unfinished artifact.
Optional ReadonlymaxHow long an enabled gate holds the picture for artifacts that are not
prepared, before it gives up and lets the frames through without them.
Defaults to two seconds, and bounds every wait the gate makes: the one
before playback begins, the one that stops a running producer at a frame,
and the per-sample one of a renderer that pulls its own samples. Infinity
holds indefinitely, and 0 never holds for artifacts at all.
Preparation falls behind for as long as the machine is losing, and that looks no different to the gate from a cook still on its way. A gate that gave up holds off until preparation finishes another frame, so a machine that is merely slow keeps stopping the picture and catching up, and one that has stopped producing costs one wait rather than one a frame.
Optional ReadonlystopHow long the prepared lead may fall to before playback stops, in seconds
of the viewer's own time. Defaults to 0.1s. A rate multiplies it, because
one wall second of runway is eight seconds of timeline at 8x, and a
requiredAheadSeconds too small to fund the margin holds it below the lead
that ends a stop rather than letting the two meet.
Optional ReadonlyresumeHow much lead a stop banks on top of stopBelowWallSeconds before
playback resumes, in seconds of the viewer's own time. Defaults to 0.2s,
so a stop lasts about as long as it takes to cook that margin and no
longer. This is what sets the length of a stop; requiredAheadSeconds
only caps it.
Optional ReadonlyrequiredCeiling on the lead the two thresholds above may ask for, in seconds of timeline. Defaults to none, which asks only that the frame about to be presented is no longer pending.
This is unrelated to the detection playback gate's field of the same name, which is a minimum coverage lead.
It buys no cooked frames: how far ahead preparation cooks and how much of that it keeps are the prepared window's own prefetch and cache spans, sized by the session rather than by this. The gate reads them only as a second ceiling, so a span too small to hold the lead lowers it further. All this can do is shorten a stop, by holding the resume lead below what the wall clock asked for. With the default thresholds that lead is 0.3s of timeline per unit of rate, so a ceiling only starts to bite once the rate lifts the lead above it: the 1s a session sets first does so near 3.3x.
Prepared-artifact playback gate, off unless
enabledsays otherwise.Off, preparation runs behind the picture and a frame the prepared window does not cover reaches no annotation layer instead of holding playback back. On, playback waits until the prepared window leads the playhead, so masks and polygons arrive with their frame rather than after it.
A source the renderer pulls samples from is held between the sample it decoded and the draw. A source that presents its own frames owns the playhead, so it is held by stopping the producer and starting it again, before playback begins and at any frame after it whose artifacts are missing. The renderer reports
Bufferingfor as long as either wait lasts.maxWaitSecondsbounds every one of those waits, so preparation that has stopped producing costs one wait and the frames after it are drawn without their artifacts.