Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
Natooz authored Nov 21, 2023
1 parent 6a59343 commit 38cfa38
Showing 1 changed file with 27 additions and 14 deletions.
41 changes: 27 additions & 14 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,19 @@
# miditoolkit
# Miditoolkit

A python package for working with MIDI data.
A Python package for working with MIDI files.

* Version: 0.1.17
* Latest update date: 2023/10/31
[![PyPI version fury.io](https://badge.fury.io/py/miditoolkit.svg)](https://pypi.python.org/pypi/miditoolkit/)
[![Python 3.7](https://img.shields.io/badge/python-3.7+-blue.svg)](https://www.python.org/downloads/release/)
[![GitHub CI](https://github.com/YatingMusic/miditoolkit/actions/workflows/pytest.yml/badge.svg)](https://github.com/YatingMusic/miditoolkit/actions/workflows/pytest.yml)
[![GitHub license](https://img.shields.io/github/license/YatingMusic/miditoolkit.svg)](https://github.com/YatingMusic/miditoolkit/blob/main/LICENSE)
[![Downloads](https://static.pepy.tech/badge/miditoolkit)](https://pepy.tech/project/miditoolkit)
[![Code style](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

The usage is similar to [pretty_midi](https://github.com/craffel/pretty-midi), while miditoolkit handles MIDI events in [symbolic timing](https://mido.readthedocs.io/en/latest/midi_files.html#about-the-time-attribute) (**ticks**, instead of seconds). Furthermore, the toolkit can parse MIDI tracks into **piano-rolls** for computation or visualization purposes.
Miditoolkit works by loading/writing MIDIs with [mido](https://github.com/mido/mido) in a user-friendly way. It is inspired from [pretty_midi](https://github.com/craffel/pretty-midi), with similar usage and core features, but handles the MIDI events in native **[ticks](https://www.recordingblogs.com/wiki/midi-tick)** time unit instead of seconds. It also comes with a few optimizations and speed-ups, and can parse MIDI tracks into **piano-rolls** for computation or visualization purposes.
If you are working with seconds time units (for e.g. music transcription), you'll be likely better with pretty_midi. Otherwise, if you are working solely on MIDI and symbolic music, miditoolkit should provide slightly faster performances.

## Main Features

* MIDI
* Global
* ticks per beat
Expand All @@ -33,6 +39,7 @@ The usage is similar to [pretty_midi](https://github.com/craffel/pretty-midi), w
* [structure analysis](https://github.com/wayne391/sf_segmenter)

## TODO

* better documentation
* absolute timing
* cropping: Control Changes
Expand All @@ -41,13 +48,19 @@ The usage is similar to [pretty_midi](https://github.com/craffel/pretty-midi), w
* new structural analysis

## Installation
* current version: 0.1.15
* **python 2 is not supported**
* Install the miditoolkit via [PYPI](https://pypi.org/project/miditoolkit/):

You can install miditoolkit via [PYPI](https://pypi.org/project/miditoolkit/):

```bash
pip install miditoolkit
```

... or directly from git if you want to get the latest features or fixes (only recommended if you need it):

```bash
pip install git+https://github.com/YatingMusic/miditoolkit
```

## Example Usage

```python
Expand All @@ -61,6 +74,7 @@ print(midi_obj)
```

Output:

```
ticks per beat: 480
max tick: 72002
Expand All @@ -71,15 +85,14 @@ markers: 71
lyrics: False
instruments: 2
```

A. [Parse and create MIDI files](examples/parse_and_create_MIDI_files.ipynb)
B. [Piano-roll Manipulation](examples/pinoroll_manipulation.ipynb)


## Philosophy
* [pretty_midi](https://github.com/craffel/pretty-midi) can parse MIDI files and generate pianorolls in absolute timing (seconds).
* [pypianoroll](https://github.com/salu133445/pypianoroll) can parse MIDI files into pianorolls in symbolic timing (through beat resolution).
* [mido](https://github.com/mido/mido) processes MIDI files in the lower level such as messages and ports.

**Miditoolkit** is designed for handling MIDI in **symbolic timing** (ticks), which is the native format of MIDI timing. We keep the midi parser as simple as possible, and offer several important functions to complete the versatility. For example, piano-rolls, tick-to-second, chromagram, and etc.
* [mido](https://github.com/mido/mido) processes MIDI files in the lower level such as messages and ports, and is the backend pretty_midi and miditoolkit;
* [pretty_midi](https://github.com/craffel/pretty-midi) parses MIDI files and pianorolls in seconds time unit, plus has audio related features;
* [pypianoroll](https://github.com/salu133445/pypianoroll) parses MIDI files into pianorolls in ticks time unit.

To customize settings and maximum the degree of freedom, users can use additional libraries like visualization, which are excluded in the toolkit.
**Miditoolkit** is designed for handling MIDI in **[ticks](https://www.recordingblogs.com/wiki/midi-tick)**, the native time unit of the MIDI protocol. We keep the midi parser as simple as possible, and offer several important functions to complete the versatility. For example, piano-rolls, tick-to-second, chromagram, etc.

0 comments on commit 38cfa38

Please sign in to comment.