Take control over your live stream video by running it yourself. Streaming + chat out of the box.
HTML activitypubbroadcastingchatdecentralizedfederationfediversegolanghacktoberfesthlslivelivestreamowncastrtmpself-hostedstreaming-videovideo
feat(video): re-enable the latency compensator in the player
Gabe Kangasc53fd173247f
diff --git a/web/components/video/OwncastPlayer/OwncastPlayer.tsx b/web/components/video/OwncastPlayer/OwncastPlayer.tsxindex d48d3e7be0..7968636f44 100644--- a/web/components/video/OwncastPlayer/OwncastPlayer.tsx+++ b/web/components/video/OwncastPlayer/OwncastPlayer.tsx@@ -88,7 +88,8 @@ export const OwncastPlayer: FC<OwncastPlayerProps> = ({const startLatencyCompensator = () => {if (latencyCompensator) {- latencyCompensator.stop();+ // Fully tear down the old instance so its check timer doesn't leak.+ latencyCompensator.disable();}latencyCompensatorEnabled = true;diff --git a/web/components/video/latencyCompensator.js b/web/components/video/latencyCompensator.jsindex 76624c15d9..3a763178c8 100644--- a/web/components/video/latencyCompensator.js+++ b/web/components/video/latencyCompensator.js@@ -1,73 +1,385 @@/*The Owncast Latency Compensator.-It will try to slowly adjust the playback rate to enable the player to get-further into the future, with the goal of being as close to the live edge as-possible, without causing any buffering events.--How does latency occur?-Two pieces are at play. The first being the server. The larger each segment is-that is being generated by Owncast, the larger gap you are going to be from-live when you begin playback.--Second is your media player.-The player tries to play every segment as it comes in.-However, your computer is not always 100% in playing things in real time, and-there are natural stutters in playback. So if one frame is delayed in playback-you may not see it visually, but now you're one frame behind. Eventually this-can compound and you can be many seconds behind.--How to help with this? The Owncast Latency Compensator will:- - Determine the start (max) and end (min) latency values.- - Keep an eye on download speed and stop compensating if it drops too low.- - Limit the playback speedup rate so it doesn't sound weird by jumping speeds.- - Force a large jump to into the future once compensation begins.- - Dynamically calculate the speedup rate based on network speed.- - Pause the compensation if buffering events occur.- - Completely give up on all compensation if too many buffering events occur.+Tries to keep playback as close to the live edge as possible without ever+making the experience worse for the viewer. It slowly adjusts the playback+rate (imperceptibly) and, in extreme cases under pristine conditions, jumps+forward — always landing inside already-buffered content.++Safety model (buffer-first):+Near the live edge your playable buffer is physically capped by your latency,+so latency can only be reduced by spending buffer. The compensator will only+spend buffer down to a floor derived from the segment duration. All latency+targets are subordinate to that floor: when the floor is reached, compensation+stops, wherever that leaves us. It never chases a wall-clock number the buffer+can't afford.++How it behaves:+ - Measures latency from segment program-date-time plus the playhead's+ position within the segment, smoothed over several samples.+ - Only acts with bandwidth headroom, a stable player, and buffer above the+ floor. Backs off immediately when any of those degrade.+ - Tapers the speedup toward 1.0 as it approaches the target latency so it+ never overshoots into the thin-buffer zone at full speed.+ - Jumps only when very far behind, only forward, and only within buffered+ content, leaving at least the buffer floor after landing.+ - Remembers recent rebuffering events: they raise the latency floor and+ pause all compensation. Too many events disables it for the session.*/-const REBUFFER_EVENT_LIMIT = 4; // Max number of buffering events before we stop compensating for latency.-const MIN_BUFFER_DURATION = 200; // Min duration a buffer event must last to be counted.-const MAX_SPEEDUP_RATE = 1.08; // The playback rate when compensating for latency.-const MAX_SPEEDUP_RAMP = 0.02; // The max amount we will increase the playback rate at once.-const TIMEOUT_DURATION = 30 * 1000; // The amount of time we stop handling latency after certain events.-const CHECK_TIMER_INTERVAL = 3 * 1000; // How often we check if we should be compensating for latency.-const BUFFERING_AMNESTY_DURATION = 3 * 1000 * 60; // How often until a buffering event expires.-const REQUIRED_BANDWIDTH_RATIO = 1.8; // The player:bitrate ratio required to enable compensating for latency.-const HIGHEST_LATENCY_SEGMENT_LENGTH_MULTIPLIER = 2.6; // Segment length * this value is when we start compensating.-const LOWEST_LATENCY_SEGMENT_LENGTH_MULTIPLIER = 1.8; // Segment length * this value is when we stop compensating.-const MIN_LATENCY = 4 * 1000; // The absolute lowest we'll continue compensation to be running at.-const MAX_LATENCY = 15 * 1000; // The absolute highest we'll allow a target latency to be before we start compensating.-const MAX_JUMP_LATENCY = 5 * 1000; // How much behind the max latency we need to be behind before we allow a jump.-const MAX_JUMP_FREQUENCY = 20 * 1000; // How often we'll allow a time jump.-const MAX_ACTIONABLE_LATENCY = 80 * 1000; // If latency is seen to be greater than this then something is wrong.-const STARTUP_WAIT_TIME = 10 * 1000; // The amount of time after we start up that we'll allow monitoring to occur.+// ---- Tunables ----+const REBUFFER_EVENT_LIMIT = 4; // Max rebuffer events before giving up for good.+const MIN_BUFFER_DURATION = 200; // Min ms a buffering event must last to be counted.+const MAX_SPEEDUP_RATE = 1.08; // Max playback rate while compensating.+const MAX_SPEEDUP_RAMP = 0.005; // Max playback rate change applied per ramp tick.+const TIMEOUT_DURATION = 30 * 1000; // How long we back off after risky events.+const CHECK_TIMER_INTERVAL = 3 * 1000; // How often we evaluate conditions.+const SPEED_ADJUSTMENT_INTERVAL = 1 * 1000; // How often micro speed adjustments run.+const BUFFERING_AMNESTY_DURATION = 4 * 60 * 1000; // Rebuffer events expire after this.+const REQUIRED_BANDWIDTH_RATIO = 2.0; // download:bitrate ratio required to start.+const CONTINUE_BANDWIDTH_RATIO = 1.5; // ratio required to keep going once running.+const HIGHEST_LATENCY_SEGMENT_LENGTH_MULTIPLIER = 2.2; // segment length * this = start threshold.+const LOWEST_LATENCY_SEGMENT_LENGTH_MULTIPLIER = 1.7; // segment length * this = stop threshold.+const MIN_LATENCY = 4 * 1000; // Absolute lowest latency we'll compensate toward.+const MAX_LATENCY = 15 * 1000; // Cap on the computed start threshold.+const MAX_JUMP_LATENCY = 5 * 1000; // How far past the start threshold before jumps are considered.+const MAX_JUMP_FREQUENCY = 20 * 1000; // Min ms between jumps.+const MAX_ACTIONABLE_LATENCY = 90 * 1000; // Latency beyond this means bad data; do nothing.+const STARTUP_WAIT_TIME = 20 * 1000; // Leave the player alone this long after startup.+const CONSECUTIVE_STABLE_CHECKS = 3; // Healthy checks required before acting.+const CRITICAL_BUFFER_SECONDS = 2; // Below this playable buffer we hard back off.+const BUFFER_FLOOR_SEGMENT_MULTIPLIER = 1.5; // Buffer floor = segment duration * this...+const MIN_BUFFER_FLOOR_SECONDS = 4; // ...but never below this many seconds.+const MIN_BUFFER_SHRINK_LIMIT = 2; // Base for the shrink-trend limit (scaled by segment duration).+const BUFFER_BOOST_PER_SECOND = 0.02; // Speedup allowance per second of buffer above the floor.+const MIN_ACTIONABLE_RATE = 1.005; // Rates below this aren't worth running.+const SPEED_CHANGE_MIN_INTERVAL = 10 * 1000; // Min ms between starting speed changes.+const JUMP_MIN_WORTHWHILE_SECONDS = 2; // Never jump less than this.+const JUMP_IGNORE_BUFFER_DURATION = 10 * 1000; // Ignore buffer events this long after a seek.+const LATENCY_SAMPLE_COUNT = 5; // Latency samples kept for smoothing.++// ---- Earned trust (rev 9) ----+// After sustained good behavior the safety cushion thins a little: trust is+// earned by 3 continuous minutes of zero rebuffer events AND measured+// bandwidth headroom >= REQUIRED_BANDWIDTH_RATIO. It reverts instantly on+// any rebuffer, timeout, or headroom loss, and must be re-earned in full.+const TRUST_EARN_DURATION = 3 * 60 * 1000; // Clean time required to earn trust.+const MIN_LATENCY_TRUSTED = 3 * 1000; // Trusted absolute latency target floor.+const TRUSTED_FLOOR_JITTER_MARGIN = 1; // Trusted floor = segment duration + this...+const MIN_BUFFER_FLOOR_SECONDS_TRUSTED = 3; // ...but never below this many seconds.++// ---- Clock-skew fallback (rev 9) ----+const SKEW_ESTIMATION_MIN_ERROR = 10 * 1000; // Only correct clock errors bigger than this.+const SKEW_SIGHTING_WINDOW = 10; // New-segment sightings kept for estimation.++const REBUFFER_STORAGE_KEY = 'owncast-latency-compensator.rebuffers';++// The playable-buffer floor the compensator will never spend below.+// Untrusted: 1.5 segments, at least 4s. Trusted: one production cadence plus+// a jitter margin — never a bare multiplier that dips under the sawtooth.+export function bufferFloorSeconds(segmentDurationSec, trusted = false) {+ if (trusted) {+ return Math.max(+ segmentDurationSec + TRUSTED_FLOOR_JITTER_MARGIN,+ MIN_BUFFER_FLOOR_SECONDS_TRUSTED,+ );+ }+ return Math.max(BUFFER_FLOOR_SEGMENT_MULTIPLIER * segmentDurationSec, MIN_BUFFER_FLOOR_SECONDS);+}++// How much the playable buffer may shrink over three checks before we back+// off. Never tighter than the natural per-segment sawtooth.+function bufferShrinkLimit(segmentDurationSec) {+ return Math.max(MIN_BUFFER_SHRINK_LIMIT, segmentDurationSec);+}++// The latency band: compensation starts above maxLatencyMs and stops at or+// below minLatencyMs. Recent rebuffering raises the stop threshold — never+// lowers it.+export function latencyThresholds(segmentDurationSec, worstRebufferLatencyMs, trusted = false) {+ let minLatencyMs = Math.max(+ trusted ? MIN_LATENCY_TRUSTED : MIN_LATENCY,+ segmentDurationSec * 1000 * LOWEST_LATENCY_SEGMENT_LENGTH_MULTIPLIER,+ );++ if (Number.isFinite(worstRebufferLatencyMs)) {+ minLatencyMs = Math.max(minLatencyMs, Math.min(worstRebufferLatencyMs + 1000, MAX_LATENCY));+ }++ let maxLatencyMs = Math.max(+ minLatencyMs * 1.4,+ Math.min(segmentDurationSec * 1000 * HIGHEST_LATENCY_SEGMENT_LENGTH_MULTIPLIER, MAX_LATENCY),+ );++ if (minLatencyMs >= maxLatencyMs) {+ maxLatencyMs = minLatencyMs + 3000;+ }++ return { minLatencyMs, maxLatencyMs };+}++// The band adjusted for what the buffer can actually afford. Near the live+// edge, latency can only be reduced by spending buffer, and the buffer floor+// caps how much is spendable: the lowest reachable latency is+// latency − (buffer − floor). The effective minimum never sits below that,+// so the natural stopping point of a catch-up is always INSIDE the band and+// the resting state is silent instead of chattering on the start threshold.+export function effectiveLatencyBand(+ segmentDurationSec,+ worstRebufferLatencyMs,+ latencyMs,+ playableBufferSec,+ trusted = false,+) {+ let { minLatencyMs, maxLatencyMs } = latencyThresholds(+ segmentDurationSec,+ worstRebufferLatencyMs,+ trusted,+ );++ if (Number.isFinite(latencyMs) && Number.isFinite(playableBufferSec)) {+ const reachableMinMs =+ latencyMs - (playableBufferSec - bufferFloorSeconds(segmentDurationSec, trusted)) * 1000;+ if (reachableMinMs > minLatencyMs) {+ minLatencyMs = reachableMinMs;+ if (minLatencyMs >= maxLatencyMs) {+ maxLatencyMs = minLatencyMs + 3000;+ }+ }+ }++ return { minLatencyMs, maxLatencyMs };+}++/*+The pure decision function: a snapshot of player state in, exactly one action+out. No side effects, no timers, no player access — this is the behavioral+contract the tests pin down.++inputs = {+ latencyMs, // smoothed latency estimate, or null if unknown+ playableBufferSec, // mean of the last 4 buffer samples (smoothed)+ playableBufferRawSec, // instantaneous buffered seconds ahead of the playhead+ bufferTrendSec, // mean(last 4) − mean(the 4 before); smoothed trend+ bandwidthRatio, // conservative download:bitrate ratio, or null+ segmentDurationSec, // current segment duration+ stableChecks, // consecutive healthy checks+ rebufferEvents, // count of recent (unexpired) rebuffer events+ worstRebufferLatencyMs, // highest latency among recent rebuffers, or null+ msSinceLastSpeedChange, // ms since the target rate last changed+ msSinceLastJump, // ms since the last jump/seek we performed+ running, // whether compensation is currently active+ trusted, // earned-trust state; thins the floor and thresholds+}++action = { type: "none" | "stop" | "timeout", reason }+ | { type: "speed", rate, reason }+ | { type: "jump", aheadSec, reason }+*/+export function decide(inputs) {+ const {+ latencyMs,+ playableBufferSec,+ playableBufferRawSec,+ bufferTrendSec,+ bandwidthRatio,+ segmentDurationSec,+ stableChecks,+ rebufferEvents,+ worstRebufferLatencyMs,+ msSinceLastSpeedChange,+ msSinceLastJump,+ running,+ trusted,+ } = inputs;++ // Unknown or absurd latency: we can't make safe decisions on bad data.+ if (!Number.isFinite(latencyMs) || Math.abs(latencyMs) > MAX_ACTIONABLE_LATENCY) {+ return { type: 'timeout', reason: 'latency unmeasurable or absurd' };+ }++ // About to run dry: hard back-off regardless of anything else. The+ // emergency check sees the raw instantaneous buffer — smoothing may+ // never delay it.+ const rawSec = Number.isFinite(playableBufferRawSec) ? playableBufferRawSec : playableBufferSec;+ if (Math.min(rawSec, playableBufferSec) < CRITICAL_BUFFER_SECONDS) {+ return { type: 'timeout', reason: 'critically low buffer' };+ }++ const floor = bufferFloorSeconds(segmentDurationSec, trusted);+ const idle = reason => ({ type: running ? 'stop' : 'none', reason });++ // Below the buffer floor we never spend buffer, no matter the latency.+ if (playableBufferSec < floor) {+ return idle('buffer at floor');+ }++ // Buffer shrinking fast: stop spending it before it becomes a stall.+ // The limit scales with segment duration: playable buffer naturally+ // sawtooths by a whole segment as segments land, so a fixed limit+ // false-trips on longer segments and causes engage/stop churn.+ if (bufferTrendSec < -bufferShrinkLimit(segmentDurationSec)) {+ return idle('buffer shrinking');+ }++ const { minLatencyMs, maxLatencyMs } = effectiveLatencyBand(+ segmentDurationSec,+ worstRebufferLatencyMs,+ latencyMs,+ playableBufferSec,+ trusted,+ );++ if (latencyMs <= minLatencyMs) {+ return idle('at target latency');+ }++ // Hysteresis: inside the band we only keep going if already running.+ if (latencyMs <= maxLatencyMs && !running) {+ return { type: 'none', reason: 'inside latency band' };+ }++ // Bandwidth headroom: strict to start, looser to continue.+ const requiredRatio = running ? CONTINUE_BANDWIDTH_RATIO : REQUIRED_BANDWIDTH_RATIO;+ if (!Number.isFinite(bandwidthRatio) || bandwidthRatio < requiredRatio) {+ return idle('insufficient bandwidth headroom');+ }++ // Jump: only when very far behind, under pristine conditions, and always+ // forward, landing inside buffered content with the floor left intact.+ if (+ latencyMs > maxLatencyMs + MAX_JUMP_LATENCY &&+ rebufferEvents === 0 &&+ stableChecks >= CONSECUTIVE_STABLE_CHECKS &&+ msSinceLastJump > MAX_JUMP_FREQUENCY &&+ playableBufferSec >= floor + 2 * segmentDurationSec+ ) {+ const aheadSec = Math.min(+ // Keep at least the buffer floor after landing.+ playableBufferSec - floor,+ // Don't jump past the target latency.+ (latencyMs - minLatencyMs) / 1000 - segmentDurationSec,+ );+ if (aheadSec >= Math.max(segmentDurationSec, JUMP_MIN_WORTHWHILE_SECONDS)) {+ return {+ type: 'jump',+ aheadSec: Math.floor(aheadSec * 100) / 100,+ reason: 'far behind live',+ };+ }+ }++ // Speed-up. Starting requires stability; continuing is re-evaluated on+ // every check so the rate tapers as conditions and distance change.+ if (!running) {+ if (stableChecks < CONSECUTIVE_STABLE_CHECKS) {+ return { type: 'none', reason: 'waiting for stability' };+ }+ if (rebufferEvents > 0) {+ return { type: 'none', reason: 'recent rebuffering' };+ }+ if (msSinceLastSpeedChange < SPEED_CHANGE_MIN_INTERVAL) {+ return { type: 'none', reason: 'rate changed too recently' };+ }+ // Entry hysteresis: starting needs segDur/2 of spendable buffer beyond+ // the floor, continuing only needs the floor — otherwise a buffer+ // hovering at the floor causes engage/stop flapping. (Kept as a plain+ // gate on purpose: folding it into the band geometry bars any catch-up+ // gaining less than the band's degenerate 3s offset.)+ if (playableBufferSec < floor + segmentDurationSec / 2) {+ return { type: 'none', reason: 'buffer too close to floor to start' };+ }+ }++ // Taper toward 1.0 as we approach the target so we never overshoot into+ // the thin-buffer zone at full speed.+ const distance = Math.min((latencyMs - minLatencyMs) / (maxLatencyMs - minLatencyMs), 1);+ const boostCap = Math.min(+ MAX_SPEEDUP_RATE - 1,+ BUFFER_BOOST_PER_SECOND * (playableBufferSec - floor),+ );+ const rate = Math.round((1 + Math.max(boostCap, 0) * distance) * 10000) / 10000;++ if (rate < MIN_ACTIONABLE_RATE) {+ return idle('not enough headroom to be worthwhile');+ }++ return { type: 'speed', rate, reason: 'catching up' };+}++function median(values) {+ const sorted = [...values].sort((a, b) => a - b);+ const mid = Math.floor(sorted.length / 2);+ return sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;+}++function mean(values) {+ return values.reduce((a, b) => a + b, 0) / values.length;+}function getCurrentlyPlayingSegment(tech) {- const targetMedia = tech.vhs.playlists.media();+ const playlist = tech.vhs.playlists.media();+ if (!playlist || !playlist.segments || playlist.segments.length === 0) {+ return null;+ }+const snapshotTime = tech.currentTime();- let segment;- // Iterate trough available segments and get first within which snapshot_time is- // eslint-disable-next-line no-plusplus- for (let i = 0, l = targetMedia.segments.length; i < l; i++) {- // Note: segment.end may be undefined or is not properly set- if (snapshotTime < targetMedia.segments[i].end) {- segment = targetMedia.segments[i];- break;+ // Find the first segment whose end is past the playhead.+ for (let i = 0; i < playlist.segments.length; i += 1) {+ // Note: segment.end may be undefined when not yet buffered.+ if (snapshotTime < playlist.segments[i].end) {+ return playlist.segments[i];}}- if (!segment) {- [segment] = targetMedia.segments;+ return playlist.segments[0];+}++// ---- Rebuffer memory persistence ----+// A page reload should not reset learned caution: events are stored in+// sessionStorage and restored (age-pruned) at construction. All storage+// access is failure-tolerant — missing or broken sessionStorage (Node,+// sandboxed iframes, private modes) silently degrades to in-memory only.++function loadPersistedRebufferEvents() {+ try {+ if (typeof window === 'undefined' || !window.sessionStorage) {+ return [];+ }+ const raw = window.sessionStorage.getItem(REBUFFER_STORAGE_KEY);+ if (!raw) {+ return [];+ }+ const events = JSON.parse(raw);+ if (!Array.isArray(events)) {+ return [];+ }+ const cutoff = Date.now() - BUFFERING_AMNESTY_DURATION;+ return events+ .filter(e => e && typeof e.atMs === 'number' && e.atMs > cutoff)+ .map(e => ({+ latencyMs: Number.isFinite(e.latencyMs) ? e.latencyMs : null,+ atMs: e.atMs,+ }));+ } catch {+ return [];}+}- return segment;+function persistRebufferEvents(events) {+ try {+ if (typeof window === 'undefined' || !window.sessionStorage) {+ return;+ }+ window.sessionStorage.setItem(REBUFFER_STORAGE_KEY, JSON.stringify(events));+ } catch {+ // Storage full or forbidden; in-memory behavior is the fallback.+ }}class LatencyCompensator {- constructor(player) {+ constructor(player, options = {}) {this.player = player;this.playing = false;this.enabled = false;@@ -75,18 +387,43 @@ class LatencyCompensator {this.inTimeout = false;this.jumpingToLiveIgnoreBuffer = false;this.timeoutTimer = 0;+ this.timeoutEndingAt = 0;this.checkTimer = 0;- this.bufferingCounter = 0;this.bufferingTimer = 0;+ this.speedAdjustmentTimer = 0;this.playbackRate = 1.0;- this.lastJumpOccurred = null;- this.startupTime = new Date();+ this.targetPlaybackRate = 1.0;+ this.lastJumpOccurred = 0;+ this.lastSpeedChange = 0;+ this.startupTime = Date.now();this.clockSkewMs = 0;+ this.skewWasSet = false;+ this.skewSightings = []; // server-minus-client estimates from new-segment sightings+ this.lastSkewSightingKey = null;this.currentLatency = null;-- // Keep track of all the latencies we encountered buffering events- // in order to determine a new minimum latency.- this.bufferedAtLatency = [];+ this.consecutiveStableChecks = 0;+ this.latencySamples = [];+ this.bandwidthHistory = [];+ this.playableBufferHistory = [];++ // Earned trust: 3 clean minutes thin the safety cushion; any rebuffer,+ // timeout, or headroom loss reverts instantly.+ this.trustSince = null;+ this.trusted = false;++ // "lowest" (default) pins to the lowest rendition while compensating;+ // "current" only blocks upswitches.+ this.qualityPinMode = options.qualityPinMode === 'current' ? 'current' : 'lowest';++ // Last decision and the signals that produced it, for stats consumers.+ this.lastAction = null;+ this.lastPlayableBufferSec = null;+ this.lastBufferFloorSec = null;++ // Recent rebuffering events: { latencyMs: number|null, atMs: number }.+ // Pruned by age on access; the count and worst latency derive from it.+ // Restored from sessionStorage so a reload keeps learned caution.+ this.rebufferEvents = loadPersistedRebufferEvents();this.player.on('playing', this.handlePlaying.bind(this));this.player.on('pause', this.handlePause.bind(this));@@ -97,258 +434,380 @@ class LatencyCompensator {this.player.on('canplaythrough', this.handlePlaying.bind(this));this.player.on('canplay', this.handlePlaying.bind(this));+ this.onStats = null;+this.check = this.check.bind(this);- this.start = this.start.bind(this);- this.enable = this.enable.bind(this);- this.countBufferingEvent = this.countBufferingEvent.bind(this);+ this.smoothSpeedAdjustment = this.smoothSpeedAdjustment.bind(this);}// To keep our client clock in sync with the server clock to determine// accurate latency the clock skew should be set here to be used in// the calculation. Otherwise if somebody's client clock is significantly// off it will have a very incorrect latency determination and make bad- // decisions.+ // decisions. When this is never called, a coarse self-estimate kicks in+ // for clocks that are more than 10s off (see observeClockSkew).setClockSkew(skewMs) {this.clockSkewMs = skewMs;+ this.skewWasSet = true;}- // This is run on a timer to check if we should be compensating for latency.+ // Watch for newly published segments; each first sighting bounds the+ // server-client clock offset: est = (pdt + duration) − clientNow, which is+ // trueSkew minus the publish/poll delay, so est <= trueSkew. The MAX of+ // recent sightings is the least-delayed bound and under-reports latency —+ // the conservative direction.+ observeClockSkew(playlist) {+ for (let i = playlist.segments.length - 1; i >= 0; i -= 1) {+ const segment = playlist.segments[i];+ if (segment.dateTimeObject) {+ const key = segment.dateTimeObject.getTime();+ if (key !== this.lastSkewSightingKey) {+ this.lastSkewSightingKey = key;+ this.skewSightings.push(key + (segment.duration || 0) * 1000 - Date.now());+ if (this.skewSightings.length > SKEW_SIGHTING_WINDOW) {+ this.skewSightings.shift();+ }+ }+ return;+ }+ }+ }++ // The skew actually used in latency math. An explicit setClockSkew always+ // wins. The self-estimate only applies when the apparent clock error is+ // large (> 10s): small errors are harmless under the buffer-first design,+ // but a clock minutes off used to make the compensator permanently inert+ // via the bad-data guard.+ effectiveClockSkewMs() {+ if (this.skewWasSet) {+ return this.clockSkewMs;+ }+ if (this.skewSightings.length === 0) {+ return 0;+ }+ const estimate = Math.max(...this.skewSightings);+ return Math.abs(estimate) > SKEW_ESTIMATION_MIN_ERROR ? estimate : 0;+ }++ enable() {+ this.enabled = true;+ clearInterval(this.checkTimer);+ clearTimeout(this.bufferingTimer);++ this.checkTimer = setInterval(() => {+ this.check();+ }, CHECK_TIMER_INTERVAL);+ }++ // Disable means we're done for good and should no longer compensate.+ disable() {+ clearInterval(this.checkTimer);+ clearInterval(this.speedAdjustmentTimer);+ this.speedAdjustmentTimer = 0;+ clearTimeout(this.timeoutTimer);+ clearTimeout(this.bufferingTimer);+ this.inTimeout = false;+ this.stop();+ this.resetPlaybackRate();+ this.enabled = false;+ }++ // Runs on a timer: gather player state, ask decide() what to do, act on it.check() {- // We have an arbitrary delay at startup to allow the player to run- // normally and hopefully get a bit of a buffer of segments before we- // start messing with it.- if (new Date().getTime() - this.startupTime.getTime() < STARTUP_WAIT_TIME) {+ if (!this.enabled) {return;}- // If we're paused then do nothing.- if (this.player.paused()) {+ // Leave the player alone right after startup so it can settle and+ // build up a buffer before we start measuring or acting.+ if (Date.now() - this.startupTime < STARTUP_WAIT_TIME) {+ this.reportIdle('startup grace period');return;}- if (this.player.seeking()) {+ if (this.inTimeout) {+ // Keep the timeout countdown flowing to stats consumers.+ this.reportStats(0, 0);return;}- if (this.inTimeout) {+ if (this.player.paused()) {+ this.consecutiveStableChecks = 0;+ this.reportIdle('paused');return;}- if (!this.enabled) {+ if (this.player.seeking()) {+ this.consecutiveStableChecks = 0;+ this.reportIdle('seeking');return;}const tech = this.player.tech({ IWillNotUseThisInPlugins: true });// We need access to the internal tech of VHS to move forward.- // If running under an Apple browser that uses CoreMedia (Safari)- // we do not have access to this as the tech is internal to the OS.+ // Native playback (e.g. Safari CoreMedia) doesn't expose it.if (!tech || !tech.vhs) {+ this.reportIdle('no VHS tech (native playback?)');return;}- // Network state 2 means we're actively using the network.- // We only want to attempt latency compensation if we're continuing to- // download new segments.+ // States 0 (NETWORK_EMPTY) and 3 (NETWORK_NO_SOURCE) mean nothing is+ // arriving. State 1 (IDLE) is normal for live HLS between segment+ // fetches and must not reset stability.const networkState = this.player.networkState();- if (networkState !== 2) {+ if (networkState === 0 || networkState === 3) {+ this.consecutiveStableChecks = 0;+ this.reportIdle('network not delivering');return;}- let totalBuffered = 0;-try {- // Check the player buffers to make sure there's enough playable content- // that we can safely play.- if (tech.vhs.stats.buffered.length === 0) {- this.timeout();+ const playlist = tech.vhs.playlists.media();+ if (!playlist || !playlist.segments || playlist.segments.length === 0) {+ this.reportIdle('no playlist data yet');return;}- tech.vhs.stats.buffered.forEach(buffer => {- totalBuffered += buffer.end - buffer.start;- });- } catch (e) {- console.error(e);- }+ const playlistBandwidth = playlist.attributes && playlist.attributes.BANDWIDTH;+ const playerBandwidth = tech.vhs.systemBandwidth;+ if (playlistBandwidth > 0 && playerBandwidth > 0) {+ this.bandwidthHistory.push(playerBandwidth / playlistBandwidth);+ if (this.bandwidthHistory.length > 10) {+ this.bandwidthHistory.shift();+ }+ }- // Determine how much of the current playlist's bandwidth requirements- // we're utilizing. If it's too high then we can't afford to push- // further into the future because we're downloading too slowly.- const currentPlaylist = tech.vhs.playlists.media();- const currentPlaylistBandwidth = currentPlaylist.attributes.BANDWIDTH;- const playerBandwidth = tech.vhs.systemBandwidth;- const bandwidthRatio = playerBandwidth / currentPlaylistBandwidth;+ if (!this.skewWasSet) {+ this.observeClockSkew(playlist);+ }- try {const segment = getCurrentlyPlayingSegment(tech);- if (!segment) {+ if (!segment || !segment.dateTimeObject) {+ this.reportIdle('no segment timing (stream lacks program-date-time?)');return;}+ const segmentDurationSec = segment.duration || playlist.targetDuration || 4;- // If we're downloading media fast enough or we feel like we have a large- // enough buffer then continue. Otherwise timeout for a bit.- if (bandwidthRatio < REQUIRED_BANDWIDTH_RATIO && totalBuffered < segment.duration * 6) {- this.timeout();- return;+ const playableBufferRawSec = this.playableBufferSeconds();+ this.playableBufferHistory.push(playableBufferRawSec);+ if (this.playableBufferHistory.length > 10) {+ this.playableBufferHistory.shift();}-- // How far away from live edge do we stop the compensator.- const computedMinLatencyThreshold = Math.max(- MIN_LATENCY,- segment.duration * 1000 * LOWEST_LATENCY_SEGMENT_LENGTH_MULTIPLIER,- );-- // Create an array of all the buffering events in the past along with- // the computed min latency above.- const targetLatencies = this.bufferedAtLatency.concat([computedMinLatencyThreshold]);-- // Determine if we need to reduce the minimum latency we computed- // above based on buffering events that have taken place in the past by- // creating an array of all the buffering events and the above computed- // minimum latency target and averaging all those values.- const minLatencyThreshold =- targetLatencies.reduce((sum, current) => sum + current, 0) / targetLatencies.length;-- // How far away from live edge do we start the compensator.- let maxLatencyThreshold = Math.max(- minLatencyThreshold * 1.4,- Math.min(segment.duration * 1000 * HIGHEST_LATENCY_SEGMENT_LENGTH_MULTIPLIER, MAX_LATENCY),- );-- // If this newly adjusted minimum latency ends up being greater than- // the previously computed maximum latency then reset the maximum- // value using the minimum + an offset.- if (minLatencyThreshold >= maxLatencyThreshold) {- maxLatencyThreshold = minLatencyThreshold + 3000;+ // The raw playable buffer sawtooths by a whole segment as segments+ // land, and the 3s check cadence aliases against 2s/4s segment+ // arrivals into a period-2 alternation that a median passes straight+ // through. An even-length MEAN cancels it: 4 samples span a full beat+ // cycle for both 2s and 4s segments.+ const history = this.playableBufferHistory;+ const playableBufferSec = mean(history.slice(-4));+ const bufferTrendSec =+ history.length >= 8 ? playableBufferSec - mean(history.slice(-8, -4)) : 0;++ // Latency is measured against the segment's program-date-time plus+ // how far into the segment the playhead is — otherwise the estimate+ // saw-tooths by a whole segment duration. Samples are median-smoothed.+ const intraSegmentMs =+ typeof segment.start === 'number'+ ? Math.max((tech.currentTime() - segment.start) * 1000, 0)+ : 0;+ const sample =+ Date.now() ++ this.effectiveClockSkewMs() -+ (segment.dateTimeObject.getTime() + intraSegmentMs);+ this.latencySamples.push(sample);+ if (this.latencySamples.length > LATENCY_SAMPLE_COUNT) {+ this.latencySamples.shift();}-- const segmentTime = segment.dateTimeObject.getTime();- const now = new Date().getTime() + this.clockSkewMs;- const latency = now - segmentTime;- this.currentLatency = latency;-- // Since the calculation of latency is based on clock times, it's possible- // things can be reported incorrectly. So we use a sanity check here to- // simply bail if the latency is reported to so high we think the whole- // thing is wrong. We can't make decisions based on bad data, so give up.- // This can also occur if somebody pauses for a long time and hits play- // again but it's not really possible to know the difference between- // the two scenarios.- if (Math.abs(latency) > MAX_ACTIONABLE_LATENCY) {- this.timeout();- return;+ const latencyMs = median(this.latencySamples);+ this.currentLatency = latencyMs;++ // Earned trust: the clock runs only while conditions are clean and+ // resets the moment they aren't. Reverting is instant, re-earning+ // takes the full duration again.+ const bandwidthRatio = this.getAverageBandwidth();+ if (+ this.bufferingCounter > 0 ||+ bandwidthRatio === null ||+ bandwidthRatio < REQUIRED_BANDWIDTH_RATIO+ ) {+ this.trustSince = null;+ } else if (this.trustSince === null) {+ this.trustSince = Date.now();}+ this.trusted =+ this.trustSince !== null && Date.now() - this.trustSince >= TRUST_EARN_DURATION;++ const floor = bufferFloorSeconds(segmentDurationSec, this.trusted);+ const healthy =+ playableBufferSec >= floor && bufferTrendSec >= -bufferShrinkLimit(segmentDurationSec);+ this.consecutiveStableChecks = healthy ? this.consecutiveStableChecks + 1 : 0;++ const worstRebufferLatencyMs = this.worstRebufferLatency();+ const action = decide({+ latencyMs,+ playableBufferSec,+ playableBufferRawSec,+ bufferTrendSec,+ bandwidthRatio,+ segmentDurationSec,+ stableChecks: this.consecutiveStableChecks,+ rebufferEvents: this.bufferingCounter,+ worstRebufferLatencyMs,+ msSinceLastSpeedChange: Date.now() - this.lastSpeedChange,+ msSinceLastJump: this.lastJumpOccurred ? Date.now() - this.lastJumpOccurred : Infinity,+ running: this.running,+ trusted: this.trusted,+ });- if (latency > maxLatencyThreshold) {- // If the current latency exceeds the max jump amount then- // force jump into the future, skipping all the video in between.- if (this.shouldJumpToLive() && latency > maxLatencyThreshold + MAX_JUMP_LATENCY) {- const jumpAmount = latency / 1000 - segment.duration * 3;- const seekPosition = this.player.currentTime() + jumpAmount;- console.info(- 'latency',- latency / 1000,- 'jumping',- jumpAmount,- 'to live from ',- this.player.currentTime(),- ' to ',- seekPosition,- );-- // Verify we have the seek position buffered before jumping.- const availableBufferedTimeEnd = tech.vhs.stats.buffered[0].end;- const availableBufferedTimeStart = tech.vhs.stats.buffered[0].start;- if (seekPosition > availableBufferedTimeStart < availableBufferedTimeEnd) {- this.jump(seekPosition);-- return;- }- }-- // Using our bandwidth ratio determine a wide guess at how fast we can play.- let proposedPlaybackRate = bandwidthRatio * 0.33;-- // But limit the playback rate to a max value.- proposedPlaybackRate = Math.max(Math.min(proposedPlaybackRate, MAX_SPEEDUP_RATE), 1.0);-- if (proposedPlaybackRate > this.playbackRate + MAX_SPEEDUP_RAMP) {- // If this proposed speed is substantially faster than the current rate,- // then allow us to ramp up by using a slower value for now.- proposedPlaybackRate = this.playbackRate + MAX_SPEEDUP_RAMP;- }-- // Limit to 3 decimal places of precision.- proposedPlaybackRate = Math.round(proposedPlaybackRate * 10 ** 3) / 10 ** 3;+ this.lastAction = action;+ this.lastPlayableBufferSec = playableBufferSec;+ this.lastBufferFloorSec = floor;- // Otherwise start the playback rate adjustment.- this.start(proposedPlaybackRate);- } else if (latency <= minLatencyThreshold) {- this.stop();+ const { minLatencyMs, maxLatencyMs } = effectiveLatencyBand(+ segmentDurationSec,+ worstRebufferLatencyMs,+ latencyMs,+ playableBufferSec,+ this.trusted,+ );+ this.reportStats(minLatencyMs, maxLatencyMs);++ switch (action.type) {+ case 'timeout':+ this.timeout();+ break;+ case 'stop':+ this.stop();+ break;+ case 'jump':+ this.jump(this.player.currentTime() + action.aheadSec);+ break;+ case 'speed':+ this.startSpeed(action.rate);+ break;+ default:+ break;}console.info('latency',- latency / 1000,+ latencyMs / 1000,'min',- minLatencyThreshold / 1000,+ minLatencyMs / 1000,'max',- maxLatencyThreshold / 1000,- 'playback rate',+ maxLatencyMs / 1000,+ 'playable',+ playableBufferSec,+ 'action',+ action.type,+ `(${action.reason})`,+ 'rate',this.playbackRate,- 'enabled:',- this.enabled,- 'running: ',- this.running,- 'skew: ',- this.clockSkewMs,- 'rebuffer events: ',+ 'target rate',+ this.targetPlaybackRate,+ 'rebuffer events',this.bufferingCounter,+ 'stable checks',+ this.consecutiveStableChecks,);- } catch {- // console.error(err);+ } catch (err) {+ console.trace(err);}}- shouldJumpToLive() {- // If we've been rebuffering some recently then don't make it worse by- // jumping more into the future.- if (this.bufferingCounter > 1) {- return false;+ // Seconds of buffered content ahead of the playhead, using the buffered+ // range that actually contains the playhead (not just the first range).+ playableBufferSeconds() {+ const buffered = this.player.buffered();+ const currentTime = this.player.currentTime();+ for (let i = 0; i < buffered.length; i++) {+ if (currentTime >= buffered.start(i) - 0.5 && currentTime <= buffered.end(i)) {+ return buffered.end(i) - currentTime;+ }}+ return 0;+ }- const now = new Date().getTime();- const delta = now - this.lastJumpOccurred;- return delta > MAX_JUMP_FREQUENCY;+ getAverageBandwidth() {+ if (this.bandwidthHistory.length < 5) {+ return null;+ }+ // Use the 30th percentile for a conservative estimate.+ const sorted = [...this.bandwidthHistory].sort((a, b) => a - b);+ return sorted[Math.floor(sorted.length * 0.3)];}- jump(seekPosition) {- this.jumpingToLiveIgnoreBuffer = true;- this.performedInitialLiveJump = true;+ getAveragePlayableBuffer() {+ if (this.playableBufferHistory.length === 0) {+ return 0;+ }+ return (+ this.playableBufferHistory.reduce((a, b) => a + b, 0) / this.playableBufferHistory.length+ );+ }- this.lastJumpOccurred = new Date();+ // ---- Rebuffer memory ----- console.info('current time', this.player.currentTime(), 'seeking to', seekPosition);- this.player.currentTime(seekPosition);+ pruneRebufferEvents() {+ const cutoff = Date.now() - BUFFERING_AMNESTY_DURATION;+ this.rebufferEvents = this.rebufferEvents.filter(e => e.atMs > cutoff);+ }- setTimeout(() => {- this.jumpingToLiveIgnoreBuffer = false;- }, 5000);+ get bufferingCounter() {+ this.pruneRebufferEvents();+ return this.rebufferEvents.length;}- setPlaybackRate(rate) {- this.playbackRate = rate;- this.player.playbackRate(rate);+ worstRebufferLatency() {+ this.pruneRebufferEvents();+ const latencies = this.rebufferEvents.map(e => e.latencyMs).filter(l => Number.isFinite(l));+ return latencies.length ? Math.max(...latencies) : null;+ }++ countBufferingEvent() {+ this.pruneRebufferEvents();+ this.rebufferEvents.push({+ latencyMs: Number.isFinite(this.currentLatency) ? this.currentLatency : null,+ atMs: Date.now(),+ });+ persistRebufferEvents(this.rebufferEvents);+ this.consecutiveStableChecks = 0;+ // Rebuffering instantly revokes earned trust.+ this.trustSince = null;+ this.trusted = false;++ if (this.rebufferEvents.length > REBUFFER_EVENT_LIMIT) {+ this.disable();+ return;+ }++ console.log(+ 'latency compensation timeout due to buffering:',+ this.rebufferEvents.length,+ 'buffering events of',+ REBUFFER_EVENT_LIMIT,+ );}- start(rate = 1.0) {- if (this.inTimeout || !this.enabled || rate === this.playbackRate) {+ // ---- Actions ----++ startSpeed(rate) {+ if (this.inTimeout || !this.enabled) {return;}- this.running = true;- this.setPlaybackRate(rate);+ if (!this.running) {+ this.running = true;+ this.enableOnlyLowQualityPlayback();+ }++ if (rate !== this.targetPlaybackRate) {+ this.targetPlaybackRate = rate;+ this.lastSpeedChange = Date.now();+ }++ this.ensureRampTimer();}stop() {@@ -356,25 +815,13 @@ class LatencyCompensator {console.log('stopping latency compensator...');}this.running = false;- this.setPlaybackRate(1.0);- }-- enable() {- this.enabled = true;- clearInterval(this.checkTimer);- clearTimeout(this.bufferingTimer);+ this.enableAllQualityPlayback();- this.checkTimer = setInterval(() => {- this.check();- }, CHECK_TIMER_INTERVAL);- }-- // Disable means we're done for good and should no longer compensate for latency.- disable() {- clearInterval(this.checkTimer);- clearTimeout(this.timeoutTimer);- this.stop();- this.enabled = false;+ // Ramp gently back to 1.0 — a stop is not an emergency.+ this.targetPlaybackRate = 1.0;+ if (this.playbackRate !== 1.0) {+ this.ensureRampTimer();+ }}timeout() {@@ -384,18 +831,94 @@ class LatencyCompensator {this.inTimeout = true;this.stop();+ // A timeout means risk was detected: return to normal speed immediately+ // and revoke earned trust.+ this.resetPlaybackRate();+ this.consecutiveStableChecks = 0;+ this.trustSince = null;+ this.trusted = false;clearTimeout(this.timeoutTimer);this.timeoutTimer = setTimeout(() => {this.endTimeout();}, TIMEOUT_DURATION);+ if (this.timeoutEndingAt === 0) {+ this.timeoutEndingAt = Date.now() + TIMEOUT_DURATION;+ }+ this.reportStats(0, 0);}endTimeout() {clearTimeout(this.timeoutTimer);this.inTimeout = false;+ this.timeoutEndingAt = 0;+ }++ jump(seekPosition) {+ // Safety invariant: we never seek backwards.+ if (seekPosition <= this.player.currentTime()) {+ return;+ }++ this.jumpingToLiveIgnoreBuffer = true;+ this.lastJumpOccurred = Date.now();+ this.consecutiveStableChecks = 0;+ this.latencySamples = [];+ this.resetPlaybackRate();++ console.info('jumping from', this.player.currentTime(), 'to', seekPosition);+ this.player.currentTime(seekPosition);++ setTimeout(() => {+ this.jumpingToLiveIgnoreBuffer = false;+ }, JUMP_IGNORE_BUFFER_DURATION);}+ // ---- Playback rate plumbing ----++ applyPlaybackRate(rate) {+ this.playbackRate = rate;+ this.player.playbackRate(rate);+ }++ resetPlaybackRate() {+ this.targetPlaybackRate = 1.0;+ this.applyPlaybackRate(1.0);+ }++ ensureRampTimer() {+ if (!this.speedAdjustmentTimer) {+ this.speedAdjustmentTimer = setInterval(+ this.smoothSpeedAdjustment,+ SPEED_ADJUSTMENT_INTERVAL,+ );+ }+ }++ // Moves the actual playback rate toward the target in imperceptible steps,+ // in both directions. Shuts its own timer down once settled at 1.0.+ smoothSpeedAdjustment() {+ if (!this.enabled || this.inTimeout) {+ this.resetPlaybackRate();+ }++ const diff = this.targetPlaybackRate - this.playbackRate;+ if (Math.abs(diff) <= MAX_SPEEDUP_RAMP) {+ if (this.playbackRate !== this.targetPlaybackRate) {+ this.applyPlaybackRate(this.targetPlaybackRate);+ }+ if (this.targetPlaybackRate === 1.0) {+ clearInterval(this.speedAdjustmentTimer);+ this.speedAdjustmentTimer = 0;+ }+ return;+ }++ this.applyPlaybackRate(this.playbackRate + Math.sign(diff) * MAX_SPEEDUP_RAMP);+ }++ // ---- Event handlers ----+handlePlaying() {const wasPreviouslyPlaying = this.playing;this.playing = true;@@ -405,25 +928,64 @@ class LatencyCompensator {return;}- if (!this.shouldJumpToLive()) {+ // Coming back from a stall: don't add seeking to the mix, just play.+ if (wasPreviouslyPlaying) {+ return;+ }++ // Cold start or resuming from a pause: catch up the accumulated gap by+ // seeking near — never onto — the live edge.+ this.seekNearLiveEdge();+ }++ // Seek forward to (live edge - buffer floor - one segment): the viewer+ // skips the gap but lands with breathing room instead of on the edge+ // itself, where the buffer is zero by definition.+ seekNearLiveEdge() {+ if (this.bufferingCounter > 0) {+ return;+ }+ if (Date.now() - this.lastJumpOccurred < MAX_JUMP_FREQUENCY) {return;}- // If we were not previously playing (was paused, or this is a cold start)- // seek to live immediately on starting playback to handle any long-pause- // scenarios or somebody starting far back from the live edge.- // If we were playing previously then that means we're probably coming back- // from a rebuffering event, meaning we should not be adding more seeking- // to the mix, just let it play.- if (!wasPreviouslyPlaying) {+ try {+ const seekable = this.player.seekable();+ if (!seekable || seekable.length === 0) {+ return;+ }+ const liveEdge = seekable.end(seekable.length - 1);++ const tech = this.player.tech({ IWillNotUseThisInPlugins: true });+ const playlist = tech && tech.vhs && tech.vhs.playlists.media();+ const segmentDurationSec = (playlist && playlist.targetDuration) || 4;++ const target = liveEdge - (bufferFloorSeconds(segmentDurationSec) + segmentDurationSec);++ // Only forward, and only when the gap is worth skipping.+ if (target - this.player.currentTime() < 2 * segmentDurationSec) {+ return;+ }+this.jumpingToLiveIgnoreBuffer = true;- this.player.liveTracker.seekToLiveEdge();- this.lastJumpOccurred = new Date();+ this.lastJumpOccurred = Date.now();+ this.consecutiveStableChecks = 0;+ this.latencySamples = [];++ console.info('seeking near live edge:', target);+ this.player.currentTime(target);++ setTimeout(() => {+ this.jumpingToLiveIgnoreBuffer = false;+ }, JUMP_IGNORE_BUFFER_DURATION);+ } catch (err) {+ console.trace(err);}}handlePause() {this.playing = false;+ this.consecutiveStableChecks = 0;}handleEnded() {@@ -442,48 +1004,123 @@ class LatencyCompensator {this.timeout();}- countBufferingEvent() {- this.bufferingCounter += 1;-- if (this.bufferingCounter > REBUFFER_EVENT_LIMIT) {- this.disable();+ handleBuffering() {+ if (Date.now() - this.startupTime < STARTUP_WAIT_TIME) {return;}- this.bufferedAtLatency.push(this.currentLatency);-- console.log(- 'latency compensation timeout due to buffering:',- this.bufferingCounter,- 'buffering events of',- REBUFFER_EVENT_LIMIT,- );-- // Allow us to forget about old buffering events if enough time goes by.- setTimeout(() => {- if (this.bufferingCounter > 0) {- this.bufferingCounter -= 1;- }- }, BUFFERING_AMNESTY_DURATION);- }-- handleBuffering() {- if (!this.enabled || this.inTimeout) {+ if (this.jumpingToLiveIgnoreBuffer) {return;}- if (this.jumpingToLiveIgnoreBuffer) {- this.jumpingToLiveIgnoreBuffer = false;+ // A stall while the player is seeking is the fetch at a seek+ // discontinuity (e.g. the viewer scrubbed), not playback starvation —+ // genuine starvation fires with seeking() false. Not our fault: don't+ // count it against the compensator or enter a timeout for it.+ if (this.player.seeking()) {return;}+ // Stop spending buffer immediately.+ if (this.running) {+ this.resetPlaybackRate();+ }+this.timeout();+ // Only count events that last long enough to matter.clearTimeout(this.bufferingTimer);this.bufferingTimer = setTimeout(() => {this.countBufferingEvent();}, MIN_BUFFER_DURATION);}++ // ---- Quality pinning ----+ // While actively compensating, renditions are restricted per+ // options.qualityPinMode: "lowest" (default) keeps only the cheapest+ // rendition so the freed headroom goes toward catching up; "current"+ // only blocks upswitches. All renditions are restored the moment+ // compensation stops.++ enableOnlyLowQualityPlayback() {+ this.setQualityPinned(true);+ }++ enableAllQualityPlayback() {+ this.setQualityPinned(false);+ }++ setQualityPinned(pinned) {+ try {+ const tech = this.player.tech({ IWillNotUseThisInPlugins: true });+ const representations =+ tech && tech.vhs && typeof tech.vhs.representations === 'function'+ ? tech.vhs.representations()+ : null;+ if (!representations || representations.length < 2) {+ return;+ }++ if (pinned && this.qualityPinMode === 'current') {+ const playlist = tech.vhs.playlists.media();+ const currentBandwidth = playlist && playlist.attributes && playlist.attributes.BANDWIDTH;+ if (!(currentBandwidth > 0)) {+ return; // can't tell what "current" is; leave renditions alone+ }+ representations.forEach(rep => {+ rep.enabled((rep.bandwidth || 0) <= currentBandwidth);+ });+ return;+ }++ const lowest = representations.reduce((a, b) =>+ (a.bandwidth || 0) <= (b.bandwidth || 0) ? a : b,+ );+ representations.forEach(rep => {+ rep.enabled(pinned ? rep === lowest : true);+ });+ } catch {+ // Renditions API unavailable; quality pinning is best-effort.+ }+ }++ // For inert states (startup grace, paused, no tech, ...) surface WHY the+ // compensator is doing nothing, so stats consumers never go stale exactly+ // when an explanation is most needed.+ reportIdle(reason) {+ this.lastAction = { type: 'idle', reason };+ this.reportStats(0, 0);+ }++ reportStats(minEndingLatency, maxStartingLatency) {+ if (!this.onStats) {+ return;+ }++ const stats = {+ latency: this.currentLatency,+ playbackRate: this.playbackRate,+ targetPlaybackRate: this.player.playbackRate(),+ enabled: this.enabled,+ running: this.running,+ bufferingEvents: this.bufferingCounter,+ inTimeout: this.inTimeout,+ timeoutRemaining: this.inTimeout ? this.timeoutEndingAt - Date.now() : 0,+ minEndingLatency,+ maxStartingLatency,+ averageBufferSeconds: this.getAveragePlayableBuffer(),+ averageBandwidthRatio: this.getAverageBandwidth(),+ consecutiveStableChecks: this.consecutiveStableChecks,+ // The last decision and the signals that produced it.+ action: this.lastAction,+ targetRate: this.targetPlaybackRate,+ playableBufferSeconds: this.lastPlayableBufferSec,+ bufferFloorSeconds: this.lastBufferFloorSec,+ trusted: this.trusted,+ };++ this.onStats(stats);+ }}export default LatencyCompensator;diff --git a/web/components/video/settings-menu.ts b/web/components/video/settings-menu.tsindex 1d44f0f2bf..f4403f1faf 100644--- a/web/components/video/settings-menu.ts+++ b/web/components/video/settings-menu.ts@@ -94,7 +94,7 @@ export function createVideoSettingsMenuButton(defaultAutoItem.selected(true);});- const supportsLatencyCompensator = false; //! !tech && !!tech.vhs;+ const supportsLatencyCompensator = !!tech && !!tech.vhs;// Only show the quality selector if there is more than one option.if (qualities.length < 2 && supportsLatencyCompensator) {