Metadata-Version: 2.1
Name: miditoolkit
Version: 0.1.17
Home-page: https://github.com/YatingMusic/miditoolkit
Author: wayne391
Author-email: s101062219@gmail.com
License: MIT
Keywords: music midi mir
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Topic :: Multimedia :: Sound/Audio :: MIDI
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.7.0
Requires-Dist: mido>=1.1.16
Requires-Dist: matplotlib

# miditoolkit

A python package for working with MIDI data. 

* Version: 0.1.17
* Latest update date: 2023/10/31

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.

## Main Features
* MIDI
    * Global
        * ticks per beat
        * tempo changes
        * key signatures
        * time signatures
        * lyrics
        * markers
    * Instruments
        * control changes
        * pitch bend
    * Editing
        * chunk/cropping
    * IO
        * BytesIO
* Piano-rolls    
    * Tools
        * notes to piano-rolls
        * piano-rolls to notes
        * chromagram
    * Visualization
* External Library
   * [structure analysis](https://github.com/wayne391/sf_segmenter)
   
## TODO
* better documentation
* absolute timing
* cropping: Control Changes
* cropping: bars
* symbolic features
* new structural analysis

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

## Example Usage

```python
import miditoolkit
path_midi = miditoolkit.midi.utils.example_midi_file()
midi_obj = miditoolkit.midi.parser.MidiFile(path_midi)
print(midi_obj)

"""
Output:

ticks per beat: 480
max tick: 72002
tempo changes: 68
time sig: 2
key sig: 0
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.

To customize settings and maximum the degree of freedom, users can use additional libraries like visualization, which are excluded in the toolkit. 


