Performance Utility Tools

Some of the exercise packages include several utility and test programs. These are all standalone scripts using Python 3 and a few additional packages as described in System Requirements.

The following scripts may be browsed in the Python tools directory on the course site.

list-MIDI-ports.py

Command-line test program for identifying available MIDI ports by printing a list of the MIDI input and output ports available via python-rtmidi. There are no options, just running it will print a list of port names:

python3 list-MIDI-ports.py

The full code follows, but may also be downloaded from list-MIDI-ports.py.

#!/usr/bin/env python3

import rtmidi
midiout = rtmidi.MidiOut()
midiin = rtmidi.MidiIn()

print("Available output ports:")
for idx, port in enumerate(midiout.get_ports()):
    print("  %d: %s" % (idx, port))

print("Available input ports:")
for idx, port in enumerate(midiin.get_ports()):
    print("  %d: %s" % (idx, port))

virtual-mpd218.py

Emulation of an Akai MPD218 Drum Pad Controller, generating local MIDI events and control changes.

merge-MIDI-files.py

Sample script to merge a set of MIDI files. This is intended as a script template to be customized for your specific application. A typical use within the course is to merge a set of single-track type 0 MIDI files exported from Ableton Live into a multi-track type 1 file for playing back on the theater system.

To run it:

python3 merge-MIDI-files.py

The default script reads five MIDI files named channel1.mid, channel2.mid, etc. It updates the channel numbers for every event, then merges all the tracks into a multi-track MIDI files named performance.mid.

The most obvious customization is to edit the list of source files, although this script could be extended to use different channel numbers, adjust event timing, filter particular messages, or other algorithmic transformations. The details of the output can be reviewed using the print-MIDI-file.py script.

Note for Ableton users: Live does not include tempo information when exporting clips as type 0 MIDI files, it instead assumes 120 BPM when generating timing tick values. If you are using a different tempo, you may wish to edit the file_tempo_in_BPM variable so your show executes at the correct pace.

The full code follows, but may also be downloaded from merge-MIDI-files.py.

#!/usr/bin/env python3

# merge-MIDI-files.py

# Sample script to merge a set of MIDI files.  This is intended as a script
# template to be customized per application.

# Typical use: merge a set of single-track type 0 MIDI files exported from
# Ableton Live into a multi-track type 1 file.

import sys

# https://mido.readthedocs.io/en/latest/index.html
import mido

#================================================================
# Load an input file.
def load_midi_file(path):
    mid = mido.MidiFile(path)
    print(f"Opened MIDI file {path}: type {mid.type}")
    if mid.type != 0:
        print("Error: this script only supports type 0 (single-track) files.")
        sys.exit(1)
    print("  Track name: %s" % (mid.tracks[0].name))
    return mid

#================================================================
def extract_metadata_track(track):
    """Return a new track containing the metadata common to all tracks."""
    track0 = mido.MidiTrack()
    track0.name = 'metadata'
    for event in track:
        if event.is_meta:
            if event.type in ['time_signature', 'key_signature', 'smpte_offset', 'set_tempo']:
                track0.append(event)

    return track0

#================================================================
def filter_track(track, channel):
    """Process a track for merging, returning a new track.  Filters out
    particular metadata events.  Rewrites channel numbers for message events in
    the track."""

    result = mido.MidiTrack()
    for event in track:
        if event.is_meta:
            if event.type not in ['time_signature', 'key_signature', 'smpte_offset', 'set_tempo']:
                result.append(event)

        else:
            result.append(event.copy(channel=channel))
    return result

#================================================================
#================================================================
# Script execution begins here.

# Load the source files in channel order.
paths = ["channel1.mid", "channel2.mid", "channel3.mid", "channel4.mid", "channel5.mid"]
sources = [load_midi_file(path) for path in paths]

#----------------------------------------------------------------
# Use the first file to generate a metadata track.  Note: no check
# is made to ensure that the subsequent files match.
track0 = extract_metadata_track(sources[0].tracks[0])

# Note: Ableton Live does not include tempo information when exporting clips as
# type 0 MIDI files, it always assumes 120 BPM when generating timing tick
# values.  The following line can be modified to insert your preferred tempo.
file_tempo_in_BPM = 120
track0.append(mido.MetaMessage(type='set_tempo', tempo=mido.bpm2tempo(file_tempo_in_BPM), time=0))

#----------------------------------------------------------------
# Create a new output file to contain all the tracks as individual tracks.
output = mido.MidiFile()
output.ticks_per_beat = sources[0].ticks_per_beat

# Add the metadata track.
output.tracks.append(track0)

#----------------------------------------------------------------
# Process each track and append to the output file.
# Note that channel numbers for each track event are rewritten starting with
# MIDI channel 1 (denoted with zero).

for channel, src in enumerate(sources):
    track = src.tracks[0]
    processed = filter_track(track, channel)
    output.tracks.append(processed)

#----------------------------------------------------------------
# Save the result.
output_path = 'performance.mid'
print(f"Writing output to {output_path}.")
output.save(output_path)

# All done.

print-MIDI-file.py

Script to display all events in a MIDI file for review.

Example use:

python3 print-MIDI-file.py performance.mid

The full code follows, but may also be downloaded from print-MIDI-file.py.

#!/usr/bin/env python3

# print-MIDI-file.py : utility script to inspect the contents of a MIDI file

import argparse

# https://mido.readthedocs.io/en/latest/index.html
import mido

parser = argparse.ArgumentParser(description = "Read a MIDI file with mido and display all the messages.")
parser.add_argument('input', help='MIDI files to process.')
args = parser.parse_args()

mid = mido.MidiFile(args.input)
print(f"Opened MIDI file type {mid.type} from {args.input}")

print("Track list:")
for i, track in enumerate(mid.tracks):
    print(f'  Track {i} name: {track.name}')

print("Resolution: %d ticks per beat." % (mid.ticks_per_beat))

# assume a default 120 BPM tempo until overridden by a tempo MetaMessage
midi_tempo = 500000

for track in mid.tracks:
    print()
    print(f"Contents of track '{track.name}':")
    for msg in track:
        if msg.is_meta:
            print(repr(msg))

            if msg.type == 'set_tempo':
                print("--> Found tempo of %d usec/beat, %f BPM." % (msg.tempo, mido.tempo2bpm(msg.tempo)))
                midi_tempo = msg.tempo

        else:
            print("%s (%f seconds)" % (repr(msg), mido.tick2second(msg.time, mid.ticks_per_beat, midi_tempo)))

spline-plot.py

Script to play a multi-segment one-dimensional cubic Bezier spline as a plot of signal versus time. This is the underlying representation used by the motion and lighting trajectory generators.

Example use:

python3 spline-plot.py 0 0 180 180 180 45 90

In general, plotting N spline segments requires 3N+1 knot values. This example will plot a two-segment spline which begins at zero and ends at 90. The intermediate knot at 180 has smooth zero velocity; the final point ends positive velocity.

The full code may be downloaded from spline-plot.py.