mirdata Documentation

The mirdata repository provides loaders for a wide variety of Music Information Retrieval (MIR) datasets. The following table summarizes the capabilities of currently supported datasets, including whether audio/annotations are downloadable, the types of annotations available (e.g., beats, tempo, pitch, chords), the number of tracks, and the licensing terms.

Dataset Summary Table

When a dataset has multiple versions (e.g., different annotation sets) but uses the same loading logic, you should write a single loader and define multiple versions using the INDEXES dictionary in the dataset module.

• Use the naming convention <datasetname>_index_<version>.json for index files.
• The INDEXES dictionary maps version names to core.Index objects.
• Use the default key in INDEXES to specify which version is loaded by default when calling mirdata.initialize('dataset_name').
• To load a specific version, use mirdata.initialize('dataset_name', version='version_name').
• To avoid downloading unnecessary data for specific versions, use the partial_download argument in core.Index to specify a subset of keys from the REMOTES dictionary.

INDEXES = {
    "default": "1.0",
    "test": "sample",
    "1.0": core.Index(filename="example_index_1.0.json", partial_download=['audio', 'v1-annotations']),
    "2.0": core.Index(filename="example_index_2.0.json", partial_download=['audio', 'v2-annotations']),
    "sample": core.Index(filename="example_index_sample.json")
}

Indexes in Mirdata are JSON manifests that map files in a dataset to their corresponding MD5 checksums. This ensures data integrity and provides a structured way to locate files.

An index must contain a top-level version key. It can also include one or more of the following top-level keys depending on the dataset organization:

• metadata: Maps metadata file names to their relative paths and MD5 checksums.
• tracks: Used for datasets organized as individual tracks (mono/multi-channel audio, spectrograms, etc.).
• multitracks: Used for datasets comprising groups of related tracks.
• records: Used for datasets organized as groups of tables (e.g., relational databases).

{
    "version": "1.0.0",
    "metadata": {
        "metadata_file_1": [
            "path_to_metadata/metadata_file_1.csv",
            "bb8b0ca866fc2423edde01325d6e34f7"
        ]
    },
    "tracks": {
        "track1": {
            "audio": ["audio_files/track1.wav", "6c77777ce77a06541cdb9f0a671afb46"],
            "beats": ["annotations/track1.beats.csv", "ab8b0ca866fc2423edde01325d6e34f7"]
        }
    }
}

Mirdata uses indexes (dictionaries) to store information about dataset files, their locations, and checksums. This is necessary for loading and validation.

Steps to create an index:

1. Create a script in scripts/ (e.g., make_dataset_index.py) that automates index generation by computing MD5 checksums for files at a given data_path.
2. Run the script on the dataset.
3. Save the resulting index in mirdata/datasets/indexes/ as dataset_index_<version>.json (e.g., dataset_index_1.0.json).

Index Structure for Tracks

Most MIR datasets use a tracks top-level key. This is a dictionary where keys are unique track IDs and values are dictionaries of files (audio, annotations, etc.) and their checksums. File paths must be relative to the dataset's top-level directory.

Index Structure for Multitracks

Multitrack datasets can use a multitracks top-level key to group related tracks and provide master/mix audio files.

{
    "version": "1.0",
    "tracks": {
        "track1": {
            "audio": [
                "audio/track1.wav",
                "912ec803b2ce49e4a541068d495ab570"
            ],
            "annotation": [
                "annotations/track1.csv",
                "2cf33591c3b28b382668952e236cccd5"
            ]
        }
    },
    "metadata": {
        "metadata_file": [
            "metadata/metadata_file.csv",
            "7a41b280c7b74e2ddac5184708f9525b"
        ]
    }
}

Mirdata supports a wide variety of annotation types. Because definitions can vary by dataset, it is strongly recommended to read the specific dataset documentation to ensure the data matches your expectations.

Common annotation categories include:

• Rhythmic/Temporal: Beats (timestamps/positions), Meter (rhythmic meter), Tempo (BPM, can be global or time-varying), and Sections (boundary timestamps).
• Pitch/Melody: F0 (pitch contours), Melody (F0 or Notes), Notes (pitch events), Key (musical key), Mode (musical mode), and Tonic (tonal center).
• Harmonic: Chords (labeled events like 'A:m7').
• Instrumental/Percussive: Drums (drum instrument events), Instruments (presence/absence), Technique (playing style, e.g., 'Pizzicato'), and Stroke Name (specific instrument stroke types).
• Vocal/Lyrics: Lyrics (text or time-aligned), Phonemes (sung phonemes), Syllables (structured syllables), and Vocal Activity (presence of singing).
• Other: Genre (global tags), Tags (broad, often free-form labels), Effect (audio effects), Matches (audio fingerprinting identifications), and Segments (specific event segments).