GitHub workflow Codecov GitHub license GitHub release

Pypianoroll is an open source Python library for working with piano rolls. It provides essential tools for handling multitrack piano rolls, including efficient I/O as well as manipulation, visualization and evaluation tools.


  • Manipulate multitrack piano rolls intuitively

  • Visualize multitrack piano rolls beautifully

  • Save and load multitrack piano rolls in a space-efficient format

  • Parse MIDI files into multitrack piano rolls

  • Write multitrack piano rolls into MIDI files

Why Pypianoroll

Our aim is to provide convenient classes for piano-roll matrix and MIDI-like track information (program number, track name, drum track indicator). Pypianoroll is also designed to provide efficient I/O for piano rolls, since piano rolls have long been considered an inefficient way to store music data due to the sparse nature.


To install Pypianoroll, please run pip install pypianoroll. To build Pypianoroll from source, please download the source and run python install.


Documentation is available here and as docstrings with the code.


Please cite the following paper if you use Pypianoroll in a published work:

Hao-Wen Dong, Wen-Yi Hsiao, and Yi-Hsuan Yang, “Pypianoroll: Open Source Python Package for Handling Multitrack Pianorolls,” in Late-Breaking Demos of the 19th International Society for Music Information Retrieval Conference (ISMIR), 2018.

[homepage] [paper] [poster] [code] [documentation]

Lakh Pianoroll Dataset

Lakh Pianoroll Dataset (LPD) is a new multitrack piano roll dataset using Pypianoroll for efficient data I/O and to save space, which is used as the training dataset in our MuseGAN project.