wav-files-format

A lightweight Rust CLI tool to standardize WAV audio files to a consistent format: 16-bit mono PCM at 16 kHz. This is ideal for machine learning datasets, audio processing pipelines, or any workflow requiring uniform audio specs.

Processes directories recursively, preserving relative paths in the output. Handles stereo-to-mono conversion (via averaging channels) and resampling with high-quality sinc interpolation. Supports input formats like 16-bit integer or float PCM; other formats raise errors.

Features

• Batch Processing: Recursively scans input directories for .wav files.
• Format Standardization:
  • Converts multi-channel to mono (averages channels).
  • Resamples to exactly 16 kHz using rubato for artifact-free sinc interpolation.
  • Outputs 16-bit signed integer PCM (RIFF little-endian).
• Error Handling: Skips failed files with console warnings; uses idiomatic Rust Result types.
• Efficient Offline Resampling: Processes entire files as single chunks to minimize artifacts.
• CLI-Driven: Simple command-line interface via clap.
• Tested: Includes unit tests for mono/stereo inputs, rate matching, and edge cases.

Installation

1. Ensure you have Rust installed (1.75.0 or later): rustup.rs.

2. Clone or download this repository.

3. Build and install the binary:

   cargo install --path .

   Or run directly:

   cargo run -- --help

Usage

wav-files-format --input <INPUT_DIR> --output <OUTPUT_DIR>

• --input (-i): Path to the input directory (required). Processes all .wav files recursively.
• --output (-o): Path to the output directory (required). Creates subdirectories to mirror input structure.

Example:

# Standardize all WAVs in ./raw_audio/ to ./processed_audio/
wav-files-format -i ./raw_audio/ -o ./processed_audio/

The tool will:

• Create the output directory if it doesn't exist.
• Preserve relative paths (e.g., raw_audio/subdir/file.wav → processed_audio/subdir/file.wav).
• Print resampling details (e.g., "Resampling from 44100 Hz to 16000 Hz") for verbose logging.
• Log errors to stderr for individual files without halting the batch.

Example

Given a stereo 44.1 kHz WAV file input.wav (2 channels, ~1 second):

mkdir -p test_input test_output
# Assume input.wav is placed in test_input/
wav-files-format -i test_input/ -o test_output/

Output: test_output/input.wav as mono 16 kHz 16-bit PCM (~16000 samples).

Testing

Run the test suite:

cargo test

Tests cover:

• Mono input at different rates (e.g., 44.1 kHz → 16 kHz).
• Stereo-to-mono conversion.
• No-op resampling when rates match.
• Sample length validation post-processing.

Uses tempfile for isolated file I/O and generates sine wave test files for reproducibility.

Dependencies

This tool favors the standard library where possible, with minimal external crates:

Crate	Purpose	Version Constraint
clap	CLI argument parsing	^4.0
hound	WAV reading/writing	^3.5
rubato	High-quality resampling	^0.12
walkdir	Recursive directory traversal	^2.3

No runtime dependencies beyond these; all are well-maintained and battle-tested.

Building from Source

git clone https://github.com/RustedBytes/wav-files-format.git
cd wav-files-format
cargo build --release

The binary (wav-files-format) will be in target/release/.

License

MIT License - see LICENSE file for details.

Contributing

• Fork the repo and open a PR with idiomatic Rust changes.
• Ensure tests pass and code is rustfmt-ed.
• Focus on simplicity: prefer stdlib over new crates.

Questions? Open an issue!

Cite

@software{Smoliakov_Wav_Files_Toolkit,
  author = {Smoliakov, Yehor},
  month = oct,
  title = {{WAV Files Toolkit: A suite of command-line tools for common WAV audio processing tasks, including conversion from other formats, data augmentation, loudness normalization, spectrogram generation, and validation.}},
  url = {https://github.com/RustedBytes/wav-files-toolkit},
  version = {0.4.0},
  year = {2025}
}