Skip to content

CLAUDE.md

Latest commit

 

History

History
94 lines (69 loc) · 3.41 KB

CLAUDE.md

File metadata and controls

94 lines (69 loc) · 3.41 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

mp4-atom is a Rust library for encoding/decoding ISO Base Media File Format (ISO/IEC 14496-12) atoms at a low level. MP4 files consist of atoms (boxes) containing data, identified by 4-byte FourCC codes (like moov, mdat, trak).

Development Commands

Build and check the code:

cargo build                                    # Build the library
cargo build --all-features                     # Build with all features (bytes, tokio, serde)
cargo check --all-targets --all-features      # Check all targets with all features

Run tests:

cargo test                                     # Run all tests
cargo test --all-targets                      # Run tests on all targets
cargo test <test_name>                        # Run a specific test

Code quality and CI checks:

just check                                     # Run full CI checks (check, clippy, fmt, shear)
just test                                      # Run all tests
just fix                                       # Auto-fix issues (fix, clippy fix, fmt, shear fix)

Linting and formatting:

cargo clippy --all-targets --all-features -- -D warnings  # Run clippy with strict warnings
cargo fmt -- --check                                       # Check formatting
cargo fmt                                                  # Auto-format code

Architecture

Core Traits

The library revolves around several key traits defined in src/:

  • Atom (atom.rs): Core trait for all atom types, provides KIND constant and encode/decode methods
  • Decode/Encode (coding.rs): For working with byte slices
  • ReadFrom/WriteTo (io.rs): Synchronous IO operations
  • AsyncReadFrom/AsyncWriteTo (tokio/): Async IO with tokio feature
  • Buf/BufMut (buf.rs): Custom buffer traits for contiguous byte slices

Module Structure

Atoms are organized hierarchically matching the MP4 format:

  • src/moov/: Movie metadata atoms (mvhd, trak, etc.)
    • trak/: Track-level atoms
      • mdia/: Media information
        • minf/stbl/: Sample table atoms
          • stsd/: Sample descriptions for codecs (h264, hevc, av01, mp4a, etc.)
  • src/moof/: Movie fragment atoms for streaming
  • src/meta/: Metadata atoms (HEIF/AVIF support)
  • src/: Top-level atoms (ftyp, mdat, free, etc.)

Key Design Patterns

  1. Atom Encoding/Decoding: Each atom type implements the Atom trait with:

    • KIND: FourCC identifier
    • decode_body(): Parse atom contents
    • encode_body(): Write atom contents

  2. Header Handling: Use Header::read_from() to handle large atoms without loading into memory

  3. Any Enum: src/any.rs provides a giant enum of all supported atoms for flexible decoding

  4. Error Handling: All operations return Result<T> with custom error types in error.rs

Feature Flags

  • bytes: Enables support for bytes crate types (Bytes, BytesMut)
  • tokio: Enables async IO support
  • serde: Enables serialization/deserialization support

Testing

Tests are located in:

  • Unit tests: Within each module using #[cfg(test)]
  • Integration tests: src/test/ directory with sample MP4 files for different codecs

Run specific codec tests:

cargo test h264    # Test H.264 support
cargo test hevc    # Test HEVC support
cargo test av1     # Test AV1 support