Skip to content

Conversion

Conversion is handled by FFmpeg through convert_file and convert_batch.

CLI Example

audio-prep convert \
    --input-dir data/raw_mp3 \
    --output-dir data/wav16k \
    --format wav \
    --sample-rate 16000 \
    --channels 1 \
    --workers 4 \
    --manifest data/manifest.jsonl

Python Example

from pathlib import Path

from audio_prep import ConversionConfig, build_manifest, convert_batch, validate_output, write_manifest

config = ConversionConfig(
    output_format="wav",
    sample_rate=16_000,
    channels=1,
    num_workers=4,
)

results = convert_batch(Path("data/raw_mp3"), Path("data/wav16k"), config)
validations = {
    result.output: validate_output(result.output, config)
    for result in results
    if result.success and result.output is not None
}
records = build_manifest(results, validations)
write_manifest(records, Path("data/manifest.jsonl"))

Output Path Rules

For batch conversion, the output path is derived from the source path relative to input_dir:

data/raw_mp3/speaker_a/clip_001.mp3

converted to WAV under data/wav16k becomes:

data/wav16k/speaker_a/clip_001.wav

If two source files in the same directory would produce the same output path, the original source extension is added to the output stem. For example, clip.mp3 and clip.wav become clip_mp3.wav and clip_wav.wav.

FFmpeg Settings

The converter always sets:

  • -ar to the configured sample rate
  • -ac to the configured channel count
  • WAV output as signed 16-bit PCM
  • FLAC output with the FLAC muxer

When normalize_loudness=True, FFmpeg also receives:

loudnorm=I=-23:LRA=7:TP=-2

Resume Behavior

When overwrite=False, an existing output is reused only if it passes validation for the current target spec. Invalid existing outputs are removed and converted again.

If an invalid existing output cannot be removed, the file is reported as a failed ConversionResult instead of raising out of the batch.

Batch Behavior

convert_batch uses a process pool when num_workers > 1. Results are sorted back into discovery order before being returned.

Bad source files do not stop the run. They return ConversionResult objects with success=False and an error message.