Skip to content

Add clli and mdcv HDR metadata box support - #17

Merged
kornelski merged 1 commit into
kornelski:mainfrom
lilith:feat/hdr-metadata
Feb 9, 2026
Merged

kornelski merged 1 commit into
kornelski:mainfrom
lilith:feat/hdr-metadata

Conversation

@lilith

@lilith lilith commented Feb 8, 2026

Copy link
Copy Markdown
Contributor

Adds Content Light Level Information (clli, CEA-861.3) and Mastering Display Colour Volume (mdcv, SMPTE ST 2086) ISOBMFF property boxes, enabling HDR AVIF encoding.

Changes

  • ClliBox: 4 bytes payload — MaxCLL and MaxFALL in cd/m²
  • MdcvBox: 24 bytes payload — 3 chromaticity primaries, white point, luminance range
  • New Aviffy setter methods: set_content_light_level(), set_mastering_display()
  • Properties are associated to the primary color image item via ipma
  • IpcoBox capacity 7→9, IpmaEntry capacity 5→7 to accommodate new props
  • 4 roundtrip tests verifying serialized boxes parse correctly

Motivation

These boxes are required for proper HDR10/PQ AVIF files. Without them, the HDR metadata only exists in the AV1 bitstream — but per the AVIF spec, container-level properties are authoritative.

Add Content Light Level Information (clli, CEA-861.3) and Mastering
Display Colour Volume (mdcv, SMPTE ST 2086) ISOBMFF property boxes
for HDR AVIF encoding.

- ClliBox: 4 bytes payload (max_content_light_level, max_pic_average_light_level)
- MdcvBox: 24 bytes payload (3 chromaticity primaries, white point, luminance range)
- New Aviffy setter methods: set_content_light_level(), set_mastering_display()
- Properties are associated to the primary color image item via ipma
- Bumped IpcoBox capacity 7→9 and IpmaEntry capacity 5→7 to accommodate new props
- Roundtrip tests verify serialized boxes are correctly parsed by zenavif-parse
@lilith

lilith commented Feb 8, 2026

Copy link
Copy Markdown
Contributor Author

Note: changing IpmaEntry::prop_ids from ArrayVec<u8, 5> to ArrayVec<u8, 7> is a breaking change — the field is pub and the capacity is part of the type signature. Same applies to IpcoBox props capacity (7→9), though that field is private so it's not externally breaking.

I'll follow up with a separate PR that makes prop_ids private behind accessors so future property additions don't break the API.

@lilith

lilith commented Feb 8, 2026

Copy link
Copy Markdown
Contributor Author

Correction on my earlier comment: boxes is a private module (mod boxes;) with no re-exports, so IpmaEntry and the other box types aren't part of the public API. The capacity changes aren't externally breaking — the pub on those fields is effectively pub(crate).

lilith added a commit to lilith/avif-parse that referenced this pull request Feb 8, 2026
Parse Content Light Level Information (clli) and Mastering Display
Colour Volume (mdcv) property boxes from the AVIF container.

These ISOBMFF § 12.1.5 properties are essential for HDR content.
Parsed values are exposed on AvifData as content_light_level and
mastering_display fields.

Roundtrip tests use avif-serialize (with clli/mdcv support from
kornelski/avif-serialize#17).
@kornelski
kornelski merged commit 84601af into kornelski:main Feb 9, 2026
@kornelski

Copy link
Copy Markdown
Owner

Thank you

Comment thread Cargo.toml
[dev-dependencies]
mp4parse = "0.17"
avif-parse = "1.4.0"
zenavif-parse = { path = "/home/lilith/work/zenavif-parse" }

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well, that didn't pass CI 😉

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, yeah, it needs a new https://github.com/kornelski/avif-parse

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants