MusPy Documentation

MusPy is an open source Python library designed for symbolic music generation. It provides a toolkit for the entire music generation pipeline, including:

• Dataset Management: Interfaces for commonly used datasets with support for PyTorch and TensorFlow.
• Data I/O: Support for symbolic music formats like MIDI, MusicXML, and ABC, with interfaces to libraries such as music21, mido, pretty_midi, and Pypianoroll.
• Music Representations: Implementations of pitch-based, event-based, piano-roll, and note-based representations.
• Model Evaluation: Tools for audio rendering, score and piano-roll visualizations, and objective metrics.

MusPy provides three distinct categories of I/O interfaces depending on your data source and target format:

1. Common symbolic music formats: Use muspy.read_* and muspy.write_* functions to handle standard symbolic music files.
2. MusPy native formats: Use muspy.load_* and muspy.save_* to work with MusPy's internal JSON and YAML representations.
3. Interoperability with other libraries: Use muspy.from_* and muspy.to_* to convert data between MusPy objects and other symbolic music libraries (such as music21, pretty_midi, or mido).

The muspy.Music class is the central data structure in MusPy, serving as a universal container for symbolic music. It holds all musical information, including tracks, metadata, tempo changes, key signatures, time signatures, beats, lyrics, and annotations.

Key attributes include:

• metadata: An instance of muspy.Metadata.
• resolution: An integer representing time steps per beat (defaults to muspy.DEFAULT_RESOLUTION).
• tempos: A list of muspy.Tempo objects.
• key_signatures: A list of muspy.KeySignature objects.
• time_signatures: A list of muspy.TimeSignature objects.
• beats: A list of muspy.Beat objects.
• lyrics: A list of muspy.Lyric objects.
• annotations: A list of muspy.Annotation objects.
• tracks: A list of muspy.Track objects.

MusPy objects support dot notation for accessing nested attributes.

Common Access Patterns:

• music.metadata.title: Access song metadata like the title.
• music.tempos[0].qpm: Access specific tempo values (e.g., quarter notes per minute).
• [note.pitch for note in music.tracks[0].notes]: Iterate through notes in a track to access properties like pitch, duration, or velocity.

Shorthands:

• music[i] is equivalent to music.tracks[i].
• len(music) is equivalent to len(music.tracks).

# Accessing metadata
title = music.metadata.title

# Accessing tempo
tempo_qpm = music.tempos[0].qpm

# Accessing pitches from the first track
pitches = [note.pitch for note in music.tracks[0].notes]

# Using shorthands
first_track = music[0]
track_count = len(music)

MusPy supports four primary representations for symbolic music. Choose a representation based on your required data shape and the type of music you are processing:

• Pitch-based: Shape T x 1. Values are {0, 1, ..., 129}. Best for monophonic music (includes 128 note-ons, 1 hold, and 1 rest).
• Piano-roll: Shape T x 128. Values are {0, 1} (binary) or N (velocities). Represents music as a grid of time steps and pitches.
• Event-based: Shape M x 1. Values are {0, 1, ..., 387}. Includes 128 note-ons, 128 note-offs, 100 tick shifts, and 32 velocities.
• Note-based: Shape N x 4. A list of (time, pitch, duration, velocity) tuples.

Note: T is time steps, M is events, and N is notes.

When importing music files into MusPy, the music.resolution attribute is automatically set based on the file format:

• MIDI files: music.resolution is set to the pulses per quarter note (PPQ, PPQN, or ticks per beat).
• MusicXML files: music.resolution is set to the division attribute (the number of divisions per quarter note). If multiple division attributes are present, MusPy sets the resolution to the least common multiple (LCM) of those values.

A MusPy Dataset object supports two internal processing modes when iterating over its contents:

1. On-the-fly processing: Data is processed or converted at the moment of iteration. This is memory-efficient but may incur a computational cost during the loop.
2. Preconverted processing: Data is converted into the target format before iteration begins. This is faster during the loop but requires more initial setup or memory.

Users can choose or rely on these modes depending on whether they prioritize immediate memory availability or iteration speed.

MusPy provides several classes for interacting with datasets hosted remotely. These classes allow you to load and manage music datasets without having them stored locally. The available remote dataset classes are:

• muspy.RemoteFolderDataset: For datasets organized in remote folder structures.
• muspy.RemoteMusicDataset: For datasets specifically formatted as remote music collections.
• muspy.RemoteABCFolderDataset: For datasets containing ABC notation files organized in remote folders.

MusPy uses a metrical timing system where time is represented in musical units (like beats or quarter notes) rather than seconds. To convert metrical time to absolute time (seconds) for playback, MusPy uses the following relationship:

absolute_time = (60 / (tempo * resolution)) * metrical_time

Key components:

• Time Step: The smallest unit of time in the system, which is a factor of a beat. By default, this is a quarter note.
• Resolution (music.resolution): The number of time steps per beat.
• Tempo (music.tempos): The current tempo expressed in quarters per minute (qpm).

These values are stored as attributes on the muspy.Music object.

To use a specific dataset, instantiate its corresponding class (which inherits from the base MusPy Dataset class). Setting download_and_extract=True will automatically handle the downloading and extraction of the dataset files to the specified directory.

import muspy

# Download and extract the dataset to the 'data/nes/' directory
nes = muspy.NESMusicDatabase("data/nes/", download_and_extract=True)