MIDIUtil

https://midiutil.readthedocs.io/en/latest/
Admin
MIDIUtil is a pure Python library for writing multi-track MIDI files with support for both format 1...
Tokens:14,953
Snippets:128
Trust Score:9.6
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install MIDIUtil from source

Source: https://midiutil.readthedocs.io/en/latest/index.html

Install MIDIUtil by running the setup script from the source code directory.

```bash
python setup.py install

```

--------------------------------

### Complete Tuning Example

Source: https://midiutil.readthedocs.io/en/latest/tuning.html

An example demonstrating how to set a custom tuning, bank, and program.

```APIDOC
## Complete Tuning Example

### Description
This example shows how to apply a custom tuning, including setting the tuning bank and program.

### Method
Multiple `MIDIFile` methods are used.

### Endpoint
N/A

### Parameters
* **track** (integer) - The track number.
* **channel** (integer) - The MIDI channel.
* **tuning** (list of tuples) - The custom tuning data.
* **program** (integer) - The tuning program number.
* **bank** (integer) - The tuning bank number.
* **time** (float) - The time at which to apply the tuning changes.

### Request Example
```python
track   = 0
channel = 0
tuning  = [(69, 500)] # Change MIDI note 69 to 500 Hz
program = 0
bank    = 0
time    = 0

MyMIDI.changeNoteTuning(track, tuning, tuningProgam=program)
MyMIDI.changeTuningBank(track, channel, time, bank) # may or may not be needed
MyMIDI.changeTuningProgram(track, channel, time, program) # ditto
```

### Response
#### Success Response (200)
This example demonstrates method calls and does not produce a direct response.

#### Response Example
None
```

--------------------------------

### Complete Tuning Example - midiutil

Source: https://midiutil.readthedocs.io/en/latest/tuning.html

A complete example demonstrating how to change a note's frequency, and then optionally set the tuning bank and program. This sequence is useful for instruments that require explicit tuning program and bank assignments.

```python
track   = 0
channel = 0
tuning  = [(69, 500)]
program = 0
bank    = 0
time    = 0
MyMIDI.changeNoteTuning(track, tuning, tuningProgam=program)
MyMIDI.changeTuningBank(track, channel, time, bank) # may or may not be needed
MyMIDI.changeTuningProgram(track, channel, time, program) # ditto
```

--------------------------------

### makeRPNCall Example

Source: https://midiutil.readthedocs.io/en/latest/class.html

An example demonstrating how to change a channel's tuning program using makeRPNCall. Note that a convenience function `changeTuningProgram` is also available.

```APIDOC
## makeRPNCall

### Description
This function is used to make a Registered Parameter Number (RPN) call, often for changing a channel's tuning program.

### Method
N/A (This is a function call within the library)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```python
makeRPNCall(track, channel, time, 0, 3, 0, program)
```

### Response
N/A
```

--------------------------------

### Configure MIDIFile Format

Source: https://midiutil.readthedocs.io/en/latest/creating.html

Example of initializing a MIDIFile with a specific format and adding events to it.

```python
MyMIDI = MIDIFile(1, file_format=1)
```

```python
track = 0
big_track = 1000
MyMIDI.addTempo(big_track, 0, 120)
MyMIDI.addNote(track, 0, 69, 0, 1, 100)
```

--------------------------------

### Install MIDIUtil using pip

Source: https://midiutil.readthedocs.io/en/latest/index.html

Install the latest stable version of MIDIUtil from the Python Package Index.

```bash
pip install MIDIUtil

```

--------------------------------

### Generate a Major Scale MIDI File

Source: https://midiutil.readthedocs.io/en/latest/index.html

This example demonstrates how to create a one-track MIDI file, set its tempo, add notes for a C-Major scale, and write it to disk. Ensure the midiutil package is imported.

```python
#!/usr/bin/env python

from midiutil import MIDIFile

degrees  = [60, 62, 64, 65, 67, 69, 71, 72] # MIDI note number
track    = 0
channel  = 0
time     = 0   # In beats
duration = 1   # In beats
tempo    = 60  # In BPM
volume   = 100 # 0-127, as per the MIDI standard

MyMIDI = MIDIFile(1) # One track, defaults to format 1 (tempo track
                     # automatically created)
MyMIDI.addTempo(track,time, tempo)

for pitch in degrees:
    MyMIDI.addNote(track, channel, pitch, time, duration, volume)
    time = time + 1

with open("major-scale.mid", "wb") as output_file:
    MyMIDI.writeFile(output_file)


```

--------------------------------

### Add Interleaved Notes

Source: https://midiutil.readthedocs.io/en/latest/creating.html

Example of adding notes that overlap in time, which may trigger deinterleaving logic depending on the MIDIFile configuration.

```python
time = 0
duration = 1
MyMIDI.addNote(track,channel,pitch,time,duration,volume)
time = 0.5
MyMIDI.addNote(track,channel,pitch,time,duration,volume)
```

--------------------------------

### MIDIFile.__init__

Source: https://midiutil.readthedocs.io/en/latest/class.html

Initializes a new MIDIFile object with specific track, format, and timing configurations.

```APIDOC
## MIDIFile.__init__

### Description
Initializes the MIDIFile class, which encapsulates a full, well-formed MIDI file object including header and track data.

### Parameters
#### Initialization Parameters
- **numTracks** (integer) - Optional - The number of tracks the file contains (default: 1).
- **removeDuplicates** (boolean) - Optional - If True, removes duplicate events before writing to disk (default: True).
- **deinterleave** (boolean) - Optional - If True, deinterleaves the notes in the stream (default: True).
- **adjust_origin** (boolean) - Optional - If True, shifts all events so the first event starts at t=0 (default: False).
- **file_format** (integer) - Optional - The format of the multi-track file, either 1 or 2 (default: 1).
- **ticks_per_quarternote** (integer) - Optional - The number of ticks per quarter note (division) (default: 960).
- **eventtime_is_ticks** (boolean) - Optional - If True, event time and duration are integer ticks instead of fractional quarter notes (default: False).
```

--------------------------------

### Initialize a MIDIFile object

Source: https://midiutil.readthedocs.io/en/latest/class.html

Create a new MIDIFile instance with a specified number of tracks.

```python
from midiutil.MidiFile import MIDIFile
midi_file = MIDIFile(1, adjust_origin=False)
```

--------------------------------

### Initialize MIDIFile Constructor

Source: https://midiutil.readthedocs.io/en/latest/creating.html

The signature of the MIDIFile __init__ method defining configuration parameters for the MIDI file.

```python
def __init__(self,
          numTracks=1,
          removeDuplicates=True,
          deinterleave=True,
          adjust_origin=False,
          file_format=1,
          ticks_per_quarternote=TICKSPERQUARTERNOTE,
          eventtime_is_ticks=False):
```

--------------------------------

### MIDIFile Object Initialization

Source: https://midiutil.readthedocs.io/en/latest/creating.html

Explains the parameters available when initializing a MIDIFile object.

```APIDOC
## MIDIFile Object Initialization

### Description
This section describes the parameters for creating a `MIDIFile` object, which is the first step in using the MIDIUtil library. Understanding these parameters is crucial as they affect the library's functionality.

### Method
`__init__`

### Endpoint
N/A (Class constructor)

### Parameters
#### Constructor Parameters
- **numTracks** (int) - Optional - Specifies the number of tracks the MIDI file should have. Defaults to 1.
- **removeDuplicates** (bool) - Optional - If True (default), duplicate notes and events are removed. If False, no duplicate removal is performed.
- **deinterleave** (bool) - Optional - If True (default), the library attempts to resolve interleaved note on/off events. If False, no shifting of events occurs.
- **adjust_origin** (bool) - Optional - If True, all events are shifted so the earliest event time is 0. Defaults to False.
- **file_format** (int) - Optional - Specifies the MIDI file format. Supports format 1 (default) and format 2.
- **ticks_per_quarternote** (int) - Optional - Defines the time resolution of the MIDI file. Defaults to 960.
- **eventtime_is_ticks** (bool) - Optional - If True, event times are interpreted as ticks; otherwise, they are interpreted as beats. Defaults to False.

### Request Example
```python
from midiutil import MIDIFile

# Example with default parameters
MyMIDI = MIDIFile()

# Example with custom parameters
MyMIDI = MIDIFile(numTracks=2, removeDuplicates=False, file_format=2, ticks_per_quarternote=480)
```

### Response
#### Success Response (Object Creation)
- **MIDIFile Object**: An instance of the MIDIFile class configured with the specified parameters.

#### Response Example
```python
# No direct response, but the object is created in memory
# MyMIDI is now a MIDIFile object
```
```

--------------------------------

### Import MIDIUtil constants

Source: https://midiutil.readthedocs.io/en/latest/class.html

Import symbolic constants for accidental types and musical modes.

```python
from midiutil.MidiFile import *
```

--------------------------------

### Change Tuning Program - midiutil

Source: https://midiutil.readthedocs.io/en/latest/tuning.html

Explicitly assign a tuning program for instruments like fluidsynth that require it. The specified tuning should have already been written using `changeNoteTuning`.

```python
MyMIDI.changeTuningProgram(track, channel, time, program)
```

--------------------------------

### changeNoteTuning

Source: https://midiutil.readthedocs.io/en/latest/class.html

Implements the 'real time single note tuning change' functionality. Note that not all hardware/software fully supports the MIDI tuning standard.

```APIDOC
## changeNoteTuning

### Description
Implements the 'real time single note tuning change' functionality. It allows for changing the frequency of specific MIDI notes. Not all hardware or software fully implements the MIDI tuning standard.

### Method
(Assumed to be a method of a MIDIFile object, e.g., `MyMIDI.changeNoteTuning(...)`)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **track** (int) - The track to which the data should be written.
- **tunings** (list of tuples) - A list of tuples, where each tuple is in (_note number_, _frequency_) format. Example: `[(69, 500)]`.
- **sysExChannel** (int, optional) - The SysEx channel of the event. Defaults to a standard value.
- **realTime** (bool, optional) - Specifies if the Universal SysEx event should be flagged as real-time. Defaults to `True`.
- **tuningProgram** (int, optional) - The tuning program number.

### Request Example
```python
from midiutil.MidiFile import MIDIFile
MyMIDI = MIDIFile(1)
tuning = [(69, 500)]
MyMIDI.changeNoteTuning(0, tuning, tuningProgram=0)
```

### Response
(This function modifies the MIDIFile object in place; no explicit return value is described for success.)

#### Success Response (200)
(No specific success response structure defined, implies in-place modification.)

#### Response Example
(N/A - function modifies object state)
```

--------------------------------

### MIDI File Format Information

Source: https://midiutil.readthedocs.io/en/latest/class.html

Explanation of MIDI file formats (1 and 2) and how they are handled by midiutil, including track indexing and tempo/time signature data.

```APIDOC
## MIDI File Formats

MIDI files can be created in format 1 or 2. 

### Format 1
In format 1 files, there is a separate tempo track which contains tempo and time signature data, but contains no note data. If one creates a single track format 1 file the actual file has two tracks – one for tempo data and one for note data. In the track indexing the tempo track can be ignored. In other words track 0 is the note track (the second track in the file). However, tempo and time signature data will be written to the first, tempo track. This is done to try and preserve as much interoperability with previous versions as possible.

### Format 2
In a format 2 file all tracks are indexed and the track parameter is interpreted literally.
```

--------------------------------

### changeNoteTuning

Source: https://midiutil.readthedocs.io/en/latest/class.html

Adds a real-time MIDI tuning standard update to a track.

```APIDOC
## changeNoteTuning

### Description
Add a real-time MIDI tuning standard update to a track.

### Parameters
- **track** (int) - Required - The track to which the tuning is applied.
- **tunings** (list) - Required - The tuning data.
- **sysExChannel** (int) - Optional - The SysEx channel.
- **realTime** (bool) - Optional - Sets the real-time flag.
- **tuningProgam** (int) - Optional - The tuning program ID.
```

--------------------------------

### Clone MIDIUtil from GitHub

Source: https://midiutil.readthedocs.io/en/latest/index.html

Clone the MIDIUtil source code repository from GitHub using either SSH or HTTPS.

```bash
git clone git@github.com:MarkCWirt/MIDIUtil.git

```

```bash
# or
git clone https://github.com/MarkCWirt/MIDIUtil.git

```

--------------------------------

### MIDIFile Class Methods

Source: https://midiutil.readthedocs.io/en/latest/genindex.html

Overview of the primary methods available in the MIDIFile class for constructing MIDI data.

```APIDOC
## MIDIFile Class Methods

### Description
The MIDIFile class provides methods to construct MIDI files by adding various events such as notes, tempo, and metadata.

### Methods
- **addNote()**: Adds a note event to the MIDI file.
- **addTempo()**: Adds a tempo event.
- **addKeySignature()**: Adds a key signature event.
- **addTimeSignature()**: Adds a time signature event.
- **addTrackName()**: Adds a track name event.
- **addCopyright()**: Adds a copyright notice.
- **addControllerEvent()**: Adds a MIDI controller event.
- **addPitchWheelEvent()**: Adds a pitch wheel event.
- **addProgramChange()**: Adds a program change event.
- **addSysEx()**: Adds a system exclusive message.
- **addUniversalSysEx()**: Adds a universal system exclusive message.
- **changeNoteTuning()**: Changes note tuning.
- **changeTuningBank()**: Changes the tuning bank.
- **changeTuningProgram()**: Changes the tuning program.
- **makeNRPNCall()**: Makes a Non-Registered Parameter Number call.
- **makeRPNCall()**: Makes a Registered Parameter Number call.
- **writeFile()**: Writes the constructed MIDI data to a file.
```

--------------------------------

### Change Channel Tuning Program with makeRPNCall

Source: https://midiutil.readthedocs.io/en/latest/class.html

Use this function to change a channel's tuning program. Note that a convenience function `changeTuningProgram` is also available for this purpose.

```python
makeRPNCall(track, channel, time, 0, 3, 0, program)
```

--------------------------------

### Write MIDI File to Disk

Source: https://midiutil.readthedocs.io/en/latest/common.html

Use `writeFile` to save the MIDI data to a file. Ensure the file is opened in binary write mode ('wb').

```python
with open("mymidifile.midi", 'wb') as output_file:
    MyMIDI.writeFile(output_file)
```

--------------------------------

### MIDIFile.writeFile

Source: https://midiutil.readthedocs.io/en/latest/common.html

Writes the MIDI data to a file handle opened for binary writing.

```APIDOC
## POST /midi/writeFile

### Description
Writes the MIDI data to a file handle opened for binary writing.

### Method
POST

### Endpoint
/midi/writeFile

### Parameters
#### Request Body
- **fileHandle** (file object) - Required - A file handle opened for binary writing.

### Request Example
```python
with open("mymidifile.midi", 'wb') as output_file:
    # Assuming MyMIDI is an instance of MIDIFile
    MyMIDI.writeFile(output_file)
```

### Response
#### Success Response (200)
- **message** (string) - Indicates the MIDI file was written successfully.

#### Response Example
```json
{
  "message": "MIDI file written successfully."
}
```
```

--------------------------------

### MIDIFile.changeNoteTuning

Source: https://midiutil.readthedocs.io/en/latest/tuning.html

Adds a real-time MIDI tuning standard update to a track. This function allows for custom note frequencies to be set.

```APIDOC
## MIDIFile.changeNoteTuning

### Description
Add a real-time MIDI tuning standard update to a track.

### Method
`MIDIFile.changeNoteTuning`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **track** (integer) - Required - The track to which the tuning is applied.
* **tunings** (list of tuples) - Required - A list of tuples representing the tuning, in (note number, frequency) format.
* **sysExChannel** (integer) - Optional - The SysEx channel of the event. Defaults to 127.
* **realTime** (boolean) - Optional - Specifies if the Universal SysEx event should be flagged as real-time or non-real-time. Defaults to True.
* **tuningProgram** (integer) - Optional - The tuning program number. Defaults to 0.

### Request Example
```python
from midiutil.MidiFile import MIDIFile
MyMIDI = MIDIFile(1)
tuning = [(69, 500)] # Change MIDI note 69 to 500 Hz
MyMIDI.changeNoteTuning(0, tuning, tuningProgam=0)
```

### Response
#### Success Response (200)
This method does not return a value, it modifies the MIDIFile object in place.

#### Response Example
None
```

--------------------------------

### Implement MIDIFile addTempo public accessor

Source: https://midiutil.readthedocs.io/en/latest/extending.html

Provides the public interface for adding tempo events to a MIDIFile, handling format-specific track routing and time conversion.

```python
def addTempo(self, track, time, tempo):
    """

    Add notes to the MIDIFile object

    :param track: The track to which the tempo event  is added. Note that
        in a format 1 file this parameter is ignored and the tempo is
        written to the tempo track
    :param time: The time (in beats) at which tempo event is placed
    :param tempo: The tempo, in Beats per Minute. [Integer]
    """
    if self.header.numeric_format == 1:
        track = 0
    self.tracks[track].addTempo(self.time_to_ticks(time), tempo,
                                insertion_order=self.event_counter)
    self.event_counter += 1
```

--------------------------------

### changeTuningProgram

Source: https://midiutil.readthedocs.io/en/latest/class.html

A convenience function to change the tuning program for a selected track. The actual tuning data should have been written previously using `changeNoteTuning`.

```APIDOC
## changeTuningProgram

### Description
Changes the tuning program for a selected track. This is a convenience function, as the same functionality can be achieved by directly sequencing controller events. The specified tuning must have already been written to the stream using `changeNoteTuning`.

### Method
(Assumed to be a method of a MIDIFile object, e.g., `MyMIDI.changeTuningProgram(...)`)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **track** (int) - The track to which the data should be written.
- **channel** (int) - The channel for the event.
- **time** (float or int) - The time of the event.
- **program** (int) - The tuning program number (0-127).
- **time_order** (bool, optional) - Preserve the ordering of the component events by ordering in time. Defaults to `False`.

### Request Example
```python
# Assuming MyMIDI is an instance of MIDIFile and tuning has been set
MyMIDI.changeTuningProgram(track=0, channel=0, time=0, program=1)
```

### Response
(This function modifies the MIDIFile object in place; no explicit return value is described for success.)

#### Success Response (200)
(No specific success response structure defined, implies in-place modification.)

#### Response Example
(N/A - function modifies object state)
```

--------------------------------

### MIDIFile.changeTuningProgram

Source: https://midiutil.readthedocs.io/en/latest/tuning.html

Changes the tuning program for a selected track. This is necessary for some instruments to apply the tuning changes.

```APIDOC
## MIDIFile.changeTuningProgram

### Description
Change the tuning program for a selected track.

### Method
`MIDIFile.changeTuningProgram`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **track** (integer) - Required - The track to which the data should be written.
* **channel** (integer) - Required - The channel for the event.
* **time** (float) - Required - The time of the event.
* **program** (integer) - Required - The tuning program number (0-127).
* **time_order** (boolean) - Optional - Preserve the ordering of the component events by ordering in time. Defaults to False.

### Request Example
```python
MyMIDI.changeTuningProgram(track, channel, time, program)
```

### Response
#### Success Response (200)
This method does not return a value, it modifies the MIDIFile object in place.

#### Response Example
None
```

--------------------------------

### Change Tuning Bank - midiutil

Source: https://midiutil.readthedocs.io/en/latest/tuning.html

Specify the tuning bank for a selected track. Fluidsynth assumes tunings are assigned to bank zero by default. The specified tuning should have already been written using `changeNoteTuning`.

```python
MyMIDI.changeTuningBank(track, channel, time, bank)
```

--------------------------------

### addProgramChange

Source: https://midiutil.readthedocs.io/en/latest/class.html

Adds a MIDI program change event.

```APIDOC
## POST /midiutil/addProgramChange

### Description
Adds a MIDI program change event.

### Method
POST

### Endpoint
/midiutil/addProgramChange

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **tracknum** (Integer) - Required - The zero-based track number to which program change event is added.
- **channel** (Integer) - Required - The MIDI channel to assign to the event. [0-15]
- **time** (Float) - Required - The time (in beats) at which the program change event is placed.
- **program** (Integer) - Required - The program number [0-127].

### Request Example
```json
{
  "tracknum": 0,
  "channel": 0,
  "time": 0.0,
  "program": 1
}
```

### Response
#### Success Response (200)
- **status** (String) - Indicates success.

#### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### addTempo

Source: https://midiutil.readthedocs.io/en/latest/class.html

Adds a tempo event to a MIDIFile object.

```APIDOC
## addTempo

### Description
Adds a tempo event to the MIDIFile object.

### Parameters
- **track** (int) - Required - The track to which the tempo event is added.
- **time** (float) - Required - The time (in beats) at which tempo event is placed.
- **tempo** (int) - Required - The tempo, in Beats per Minute.
```

--------------------------------

### MIDIFile.addTempo

Source: https://midiutil.readthedocs.io/en/latest/common.html

Adds a tempo event to a specified track at a given time.

```APIDOC
## POST /midi/addTempo

### Description
Adds a tempo event to a specified track at a given time.

### Method
POST

### Endpoint
/midi/addTempo

### Parameters
#### Request Body
- **track** (integer) - Required - The track to which the tempo event is added. Ignored for format 1 files.
- **time** (float) - Required - The time (in beats) at which the tempo event is placed.
- **tempo** (integer) - Required - The tempo in Beats per Minute.

### Request Example
```json
{
  "track": 0,
  "time": 0.0,
  "tempo": 120
}
```

### Response
#### Success Response (200)
- **message** (string) - Indicates successful addition of the tempo event.

#### Response Example
```json
{
  "message": "Tempo event added successfully."
}
```
```

--------------------------------

### Implement MIDITrack addTempo accessor

Source: https://midiutil.readthedocs.io/en/latest/extending.html

Adds a tempo change event to the MIDITrack event list.

```python
def addTempo(self, tick, tempo, insertion_order=0):
    '''
    Add a tempo change (or set) event.
    '''
    self.eventList.append(Tempo(tick, tempo,
                          insertion_order=insertion_order))
```

--------------------------------

### Add Program Change Event

Source: https://midiutil.readthedocs.io/en/latest/common.html

Use `addProgramChange` to specify the instrument for a track. Note that program numbers are zero-indexed in this library, unlike some musician-centric documentation.

```python
track   = 0
channel = 0
time    = 8 # Eight beats into the composition
program = 42 # A Cello

MyMIDI.addProgramChange(track, channel, time, program)
```

--------------------------------

### time_order Parameter Explanation

Source: https://midiutil.readthedocs.io/en/latest/class.html

Details on the `time_order` parameter, which serves as a workaround for sequencers that may not preserve the order of MIDI events.

```APIDOC
## time_order Parameter

### Description
The `time_order` parameter is a workaround for sequencers that might not maintain the original order of MIDI events. When set to `True`, successive events are slightly offset in time to ensure correct ordering, particularly for events like controller settings preceding data bytes.

### Method
N/A

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
N/A
```

--------------------------------

### writeFile Function

Source: https://midiutil.readthedocs.io/en/latest/class.html

Documentation for the `writeFile` function, which is used to write MIDI data to a file.

```APIDOC
## writeFile

### Description
Writes the MIDI File to a specified file handle.

### Method
N/A (This is a function call within the library)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```python
writeFile(_fileHandle_)
```

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### Change Note Tuning - midiutil

Source: https://midiutil.readthedocs.io/en/latest/tuning.html

Use this function to add a real-time MIDI tuning standard update to a track. The `tunings` argument is a list of tuples in (note number, frequency) format. Note that not all hardware or software fully implements the MIDI tuning standard.

```python
from midiutil.MidiFile import MIDIFile
MyMIDI = MIDIFile(1)
tuning = [(69, 500)]
MyMIDI.changeNoteTuning(0, tuning, tuningProgam=0)
```

--------------------------------

### MIDIFile.addProgramChange

Source: https://midiutil.readthedocs.io/en/latest/common.html

Adds a MIDI program change event to a track.

```APIDOC
## POST /midi/addProgramChange

### Description
Adds a MIDI program change event to a track, specifying the instrument voice.

### Method
POST

### Endpoint
/midi/addProgramChange

### Parameters
#### Request Body
- **tracknum** (integer) - Required - The zero-based track number.
- **channel** (integer) - Required - The MIDI channel to assign to the event. [0-15]
- **time** (float) - Required - The time (in beats) at which the program change event is placed.
- **program** (integer) - Required - The program number (instrument) to set. [0-127]

### Request Example
```json
{
  "tracknum": 0,
  "channel": 0,
  "time": 8.0,
  "program": 42
}
```

### Response
#### Success Response (200)
- **message** (string) - Indicates successful addition of the program change event.

#### Response Example
```json
{
  "message": "Program change event added successfully."
}
```
```

--------------------------------

### addCopyright

Source: https://midiutil.readthedocs.io/en/latest/class.html

Adds a copyright notice to the MIDIFile object.

```APIDOC
## POST /midiutil/addCopyright

### Description
Adds a copyright notice to the MIDIFile object.

### Method
POST

### Endpoint
/midiutil/addCopyright

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **track** (Integer) - Required - The track to which the notice is added.
- **time** (Float) - Required - The time (in beats) at which notice event is placed. In general this should be time t=0.
- **notice** (String) - Required - The copyright notice.

### Request Example
```json
{
  "track": 0,
  "time": 0.0,
  "notice": "Copyright (c) 2023 Example Corp."
}
```

### Response
#### Success Response (200)
- **status** (String) - Indicates success.

#### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### addNote

Source: https://midiutil.readthedocs.io/en/latest/class.html

Adds notes to the MIDIFile object.

```APIDOC
## POST /midiutil/addNote

### Description
Adds notes to the MIDIFile object.

### Method
POST

### Endpoint
/midiutil/addNote

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **track** (Integer) - Required - The track to which the note is added.
- **channel** (Integer) - Required - The MIDI channel to assign to the note. [0-15]
- **pitch** (Integer) - Required - The MIDI pitch number [0-127].
- **time** (Float or Integer) - Required - The time at which the note sounds. Can be quarter notes (Float) or ticks (Integer).
- **duration** (Float or Integer) - Required - The duration of the note. Can be quarter notes (Float) or ticks (Integer).
- **volume** (Integer) - Required - The volume (velocity) of the note [0-127].
- **annotation** (Any) - Optional - Arbitrary data to attach to the note.

### Request Example
```json
{
  "track": 0,
  "channel": 0,
  "pitch": 60,
  "time": 0.0,
  "duration": 1.0,
  "volume": 100,
  "annotation": "My first note"
}
```

### Response
#### Success Response (200)
- **status** (String) - Indicates success.

#### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### addText

Source: https://midiutil.readthedocs.io/en/latest/class.html

Adds a text event to a MIDI track.

```APIDOC
## addText

### Description
Add a text event to a specific track.

### Parameters
- **track** (int) - Required - The track to which the notice is added.
- **time** (float) - Required - The time (in beats) at which text event is placed.
- **text** (string) - Required - The text to add.
```

--------------------------------

### RPN and NRPN Controllers

Source: https://midiutil.readthedocs.io/en/latest/class.html

Explanation of how RPN and NRPN controllers are used to extend the number of available MIDI controllers for parameter editing.

```APIDOC
## RPN and NRPN Controllers

### Description
Registered Parameter Numbers (RPN) and Non-Registered Parameter Numbers (NRPN) extend MIDI controller capabilities. They are used to send parameter data to synthesizers for editing sound patches. RPNs are standardized by MIDI associations, while NRPNs are manufacturer-specific.

### Method
N/A

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
N/A
```

--------------------------------

### addUniversalSysEx

Source: https://midiutil.readthedocs.io/en/latest/class.html

Adds a Universal System Exclusive event.

```APIDOC
## addUniversalSysEx

### Description
Add a Universal System Exclusive event.

### Parameters
- **track** (int) - Required - The track to which the event should be written.
- **time** (float) - Required - The time of the event, in beats.
- **code** (int) - Required - The event code.
- **subcode** (int) - Required - The event sub-code.
- **payload** (binary) - Required - The payload for the event.
- **sysExChannel** (int) - Optional - The SysEx channel.
- **realTime** (bool) - Optional - Sets the real-time flag.
- **manID** (int) - Optional - The manufacturer ID for the event.
```

--------------------------------

### addSysEx

Source: https://midiutil.readthedocs.io/en/latest/class.html

Adds a System Exclusive event.

```APIDOC
## POST /midiutil/addSysEx

### Description
Adds a System Exclusive event.

### Method
POST

### Endpoint
/midiutil/addSysEx

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **track** (Integer) - Required - The track to which the event should be written.
- **time** (Float) - Required - The time of the event.
- **manID** (Integer) - Required - The manufacturer ID for the event.
- **payload** (String) - Required - The payload for the event. This should be a binary-packed value, and will vary for each type and function.

### Request Example
```json
{
  "track": 0,
  "time": 0.0,
  "manID": 123,
  "payload": "0F7"
}
```

### Response
#### Success Response (200)
- **status** (String) - Indicates success.

#### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### Add a key signature

Source: https://midiutil.readthedocs.io/en/latest/class.html

Add a key signature to a specific track using imported constants.

```python
MyMIDI.addKeySignature(0, 0, 3, SHARPS, MINOR)
```

--------------------------------

### Add Tempo to MIDI Track

Source: https://midiutil.readthedocs.io/en/latest/common.html

Use `addTempo` to set the tempo for a specific track at a given time. The tempo is specified in beats per minute (BPM).

```python
track = 0
time  = 0   # beats, beginning of track
tempo = 120 # BPM
MyMIDI.addTempo(track, time, tempo)
```

--------------------------------

### MIDIFile.addTrackName

Source: https://midiutil.readthedocs.io/en/latest/common.html

Assigns a name to a specified track.

```APIDOC
## POST /midi/addTrackName

### Description
Assigns a name to a specified track.

### Method
POST

### Endpoint
/midi/addTrackName

### Parameters
#### Request Body
- **track** (integer) - Required - The track to which the name is assigned.
- **time** (float) - Required - The time (in beats) at which the track name event is placed (typically 0).
- **trackName** (string) - Required - The name to assign to the track.

### Request Example
```json
{
  "track": 0,
  "time": 0.0,
  "trackName": "Bassline 1"
}
```

### Response
#### Success Response (200)
- **message** (string) - Indicates successful assignment of the track name.

#### Response Example
```json
{
  "message": "Track name assigned successfully."
}
```
```

--------------------------------

### MIDIFile.addNote

Source: https://midiutil.readthedocs.io/en/latest/common.html

Adds a note to the MIDIFile object with specified parameters.

```APIDOC
## POST /midi/addNote

### Description
Adds a note to the MIDIFile object.

### Method
POST

### Endpoint
/midi/addNote

### Parameters
#### Request Body
- **track** (integer) - Required - The track to which the note is added.
- **channel** (integer) - Required - The MIDI channel to assign to the note. [0-15]
- **pitch** (integer) - Required - The MIDI pitch number. [0-127]
- **time** (float or integer) - Required - The time at which the note sounds (in quarter notes or ticks).
- **duration** (float or integer) - Required - The duration of the note (in quarter notes or ticks).
- **volume** (integer) - Required - The volume (velocity) of the note. [0-127]
- **annotation** (any) - Optional - Arbitrary data to attach to the note.

### Request Example
```json
{
  "track": 0,
  "channel": 0,
  "pitch": 60,
  "time": 0.0,
  "duration": 1.0,
  "volume": 100,
  "annotation": null
}
```

### Response
#### Success Response (200)
- **message** (string) - Indicates successful addition of the note.

#### Response Example
```json
{
  "message": "Note added successfully."
}
```
```

--------------------------------

### Add Notes to MIDI File

Source: https://midiutil.readthedocs.io/en/latest/common.html

Use `addNote` to add musical notes to a MIDI track. Specify track, channel, pitch, time, duration, and volume. The `annotation` parameter can hold arbitrary data.

```python
track    = 0   # Track numbers are zero-origined
channel  = 0   # MIDI channel number
pitch    = 60  # MIDI note number
time     = 0   # In beats
duration = 1   # In beats
volume   = 100 # 0-127, 127 being full volume

MyMIDI.addNote(track,channel,pitch,time,duration,volume)
time  = 1
pitch = 61
MyMIDI.addNote(track,channel,pitch,time,duration,volume)
```

--------------------------------

### addTrackName

Source: https://midiutil.readthedocs.io/en/latest/class.html

Assigns a name to a MIDI track.

```APIDOC
## addTrackName

### Description
Name a track.

### Parameters
- **track** (int) - Required - The track to which the name is assigned.
- **time** (float) - Required - The time (in beats) at which the track name event is placed.
- **trackName** (string) - Required - The name to assign to the track.
```

--------------------------------

### changeTuningBank

Source: https://midiutil.readthedocs.io/en/latest/class.html

A convenience function to change the tuning bank for a selected track. The actual tuning data should have been written previously using `changeNoteTuning`.

```APIDOC
## changeTuningBank

### Description
Changes the tuning bank for a selected track. This is a convenience function, as the same functionality can be achieved by directly sequencing controller events. The specified tuning must have already been written to the stream using `changeNoteTuning`.

### Method
(Assumed to be a method of a MIDIFile object, e.g., `MyMIDI.changeTuningBank(...)`)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **track** (int) - The track to which the data should be written.
- **channel** (int) - The channel for the event.
- **time** (float or int) - The time of the event.
- **bank** (int) - The tuning bank number (0-127).
- **time_order** (bool, optional) - Preserve the ordering of the component events by ordering in time. Defaults to `False`.

### Request Example
```python
# Assuming MyMIDI is an instance of MIDIFile and tuning has been set
MyMIDI.changeTuningBank(track=0, channel=0, time=0, bank=1)
```

### Response
(This function modifies the MIDIFile object in place; no explicit return value is described for success.)

#### Success Response (200)
(No specific success response structure defined, implies in-place modification.)

#### Response Example
(N/A - function modifies object state)
```

--------------------------------

### MIDIFile.changeTuningBank

Source: https://midiutil.readthedocs.io/en/latest/tuning.html

Changes the tuning bank for a selected track. This is used in conjunction with tuning programs.

```APIDOC
## MIDIFile.changeTuningBank

### Description
Change the tuning bank for a selected track.

### Method
`MIDIFile.changeTuningBank`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **track** (integer) - Required - The track to which the data should be written.
* **channel** (integer) - Required - The channel for the event.
* **time** (float) - Required - The time of the event.
* **bank** (integer) - Required - The tuning bank (0-127).
* **time_order** (boolean) - Optional - Preserve the ordering of the component events by ordering in time. Defaults to False.

### Request Example
```python
MyMIDI.changeTuningBank(track, channel, time, bank)
```

### Response
#### Success Response (200)
This method does not return a value, it modifies the MIDIFile object in place.

#### Response Example
None
```

--------------------------------

### addTimeSignature

Source: https://midiutil.readthedocs.io/en/latest/class.html

Adds a time signature event to a MIDI track.

```APIDOC
## addTimeSignature

### Description
Add a time signature event.

### Parameters
- **track** (int) - Required - The track to which the signature is assigned.
- **time** (float) - Required - The time (in beats) at which the event is placed.
- **numerator** (int) - Required - The numerator of the time signature.
- **denominator** (int) - Required - The denominator of the time signature, expressed as a power of two.
- **clocks_per_tick** (int) - Required - The number of MIDI clock ticks per metronome click.
- **notes_per_quarter** (int) - Optional - The number of annotated 32nd notes in a MIDI quarter note (default 8).
```

--------------------------------

### eventtime_is_ticks Configuration

Source: https://midiutil.readthedocs.io/en/latest/creating.html

Controls how event times are interpreted. When True, times are in ticks; when False, times are in quarter-notes.

```APIDOC
## eventtime_is_ticks

### Description
If set to `True`, all times passed into the event creation functions should be specified in ticks. Otherwise they should be specified in quarter-notes (the default).

### Method
Configuration Setting

### Endpoint
N/A (Internal Library Setting)

### Parameters
#### Query Parameters
- **eventtime_is_ticks** (boolean) - Required - Set to `True` to use ticks for time, `False` for quarter-notes.
```

--------------------------------

### Assign Name to MIDI Track

Source: https://midiutil.readthedocs.io/en/latest/common.html

Use `addTrackName` to assign a name to a MIDI track. The name is typically set at time 0, the beginning of the track.

```python
track      = 0
time       = 0
track_name = "Bassline 1"
MyMIDI.addTrackName(track, time, track_name)
```

--------------------------------

### Tempo Event Class Implementation

Source: https://midiutil.readthedocs.io/en/latest/extending.html

Subclass of GenericEvent to represent a MIDI tempo event. It handles tempo conversion, serialization, and equality checks. Use this as a template for custom event types.

```python
class Tempo(GenericEvent):
    '''
    A class that encapsulates a tempo meta-event
    '''
    evtname = 'Tempo'
    sec_sort_order = 3

    def __init__(self, tick, tempo, insertion_order=0):
        self.tempo = int(60000000 / tempo)
        super(Tempo, self).__init__(tick, insertion_order)

    def __eq__(self, other):
        return (self.evtname == other.evtname and
                self.tick == other.tick and
                self.tempo == other.tempo)

    __hash__ = GenericEvent.__hash__

    def serialize(self, previous_event_tick):
        """Return a bytestring representation of the event, in the format required for
        writing into a standard midi file.
        """

        midibytes = b""
        code = 0xFF
        subcode = 0x51
        fourbite = struct.pack('>L', self.tempo)  # big-endian uint32
        threebite = fourbite[1:4]  # Just discard the MSB
        varTime = writeVarLength(self.tick - previous_event_tick)
        for timeByte in varTime:
            midibytes += struct.pack('>B', timeByte)
        midibytes += struct.pack('>B', code)
        midibytes += struct.pack('>B', subcode)
        midibytes += struct.pack('>B', 0x03)  # length in bytes of 24-bit tempo
        midibytes += threebite
        return midibytes

```

--------------------------------

### addKeySignature

Source: https://midiutil.readthedocs.io/en/latest/class.html

Adds a Key Signature to a track.

```APIDOC
## POST /midiutil/addKeySignature

### Description
Adds a Key Signature to a track.

### Method
POST

### Endpoint
/midiutil/addKeySignature

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **track** (Integer) - Required - The track to which this should be added.
- **time** (Float) - Required - The time at which the signature should be placed.
- **accidentals** (Integer) - Required - The number of accidentals in the key signature.
- **accidental_type** (String) - Required - The type of accidental (e.g., 'SHARPS', 'FLATS').
- **mode** (String) - Required - The mode of the scale (e.g., 'MAJOR', 'MINOR').
- **insertion_order** (Integer) - Optional - The insertion order of the key signature. Defaults to 0.

### Request Example
```json
{
  "track": 0,
  "time": 0.0,
  "accidentals": 3,
  "accidental_type": "SHARPS",
  "mode": "MINOR"
}
```

### Response
#### Success Response (200)
- **status** (String) - Indicates success.

#### Response Example
```json
{
  "status": "success"
}
```
```
Tokens:
Raw