fix(mux): derive missing video geometry

[kixelated]

Summary

• derive missing H.264, H.265, VP8, VP9, and AV1 geometry from codec configuration or keyframes before authoring immutable fMP4/MKV headers
• keep polling past provisional frames until both codec configuration and usable geometry are available, while allowing later catalog geometry to unblock export
• teach the one-shot fMP4 muxer used by fetch-on-demand HLS to wait for and derive the same missing geometry from fetched keyframes
• reject synthesized fMP4 video tracks with absent, zero, or unrepresentable dimensions instead of silently writing 0x0 metadata
• surface malformed fixed codec metadata as an export error instead of waiting indefinitely for geometry that can never arrive

The root cause was that catalog dimensions are optional and may arrive independently from media, but the exporters treated codec readiness as sufficient to freeze their headers. A codec-only catalog could therefore produce a permanent 0x0 fMP4 init segment or an MKV header without geometry. The one-shot fMP4 path instead failed before fetching media because it tried to synthesize its init segment immediately. Both cases occur with in-tree RTC VP8/VP9 publishers, which do not currently put dimensions in the catalog.

Fixes #2797.

Public API changes

• None. Geometry derivation and readiness tracking are internal to moq-mux.

Test plan

• nix develop --command just fix
• nix develop --command just check
• nix develop --command just test (1,192 Rust tests and 50 Python tests passed)

No wire format or public catalog API changed, so the cross-package wire/draft sync rows do not apply.

(Written by GPT-5)

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9ec6e875c3

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 600d4f82-fd67-4ade-9988-bd4ad6bf6b4a

📥 Commits

Reviewing files that changed from the base of the PR and between 9ec6e87 and 1b19ec7.

📒 Files selected for processing (6)

• rs/moq-ffi/src/test.rs
• rs/moq-hls/src/export/mod.rs
• rs/moq-mux/src/container/fmp4/export_test.rs
• rs/moq-mux/src/container/fmp4/muxer.rs
• rs/moq-mux/src/container/group.rs
• rs/moq-mux/src/container/source.rs

🚧 Files skipped from review as they are similar to previous changes (3)

• rs/moq-hls/src/export/mod.rs
• rs/moq-mux/src/container/fmp4/export_test.rs
• rs/moq-mux/src/container/source.rs

---

Walkthrough

The change resolves video geometry from catalog metadata, codec descriptions, and encoded payloads. fMP4 and MKV exporters now wait for required geometry before emitting initialization headers. Legacy fMP4 synthesis uses resolved video configuration and rejects missing or invalid dimensions. AV1 sequence-header parsing now supports dimension extraction. Tests cover dimension discovery, initialization delays, error handling, and shared VP8 configuration setup.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes address issue #2797 by requiring or deriving video geometry before fMP4 and MKV headers are finalized.
Out of Scope Changes check	✅ Passed	The production changes and related tests remain within the linked issue scope of resolving missing video geometry during export.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Title check	✅ Passed	The title clearly summarizes the main change: deriving missing video geometry in the muxer.
Description check	✅ Passed	The description directly explains the geometry derivation, readiness changes, validation, affected formats, and test coverage.

✨ Finishing Touches

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch codex/fix-mux-video-geometry

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}