[bilipp]

Summary

AV1 played as a black picture with sound on Apple TV (DVprofile10.mkv: AV1 Main 10, 4K, Dolby Vision profile 10.1).

FFmpeg's native AV1 decoder only drives hardware. Without an hwaccel it returns ENOSYS for every packet (libavcodec/av1dec.c), and only Apple's newest chips decode AV1 in hardware. The build had no other AV1 decoder, so the video lane failed while audio played on. Lume's engine fallback never triggered, because the session stayed .playing on audio.

This links dav1d for software AV1 and picks the right decoder for each path. Two commits:

build(ffmpeg): link dav1d for software AV1 decoding

• build/scripts/build-dav1d.sh cross-compiles dav1d 1.5.4 (VideoLAN, BSD-2-Clause) with meson for every slice: static, NEON/NASM assembly on, tools and tests off.
  • meson's host system stays darwin for every slice, because dav1d's own checks only recognise darwin/ios/tvos; visionOS would otherwise miss the Mach-O symbol prefix its assembly needs. subsystem carries the real platform.
• build-ffmpeg.sh builds dav1d first and links it with --enable-libdav1d. pkg-config is pinned (PKG_CONFIG_LIBDIR) to this slice's dav1d only, never a host Homebrew copy. libdav1d.a lands next to FFmpeg's libraries, so make-xcframework.sh merges it into libffmpeg.a.
• build/scripts/fetch-sources.sh downloads every pinned tarball in versions.json and checks its SHA-256. dav1d's matches VideoLAN's published checksum. CI uses it in place of three copies of the FFmpeg-only download step, and installs meson/ninja where it builds slices.

fix(decode): choose the AV1 decoder per path instead of by registration

• With dav1d linked, avcodec_find_decoder(AV1) returns libdav1d, which is registered ahead of the native decoder and has no VideoToolbox hwaccel. Keeping that lookup would have traded the black picture for losing AV1 hardware decoding on chips that have it.
• VideoDecoder.decoder(for:hardware:) walks the registered decoders in order, with experimental ones last, as avcodec_find_decoder does:
  • hardware path: the first decoder with a VideoToolbox device config;
  • software path: the first decoder that can run without hardware, skipping AV_CODEC_CAP_HARDWARE and the native av1 decoder. FFmpeg sets no capability flag on it, but it is hwaccel-only by implementation.
• The AV1 hardware path is only opened when VTIsHardwareDecodeSupported(kCMVideoCodecType_AV1) says the chip has an AV1 decoder, because the native decoder has no software fallback of its own. Every other codec resolves exactly as before.

Artifact URL (follow-up after the tag)

Package.swift still points at the v0.2.0 artifact, which has no dav1d. The new checksum can only exist once a tagged release has built the xcframework, so the bump follows the tag, as #36 did for v0.2.0. Until then, consumers resolving the package by URL keep the old binary, and AV1 fails there exactly as it does today; the decoder selection falls back correctly without dav1d. CI builds its own FFmpeg (the cache key covers build/scripts/** and versions.json), so this PR's tests run against dav1d.

Type of change

• fix — bug fix
• feat — new capability
• perf — performance improvement
• refactor — neither fixes a bug nor adds a feature
• docs — documentation only (setup steps in AGENTS.md / README / CONTRIBUTING, the new decoder-choice invariant in AGENTS.md)
• test — adding or fixing tests
• build / chore — build pipeline, tooling, or maintenance

Invariants

The only data-plane change is which AVCodec VideoDecoder.setupCodec opens; it still runs on the decode thread.

• No blocking FFmpeg call was added to an actor, and no stage bypasses Channel.
• No rebuild-in-place: a new URL is still a new session object.
• Raw container timestamps still stop at TimestampUnwrapper.
• A/V sync is still owned by AVSampleBufferRenderSynchronizer (no new heuristics or clocks).
• No force unwraps, as!, fatalError, or assertionFailure in engine paths; failures are typed.
• No new global mutable state; configuration still flows through PlayerConfiguration.
• No control flow derived from av_log strings. The hardware-only check reads the decoder's name and capability flags, never log output.

Licensing

• dav1d is BSD-2-Clause. It's permissive and compatible with the LGPL build, and adds no relinking requirement.
• THIRD-PARTY-NOTICES.md has a new dav1d section and table row, and adds the one new obligation for anyone shipping a binary: reproduce dav1d's copyright notice.
• The licence text is in LICENSES/dav1d-BSD-2-Clause.txt, a verbatim copy of COPYING from the 1.5.4 tarball. dav1d is unmodified; no patches are applied.
• The build stays LGPL. All eight locally built slices configure as:

License: LGPL version 2.1 or later

Verification

• swift build is warning-free. Nothing from this branch warns. Render/SystemRenderer.swift:63-64 has two main-actor isolation warnings that are not touched here.
• swift test is green, against a locally built xcframework with dav1d:

Test run with 90 tests in 14 suites passed after 35.884 seconds.

Each commit passes on its own; the build commit alone gives 89 tests.

• I added or updated tests for this change.
  • DecoderTests "video: AV1 decodes with or without AV1 hardware" checks that decoding reaches end of stream without .failed and that frames are monotonic and stay 10-bit. It runs on VideoToolbox exactly when the host chip has an AV1 decoder, and through dav1d otherwise.
  • Negative control: against the pre-dav1d xcframework the test fails (no frames, no end of stream).
• New media fixtures were added to generate-fixtures.sh: av1.mkv, AV1 Main 10-bit via SVT-AV1, which Homebrew's ffmpeg ships and CI already installs. No binary media committed.

Platforms verified

• macOS: tests, plus the throughput check below
• iOS / iPadOS: builds and links (device and arm64 simulator). Not run.
• tvOS: builds and links (device and arm64 simulator). Playback on Apple TV not yet verified.
• visionOS: builds and links (device and arm64 simulator). Not run.

generic/platform=iOS Simulator and tvOS Simulator fail to link for x86_64 locally, on core FFmpeg symbols (_av_buffer_ref…). That's because the local build has no x86_64 simulator slices; it's not caused by this change. The release job builds all 10 slices.

Real-world content

• MKV, AV1 Main 10-bit 4K (3840×1920, 23.976 fps, ~11 Mbps), Dolby Vision profile 10.1 (HDR10-compatible base layer), E-AC-3 Atmos audio, local VOD.
  • Before: black picture, audio fine.
  • After: decodes through dav1d at 176.6 fps in the engine's software path on an M1 Pro (release build), delivered as 10-bit x420 buffers.
• For scale, host ffmpeg -c:v libdav1d on the same file decodes at 75 fps with 2 threads. The Apple TV 4K (A15) should comfortably exceed 24 fps, but hasn't been measured.