In this guide
Work through a disjoint exampleRead a new snapshot for each observationUse the trend to ask the next questionA buffer display can be misleading if it collapses several loaded intervals into one number. A viewer may have data near the beginning and near the end of a programme while the next few seconds at the current position remain unavailable.
For an existing web player you develop or diagnose, the buffered TimeRanges snapshot lets you calculate a narrower measure: how much buffered media lies directly ahead in the current continuous interval.
Work through a disjoint example
Consider an original hypothetical snapshot with buffered intervals [0, 25] and [80, 110] seconds. Playback is at 20 seconds. The immediate buffered time ahead is 25 − 20 = 5 seconds. Using the last endpoint gives 110 − 20 = 90 seconds, which incorrectly includes fifty-five seconds of gap and a remote interval.
If playback is instead at 82 seconds, the relevant interval is [80, 110] and the simple result is twenty-eight seconds. If playback is at 50 seconds, neither interval contains it. Report no containing buffered interval rather than manufacturing a positive buffer from the later endpoint.
Read a new snapshot for each observation
Check buffered.length before reading start or end values, then find an interval containing currentTime. Read the property again at the next sample because the returned object is static. Keep the sample time with the calculated result; media loading and eviction can change the ranges between observations.
At an interval boundary, numerical precision and the player’s timing behavior need care. A developer may choose a small documented tolerance for an application-specific display, but it should not silently bridge a meaningful gap. This worked explanation does not prescribe one universal tolerance for every media pipeline.
Use the trend to ask the next question
If the containing interval’s available time falls while requests arrive late, the calculation supports a buffer-depletion account. If it stays large while video stops, inspect the media error and frame-presentation evidence rather than blaming insufficient downloaded duration alone. Data being buffered does not certify valid decoding.
Keep seekable separate. A seekable endpoint may be far ahead because the server supports retrieval, even though that media has not arrived locally. A useful diagnostic note records currentTime, all relevant buffered intervals, the derived immediate time ahead and the request interval being compared.
| Current position | Buffered ranges | Immediate time ahead |
|---|---|---|
| 20 s | 0–25 and 80–110 s | 5 s |
| 82 s | 0–25 and 80–110 s | 28 s |
| 50 s | 0–25 and 80–110 s | No containing interval |