{"id":13862075,"url":"https://github.com/carlosholivan/musicaiz","last_synced_at":"2025-07-14T11:32:22.009Z","repository":{"id":47130646,"uuid":"514237633","full_name":"carlosholivan/musicaiz","owner":"carlosholivan","description":"A python framework for symbolic music generation, evaluation and analysis","archived":false,"fork":false,"pushed_at":"2023-06-15T01:37:05.000Z","size":5621,"stargazers_count":166,"open_issues_count":3,"forks_count":17,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-11-09T06:19:09.095Z","etag":null,"topics":["audio","deep-learning","machine-learning","mir","music","music-generation","music-information-retrieval","python","symbolic"],"latest_commit_sha":null,"homepage":"https://carlosholivan.github.io/musicaiz","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/carlosholivan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.md"}},"created_at":"2022-07-15T11:03:04.000Z","updated_at":"2024-10-07T00:27:17.000Z","dependencies_parsed_at":"2024-01-21T03:59:04.358Z","dependency_job_id":"64400835-8243-4f3d-8ef0-cb772d80fca1","html_url":"https://github.com/carlosholivan/musicaiz","commit_stats":{"total_commits":107,"total_committers":2,"mean_commits":53.5,"dds":0.009345794392523366,"last_synced_commit":"13c81d3d8d726b3598e03c7cd61121a42251c229"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carlosholivan%2Fmusicaiz","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carlosholivan%2Fmusicaiz/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carlosholivan%2Fmusicaiz/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carlosholivan%2Fmusicaiz/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/carlosholivan","download_url":"https://codeload.github.com/carlosholivan/musicaiz/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225974288,"owners_count":17553925,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["audio","deep-learning","machine-learning","mir","music","music-generation","music-information-retrieval","python","symbolic"],"created_at":"2024-08-05T06:01:36.492Z","updated_at":"2024-11-22T22:30:27.947Z","avatar_url":"https://github.com/carlosholivan.png","language":"Python","funding_links":[],"categories":["Python","License"],"sub_categories":[],"readme":"![plot](https://github.com/carlosholivan/musicaiz/blob/main/docs/images/logo_rectangle.png?raw=true)\n\n# MUSICAIZ\n\nA Python library for symbolic music generation, analysis and visualization.\n\nPublished in SoftwareX 2023.\n\n\u003c!-- SHIELDS --\u003e\n\u003c!-- markdownlint-disable --\u003e\n\u003ctable\u003e\n  \u003ccolgroup\u003e\n    \u003ccol style=\"width: 10%;\"/\u003e\n    \u003ccol style=\"width: 90%;\"/\u003e\n  \u003c/colgroup\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003cth\u003eCI\u003c/th\u003e\n      \u003ctd\u003e\n        \u003cimg alt=\"build\" src=\"https://github.com/carlosholivan/musicaiz/actions/workflows/ci.yml/badge.svg\"/\u003e\n        \u003ca href=\"https://readthedocs.org/musicaiz/\"\u003e\n        \u003cimg alt=\"docs\" src=\"https://readthedocs.org/projects/musicaiz/badge/?version=latest\"/\u003e\n        \u003c/a\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003cth\u003ePaper\u003c/th\u003e\n      \u003ctd\u003e\n        \u003ca href=\"https://arxiv.org/abs/2209.07974\"\u003e\n        \u003cimg alt= \"arXiv\" src=\"https://img.shields.io/badge/arXiv-1234.56789-00ff00.svg\"/\u003e\n        \u003c/a\u003e\n        \u003ca href=\"https://www.sciencedirect.com/science/article/pii/S2352711023000614\"\u003e\n        \u003cimg alt= \"journal\" src=\"https://img.shields.io/static/v1?label=SoftwareX\u0026message=article\u0026color=blueviolet\"/\u003e\n        \u003c/a\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003cth\u003ePyPI\u003c/th\u003e\n      \u003ctd\u003e\n        \u003ca href=\"https://pypi.org/project/musicaiz/\"\u003e\n          \u003cimg alt=\"PyPI - Package Version\" src=\"https://img.shields.io/pypi/v/musicaiz\"/\u003e\n        \u003c/a\u003e\n        \u003ca href=\"https://pypi.org/project/musicaiz\"\u003e\n          \u003cimg alt=\"PyPI - Supported Python Versions\" src=\"https://img.shields.io/pypi/pyversions/musicaiz?logo=python\u0026amp;logoColor=white\"/\u003e\n        \u003c/a\u003e\n        \u003ca href=\"https://pypi.org/project/musicaiz\"\u003e\n          \u003cimg alt=\"PyPI - Wheel\" src=\"https://img.shields.io/pypi/wheel/musicaiz\"/\u003e\n        \u003c/a\u003e\n        \u003ca href=\"hhttps://pypistats.org/packages/musicaiz\"\u003e\n          \u003cimg alt=\"Downloads\" src=\"https://img.shields.io/pypi/dm/musicaiz\"/\u003e\n        \u003c/a\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003cth\u003eActivity\u003c/th\u003e\n      \u003ctd\u003e\n        \u003cimg alt=\"Maintenance\" src=\"https://img.shields.io/maintenance/yes/2022\"/\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003cth\u003eQA\u003c/th\u003e\n      \u003ctd\u003e\n        \u003ca href=\"https://codecov.io/gh/carlosholivan/musicaiz\"\u003e\n          \u003cimg alt=\"codecov\" src=\"https://codecov.io/gh/carlosholivan/musicaiz/branch/main/graph/badge.svg?token=RGSRMMF8PF\"/\u003e\n        \u003c/a\u003e\n        \u003ca href=\"https://api.codiga.io/project/34718/status/svg\"\u003e\n          \u003cimg alt=\"Code Quality\" src=\"https://api.codiga.io/project/34718/status/svg\"/\u003e\n        \u003c/a\u003e\n        \u003ca href=\"https://api.codiga.io/project/34718/score/svg\"\u003e\n          \u003cimg alt=\"Code Score\" src=\"https://api.codiga.io/project/34718/score/svg\"/\u003e\n        \u003c/a\u003e\n        \u003ca href=\"https://github.com/pre-commit/pre-commit\"\u003e\n          \u003cimg alt=\"pre-commit\" src=\"https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit\u0026amp;logoColor=white\"/\u003e\n        \u003c/a\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003cth\u003eCode\u003c/th\u003e\n      \u003ctd\u003e\n        \u003ca href=\"https://github.com/carlosholivan/musicaiz/blob/master/LICENSE\"\u003e\n          \u003cimg alt=\"License\" src=\"https://img.shields.io/github/license/carlosholivan/musicaiz\"/\u003e\n        \u003c/a\u003e\n        \u003cimg alt=\"GitHub top language\" src=\"https://img.shields.io/github/languages/top/carlosholivan/musicaiz\"/\u003e\n        \u003ca href=\"https://github.com/psf/black\"\u003e\n          \u003cimg alt=\"Code Style: Black\" src=\"https://img.shields.io/badge/code%20style-black-black\"/\u003e\n        \u003c/a\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\n\n[See the docs](https://carlosholivan.github.io/musicaiz)\n\nThe modules contained in this library are:\n\n- [Loaders](musicaiz/loaders.py)\u003cbr/\u003e\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;contains the basic initialization to import files.\n\n````python\nfrom musicaiz.loaders import Musa\n\n    midi = Musa(\n      file=\"my_midifile.mid\"\n    )\n````\n\n- [Structure](musicaiz/structure/)\u003cbr/\u003e\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;contains the structure elements in music (instruments, bars and notes).\n\n````python\n# Define a Note object\nfrom musicaiz.structure import Note\n\n    note = Note(\n      pitch=12,\n      start=0.0,\n      end=1.0,\n      velocity=75,\n      bpm=120,\n      resolution=96\n    )\n````\n\n- [Harmony](musicaiz/harmony/)\u003cbr/\u003e\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;contains the harmonic elements in music (intervals, chords and keys).\n\n````python\nfrom musicaiz.structure import Chords, Tonality\n\n    # Initialize a chord by its notation\n    chord_name = \"Cm7b5\"\n    chord = Chord(chord_name)\n    # get the notes in the chord\n    chord.get_notes(inversion=0)\n\n    # Initialize Tonality\n    tonality = Tonality.E_MINOR\n    # get different scales\n    tonality.natural\n    tonality.harmonic\n    tonality.melodic\n    # get the notes in a scale\n    tonality.scale_notes(\"NATURAL\")\n    # get a chord from a scale degree\n    Tonality.get_chord_from_degree(\n      tonality=\"E_MINOR\",\n      degree=\"V\",\n      scale=\"NATURAL\",\n      chord_type=\"triad\",\n    )\n````\n\n- [Rhythm](musicaiz/rhythm/)\u003cbr/\u003e\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;contains rhythmic or timing elements in music (quantization).\n- [Features](musicaiz/features/)\u003cbr/\u003e\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;contains classic features to analyze symbolic music data (pitch class histograms...).\n- [Algorithms](musicaiz/algorithms/)\u003cbr/\u003e\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;contains algorithms for chord prediction, key prediction, harmonic transposition...\n- [Plotters](musicaiz/plotters/)\u003cbr/\u003e\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;contains different ways of plotting music (pinorolls or scores).\n\n````python\nfrom musicaiz.plotters import Pianoroll, PianorollHTML\n\n    # Matplotlib\n    musa_obj = Musa(midi_sample)\n    plot = Pianoroll(musa_obj)\n    plot.plot_instruments(\n        program=[48, 45],\n        bar_start=0,\n        bar_end=4,\n        print_measure_data=True,\n        show_bar_labels=False,\n        show_grid=False,\n        show=True,\n    )\n\n    # Pyplot HTML\n    musa_obj = Musa(midi_sample)\n    plot = PianorollHTML(musa_obj)\n    plot.plot_instruments(\n        program=[48, 45],\n        bar_start=0,\n        bar_end=4,\n        show_grid=False,\n        show=False\n    )\n````\n\n- [Tokenizers](musicaiz/tokenizers/)\u003cbr/\u003e\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;contains different encodings to prepare symbolic music data to train a sequence model.\n\n````python\nfrom musicaiz.tokenizers import MMMTokenizer, MMMTokenizerArguments\n\n    # Tokenize file\n    midi = \"my_midifile.mid\"\n    args = MMMTokenizerArguments(\n      windowing=True,\n      time_unit=\"SIXTEENTH\",\n      num_programs=None,\n      shuffle_tracks=True,\n      track_density=False,\n      window_size=4,\n      hop_length=1,\n      time_sig=False,\n      velocity=False,\n      quantize=False,\n      tempo=True,\n    )\n    # save configs\n    MMMTokenizerArguments.save(args, \"./\")\n    tokenizer = MMMTokenizer(midi, args)\n    got = tokenizer.tokenize_file()\n\n    # get tokens analysis\n    my_tokens = \"PIECE_START TRACK_START ...\"\n    MMMTokenizer.get_tokens_analytics(my_tokens)\n\n    # Convert tokens to Musa objects\n    MMMTokenizer.tokens_to_musa(\n      tokens=my_tokens,\n      absolute_timing=True,\n      time_unit=\"SIXTEENTH\",\n      time_sig=\"4/4\",\n      resolution=96\n    )\n\n    # get vocabulary\n    MMMTokenizer.get_vocabulary(\n      dataset_path=\"apth/to/dataset/tokens\",\n    )\n````\n\n- [Converters](musicaiz/converters/)\u003cbr/\u003e\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;contains converters to other formats (JSON,...).\n\n````python\nfrom musicaiz.loaders import Musa\nfrom musicaiz.loaders import musa_to_proto, proto_to_musa\n\n  # Convert a musicaiz objects in protobufs\n  midi = Musa(midi_sample, structure=\"bars\")\n  protobuf = musa_to_proto(midi)\n\n  # Convert a protobuf to musicaiz objects\n  musa = proto_to_musa(protobuf)\n    \n````\n\n- [Datasets](musicaiz/datasets/)\u003cbr/\u003e\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;contains helper methods to work with MIR open-source datasets.\n\n````python\nfrom musicaiz.tokenizers import MMMTokenizer, MMMTokenizerArguments\nfrom musicaiz.datasets import JSBChorales\n\n    # Tokenize a dataset in musicaiz\n    output_path = \"path/to/store/tokens\"\n\n    args = MMMTokenizerArguments(\n        prev_tokens=\"\",\n        windowing=True,\n        time_unit=\"HUNDRED_TWENTY_EIGHT\",\n        num_programs=None,\n        shuffle_tracks=True,\n        track_density=False,\n        window_size=32,\n        hop_length=16,\n        time_sig=True,\n        velocity=True,\n    )\n    dataset = JSBChorales()\n    dataset.tokenize(\n        dataset_path=\"path/to/JSB Chorales/midifiles\",\n        output_path=output_path,\n        output_file=\"token-sequences\",\n        args=args,\n        tokenize_split=\"all\"\n    )\n    vocab = MMMTokenizer.get_vocabulary(\n        dataset_path=output_path\n    )\n````\n\n- [Models](musicaiz/models/)\u003cbr/\u003e\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;contains ML models to generate symbolic music.\n\n## License\n\nThis project is licensed under the terms of the [AGPL v3 license](LICENSE).\n\n\n## Install\n\nTo install the latest stable version run: `pip install musicaiz`\n\nTo install the latest version, clone this repository and run:\n\n`pip install -e .`\n\nIf you want to train the models in the [models](musicaiz/models/) submodule, you must install `apex`. Follow the instructions on https://github.com/NVIDIA/apex.\n\n\n## Develop\n\n### Conda dev environment\n\nRun 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.\n\n`conda create --name python=3.9`\n\n`conda env update -f environment.yml`\n\n`conda activate musicaiz`\n\n### Linting\n\nflake8 and black\n\n### Typing\n\nUse mypy package to check variables tpyes:\n\n`mypy musicaiz`\n\n## Examples\n\nSee docs.\n\n## Citing\n\nIf you use this software for your research, please cite:\n\n````\n@article{HERNANDEZOLIVAN2023101365,\n    title = {Musicaiz: A python library for symbolic music generation, analysis and visualization},\n    journal = {SoftwareX},\n    volume = {22},\n    pages = {101365},\n    year = {2023},\n    issn = {2352-7110},\n    doi = {https://doi.org/10.1016/j.softx.2023.101365},\n    url = {https://www.sciencedirect.com/science/article/pii/S2352711023000614},\n    author = {Carlos Hernandez-Olivan and Jose R. Beltran},\n}\n````\n\n## Contributing\n\nMusicaiz software can be extended in different ways, see some example in [TODOs](TODOs.md). If you want to contribute, please follow the guidelines in [Develop](##Develop)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarlosholivan%2Fmusicaiz","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcarlosholivan%2Fmusicaiz","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarlosholivan%2Fmusicaiz/lists"}