fix: split large appendBuffer to stop QuotaExceededError on high-bitrate segments by alchemyyy · Pull Request #7753 · video-dev/hls.js

alchemyyy · 2026-03-18T05:04:06Z

This PR will...

Split large HLS fMP4 segments into smaller chunks before appending to MSE SourceBuffer, preventing QuotaExceededError with high-bitrate streams.

Why is this Pull Request needed?

When an HLS fMP4 segment exceeds Chromium's per-SourceBuffer quota (~150MB), appendBuffer() throws QuotaExceededError. With high-bitrate remuxed streams (80-150+ Mbps), a single segment can easily reach 95-100MB. At playback start there is no back buffer to evict, so hls.js enters an unrecoverable loop: download → append → QuotaExceededError → flush → retry → repeat.

This PR adds splitAppendData() to buffer-controller.ts that splits large Uint8Array buffers into ≤16MB chunks before appending. When data.byteLength exceeds 16MB, onBufferAppending splits the data and recursively creates separate append operations for each chunk — each with full error handling including QuotaExceeded recovery.

Splitting is attempted first at fMP4 top-level box boundaries. If that can't produce small-enough chunks (e.g. a single giant mdat box, which is the typical FFmpeg HLS output: styp + moof + mdat), it falls back to naive byte splitting. MSE SourceBuffer natively handles reassembly of partial box data across sequential appendBuffer() calls.

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

The fMP4 box-boundary splitting logic in splitAppendData() — verify it correctly parses top-level box headers and falls back to naive splitting when boxes exceed the chunk size
The recursive chunk append flow in onBufferAppending — each chunk gets its own queued operation with the same frag/part/chunkMeta context and error handling

Resolves issues:

Fixes #6711, #6776. Related: #5587, #6529.

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

…high-bitrate segments

robwalch · 2026-03-19T17:21:57Z

Can you provide a sample that reproduces the issue?

Move fMP4 box-boundary splitting functions (`readMp4BoxSize`, `splitAtBoxBoundaries`, `splitAppendData`) from buffer-controller to mp4-tools where they belong. Replace hardcoded `MAX_APPEND_SIZE` constant with a new `config.maxAppendSize` option (default: `Infinity`) so the feature is opt-in and the chunk size is user-configurable. Splitting only activates when `maxAppendSize` is finite.

alchemyyy · 2026-03-23T21:46:30Z

Can you provide a sample that reproduces the issue?

Howdy! Apologies for the delay in reply, wanted to be able to sit down with this.

I wouldn't be able to provide the test file here directly. If you'd like to reach out via email rather than source it yourself, that may work.

I can at least provide an mkvinfo dump and some general context. I came across this issue when beginning at or moving into playback around the 11 minute mark in the test file through jellyfin-web 10.11 on Brave 1.88.134. I was able to reproduce this issue consistently.

Test File Info

</details>

robwalch · 2026-04-01T01:42:14Z

The entire segment still needs to be appended whether whole or in parts. Forcing it into the queue as multiple appends does not prevent QuotaExceeded errors. I'm seeing either corruption errors or unresolved buffer full errors with these changes.

It's unclear if these changes are intended to work on top of #7749 or replace them. Please rebased against latest - #7749 has been merged, but those changes are missing from this branch.

robwalch · 2026-04-01T22:43:44Z

+          this.onBufferAppending(event, {
+            ...eventData,
+            data: chunks[i],


The BUFFER_APPENDING event data's chunkMeta should specify the chunk "id" (index) to aid in tracking append progress:

hls.js/src/controller/base-stream-controller.ts

Lines 1242 to 1251 in 6373b33

const segment: BufferAppendingData = {

type: data.type,

frag,

part,

chunkMeta,

offset,

parent: frag.type,

data: buffer,

};

this.hls.trigger(Events.BUFFER_APPENDING, segment);

const chunkMeta = new ChunkMetadata( frag.level, frag.sn, i, // chunk ID should match index of split data payload.byteLength );

fix: split large appendBuffer calls to prevent QuotaExceededError on …

a3e48a2

…high-bitrate segments

robwalch added this to the 1.7.0 milestone Mar 19, 2026

github-project-automation bot added this to HLS.js Release Planning and Backlog Mar 19, 2026

github-project-automation bot moved this to Top priorities in HLS.js Release Planning and Backlog Mar 19, 2026

robwalch linked an issue Mar 19, 2026 that may be closed by this pull request

Fragments keeps reloading in a loop #6776

Closed

5 tasks

robwalch requested changes Mar 19, 2026

View reviewed changes

Comment thread src/controller/buffer-controller.ts Outdated

Comment thread src/controller/buffer-controller.ts Outdated

This was referenced Mar 24, 2026

HLS Error: Type: mediaError Details: bufferFullError jellyfin/jellyfin-web#4866

Open

Return maxMaxBufferLength to default value jellyfin/jellyfin-web#7740

Open

robwalch requested changes Apr 1, 2026

View reviewed changes

robwalch removed this from the 1.7.0 milestone Apr 1, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix: split large appendBuffer to stop QuotaExceededError on high-bitrate segments#7753

fix: split large appendBuffer to stop QuotaExceededError on high-bitrate segments#7753
alchemyyy wants to merge 2 commits intovideo-dev:masterfrom
alchemyyy:fix/chunked-append-large-segments

alchemyyy commented Mar 18, 2026

Uh oh!

robwalch commented Mar 19, 2026

Uh oh!

Uh oh!

Uh oh!

alchemyyy commented Mar 23, 2026

Uh oh!

robwalch commented Apr 1, 2026

Uh oh!

robwalch Apr 1, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	const segment: BufferAppendingData = {
	type: data.type,
	frag,
	part,
	chunkMeta,
	offset,
	parent: frag.type,
	data: buffer,
	};
	this.hls.trigger(Events.BUFFER_APPENDING, segment);

Conversation

alchemyyy commented Mar 18, 2026

This PR will...

Why is this Pull Request needed?

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

Resolves issues:

Checklist

Uh oh!

robwalch commented Mar 19, 2026

Uh oh!

Uh oh!

Uh oh!

alchemyyy commented Mar 23, 2026

Uh oh!

robwalch commented Apr 1, 2026

Uh oh!

robwalch Apr 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

robwalch Apr 1, 2026 •

edited

Loading