midiogre.core package

Submodules

midiogre.core.compositions module

Composition module for chaining multiple MIDI transforms.

This module provides functionality to compose multiple MIDI transforms into a single transform pipeline. The transforms are applied sequentially in the order they are provided.

Example

>>> from midiogre.augmentations import PitchShift, OnsetTimeShift
>>> from midiogre.core import Compose
>>>
>>> # Create a transform pipeline
>>> transform = Compose([
...     PitchShift(max_shift=2, p=0.5),
...     OnsetTimeShift(max_shift=0.1, p=0.3)
... ])
>>>
>>> # Apply transforms to MIDI data
>>> transformed_midi = transform(midi_data)

class midiogre.core.compositions.Compose(transforms)[source]

Bases: object

A class for composing multiple MIDI transforms into a single transform.

This class allows you to chain multiple transforms together and apply them sequentially to MIDI data. Each transform in the pipeline must be a callable that takes a PrettyMIDI object as input and returns a transformed PrettyMIDI object.

Parameters:: transforms (list or tuple) – A sequence of MIDI transforms to be applied in order. Each transform should be a callable that takes a PrettyMIDI object as input and returns a transformed PrettyMIDI object.
Raises:: TypeError – If transforms is not a list or tuple.

Example

>>> # Create transforms
>>> pitch_shift = PitchShift(max_shift=2)
>>> onset_shift = OnsetTimeShift(max_shift=0.1)
>>>
>>> # Compose transforms
>>> transform = Compose([pitch_shift, onset_shift])
>>>
>>> # Apply to MIDI data
>>> transformed_midi = transform(midi_data)

__call__(midi_data)[source]

Apply all transforms sequentially to the MIDI data.

Parameters:: midi_data (PrettyMIDI) – The MIDI data to transform.
Returns:: The transformed MIDI data after applying all transforms in sequence.
Return type:: PrettyMIDI

__init__(transforms)[source]

Compose several MIDIOgre transforms together.

Parameters:: transforms (list) – list of MIDIOgre transforms to be performed in the given order

__len__()[source]

Return the number of transforms in the composition.

Returns:: Number of transforms in the pipeline.
Return type:: int

midiogre.core.conversions module

MIDI format conversion module.

This module provides tools for converting between different MIDI representations and formats, primarily to enable composition of multiple MIDI augmentations. Similar to image augmentation libraries like albumentations, these converters allow you to seamlessly chain transforms that operate on different MIDI formats.

The module supports conversions between: - Mido MidiFile objects - PrettyMIDI objects - Piano roll representations (NumPy arrays and PyTorch tensors)

Primary Use Case - Augmentation Pipeline:

>>> from midiogre.augmentations import PitchShift, TempoShift, OnsetTimeShift
>>> from midiogre.core.conversions import ConvertToMido, ConvertToPrettyMIDI
>>> from midiogre.core import Compose
>>>
>>> # Create a pipeline with transforms that need different MIDI formats
>>> transform = Compose([
...     PitchShift(max_shift=2),  # Uses PrettyMIDI
...     ConvertToMido(),  # Convert to Mido format
...     TempoShift(max_shift=20.0),  # Uses Mido
...     ConvertToPrettyMIDI(),  # Convert back to PrettyMIDI
...     OnsetTimeShift(max_shift=0.1)  # Uses PrettyMIDI
... ])
>>>
>>> # Apply entire pipeline with automatic format conversion
>>> midi_data = pretty_midi.PrettyMIDI('song.mid')
>>> transformed = transform(midi_data)

Other Use Cases:

>>> # Direct format conversion
>>> mido_obj = ConvertToMido()('song.mid')
>>> pretty_midi_obj = ConvertToPrettyMIDI()(mido_obj)
>>>
>>> # Create piano roll representation
>>> from midiogre.core.conversions import ToPRollTensor
>>> piano_roll = ToPRollTensor()(pretty_midi_obj)

Note

When composing transforms, the converters handle format compatibility automatically. You only need to ensure that: 1. The input format matches what the first transform expects 2. You convert between formats when switching between Mido and PrettyMIDI transforms 3. The final output format is what you need for your application

class midiogre.core.conversions.BaseConversion[source]

Bases: object

Base class for all MIDI format conversions.

This class defines the interface that all conversion classes must implement. Conversion classes are callable objects that take a MIDI object or file path as input and return a transformed representation.

The __call__ method handles input validation and file path resolution, while the actual conversion logic should be implemented in the apply method.

__call__(midi_data)[source]

Convert the MIDI data.

Parameters:: midi_data (Union[str, PrettyMIDI, MidiFile]) – The MIDI data to convert. Can be: - A file path string - A PrettyMIDI object - A Mido MidiFile object
Returns:: The converted MIDI data.
Raises:: ValueError – If a file path is provided but the file does not exist.

__init__()[source]: Initialize the conversion.

apply(midi_data)[source]

Apply the conversion to the MIDI data.

This method should be implemented by all conversion classes.

Parameters:: midi_data – The MIDI data to convert.
Returns:: The converted MIDI data.
Raises:: NotImplementedError – If the child class does not implement this method.

class midiogre.core.conversions.ConvertToMido[source]

Bases: BaseConversion

Convert MIDI data to a Mido MidiFile object.

This converter is particularly useful when working with transforms that require Mido objects, such as TempoShift.

Example

>>> converter = ConvertToMido()
>>> # Convert from file
>>> mido_obj = converter('song.mid')
>>> # Convert from PrettyMIDI
>>> mido_obj = converter(pretty_midi_obj)

__init__()[source]: Initialize the Mido converter.

apply(path_to_midi)[source]

Convert MIDI data to a Mido MidiFile object.

Parameters:: path_to_midi (str) – Path to the MIDI file to load.
Returns:: The loaded MIDI data as a Mido object.
Return type:: mido.MidiFile

Warning

If tempo, key signature, or time signature events are found on non-zero tracks, they may not be interpreted correctly as this violates the MIDI type 0/1 specification.

class midiogre.core.conversions.ConvertToPrettyMIDI[source]

Bases: BaseConversion

Convert MIDI data to a PrettyMIDI object.

This converter is useful when working with most MIDIOgre transforms, as they typically operate on PrettyMIDI objects. It can convert from either a file path or a Mido MidiFile object.

Example

>>> converter = ConvertToPrettyMIDI()
>>> # Convert from file
>>> pretty_midi_obj = converter('song.mid')
>>> # Convert from Mido
>>> pretty_midi_obj = converter(mido_obj)

__init__()[source]: Initialize the PrettyMIDI converter.

apply(midi_data)[source]

Convert MIDI data to a PrettyMIDI object.

Parameters:: midi_data (Union[str, MidiFile]) – The MIDI data to convert. Can be: - A file path string - A Mido MidiFile object
Returns:: The converted MIDI data.
Return type:: pretty_midi.PrettyMIDI

class midiogre.core.conversions.ToPRollNumpy(binarize=False, fs=100, times=None, pedal_threshold=64)[source]

Bases: BaseConversion

Convert MIDI data to a piano roll NumPy array.

This converter transforms MIDI data into a piano roll representation as a 2D NumPy array of shape (128, time_steps). The array values represent note velocities at each time step.

Parameters:

binarize (bool, optional) – Whether to binarize the piano roll. Default: False
fs (int, optional) – Sampling frequency in Hz. Default: 100
times (array-like, optional) – Times at which to sample the piano roll. Default: None
pedal_threshold (int, optional) – Threshold above which the sustain pedal is activated. Default: 64

Example

>>> converter = ToPRollNumpy(fs=200)  # 200 Hz sampling
>>> piano_roll = converter(pretty_midi_obj)  # Shape: (128, time_steps)

__init__(binarize=False, fs=100, times=None, pedal_threshold=64)[source]

Initialize the piano roll converter.

Parameters:

binarize (bool, optional) – Whether to binarize the piano roll.
fs (int, optional) – Sampling frequency in Hz.
times (array-like, optional) – Times at which to sample.
pedal_threshold (int, optional) – Sustain pedal threshold.

apply(midi_data)[source]

Convert MIDI data to a piano roll NumPy array.

Parameters:: midi_data (pretty_midi.PrettyMIDI) – The MIDI data to convert.
Returns:: Piano roll array of shape (128, time_steps).
Return type:: np.ndarray

Note

For more details on the piano roll format, see: https://craffel.github.io/pretty-midi/#pretty_midi.PrettyMIDI.get_piano_roll

class midiogre.core.conversions.ToPRollTensor(binarize=False, device='cpu', fs=100, times=None, pedal_threshold=64)[source]

Bases: ToPRollNumpy

Convert MIDI data to a piano roll PyTorch tensor.

This converter transforms MIDI data into a piano roll representation as a 2D PyTorch tensor of shape (128, time_steps). The tensor values represent note velocities at each time step.

This class inherits from ToPRollNumpy and adds PyTorch-specific functionality, such as device placement.

Parameters:

binarize (bool, optional) – Whether to binarize the piano roll. Default: False
device (str, optional) – PyTorch device to place the tensor on. Default: ‘cpu’
fs (int, optional) – Sampling frequency in Hz. Default: 100
times (array-like, optional) – Times at which to sample the piano roll. Default: None
pedal_threshold (int, optional) – Threshold above which the sustain pedal is activated. Default: 64

Example

>>> converter = ToPRollTensor(fs=200, device='cuda')
>>> piano_roll = converter(pretty_midi_obj)  # Shape: (128, time_steps)

__init__(binarize=False, device='cpu', fs=100, times=None, pedal_threshold=64)[source]

Initialize the piano roll tensor converter.

Parameters:

binarize (bool, optional) – Whether to binarize the piano roll.
device (str, optional) – PyTorch device to place the tensor on.
fs (int, optional) – Sampling frequency in Hz.
times (array-like, optional) – Times at which to sample.
pedal_threshold (int, optional) – Sustain pedal threshold.

apply(midi_data)[source]

Convert MIDI data to a piano roll PyTorch tensor.

Parameters:: midi_data (pretty_midi.PrettyMIDI) – The MIDI data to convert.
Returns:: Piano roll tensor of shape (128, time_steps).
Return type:: torch.Tensor

Note

For more details on the piano roll format, see: https://craffel.github.io/pretty-midi/#pretty_midi.PrettyMIDI.get_piano_roll

midiogre.core.transforms_interface module

Base interface for all MIDI data augmentation transforms.

This module provides the base class for implementing MIDI data augmentation transforms. All transforms in MIDIOgre inherit from this class and must implement the apply method.

Example

>>> class MyTransform(BaseMidiTransform):
...     def __init__(self, p_instruments=1.0, p=0.5):
...         super().__init__(p_instruments=p_instruments, p=p)
...
...     def apply(self, midi_data):
...         # Implement your transform logic here
...         return midi_data

class midiogre.core.transforms_interface.BaseMidiTransform(p_instruments, p, eps=1e-12)[source]

Bases: object

Base class for all MIDI data augmentation transforms.

This class provides common functionality for MIDI transforms including: - Probability handling for transform application - Instrument selection for multi-instrument MIDI files - Basic validation of transform parameters

All transforms should inherit from this class and implement the apply method.

Parameters:

p_instruments (float) – Probability of applying the transform to each instrument when multiple instruments are present. Must be in range [0, 1]. Default: 1.0 (apply to all instruments)
p (float) – Probability of applying the transform to selected notes within each chosen instrument. Must be in range [0, 1]. Default: 0.5
eps (float, optional) – Small epsilon value for numerical stability. Default: 1e-12

Raises:

ValueError – If p or p_instruments are not in range [0, 1]

__call__(midi_data)[source]

Apply the transform to the MIDI data.

This method makes the transform callable, allowing it to be used as a function.

Parameters:: midi_data – A PrettyMIDI object containing the MIDI data to transform.
Returns:: The transformed PrettyMIDI object.

apply(midi_data)[source]

Apply the transform to the MIDI data.

This method should be implemented by all transform classes.

Parameters:: midi_data – A PrettyMIDI object containing the MIDI data to transform.
Returns:: The transformed PrettyMIDI object.
Raises:: NotImplementedError – If the child class does not implement this method.

midiogre.core package

Submodules

midiogre.core.compositions module

midiogre.core.conversions module

midiogre.core.transforms_interface module

Module contents