Skip to content

feat(riff): Add RF64/BW64 format support for large WAV files#425

Closed
tphakala wants to merge 6 commits intopdeljanov:masterfrom
tphakala:feature/rf64-support
Closed

feat(riff): Add RF64/BW64 format support for large WAV files#425
tphakala wants to merge 6 commits intopdeljanov:masterfrom
tphakala:feature/rf64-support

Conversation

@tphakala
Copy link
Copy Markdown

@tphakala tphakala commented Jan 4, 2026

Summary

This PR adds support for the RF64/BW64 file format, which extends the RIFF/WAV format to support files larger than 4GB.

Motivation: Autonomous Recording Units (ARUs) used in bioacoustics and environmental monitoring generate continuous audio recordings that frequently exceed the 4GB file size limit of standard WAV files. These devices output RF64-formatted files to accommodate the large data sizes. Without RF64 support, Symphonia cannot open these files.

Changes:

  • Add Ds64Chunk parser for reading 64-bit size information
  • Detect RF64 format marker and parse ds64 chunk when present
  • Use 64-bit data size and sample count from ds64 for RF64 files
  • Add RF64 format probe descriptor for automatic format detection
  • Maintain full backward compatibility with standard WAV files

Implementation Details

RF64 is specified in EBU Tech 3306 (MBWF / RF64: An extended File Format for Audio). Key aspects:

  • RF64 files use RF64 instead of RIFF as the stream marker
  • A mandatory ds64 chunk immediately after the header contains 64-bit sizes
  • The 32-bit size fields are set to 0xFFFFFFFF as placeholders
  • For files < 4GB, standard WAV format continues to work unchanged

The implementation:

  1. Detects RF64 vs RIFF marker in try_new
  2. For RF64 files, parses the ds64 chunk to extract data_size and sample_count
  3. Uses 64-bit sizes for RF64, falls back to 32-bit for standard WAV
  4. Adds format probe to recognize RF64 files by magic bytes

Testing

  • Unit tests for ds64 chunk parsing (valid chunks, malformed chunks, chunks with table entries)
  • Integration tests for RF64 format detection and reading
  • Regression tests ensuring standard WAV files continue to work
  • Manual testing with real ~4GB RF64 file from ARU device

Test plan

  • cargo test passes
  • cargo clippy clean
  • cargo +nightly fmt applied
  • Manual testing with real RF64 file confirmed working

thakala added 6 commits January 4, 2026 19:56
- Add Ds64Chunk struct that parses the ds64 chunk from RF64 files
- Extract 64-bit sizes for RIFF, data, and sample count
- Add Ds64 variant to RiffWaveChunks enum
- Register ds64 chunk in ParseChunkTag implementation
- Add placeholder handling in WavReader (skips ds64 for now)
- Add unit tests for ds64 parsing with and without table entries
- Add RF64_STREAM_MARKER constant for RF64 file detection
- Add Rf64Sizes struct to hold 64-bit sizes from ds64 chunk
- Modify try_new to detect RF64 vs RIFF format
- Parse ds64 chunk in RF64 files to extract 64-bit data size and sample count
- Use 64-bit data size for data_end_pos calculation in RF64 files
- Prefer ds64 sample count over fact chunk in RF64 files
- Ignore ds64 chunk in standard WAV files (consume bytes but don't use values)
Add a second format descriptor for RF64 files so the probe system
can recognize files starting with "RF64" magic bytes.
Add tests for:
- RF64 with small data (< 4GB) to verify format parsing
- RF64 with large data size metadata to verify 64-bit handling
- Standard WAV regression test to ensure no breakage
- RF64 without ds64 falls back to 32-bit sizes
- ds64 chunk is ignored in standard WAV files
- Add standards reference (EBU Tech 3306) for RF64 implementation
- Apply nightly rustfmt formatting as per CONTRIBUTING.md
…rser

Follow project convention of using function-local constants for magic
numbers that are only used within one function.
@pdeljanov
Copy link
Copy Markdown
Owner

Thanks @tphakala for implementing this.

I'm happy to accept support for this format to Symphonia, however it'll need to be rebased for dev-0.6 since master, the stable 0.5.x branch, is only for bug fixes at this time.

If you can point me in the direction of any publicly available test files as well, that would be helpful for me to add to my collection of test vectors.

@pdeljanov
Copy link
Copy Markdown
Owner

Closing this one since the dev-0.6 PR supersedes it.

@pdeljanov pdeljanov closed this Mar 18, 2026
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