MUSICAIZ

A Python library for symbolic music generation, analysis and visualization.

Published in SoftwareX 2023.

CI
Paper
PyPI
Activity
QA
Code

See the docs

The modules contained in this library are:

• Loaders
      contains the basic initialization to import files.

from musicaiz.loaders import Musa

    midi = Musa(
      file="my_midifile.mid"
    )

• Structure
      contains the structure elements in music (instruments, bars and notes).

# Define a Note object
from musicaiz.structure import Note

    note = Note(
      pitch=12,
      start=0.0,
      end=1.0,
      velocity=75,
      bpm=120,
      resolution=96
    )

• Harmony
      contains the harmonic elements in music (intervals, chords and keys).

from musicaiz.structure import Chords, Tonality

    # Initialize a chord by its notation
    chord_name = "Cm7b5"
    chord = Chord(chord_name)
    # get the notes in the chord
    chord.get_notes(inversion=0)

    # Initialize Tonality
    tonality = Tonality.E_MINOR
    # get different scales
    tonality.natural
    tonality.harmonic
    tonality.melodic
    # get the notes in a scale
    tonality.scale_notes("NATURAL")
    # get a chord from a scale degree
    Tonality.get_chord_from_degree(
      tonality="E_MINOR",
      degree="V",
      scale="NATURAL",
      chord_type="triad",
    )

• Rhythm
      contains rhythmic or timing elements in music (quantization).
• Features
      contains classic features to analyze symbolic music data (pitch class histograms...).
• Algorithms
      contains algorithms for chord prediction, key prediction, harmonic transposition...
• Plotters
      contains different ways of plotting music (pinorolls or scores).

from musicaiz.plotters import Pianoroll, PianorollHTML

    # Matplotlib
    musa_obj = Musa(midi_sample)
    plot = Pianoroll(musa_obj)
    plot.plot_instruments(
        program=[48, 45],
        bar_start=0,
        bar_end=4,
        print_measure_data=True,
        show_bar_labels=False,
        show_grid=False,
        show=True,
    )

    # Pyplot HTML
    musa_obj = Musa(midi_sample)
    plot = PianorollHTML(musa_obj)
    plot.plot_instruments(
        program=[48, 45],
        bar_start=0,
        bar_end=4,
        show_grid=False,
        show=False
    )

• Tokenizers
      contains different encodings to prepare symbolic music data to train a sequence model.

from musicaiz.tokenizers import MMMTokenizer, MMMTokenizerArguments

    # Tokenize file
    midi = "my_midifile.mid"
    args = MMMTokenizerArguments(
      windowing=True,
      time_unit="SIXTEENTH",
      num_programs=None,
      shuffle_tracks=True,
      track_density=False,
      window_size=4,
      hop_length=1,
      time_sig=False,
      velocity=False,
      quantize=False,
      tempo=True,
    )
    # save configs
    MMMTokenizerArguments.save(args, "./")
    tokenizer = MMMTokenizer(midi, args)
    got = tokenizer.tokenize_file()

    # get tokens analysis
    my_tokens = "PIECE_START TRACK_START ..."
    MMMTokenizer.get_tokens_analytics(my_tokens)

    # Convert tokens to Musa objects
    MMMTokenizer.tokens_to_musa(
      tokens=my_tokens,
      absolute_timing=True,
      time_unit="SIXTEENTH",
      time_sig="4/4",
      resolution=96
    )

    # get vocabulary
    MMMTokenizer.get_vocabulary(
      dataset_path="apth/to/dataset/tokens",
    )

• Converters
      contains converters to other formats (JSON,...).

from musicaiz.loaders import Musa
from musicaiz.loaders import musa_to_proto, proto_to_musa

  # Convert a musicaiz objects in protobufs
  midi = Musa(midi_sample, structure="bars")
  protobuf = musa_to_proto(midi)

  # Convert a protobuf to musicaiz objects
  musa = proto_to_musa(protobuf)
    

• Datasets
      contains helper methods to work with MIR open-source datasets.

from musicaiz.tokenizers import MMMTokenizer, MMMTokenizerArguments
from musicaiz.datasets import JSBChorales

    # Tokenize a dataset in musicaiz
    output_path = "path/to/store/tokens"

    args = MMMTokenizerArguments(
        prev_tokens="",
        windowing=True,
        time_unit="HUNDRED_TWENTY_EIGHT",
        num_programs=None,
        shuffle_tracks=True,
        track_density=False,
        window_size=32,
        hop_length=16,
        time_sig=True,
        velocity=True,
    )
    dataset = JSBChorales()
    dataset.tokenize(
        dataset_path="path/to/JSB Chorales/midifiles",
        output_path=output_path,
        output_file="token-sequences",
        args=args,
        tokenize_split="all"
    )
    vocab = MMMTokenizer.get_vocabulary(
        dataset_path=output_path
    )

• Models
      contains ML models to generate symbolic music.

License

This project is licensed under the terms of the AGPL v3 license.

Install

To install the latest stable version run: pip install musicaiz

To install the latest version, clone this repository and run:

pip install -e .

If you want to train the models in the models submodule, you must install apex. Follow the instructions on https://github.com/NVIDIA/apex.

Develop

Conda dev environment

Run the following commands to create a conda env. Note that if you skip the first command, a newer python version might be installed and the package will not work.

conda create --name python=3.9

conda env update -f environment.yml

conda activate musicaiz

Linting

flake8 and black

Typing

Use mypy package to check variables tpyes:

mypy musicaiz

Examples

See docs.

Citing

If you use this software for your research, please cite:

@article{HERNANDEZOLIVAN2023101365,
    title = {Musicaiz: A python library for symbolic music generation, analysis and visualization},
    journal = {SoftwareX},
    volume = {22},
    pages = {101365},
    year = {2023},
    issn = {2352-7110},
    doi = {https://doi.org/10.1016/j.softx.2023.101365},
    url = {https://www.sciencedirect.com/science/article/pii/S2352711023000614},
    author = {Carlos Hernandez-Olivan and Jose R. Beltran},
}

Contributing

Musicaiz software can be extended in different ways, see some example in TODOs. If you want to contribute, please follow the guidelines in Develop