Skip to content

Quick Start

Convert Source Audio To 16 kHz Mono WAV

CLI:

audio-prep convert \
    --input-dir data/raw_mp3 \
    --output-dir data/wav16k \
    --workers 4 \
    --manifest data/manifest.jsonl

Python:

from pathlib import Path

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

config = ConversionConfig(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"))

Expected result:

  • Converted files under data/wav16k
  • Matching subdirectories from data/raw_mp3
  • A JSONL manifest at data/manifest.jsonl
  • Exit code 0 if every file converted and validated
  • Exit code 1 if any file failed conversion or validation

Convert To FLAC

CLI:

audio-prep convert \
    --input-dir data/raw_mp3 \
    --output-dir data/flac16k \
    --format flac \
    --manifest data/flac_manifest.jsonl

Python:

from pathlib import Path

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

config = ConversionConfig(output_format="flac", num_workers=4)
results = convert_batch(Path("data/raw_mp3"), Path("data/flac16k"), 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/flac_manifest.jsonl"))

Force Rebuild Existing Outputs

CLI:

audio-prep convert \
    --input-dir data/raw_mp3 \
    --output-dir data/wav16k \
    --overwrite

Python:

from pathlib import Path

from audio_prep import ConversionConfig, convert_batch

config = ConversionConfig(overwrite=True)
results = convert_batch(Path("data/raw_mp3"), Path("data/wav16k"), config)

Without --overwrite, valid existing outputs are reused and invalid existing outputs are replaced.

Chunk Speech

CLI:

audio-prep chunk \
    --input-dir data/raw_mp3 \
    --output-dir data/chunks \
    --min-duration-sec 5 \
    --max-duration-sec 20 \
    --workers 4 \
    --manifest data/chunk_manifest.jsonl

Python:

from pathlib import Path

from audio_prep import ChunkConfig, build_chunk_manifest, chunk_batch, write_manifest

config = ChunkConfig(min_duration_sec=5, max_duration_sec=20, num_workers=4)
results = chunk_batch(Path("data/raw_mp3"), Path("data/chunks"), config)
records = build_chunk_manifest(results)
write_manifest(records, Path("data/chunk_manifest.jsonl"))

Use --allow-energy-fallback only when Silero VAD is not available and an approximate offline detector is acceptable.