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.

````python from musicaiz.loaders import Musa

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

````

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

````python

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).

````python 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).

````python 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.

````python 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,...).

````python from musicaiz.loaders import Musa from musicaiz.loaders import musatoproto, prototomusa

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

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

````

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

````python 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