amt-augmentor 1.2.1

Audio + MIDI paired augmentation toolkit for Automatic Music Transcription (AMT)

AMT-Augmentor

Python Data Augmentation Toolkit for Automatic Music Transcription (AMT)

Developed by Bots for Music, maintained by Lars Monstad

📦 View on PyPI

Note: Formerly known as amt-augpy. Starting with v1.0.9, the package is amt-augmentor.

A Python toolkit for augmenting Automatic Music Transcription (AMT) datasets through various audio transformations while maintaining synchronization between audio and MIDI files. The dataset follows the same format as MAESTRO v3.0.0, which is commonly used for Automatic Music Transcription (AMT) tasks.

The toolkit expects a folder containing paired audio and MIDI files with matching names. The audio file and MIDI file must be ground truth data, as this toolkit is only for augmenting existing datasets - a common technique in Machine Learning.

dataset/
├── song1.wav        # Audio file
├── song1.mid        # Ground truth annotated midi file

Features

Audio Transformations

• Time Stretching: Tempo modification while maintaining pitch
• Pitch Shifting: Transposition while preserving timing
• Reverb & Filtering: Room acoustics and frequency filtering effects
• Gain & Chorus: Depth and richness enhancement
• Noise Augmentation: Controlled noise addition for robustness training
• Pause Manipulation: Detection and modification of musical pauses
• Audio Merging: Combine multiple audio files into one for complex training scenarios

Processing & Dataset Handling

• Audio Standardization: Conversion to 44.1kHz WAV format
• Parallel Processing: Multi-core processing for faster augmentation
• Configuration System: YAML-based parameter customization
• Dataset Validation: Automatic validation of train/test/validation splits
• Dataset Modification: Built-in tools to modify existing dataset splits
• MAESTRO Compatibility: Dataset format compatible with MAESTRO v3.0.0

Why AMT-Augmentor?

Built for AMT, not just audio. Unlike general audio augmenters, AMT-Augmentor keeps paired audio+MIDI aligned by applying transform-consistent updates to MIDI (transpose for pitch shift, time-scale for stretch) and ships MAESTRO-style dataset tools (CSV builder + split validation) to avoid leakage. It also supports semitone/time-aware transforms and reproducible runs via --seed.

Requirements

• Python 3.9, 3.10, 3.11, 3.12, or 3.13
• System dependencies: libsndfile and ffmpeg (for audio processing)

Installation

You can install AMT-Augmentor either via pip or by cloning the repository:

Using pip

pip install amt-augmentor

From source

git clone https://github.com/LarsMonstad/amt-augmentor.git
cd amt-augmentor
pip install -e .

Usage

Basic Usage

amt-augmentor /path/to/dataset/directory
# Or running directly
python -m amt_augmentor.main /path/to/dataset/directory

This will process all compatible audio files in the directory and their corresponding MIDI files. The script automatically selects random parameters within predefined ranges for each augmentation type.

Advanced Usage

# Use a custom configuration file
amt-augmentor /path/to/dataset/directory --config my_config.yaml

# Set random seed for reproducible augmentation
# (forces num_workers=1 — worker subprocesses don't inherit RNG state)
amt-augmentor /path/to/dataset/directory --seed 42

# Reproducible train/test/validation split (independent of --seed)
amt-augmentor /path/to/dataset/directory --split-seed 7

# Specify an output directory
amt-augmentor /path/to/dataset/directory --output-directory /path/to/output

# Generate a default configuration file
amt-augmentor --generate-config my_config.yaml

# Disable specific effects
amt-augmentor /path/to/dataset/directory --disable-effect timestretch --disable-effect chorus

# Control merge behavior via the YAML config (merge.merge_num)
# (no CLI flag — see config.sample.yaml for the merge_audio.merge_num key)

# Modify existing dataset CSV files
amt-augmentor --modify-csv dataset.csv --list-split all  # List all songs
amt-augmentor --modify-csv dataset.csv --move-to-split test --song-patterns "Mozart"  # Move songs
amt-augmentor --modify-csv dataset.csv --remove-songs --song-patterns "BadRecording"  # Remove songs

# Parallel processing with 8 workers
amt-augmentor /path/to/dataset/directory --num-workers 8

# Custom train/test/validation split
amt-augmentor /path/to/dataset/directory --train-ratio 0.8 --test-ratio 0.1 --validation-ratio 0.1

# Force specific songs to test set (prevents augmentation)
amt-augmentor /path/to/dataset/directory --custom-test-songs "song1,song3,song5"

# Force specific songs to validation set (prevents augmentation)
amt-augmentor /path/to/dataset/directory --custom-validation-songs "song2,song4"

# Dry run to preview what will be processed
amt-augmentor /path/to/dataset/directory --dry-run

# Verbose output for debugging
amt-augmentor /path/to/dataset/directory --verbose

# Check for valid MIDI-WAV pairs before processing
amt-augmentor /path/to/dataset/directory --check-pairs

# List available effects
amt-augmentor --list-effects

# Check version
amt-augmentor --version

Help and options

amt-augmentor --help

Configuration

All augmentation parameters can be customized using a YAML configuration file. See config.sample.yaml for a complete example with documentation.

File Format Support

Audio

• Input: WAV, FLAC, MP3, M4A, AIFF
• Output: WAV (44.1kHz)

Annotations

• MIDI (.mid)

Output Structure

On first run, the toolkit reorganizes your dataset into two subfolders:

<dataset>/
    original/    # your pristine audio + MIDI pairs (moved from the input dir)
    augmented/   # every augmented file produced by the pipeline

Keeping augmented output in its own folder means you can delete augmented/ to reset the dataset without touching any source material.

Augmented files follow the naming convention:

original_name_augmented_effect_parameter_randomsuffix.extension

The _augmented_ identifier ensures all augmented files are properly recognized and handled during dataset creation. Example of augmented/ contents:

piano_augmented_timestretch_1.2_abc123.wav
piano_augmented_timestretch_1.2_abc123.mid
piano_augmented_noise_1.5_def456.wav
piano_augmented_noise_1.5_def456.mid
piano_augmented_merge_piano2_ghi789.wav
piano_augmented_merge_piano2_ghi789.mid

The generated CSV references files with their subfolder prefix (<dataset>/original/... and <dataset>/augmented/...), so the physical layout mirrors the CSV exactly.

Dataset Creation & Validation

The dataset follows the same format as MAESTRO v3.0.0. Songs assigned to test or validation splits will have their augmented versions excluded to prevent data leakage.

Creating the Dataset CSV

# Create dataset with default split ratios (70% train, 15% test, 15% validation)
amt-augmentor /path/to/directory

# Create dataset with custom split ratios
amt-augmentor /path/to/directory --train-ratio 0.8 --test-ratio 0.1 --validation-ratio 0.1

# Force specific songs to test set (they won't be augmented)
amt-augmentor /path/to/directory --custom-test-songs "song1,song3,song5"

# Force specific songs to validation set (they won't be augmented)
amt-augmentor /path/to/directory --custom-validation-songs "song2,song4"

--custom-test-songs and --custom-validation-songs use case-insensitive substring matching against the song stem. If the same title matches both lists, test wins and a warning is printed. Pinned songs are also skipped at augmentation time — no augmented WAVs/MIDIs are written for them — so held-out evaluation data stays untouched on disk and in the CSV. Substring matching means --custom-test-songs "Spretten" will pin every variant (Spretten_original1, Spretten_angry, Spretten_sad, ...) to the same split.

Validating the Dataset Split

Dataset split validation is automatically performed after CSV creation to ensure:

• Augmented songs are not included in test/validation splits
• No cross-split contamination occurs (an augmented row's source original must live in the same split)
• Every augmented row has a matching original (no "orphan aug" rows)

You can also run validation as a standalone, side-effect-free check — useful after hand-editing a CSV, merging datasets, or receiving a split from someone else:

# Human-readable report (exits 0 regardless)
amt-augmentor --validate-csv dataset.csv

# CI-friendly: non-zero exit when contamination is found
amt-augmentor --validate-csv dataset.csv --strict

# Machine-readable JSON (for piping into other tooling)
amt-augmentor --validate-csv dataset.csv --json

# Equivalent direct invocation of the validator module
python -m amt_augmentor.validate_split dataset.csv --strict

CSV Format

The generated CSV follows the MAESTRO format with the following columns:

• canonical_composer
• canonical_title
• split
• year
• midi_filename
• audio_filename
• duration

Modifying Existing Datasets

After creating a dataset CSV, you can easily modify it to adjust train/test/validation splits:

# List all songs and their distribution
amt-augmentor --modify-csv dataset.csv --list-split all

# List only test songs
amt-augmentor --modify-csv dataset.csv --list-split test

# List all songs with detailed view
amt-augmentor --modify-csv dataset.csv --list-split all --verbose

# Move songs to a different split (substring matching)
amt-augmentor --modify-csv dataset.csv --move-to-split test --song-patterns "Mozart,Chopin"

# Remove songs from dataset
amt-augmentor --modify-csv dataset.csv --remove-songs --song-patterns "BadRecording1,BadRecording2"

# Create backup before modifications (off by default)
amt-augmentor --modify-csv dataset.csv --move-to-split validation --song-patterns "Bach" --backup

Features:

• Substring matching: Patterns like "Mozart" match any song containing that substring
• Smart augmented handling: Augmented versions automatically stay in train split only
• Backup option: Use --backup to create a backup before modifications

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

For development:

1. Install development dependencies: pip install -e ".[dev]"
2. Run tests: pytest tests/
3. Check typing: mypy amt_augmentor
4. Format code: black amt_augmentor

Contributors

• Lars Monstad (@LarsMonstad) – Original author and maintainer
• @monoamine11231 – Noise augmentation, custom test songs feature, and various improvements

Contact

For questions or collaboration:

• Email: [e-mail]
• Organization: https://botsformusic.com
• GitHub: https://github.com/LarsMonstad/amt-augmentor

License

MIT License - see LICENSE file for details.

Citation

If you use this toolkit in your research, please cite:

@software{amt_augmentor,
  author       = {Lars Monstad and contributors},
  title        = {AMT-Augmentor: Audio + MIDI augmentation toolkit for AMT datasets},
  version      = {1.1.2},
  year         = {2025},
  publisher    = {Bots for Music},
  url          = {https://github.com/LarsMonstad/amt-augmentor}
}