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

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

fortunto2 / musicaiz