Skip to content

Media: use craft-media for bitstream, isobmff and matroska - #1034

Merged
aiongg merged 4 commits into
storytold:mainfrom
aiongg:craft-media
Oct 23, 2026
Merged

aiongg merged 4 commits into
storytold:mainfrom
aiongg:craft-media

Conversation

@aiongg

@aiongg aiongg commented Oct 19, 2026 •

Copy link
Copy Markdown
Contributor

What

deckcraft-bitstream, deckcraft-isobmff and deckcraft-matroska become re-exports of
craft_media::{bitstream, isobmff, matroska} from craft-libs:

  • Root Cargo.toml: craft-media in [workspace.dependencies], default-features = false.
    Each crate enables the feature it re-exports.
  • Each crate's src/lib.rs is one pub use craft_media::<module>::*; line. The sources they
    replace are deleted (8,909 lines).
  • deckcraft-bitstream keeps budget (the picture-store memory budget the H.264, HEVC, VP9 and
    AV1 decoders check) as its own module next to the re-export. budget.rs is unchanged.
  • The packages, their names and their public paths stay (deckcraft_bitstream::budget,
    deckcraft_matroska::ebml, deckcraft_matroska::element_ids), so the codec crates build
    unchanged and cargo xtask layers keeps its table.
  • crates/media/src/video.rs: codec_name names the new CodecConfig::Apv ("APV"). It is the
    only exhaustive match on a container type outside the replaced crates.
  • The unit tests of the three copies moved to craft-libs with the code.

DeckCraft's copies were older than FilmCraft's, so DeckCraft gains APV (MP4 and Matroska),
MPEG-1 audio in Matroska (Codec::Mp1), .mp2 as MPEG audio, AAC channel configurations 11–14,
SampleEntry::av1/flac, Mp4Writer::set_sample_entry, Matroska block additions
(Sample::addition, MkvFile::read_sample_addition) and isobmff::boxes.

Every input check in DeckCraft's copies is in craft-media: read_ue_plus, NAL length widths
1–4 and the overflow-safe NAL length check, read_se/write_se range handling, the
chapter/tag nesting limit, the box, run, trun and crop checks, and the QuickTime v2 channel
count and lpcm bit-depth checks (craft-libs#246).

Behaviour that differs from DeckCraft's copies, for input outside the contract only:

  • The NAL length width error is BitError::InvalidNalLengthSize (DeckCraft's copy:
    InvalidLengthSize). Nothing in DeckCraft names either.
  • read_se reads the code for i32::MIN, as the spec allows; DeckCraft's copy rejected it.
    Every se(v) field the H.264 and HEVC decoders use in arithmetic is range-checked first.
  • PcmConfig::bytes_per_frame returns u32 and saturates; DeckCraft's returned Option<u32>.
    DeckCraft decodes audio with Symphonia, so this only affects what media.info reports.
  • Matroska: a cluster timestamp above i64::MAX, or a block timestamp that overflows, saturates
    at i64::MAX instead of failing the open. Chapter and tag nesting is cut at 64 levels instead
    of 32.
  • MkvWriter writes craft-media as MuxingApp/WritingApp. DeckCraft does not mux Matroska.

Why

FilmCraft, SoundCraft, LightCraft and EffectCraft use the same code. The copies had drifted:
DeckCraft lacked FilmCraft's APV and block-addition work, and FilmCraft lacked DeckCraft's
overflow checks. craft-media has both, and with one shared copy a fix lands once.

Pin

craft-media is pinned to storytold/craft-libs at f0ad6c1e (craft-libs#246, after #182,
#196 and #245), the same way as craft-pdf.

Checks

cargo xtask ci at cdf116a, on Linux with CRAFT_FONTS_DIR set to craft-fonts at 43913056 (the ref CI uses): all 8 steps passed.

  • cargo fmt --all -- --check, cargo xtask pdf-deps, cargo clippy --workspace --all-targets -- -D warnings: clean.
  • Tests: 1,686 passed, 6 skipped; doctests pass.
  • cargo xtask assets: all 47 asset files attributed.
  • cargo xtask layers: 28 crates, no layering violations.
  • cargo xtask wasm: all 23 crates ok, including deckcraft-bitstream, -isobmff, -matroska and -media.
  • End to end with deckcraft-cli run: insert.video of an ffmpeg-made H.264/AAC .mp4 and a VP9/Opus .mkv, then media.info and --save to .pptx. Both probe with the right container, codecs and duration and get a decoded poster frame. Reopened from the .pptx, media.info is identical to the same steps on main (c787f4f).

Summary by CodeRabbit

  • New Features
    • Video codec identification now recognizes APV and reports its codec name.
  • Refactor
    • Bitstream, ISO BMFF, and Matroska/WebM functionality is now provided through shared media components rather than local implementations.
    • Matroska and ISO BMFF crates no longer include their former local parsing, writing, and supporting APIs. Check the shared media components for the currently available functionality.

deckcraft-bitstream, deckcraft-isobmff and deckcraft-matroska re-export
craft_media::{bitstream, isobmff, matroska} from craft-libs. The packages
and their public paths stay, so the codec crates build unchanged.
deckcraft-bitstream keeps the decoder memory budget as its own module
(budget). deckcraft-media names the new CodecConfig::Apv entry.
@coderabbitai

coderabbitai Bot commented Oct 19, 2026 •

Copy link
Copy Markdown
Contributor

Review in Change Stack →

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration
📥 Commits

Reviewing files that changed from the base of the PR and between c787f4f and cdf116a.

⛔ Files ignored due to path filters: 1
  • Cargo.lock is excluded by !**/*.lock
📒 Files selected for processing: 24
  • Cargo.toml
  • crates/bitstream/Cargo.toml
  • crates/bitstream/src/lib.rs
  • crates/isobmff/Cargo.toml
  • crates/isobmff/src/bytes.rs
  • crates/isobmff/src/codec.rs
  • crates/isobmff/src/demux.rs
  • crates/isobmff/src/error.rs
  • crates/isobmff/src/lib.rs
  • crates/isobmff/src/mux.rs
  • crates/isobmff/src/source.rs
  • crates/matroska/Cargo.toml
  • crates/matroska/src/codec.rs
  • crates/matroska/src/demux.rs
  • crates/matroska/src/ebml.rs
  • crates/matroska/src/error.rs
  • crates/matroska/src/ids.rs
  • crates/matroska/src/lib.rs
  • crates/matroska/src/meta.rs
  • crates/matroska/src/mux.rs
  • crates/matroska/src/source.rs
  • crates/matroska/src/synthetic_tests.rs
  • crates/matroska/src/track.rs
  • crates/media/src/video.rs
💤 Files with no reviewable changes: 16
  • crates/isobmff/src/mux.rs
  • crates/matroska/src/source.rs
  • crates/matroska/src/codec.rs
  • crates/isobmff/src/error.rs
  • crates/matroska/src/ebml.rs
  • crates/isobmff/src/codec.rs
  • crates/isobmff/src/source.rs
  • crates/isobmff/src/demux.rs
  • crates/matroska/src/synthetic_tests.rs
  • crates/matroska/src/error.rs
  • crates/matroska/src/ids.rs
  • crates/matroska/src/meta.rs
  • crates/isobmff/src/bytes.rs
  • crates/matroska/src/mux.rs
  • crates/matroska/src/track.rs
  • crates/matroska/src/demux.rs

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 5 remain after this review.

📝 Walkthrough

The workspace adds a pinned craft-media dependency. The bitstream, ISO BMFF, and Matroska crates now re-export APIs from it instead of defining those implementations locally. The video codec-name mapping adds APV.

Changes: Shared media crate adoption

Layer / File(s) Summary
Dependency and bitstream re-export
Cargo.toml, crates/bitstream/Cargo.toml, crates/bitstream/src/lib.rs
The workspace adds the pinned craft-media dependency. The bitstream crate enables its feature and re-exports its API; the local budget module remains.
ISO BMFF re-export
crates/isobmff/Cargo.toml, crates/isobmff/src/*
The crate enables the isobmff feature and replaces its local ISO BMFF implementation with a wildcard re-export from craft-media.
Matroska re-export
crates/matroska/Cargo.toml, crates/matroska/src/*
The crate enables the matroska feature and replaces its local Matroska implementation with a wildcard re-export from craft-media.

APV codec name

Layer / File(s) Summary
APV codec-name mapping
crates/media/src/video.rs
codec_name now returns "APV" for CodecConfig::Apv.

Priority: ➖ Normal

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Refactor

Possibly related issues

  • storytold/craft-libs#115 — This change replaces DeckCraft’s local bitstream and ISO BMFF implementations with shared craft-media APIs.
  • storytold/deckcraft#1183 — The bitstream implementation is replaced by the craft-media API, but the supplied change summary does not establish whether the reported validation weakness is fixed.

Suggested reviewers: echelon, nikitkao, marekspodbiedry

Merge Risk: ⚪ Minimal · up to cdf11

This change moves the bitstream, ISO BMFF and Matroska implementations behind a pinned shared dependency and adds an APV codec label. Existing consumers keep their public paths, and the author reports clean CI and matching media round-trip results. No concrete merge-blocking risk was found. Reviewers should be aware of the documented behavior differences for malformed inputs.

Security architecture risk: 🔵 Low · up to cdf11

The shared dependency is pinned, and APV labeling does not enable an additional decoder. No introduced vulnerability was demonstrated, but the replacement parser implementations were unavailable for verifying their input checks and resource limits.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

  • inferred — The directly supported exposure is processing attacker-controlled media through existing container and bitstream consumers. The inspected change does not demonstrate additional service authority or a new decoder path; failure containment still depends on the replacement parser’s behavior.

Trust Boundaries and Controls

  • observed — The existing MP4 table-fit check remains before the conditional Symphonia fallback. It is not a general guard before the primary container parser and therefore does not independently establish the replacement parser’s safety.

Resilience and Maintainability Implications

  • observed — The local picture-budget module remains exposed. The full comparison shows no changes to budget.rs or the inspected H.264 decoder and parameter consumers; this is counterevidence to a local budget-lifecycle change, not proof of equivalent shared bitstream behavior.

Hardening Proposals

  • proposed — Verify the exact pinned dependency source against the removed implementations for bounds checks, truncation handling, nesting limits, arithmetic safety, and resource limits. This would close the main evidence gap; it is not a finding that those controls are missing.
Pre-merge checks: Passed 4 · Failed 1

Failed Failed checks: 1 warning

Check name Status Explanation Resolution
Docstring Coverage Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 4 files. (4 skipped: 4 … Write docstrings for the functions missing them to satisfy the coverage threshold.
Passed Passed checks: 4 passed
Check name Status Explanation
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check Passed The title clearly and concisely describes the main change: replacing the bitstream, isobmff, and matroska implementations with craft-media.
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 4 files. (4 skipped: 4 unsupported.)

Resolution

Write docstrings for the functions missing them to satisfy the coverage threshold.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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

@skylartaylor

Copy link
Copy Markdown
Member

Please repin to the canonical craft-media merge commit and rerun the media import/save/reopen and WASM checks against that revision.

@aiongg
aiongg marked this pull request as ready for review October 23, 2026 20:31
@aiongg

aiongg commented Oct 23, 2026

Copy link
Copy Markdown
Contributor Author

Repinned to storytold/craft-libs at f0ad6c1e (craft-libs#246) and merged main. cargo xtask ci passes, including wasm. Media import, save and reopen give the same results as main; details under Checks.

@aiongg
aiongg merged commit 7626f74 into storytold:main Oct 23, 2026
4 checks passed
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.

2 participants