From 9f3cf5acedf58d4905e7ab6e097a6da5498524cd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?L=C3=A9onard?= Date: Tue, 3 Nov 2026 16:45:02 +0100 Subject: [PATCH] fix(player): HEVC whose parameter sets travel in-band only plays in Tier B again MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Price of Confession (TFA) ships a bare 23-byte hvcC: no VPS/SPS/PPS arrays, the parameter sets repeat in the stream. Tier B writes an hvc1 sample entry, which carries them out-of-band: Safari's VideoToolbox could not start (black « Buffering », no error, no demotion), and the Gecko-mac CRA splicer refused the record and fell to the WASM transcode (Zen buffering in a loop). completeHvcc() fills the record from the keyframe the run starts on, for the muxer and the splicer alike. Bench: the 10-bit E-AC-3 clip now has the same bare hvcC (repeat-headers + fixtures/bare-hvcc.py, which empties the CodecPrivate in place behind an EBML Void). It stalls at 0 s on the iPad and is refused by the splice on Firefox without the fix, and plays with it. CHANGELOG and the msePlaysAudio comment corrected: the first fix blamed the audio. --- CHANGELOG.md | 11 ++- packages/iris-core/src/caps.ts | 4 +- .../src/decode/hevc-cra-splice.test.ts | 60 ++++++++++++++- .../iris-core/src/decode/hevc-cra-splice.ts | 75 +++++++++++++++++++ packages/iris-core/src/tiers/tier-b-mse.ts | 10 ++- web/e2e/fixtures/bare-hvcc.py | 48 ++++++++++++ web/e2e/fixtures/make.sh | 23 +++--- web/e2e/specs/s03-firefox-cra-splice.spec.ts | 11 +++ 8 files changed, 224 insertions(+), 18 deletions(-) create mode 100644 web/e2e/fixtures/bare-hvcc.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 7f6aba5c..65844294 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,10 +9,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Fixed -- **iPad on Dolby audio**: a release with AC-3 / E-AC-3 audio (most WEB HEVC - MULTi rips) no longer has Safari decode and re-encode the sound before the - picture can start; Safari plays Dolby itself, so the track goes through as it - is. An iPad sat on a black « Buffering » on such an episode. +- **HEVC releases that keep their parameter sets in the stream** (some WEB + rips, TFA's among them) play in the browser again: Safari sat on a black + « Buffering » with no error, and Firefox / Zen on macOS fell back to the slow + WASM transcode and buffered in a loop. The player now builds the missing + codec header from the first keyframe. +- **Dolby audio on Safari**: AC-3 / E-AC-3 goes through as it is, since Safari + plays it itself, instead of being decoded and re-encoded in the page. ## [1.7.1] - 2026-10-31 diff --git a/packages/iris-core/src/caps.ts b/packages/iris-core/src/caps.ts index cdd44ac1..367024a5 100644 --- a/packages/iris-core/src/caps.ts +++ b/packages/iris-core/src/caps.ts @@ -73,8 +73,8 @@ export function mseSupportsType(mime: string): boolean { * Whether MSE plays this audio track as it is, so it rides into the fMP4 untouched. The * server's `browser_native` covers the codecs every browser takes (AAC, Opus, MP3); AC-3 and * E-AC-3 are asked of this browser: Safari (macOS and iPadOS) decodes Dolby itself. There the - * libav.js decode + AudioEncoder re-encode is pure risk: the video feed waits on the transcoded - * audio, and an iPad on a WEB rip's E-AC-3 5.1 sat black on « Buffering » with no error. + * libav.js decode + AudioEncoder re-encode is only cost and risk: the video feed waits on the + * transcoded audio, and a lossy AAC replaces the original track. */ export function msePlaysAudio(track: { codec: string; codec_string?: string | null; browser_native: boolean }): boolean { if (track.browser_native) return true; diff --git a/packages/iris-core/src/decode/hevc-cra-splice.test.ts b/packages/iris-core/src/decode/hevc-cra-splice.test.ts index 93eb59a3..3cf3bff0 100644 --- a/packages/iris-core/src/decode/hevc-cra-splice.test.ts +++ b/packages/iris-core/src/decode/hevc-cra-splice.test.ts @@ -1,5 +1,5 @@ import { describe, expect, it } from 'vitest'; -import { escapeRbsp, HevcSpliceUnsupported, NEEDS_WHOLE_NAL, patchNalPrefix, unescapeRbsp } from './hevc-cra-splice'; +import { completeHvcc, escapeRbsp, HevcSpliceUnsupported, NEEDS_WHOLE_NAL, patchNalPrefix, unescapeRbsp } from './hevc-cra-splice'; /** Deterministic pseudo-random bytes, zero-heavy so emulation prevention happens a lot. */ function rbspBytes(seed: number, length: number): Uint8Array { @@ -86,3 +86,61 @@ describe('patchNalPrefix', () => { ).toThrow('broken'); }); }); + +describe('completeHvcc', () => { + // NAL headers: type << 1, then nuh_temporal_id_plus1 = 1 + const vps = Uint8Array.of(32 << 1, 1, 0xaa, 0xbb); + const sps = Uint8Array.of(33 << 1, 1, 0xcc); + const pps = Uint8Array.of(34 << 1, 1, 0xdd); + const slice = Uint8Array.of(21 << 1, 1, 0xee, 0xff); + const lengthPrefixed = (...nals: Uint8Array[]) => { + const out: number[] = []; + for (const nal of nals) out.push(0, 0, nal.length >> 8, nal.length & 0xff, ...nal); + return Uint8Array.from(out); + }; + const bare = () => { + const h = new Uint8Array(23); + h[0] = 1; + h[21] = 0xff; // lengthSizeMinusOne = 3 + return h; + }; + + it('fills a bare record from the parameter sets the keyframe carries in-band', () => { + const hvcc = bare(); + const out = completeHvcc(hvcc, lengthPrefixed(vps, sps, pps, slice)); + expect(Array.from(out.subarray(0, 22))).toEqual(Array.from(hvcc.subarray(0, 22))); + expect(out[22]).toBe(3); + expect(Array.from(out.subarray(23))).toEqual([ + 0x80 | 32, + 0, + 1, + 0, + 4, + ...vps, + 0x80 | 33, + 0, + 1, + 0, + 3, + ...sps, + 0x80 | 34, + 0, + 1, + 0, + 3, + ...pps + ]); + }); + + it('leaves a record that has its own SPS and PPS alone', () => { + const full = completeHvcc(bare(), lengthPrefixed(vps, sps, pps, slice)); + expect(completeHvcc(full, lengthPrefixed(Uint8Array.of(33 << 1, 1, 0x11), pps, slice))).toBe(full); + }); + + it('gives the record back unchanged when the keyframe has nothing to offer or does not parse', () => { + const hvcc = bare(); + expect(completeHvcc(hvcc, lengthPrefixed(slice))).toBe(hvcc); + expect(completeHvcc(hvcc, Uint8Array.of(0, 0, 0, 99, 1, 2))).toBe(hvcc); + expect(completeHvcc(hvcc.subarray(0, 10), lengthPrefixed(vps, sps, pps))).toEqual(hvcc.subarray(0, 10)); + }); +}); diff --git a/packages/iris-core/src/decode/hevc-cra-splice.ts b/packages/iris-core/src/decode/hevc-cra-splice.ts index 1d368f09..aa64ad37 100644 --- a/packages/iris-core/src/decode/hevc-cra-splice.ts +++ b/packages/iris-core/src/decode/hevc-cra-splice.ts @@ -960,6 +960,81 @@ export function splicePacket(splicer: HevcCraSplicer, packet: EncodedPacket): En ); } +/** + * The `hvcC` with the parameter sets the keyframe carries in-band, when the record has no SPS + * or no PPS of its own. Some WEB rips (TFA's) ship a bare 23-byte header and repeat VPS/SPS/PPS + * in the stream. The fMP4 we write says `hvc1`, which means "parameter sets in the sample + * entry": WebKit's VideoToolbox can't start without them (black screen, no error, the iPad + * « Buffering » report), and the CRA splicer refuses the record. Anything unreadable comes back + * unchanged, so a damaged keyframe never makes a working record worse. + */ +export function completeHvcc(hvcc: Uint8Array, keyframe: Uint8Array): Uint8Array { + if (hvcc.length < 23) return hvcc; + const nalLengthSize = ((hvcc[21] as number) & 3) + 1; + const arrays: { head: number; nals: Uint8Array[] }[] = []; + let p = 23; + for (let a = 0; a < (hvcc[22] as number); a += 1) { + if (p + 3 > hvcc.length) return hvcc; + const head = hvcc[p] as number; + const count = ((hvcc[p + 1] as number) << 8) | (hvcc[p + 2] as number); + p += 3; + const nals: Uint8Array[] = []; + for (let i = 0; i < count; i += 1) { + if (p + 2 > hvcc.length) return hvcc; + const len = ((hvcc[p] as number) << 8) | (hvcc[p + 1] as number); + p += 2; + if (p + len > hvcc.length) return hvcc; + nals.push(hvcc.subarray(p, p + len)); + p += len; + } + arrays.push({ head, nals }); + } + const own = (type: number) => arrays.some((a) => (a.head & 0x3f) === type && a.nals.length > 0); + if (own(NAL.SPS) && own(NAL.PPS)) return hvcc; + + const inband = new Map(); + p = 0; + while (p + nalLengthSize <= keyframe.length) { + let len = 0; + for (let i = 0; i < nalLengthSize; i += 1) len = (len << 8) | (keyframe[p + i] as number); + p += nalLengthSize; + if (len < 2 || p + len > keyframe.length) return hvcc; + const nal = keyframe.subarray(p, p + len); + const type = nalType(nal); + if (type === NAL.VPS || type === NAL.SPS || type === NAL.PPS) inband.set(type, [...(inband.get(type) ?? []), nal]); + p += len; + } + if (!inband.has(NAL.SPS) || !inband.has(NAL.PPS)) return hvcc; + + const parameterSets: number[] = [NAL.VPS, NAL.SPS, NAL.PPS]; + const merged = [ + ...parameterSets.flatMap((type) => { + const nals = inband.get(type) ?? arrays.find((a) => (a.head & 0x3f) === type)?.nals ?? []; + // array_completeness = 1: every set of this type is in the record + return nals.length > 0 ? [{ head: 0x80 | type, nals }] : []; + }), + ...arrays.filter((a) => !parameterSets.includes(a.head & 0x3f)) + ]; + const size = 23 + merged.reduce((sum, a) => sum + 3 + a.nals.reduce((s, nal) => s + 2 + nal.length, 0), 0); + const out = new Uint8Array(size); + out.set(hvcc.subarray(0, 22)); + out[22] = merged.length; + p = 23; + for (const a of merged) { + out[p] = a.head; + out[p + 1] = a.nals.length >> 8; + out[p + 2] = a.nals.length & 0xff; + p += 3; + for (const nal of a.nals) { + out[p] = nal.length >> 8; + out[p + 1] = nal.length & 0xff; + out.set(nal, p + 2); + p += 2 + nal.length; + } + } + return out; +} + /** `VideoDecoderConfig.description` as bytes, whatever buffer shape it came in. */ export function descriptionBytes(description: AllowSharedBufferSource | undefined): Uint8Array { if (!description) throw new HevcSpliceUnsupported('decoder config carries no hvcC'); diff --git a/packages/iris-core/src/tiers/tier-b-mse.ts b/packages/iris-core/src/tiers/tier-b-mse.ts index f728ba2c..9eb73d92 100644 --- a/packages/iris-core/src/tiers/tier-b-mse.ts +++ b/packages/iris-core/src/tiers/tier-b-mse.ts @@ -35,7 +35,7 @@ import { import { hevcMseNeedsIdrStart, isFirefox, isMobileLike, msePlaysAudio } from '../caps'; import { pickAudioEncoder, transcodeSampleSource, type AudioEncoderChoice } from '../decode/audio-plan'; -import { HevcCraSplicer, descriptionBytes, splicePacket } from '../decode/hevc-cra-splice'; +import { HevcCraSplicer, completeHvcc, descriptionBytes, splicePacket } from '../decode/hevc-cra-splice'; import { ensureLibavAudioDecoderRegistered } from '../decode/libav-audio-decoder'; import { libavCanDecode } from '../decode/libav-codecs'; import { @@ -935,8 +935,14 @@ export const mountTierB: EngineMount = async (opts) => { const videoP = (async () => { const startPacket = videoStartPacket; if (!startPacket) return; - const decoderConfig = await videoTrack.getDecoderConfig(); + const sourceConfig = await videoTrack.getDecoderConfig(); if (stale()) return; + // A bare hvcC (parameter sets in-band only) gets them from this run's keyframe: + // the `hvc1` sample entry we write needs them, and so does the splicer. + const decoderConfig = + sourceVideoCodec === 'hevc' && sourceConfig?.description + ? { ...sourceConfig, description: completeHvcc(descriptionBytes(sourceConfig.description), startPacket.data) } + : sourceConfig; let firstMeta = true; // Gecko 154+ on macOS opens a coded frame group only on an IDR, and an // open-GOP HEVC rip has one, at t=0. The splicer relabels the CRA this diff --git a/web/e2e/fixtures/bare-hvcc.py b/web/e2e/fixtures/bare-hvcc.py new file mode 100644 index 00000000..48db76cf --- /dev/null +++ b/web/e2e/fixtures/bare-hvcc.py @@ -0,0 +1,48 @@ +"""Empties an MKV's HEVC CodecPrivate down to the bare 23-byte hvcC header (no parameter-set +arrays), the way some WEB rips ship it: the stream must then carry VPS/SPS/PPS in-band +(x265 repeat-headers). Rewritten in place: the freed bytes become an EBML Void element right +after it, so every offset in the file (SeekHead, Cues) stays valid. Usage: bare-hvcc.py """ + +import sys + +CODEC_PRIVATE = b"\x63\xa2" +VOID = 0xEC + + +def read_size(buf: bytes, p: int) -> tuple[int, int]: + first = buf[p] + length = 1 + while length <= 8 and not first & (0x80 >> (length - 1)): + length += 1 + value = first & (0xFF >> length) + for i in range(1, length): + value = (value << 8) | buf[p + i] + return value, length + + +def write_size(value: int, length: int) -> bytes: + return ((1 << (7 * length)) | value).to_bytes(length, "big") + + +def main(path: str) -> None: + data = bytearray(open(path, "rb").read()) + p = data.find(CODEC_PRIVATE) + while p != -1: + size, size_len = read_size(data, p + 2) + body = p + 2 + size_len + # the HEVC one: configurationVersion 1, and room for arrays to drop + if data[body] == 1 and size > 23 + 3: + break + p = data.find(CODEC_PRIVATE, p + 1) + if p == -1: + sys.exit(f"{path}: no HEVC CodecPrivate with parameter sets") + data[p + 2 : body] = write_size(23, size_len) + data[body + 22] = 0 + freed = size - 23 + # a Void: its ID, an 8-byte size, then filler + data[body + 23 : body + size] = bytes([VOID]) + write_size(freed - 9, 8) + bytes(freed - 9) + open(path, "wb").write(data) + + +if __name__ == "__main__": + main(sys.argv[1]) diff --git a/web/e2e/fixtures/make.sh b/web/e2e/fixtures/make.sh index 0f3ace7e..73d00ca8 100755 --- a/web/e2e/fixtures/make.sh +++ b/web/e2e/fixtures/make.sh @@ -61,15 +61,20 @@ make Bench.Kilo.2011.720p.WEB.HEVC.AAC-IRIS.mkv $(video 1280x720 60) $(stereo48 -x265-params "log-level=error:keyint=48:min-keyint=48:scenecut=0:open-gop=1:bframes=3" \ -metadata:s:a:0 language=eng -c:a aac -b:a 128k -ar 48000 -# Scenario 12: what a WEB HEVC MULTi rip looks like on an iPad: 1080p Main 10, open GOP, two -# E-AC-3 5.1 tracks (French first), 5 min so the window rolls and evicts. -# shellcheck disable=SC2046 -make Bench.Papa.2016.1080p.WEB.HEVC10.EAC3-IRIS.mkv $(video 1920x1080 300) \ - -f lavfi -i "aevalsrc=exprs=${bed}|${bed}|${beep}|0|${bed}|${bed}:s=48000:c=5.1:d=300" \ - -map 0:v -map 1:a -map 1:a \ - -c:v libx265 -preset ultrafast -pix_fmt yuv420p10le -tag:v hev1 \ - -x265-params "log-level=error:keyint=96:min-keyint=96:scenecut=0:open-gop=1:bframes=3" \ - -metadata:s:a:0 language=fre -metadata:s:a:1 language=eng -c:a eac3 -b:a 640k -ar 48000 +# Scenario 12: what a WEB HEVC MULTi rip (TFA) looks like on an iPad: 1080p Main 10, open GOP, +# two E-AC-3 5.1 tracks (French first), and a bare hvcC: the parameter sets travel in-band only +# (repeat-headers), the CodecPrivate is emptied after the mux. 5 min so the window rolls. +if [[ ! -f "$out/Bench.Papa.2016.1080p.WEB.HEVC10.EAC3-IRIS.mkv" || "$force" == "--force" ]]; then + # shellcheck disable=SC2046 + make Bench.Papa.2016.1080p.WEB.HEVC10.EAC3-IRIS.tmp.mkv $(video 1920x1080 300) \ + -f lavfi -i "aevalsrc=exprs=${bed}|${bed}|${beep}|0|${bed}|${bed}:s=48000:c=5.1:d=300" \ + -map 0:v -map 1:a -map 1:a \ + -c:v libx265 -preset ultrafast -pix_fmt yuv420p10le -tag:v hev1 \ + -x265-params "log-level=error:keyint=96:min-keyint=96:scenecut=0:open-gop=1:bframes=3:repeat-headers=1" \ + -metadata:s:a:0 language=fre -metadata:s:a:1 language=eng -c:a eac3 -b:a 640k -ar 48000 + python3 "$here/bare-hvcc.py" "$out/Bench.Papa.2016.1080p.WEB.HEVC10.EAC3-IRIS.tmp.mkv" + mv "$out/Bench.Papa.2016.1080p.WEB.HEVC10.EAC3-IRIS.tmp.mkv" "$out/Bench.Papa.2016.1080p.WEB.HEVC10.EAC3-IRIS.mkv" +fi # Scenario 1: mono audio (must reach both ears). # shellcheck disable=SC2046 diff --git a/web/e2e/specs/s03-firefox-cra-splice.spec.ts b/web/e2e/specs/s03-firefox-cra-splice.spec.ts index c98d2942..c0eb787d 100644 --- a/web/e2e/specs/s03-firefox-cra-splice.spec.ts +++ b/web/e2e/specs/s03-firefox-cra-splice.spec.ts @@ -43,6 +43,17 @@ test('HEVC open GOP + E-AC-3 5.1: the audio goes through libav.js in its worker' expect(logs.matching(/libav\.js worker unavailable/)).toEqual([]); }); +test( + 'HEVC Main 10 with a bare hvcC (parameter sets in-band only): the splice still runs', + { tag: ['@firefox'] }, + async ({ page, state, logs }) => { + test.skip(!state.libavIris, 'the Iris libav.js variant is not built here (Dockerfile libav-builder stage; IRIS_E2E_LIBAV_DIR)'); + await needsHevc(page); + await resumeAndSeek(page, state, logs, 'hevc10Eac3'); + expect(logs.matching(/hvcC carries no SPS\/PPS/)).toEqual([]); + } +); + test('the libav.js variant probe tells a missing build from a served one', { tag: ['@firefox', '@chrome'] }, async ({ page, state }) => { const res = await page.request.head('/libavjs/libav-6.10.9.0-iris.wasm.mjs'); const type = res.headers()['content-type'] ?? '';