Skip to main content

AMT-AugPy

Python Data Augmentation Toolkit for Automatic Music Transcription (AMT)

Python License: MIT Librosa NumPy SoundFile

A comprehensive 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.

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

Features

  • Time Stretching: Modify the tempo of audio files while maintaining pitch
  • Pitch Shifting: Transpose audio files up or down while preserving timing
  • Reverb & Filtering: Apply room acoustics and frequency filtering effects
  • Gain & Chorus: Add depth and richness through gain and chorus effects
  • Smart Pause Detection: Identify and manipulate musical pauses based on note timing
  • Audio Standardization: Convert various audio formats to 44.1kHz WAV
  • Parallel Processing: Utilize multi-core processing for faster augmentation
  • Configurable Parameters: Easily customize all augmentation parameters

What's New in 1.0.5

  • Configuration System: Use YAML configuration files to customize all parameters
  • Parallel Processing: Process multiple effects concurrently for faster performance
  • Better Error Handling: Improved error detection and reporting
  • Extended Format Support: Added support for M4A and AIFF audio formats
  • Type Annotations: Full Python type hints for better code quality
  • Expanded Documentation: Improved documentation and examples

Installation

You can install amt-augpy either via pip or by cloning the repository:

Using pip

pip install amt-augpy1.0

From source

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

For development, install with additional development dependencies:

pip install -e ".[dev]"

Dependencies

  • librosa
  • soundfile
  • numpy
  • pedalboard
  • pretty_midi
  • pyyaml
  • tqdm

Usage

Basic Usage

amt-augpy /path/to/dataset/directory
# Or running directly
python -m amt_augpy.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-augpy /path/to/dataset/directory --config my_config.yaml

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

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

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

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

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

Help and options

amt-augpy --help

Configuration

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

Sample Configuration

# Time stretching configuration
time_stretch:
  enabled: true
  variations: 3
  min_factor: 0.6
  max_factor: 1.6

# Pitch shifting configuration
pitch_shift:
  enabled: true
  variations: 3
  min_semitones: -5
  max_semitones: 5

# Processing configuration
processing:
  num_workers: 4
  output_dir: null

File Format Support

Audio

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

Annotations

  • MIDI (.mid)

Output Structure

For each input file pair (audio + MIDI), the toolkit generates multiple augmented versions with the following naming convention:

original_name_effect_parameter_randomsuffix.extension

Example:

piano_timestretch_1.2_abc123.wav
piano_timestretch_1.2_abc123.mid

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-augpy /path/to/directory

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

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
  • Original and augmented songs are properly distributed

CSV Format

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

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

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_augpy
  4. Format code: black amt_augpy

License

MIT License - see LICENSE file for details.

Citation

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

@software{amt_augpy,
  author    = {Lars Monstad},
  title     = {amt-augpy: Audio augmentation toolkit for AMT datasets},
  version   = {1.0},
  year      = {2025}
}

Metadata

Release files for amt-augpy1.0 1.0.8

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for amt-augpy1.0 1.0.8
File Size Uploaded Provenance Actions
amt_augpy1_0-1.0.8.tar.gz 29.8 kB Without provenance Details for amt_augpy1_0-1.0.8.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for amt-augpy1.0 1.0.8
File Interpreter ABI Platform Actions
amt_augpy1_0-1.0.8-py3-none-any.whl Python 3 none any Details for amt_augpy1_0-1.0.8-py3-none-any.whl

Total release size: 57.6 kB

Release files / amt_augpy1_0-1.0.8.tar.gz

Download URL amt_augpy1_0-1.0.8.tar.gz
Size 29.8 kB
Tags Source
SHA-256 checksum
How to use checksums
92b0ad9e6f887ea614cface670d34492235411689381bf791ee794caae388122
BLAKE2b-256 checksum
How to use checksums
05ecec46fe4eec85f04530b4dfd0b3fc85775d6c52db208d8515d91abb891f85
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.8.18

Release files / amt_augpy1_0-1.0.8-py3-none-any.whl

Download URL amt_augpy1_0-1.0.8-py3-none-any.whl
Size 27.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d985ea268bb8a1f1b30ea6d78e75a36ea180b5185ca1d7e9ac07a9f1f8dcbf0b
BLAKE2b-256 checksum
How to use checksums
17f68e11a55d3dadcfbb0e9e61d3dd8e1a3bbe3e2b3aa756459c55e6bbfe3b7a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.8.18

Security for amt-augpy1.0 1.0.8

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page