[hongjun-bae]

This PR will...

Mark a fragment as a gap when its append fails with a SourceBuffer error, so playback continues after the automatic recoverMediaError() instead of loading the same fragment again.

Why is this Pull Request needed?

A SourceBuffer error sets HTMLMediaElement.error, and error-controller resets the MediaSource with recoverMediaError(). Without an alternate level the same fragment is loaded after every reset until append errors escalate to fatal.

Are there any points in the code the reviewer needs to double check?

• buffer-controller only names the error it creates in onSBUpdateError (HlsJsSourceBufferError). Retry counts, append error counting and fatal escalation are unchanged.
• stream-controller and audio-stream-controller handle MEDIA_SOURCE_REQUIRES_RESET with that name and mark the fragment with addAsGap(). Fragments of an ended playlist are not marked, so a damaged VOD segment keeps the existing retry path and ends fatal.
• Gaps are carried across detach with gapFragments(), as suggested. Fragment and part selection skip only fragments marked this way. The seek that follows re-attach skips the gap purge once when such a gap was carried; later seeks clear the tracker entries, so a marked fragment is retried when it is loaded again as a whole segment or after a playlist update.
• The fragment is marked, not the part. The byte stream parser keeps an incomplete media segment and fails once later bytes do not parse (segment parser loop, append error), so a truncated part is accepted and the error is reported on the next append. Marking the reported part marked healthy media and ended fatal in 2 of 5 runs. The previous fragment is marked too when the buffer ends more than maxBufferHole before the parsed start of the refused fragment or first part, on the inference that its tail never reached the buffer. A damaged first part leaves no such hole, so only its own fragment is marked. Decoder errors do not raise the SourceBuffer error event and are not marked.

Resolves issues:

#8035

Checklist

• changes have been done against master branch, and PR does not conflict
• new unit / functional tests have been added (whenever applicable)
• API or design changes are documented in API.md

The api-extractor report adds FragmentTracker.gapFragments(), FragmentTracker.isGap() and the protected onSourceBufferError(). npm run test:unit passes 1233 tests.

Tested in Chrome on three live LL-HLS streams (2, 4 and 5 parts per segment), over CDN (five variants, 1080p pinned by the player via preserveManualLevelOnError, so every reset came back to the damaged variant) and over a P2P agent (one variant), at the live edge, rewound 120 s into the DVR window (whole-segment loading) and without DVR. One segment was corrupted in the player before append:

• every part truncated, and the first video NAL length overwritten as in SourceBuffer append rejection loops indefinitely on a single variant stream: locally determined gaps do not survive recoverMediaError() #8035: 14/14 recovered with one reset, only that segment skipped
• only the last part truncated: 9/9 recovered with one reset, that segment and the next skipped (4 s with two parts, 6 to 7 s with five); master on the same stream: fatal
• rewound into the DVR window, or a rendition without parts, with the last part truncated: 6/6 recovered with one reset, that segment and the next skipped; master: 70 and 34 resets in 60 s, or fatal

Not covered: a tail cut by so few bytes that the next append completes it, or damage the demuxer accepts and only the decoder rejects; those stall on master and here alike. After re-attach, if playback stalls a few ms before the marked fragment, the gap-controller nudge seek clears the mark and the fragment is refused once more (3 of about 60 runs). Automatic level selection was not measured.

[robwalch]

This needs to be re-thinked such that more of the existing error handling and selection logic is reused or tuned to handle the problem. This PR only adds new code. This "bandaid" will likely cause new regressions and skip valid media, in addition to addressing whatever is causing #8035.

[hongjun-bae]

@robwalch I believe treating corrupted chunks as gaps rather than errors could significantly improve playback QoE. Any remaining concerns, or are we good to merge?

[robwalch]

We should remove this, and just never remove gaps on first seek (from 0) after reattach. That way, we're not introducing use of Set to the library, or a another state flag (keepGapsOnSeek) to stream controllers.

[hongjun-bae]

Removed, with the Set and the flag. onMediaSeeking now keeps gaps until hasEnoughToStart is set and the seek lands outside the buffer, as in the thread below.

[robwalch]

Remove along with sourceBufferErrorGaps

[hongjun-bae]

Removed.

[robwalch]

Remove in favor of keeping gaps on seek to start pos.

[hongjun-bae]

Removed. The detach still carries tracked gaps across removeAllFragments().

[robwalch]

Use hasEnoughToStart:

Suggested change

	if (this.keepGapsOnSeek) {
	// Keep gap fragments on the first seek after re-attach
	this.keepGapsOnSeek = false;
	} else {
	// Remove gap fragments
	this.fragmentTracker.removeFragmentsInRange(
	currentTime,
	Infinity,
	this.playlistType,
	true,
	);
	}
	if (this.hls?.hasEnoughToStart) {
	// Remove gap fragments on seek after `seekToStartPos`
	this.fragmentTracker.removeFragmentsInRange(
	currentTime,
	Infinity,
	this.playlistType,
	true,
	);
	}

Then, change stream-controller to set _hasEnoughToStart immediately after seekToStartPos():

     if (!this._hasEnoughToStart && BufferHelper.getBuffered(media).length) {
-      this._hasEnoughToStart = true;
       this.seekToStartPos();
+      this._hasEnoughToStart = true;
     }

[hongjun-bae]

Applied as suggested, with one more condition: gaps are removed only when the seek lands outside the buffer (!fowardBuffer).

The gate alone left two measured cases:

• seeking is dispatched from a queued task, so onMediaSeeking already reads hasEnoughToStart === true for the seek issued by seekToStartPos() after re-attach. Rewound into the DVR window, 6 of 6 runs removed the carried gap on that seek and ended fatal.
• At the live edge the stream controller sometimes restarts with startPosition = -1 and no start seek; the next seek is the gap-controller's buffer-start adjustment (or a nudge), and it removed a gap ahead of the playhead, 4 of 4 runs.

The seeks hls.js issues itself all land inside the buffer. A user seek onto a gap lands outside it and still removes gaps so they are retried. With this, all eight cells (CDN/P2P, LL-HLS/HLS, live edge/rewound) recover with one reset, 52 of 52 runs, and no seek issued by hls.js removed a tracked gap.