Tune live latency
Use this page to play a live stream closer to the live edge, or further behind it for fewer stalls. The liveBuffer() plugin holds the latency. <moqtail-video> installs it by default. MOQtailPlayer installs no plugins, so you list it yourself.
What sets the latency
liveBuffer() works on live streams only. It takes its target latency from the first of these that is set:
- The catalog:
targetLatency, elsebuffers.target, of the first playing track that sets either (MSF 5.2.9). That track'sbuffers.minandbuffers.maxbound the forward buffer (MSF 5.2.10). - The
targetLatencyyou pass toliveBuffer(), 1 s by default.
A target in the catalog wins over yours.
The controller measures latency with the wallclock values of the stream's media timeline, when there is one (MSF 11.6). Without them, the latency it measures is the forward buffer: the seconds buffered ahead of the playhead.
On every timeupdate it compares the forward buffer with its goal, the forward buffer that gives the target latency. The goal never goes below stallThreshold, so a target below the stall threshold can't be reached. Then:
- Within
toleranceof the goal, playback runs at rate 1. - Above the goal, playback runs at
catchupRateuntil it is back. - Below the goal, playback runs at
2 - catchupRate, and slower as the buffer runs out belowstallThreshold, down tominRate. - Above
jumpFactortimes the goal, after a seek back for example, the controller jumps to the goal.
The <video> sink has no precise playback rate when it plays through ManagedMediaSource, as it does in Safari: every rate change stalls playback for a moment. There the rate stays 1, and the controller jumps to the goal once the forward buffer is more than jumpTolerance off it. A jump is a visible skip.
When the viewer seeks back, the controller leaves the rate at 1 until a seek to the live edge.
Options
liveBuffer() takes these options, all in seconds except the rates:
| Option | Default | Valid values | Effect |
|---|---|---|---|
catchupRate | 1.1 | above 1, below 2 | The rate above the goal. Below it, the rate is 2 - catchupRate. |
targetLatency | 1 | above 0 | The latency to hold when the catalog sets no target. |
tolerance | 0.1 | 0 or more | How far the forward buffer may stray from its goal before the rate changes. |
stallThreshold | 0.5 | 0 or more | The forward buffer below which playback is about to stall. The goal never goes below it. |
minRate | 0.6 | above 0, at most 1 | The slowest rate, as the buffer runs out. |
jumpFactor | 4 | above 1 | A forward buffer this many times its goal is jumped instead of caught up. |
jumpTolerance | 0.5 | above 0 | On a sink without a precise rate, how far off its goal the forward buffer may get before a jump. |
Every value must also be finite. A value out of range is a TypeError when the player is created: the MOQtailPlayer constructor throws it, and <moqtail-video> fires error.
Two sink options work with the controller. Pass them as the second argument of player.sink(). <moqtail-video> always uses their defaults.
| Sink | Option | Default | Effect |
|---|---|---|---|
<video> | liveEdgeDelay | 0.75 | How far behind the end of the buffer the sink's own live jumps land: past a gap in the buffer, or when a tab that was hidden has fallen behind the live window. |
<canvas> | preroll | 0.5 | Seconds of media queued before playback starts, and again after each stall. |
Both take finite values of 0 or more. Lower preroll together with stallThreshold, or every stall refills 0.5 s.
Pass the options
With MOQtailPlayer, list liveBuffer() in plugins:
import { MOQtailPlayer, abr, liveBuffer } from 'moqtail/player'
const video = document.querySelector('video')!
const player = new MOQtailPlayer({
plugins: [liveBuffer({ targetLatency: 2 }), abr()],
})
.source('moqt://relay.moqtail.dev#msf:moqtail-ch07--catalog')
.sink(video)
await player.start()With <moqtail-video>, set config.plugins before src. The element reads config each time it loads a source, and changing it later doesn't restart playback. Your list replaces the default plugins, so list abr() too to keep adaptive bitrate:
import { abr, liveBuffer } from 'moqtail/player'
import { defineMOQtailVideo, type MOQtailVideoElement } from 'moqtail/player/component'
defineMOQtailVideo()
const video = document.querySelector<MOQtailVideoElement>('moqtail-video')!
video.config = { plugins: [liveBuffer({ targetLatency: 2 }), abr()] }
video.src = 'moqt://relay.moqtail.dev#msf:moqtail-ch07--catalog'Play at the lowest latency on a canvas
The canvas sink plays live LOC tracks, decoded with WebCodecs. This setup holds about 250 ms:
import { MOQtailPlayer, abr, liveBuffer } from 'moqtail/player'
const canvas = document.querySelector('canvas')!
const player = new MOQtailPlayer({
plugins: [liveBuffer({ targetLatency: 0.25, stallThreshold: 0.1, tolerance: 0.05 }), abr()],
})
.source('moqt://relay.moqtail.dev#msf:moqtail-testsrc--catalog')
.sink(canvas, { preroll: 0.1 })
await player.start()targetLatency: 0.25asks for a quarter of a second, unless the catalog sets its own target.stallThreshold: 0.1lets the goal go below the default 0.5 s.tolerance: 0.05keeps the band around the goal small next to the target.preroll: 0.1matchesstallThreshold, so a stall refills 0.1 s, not 0.5 s.
Video starts at once. Audio waits for a user gesture on the page, such as a click. The lower the target, the less buffer there is to hide a late object, so expect more stalls on a link with jitter.
Play steadier on a video element
For fewer stalls and fewer visible rate changes, hold more latency:
import { MOQtailPlayer, abr, liveBuffer } from 'moqtail/player'
const video = document.querySelector('video')!
const player = new MOQtailPlayer({
plugins: [liveBuffer({ targetLatency: 3, tolerance: 0.3, catchupRate: 1.05, jumpTolerance: 1 }), abr()],
})
.source('moqt://relay.moqtail.dev#msf:moqtail-ch07--catalog')
.sink(video, { liveEdgeDelay: 1.5 })
await player.start()targetLatency: 3keeps 3 s of media to ride out late objects.tolerance: 0.3changes the rate less often.catchupRate: 1.05makes each catch-up slower and harder to notice.jumpTolerance: 1skips less often in Safari, where the controller jumps instead.liveEdgeDelay: 1.5leaves more buffer after the sink jumps a gap.
More information
liveBufferandLiveBufferConfigMSEOptionsandPlayoutOptionsBufferController, to write your own: see Write plugins and elements- How the player works