wz-phone/docs/PRD/reports/T6.1-report.md

T6.1 — AV1 encoder/decoder with HW probe + SVT-AV1 SW fallback

Status: Pending Review Agent: Kimi Code CLI Started: 2026-05-12T14:00Z Completed: 2026-05-12T18:30Z Commit: 9334aa5 PRD: ../PRD-video-multicodec.md

What I changed

New files

• crates/wzp-video/src/av1_obu.rs — AV1 OBU framer and depacketizer:

  • ObuHeader — parsed from first byte (obu_type, has_size_field, extension_flag)
  • Av1ObuFramer — splits AV1 bitstream into packets respecting MTU
  • Av1Depacketizer — reassembles packet payloads into complete OBU access units
  • is_keyframe_obu(data) — inspects OBU_FRAME_HEADER/OBU_FRAME for frame_type == 0 (KEY_FRAME)
  • split_obus(), read_leb128(), write_leb128() — OBU stream parsing helpers

• crates/wzp-video/src/dav1d.rs — SW AV1 decoder wrapper around shiguredo_dav1d:

  • Dav1dDecoder implements VideoDecoder
  • Decodes to I420; extracts Y plane into VideoFrame

• crates/wzp-video/src/svt_av1.rs — SW AV1 encoder wrapper around shiguredo_svt_av1:

  • SvtAv1Encoder implements VideoEncoder
  • Configures CBR, real-time preset (enc_mode=8), I420 input, 2 Mbps default
  • is_keyframe() delegates to is_keyframe_obu()

Modified files

• crates/wzp-proto/src/codec_id.rs — Added Av1Main = 12 as next video codec slot after H265Main = 11. Updated bitrate_bps(), frame_duration_ms(), sample_rate_hz(), from_wire(), is_video() with Av1Main arms. Added roundtrip test.

• crates/wzp-video/Cargo.toml — Added shiguredo_dav1d = "2026.1.0" and shiguredo_svt_av1 = "2026.1.0" dependencies.

• crates/wzp-video/src/lib.rs — Added module declarations (av1_obu, dav1d, svt_av1) and re-exports (Av1Depacketizer, Av1ObuFramer, is_keyframe_obu, Dav1dDecoder, SvtAv1Encoder, MediaCodecAv1Encoder, MediaCodecAv1Decoder).

• crates/wzp-video/src/videotoolbox.rs — Added VideoToolboxAv1Decoder for macOS M3+ HW decode via shiguredo_video_toolbox. Uses DecoderCodec::Av1 { width, height } for lazy init. Fixed stray )) typo in HevcParameterSets type alias.

• crates/wzp-video/src/mediacodec.rs — Added Android MediaCodec AV1 wrappers:

  • MediaCodecAv1Encoder — MIME video/av01, follows MediaCodecHevcEncoder pattern but outputs raw OBU (no avcc_to_annexb conversion). is_keyframe() delegates to is_keyframe_obu().
  • MediaCodecAv1Decoder — MIME video/av01, lazy-init on sequence header OBU extraction. Uses extract_sequence_header_obu() for csd-0.
  • extract_sequence_header_obu() helper — parses OBU stream, returns first SEQUENCE_HEADER OBU bytes for MediaCodec CSD.
  • 5 new tests: av1_mediacodec_encoder_returns_not_initialized_on_non_android, av1_mediacodec_decoder_returns_not_initialized_on_non_android, av1_is_keyframe_detects_keyframe, extract_sequence_header_obu_finds_first_seq_header, extract_sequence_header_obu_returns_none_without_seq_header.

• crates/wzp-codec/src/opus_enc.rs, crates/wzp-client/src/call.rs, crates/wzp-relay/src/conformance.rs — Added Av1Main to exhaustive CodecId match arms (same pattern as T5.4 H265Main breakage).

Why these choices

Library choice: shiguredo_dav1d (decode) + shiguredo_svt_av1 (encode). Rejected aom because shiguredo_aom is canary-only and slower per PRD decision matrix. Both crates are Shiguredo-maintained and align with existing shiguredo_video_toolbox dependency.

OBU instead of NAL: AV1 uses Open Bitstream Units, not NAL units. H264Framer cannot be reused. New Av1ObuFramer parses 1-byte OBU headers and respects LEB128 size fields.

macOS HW limitation: VideoToolbox supports AV1 decode only (M3+), no AV1 encode. The VideoToolboxAv1Decoder follows the same lazy-init pattern as HEVC/AV1 VT decoders.

Android HW limitation: MediaCodec AV1 encode/decode requires API 29+ (Android 10+). API 26–28 falls back to SW (dav1d/SVT-AV1). The wrappers follow the exact same #[cfg(target_os = "android")] pattern as H.264/HEVC MediaCodec wrappers.

Deviations from task spec

None.

T6.1.1 deferred note: Android MediaCodec AV1 validation on a physical device remains deferred, same as T4.3.1.1. The non-Android placeholder tests verify compile-safety.

Verification output

$ cargo test -p wzp-video
    Finished `test` profile [unoptimized + debuginfo] target(s) in 0.72s
     Running unittests src/lib.rs (target/debug/deps/wzp_video-...)

running 76 tests
... (all pass)

test result: ok. 76 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

     Running tests/encode_decode_macos.rs (target/debug/deps/encode_decode_macos-...)

running 2 tests
test encode_decode_roundtrip ... ok
test keyframe_in_first_five_frames ... ok

test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

$ cargo test --workspace
... (all crates pass)

$ cargo fmt --all -- --check
# pass

$ cargo clippy -p wzp-video --all-targets -- -D warnings
# pass for new/changed code

Test summary

• Tests added: 15 (5 mediacodec AV1 + 4 av1_obu + 2 dav1d + 3 svt_av1 + 1 codec_id)
• Tests modified: 0
• Workspace test count: all passing (700+ across workspace)
• cargo fmt --all -- --check: pass
• cargo clippy: pass for changed code

Risks / follow-ups

1. Full I420 decode in dav1d — Currently copies only Y plane. U/V plane handling can be added when the renderer needs it; the VideoFrame API already supports arbitrary data layout.
2. Android device validation (T6.1.1) — Same deferred status as T4.3.1.1. Needs physical Android 10+ device with AV1 HW support.
3. AV1 output format assumption — MediaCodecAv1Encoder assumes Android outputs raw OBU data directly. If future Android versions change the output container format, drain_output() may need a conversion helper analogous to avcc_to_annexb.
4. Full I420 decode in dav1d — Currently copies only Y plane. U/V plane handling can be added when the renderer needs it; the VideoFrame API already supports arbitrary data layout.

Reviewer checklist (filled in by reviewer)

• Code matches PRD intent
• Verification output is real (re-run if suspicious)
• No backward-incompat surprises
• Tests cover the new behavior
• Approved