Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 7 additions & 4 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
4 changes: 2 additions & 2 deletions packages/iris-core/src/caps.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
60 changes: 59 additions & 1 deletion packages/iris-core/src/decode/hevc-cra-splice.test.ts
Original file line number Diff line number Diff line change
@@ -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 {
Expand Down Expand Up @@ -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));
});
});
75 changes: 75 additions & 0 deletions packages/iris-core/src/decode/hevc-cra-splice.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<number, Uint8Array[]>();
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');
Expand Down
10 changes: 8 additions & 2 deletions packages/iris-core/src/tiers/tier-b-mse.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down Expand Up @@ -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
Expand Down
48 changes: 48 additions & 0 deletions web/e2e/fixtures/bare-hvcc.py
Original file line number Diff line number Diff line change
@@ -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 <file>"""

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])
23 changes: 14 additions & 9 deletions web/e2e/fixtures/make.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
11 changes: 11 additions & 0 deletions web/e2e/specs/s03-firefox-cra-splice.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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'] ?? '';
Expand Down
Loading