/ 
MIDI-Perl-0.52
River stage two • 16 direct dependents • 24 total dependents
/ MIDI

NAME

MIDI -- read, compose, modify, and write MIDI files.

SYNOPSIS

use MIDI;
$chimes_track = MIDI::Track->new({ 'events' => [
 ['text_event',0, 'www.ely.anglican.org/parishes/camgsm/chimes.html'],
 ['text_event',0, 'Lord through this hour/ be Thou our guide'],
 ['text_event',0, 'so, by Thy power/ no foot shall slide'],
 ['text_event',0, '(coded at ' . scalar(localtime) . ' )'],
 ['patch_change', 0, 1, 8], # Patch 8 = Celesta
 map( (['note_on',0,1,$_->[0],96], ['note_off',$_->[1],1,$_->[0],0]),
      [25,96],[29,96],[27,96],[20,192],[25,96],[27,96],[29,96],[25,192],
      [29,96],[25,96],[27,96],[20,192],[20,96],[27,96],[29,96],[25,192],
    )# [Note,Duration] ==> ['note_on',0,1, N ,96], ['note_off', D ,1, N ,0]
] });
$chimes = MIDI::Opus->new(
 { 'format' => 0, 'ticks' => 96, 'tracks' => [ $chimes_track ] } );
$chimes->write_to_file('chimes.mid');

DESCRIPTION

This suite of modules provides routines for reading, composing, modifying, and writing MIDI files.

From FOLDOC (http://wombat.doc.ic.ac.uk/foldoc/):

    MIDI, Musical Instrument Digital Interface

    <multimedia, file format> (MIDI /mi'-dee/, /mee'-dee/) A hardware specification and protocol used to communicate note and effect information between synthesisers, computers, music keyboards, controllers and other electronic music devices. [...]

    The basic unit of information is a "note on/off" event which includes a note number (pitch) and key velocity (loudness). There are many other message types for events such as pitch bend, patch changes and synthesizer-specific events for loading new patches etc.

    There is a file format for expressing MIDI data which is like a dump of data sent over a MIDI port. [...]

COMPONENTS

The MIDI suite consists of these modules:

MIDI (which you're looking at), MIDI::Opus, MIDI::Track, and MIDI::Event. All of these contain documentation in pod format. You should read all these pods.

For your reference, there is also a document in pod format which is not itself an actual module: MIDI::Filespec. It is an old version of the MIDI file specification.

INTRODUCTION

This suite of modules is basically object-oriented. MIDI opuses ("songs") are represented as objects belonging to the class MIDI::Opus. An opus contains tracks, which are objects belonging to the class MIDI::Track. A track will generally contain a list of events, where each event is a list consisting of a command, a delta-time, and some number of parameters. In other words, opuses and tracks are objects, and the events in a track comprise a LoL (and if you don't know what an LoL is, you must read perllol).

While this suite does provide some functionality accessible only if you're comfortable with various kinds of references, and while there are some options that deal with the guts of MIDI encoding, you can (I hope) get along just fine with just a basic grasp of the MIDI "standard", and a command of LoLs. I have tried, at various points in this documentation, to point out what things are not likely to be of use to the casual user.

TO DO

Hopefully provide much better documentation in a later release of this module.

Maybe have a MIDI cookbook of commonly used short scripts?

Have a more abstract level of abstraction than MIDI events, such that 1) notes are represented as a single event, instead of each a pair of a note_on event and a note_off event; and 2) events are represented as having a given time-offset from start-of-track, instead of this fishy delta-time business, which is not exactly prime for composition. Actually, I'm currently working on this -- expect it to show up as another attribute of a track object, maybe $track->score, beside $track->events, and stored similarly to the events LoL.

Have modules carp/croak instead of warn/die.

Have more modules "use strict".

A PLEA: Currently this suite can only read/write MIDI data from/to MIDI files. However, it would be desirable to have realtime access to a MIDI device -- at least on systems where a MIDI device (whether thru a hardware port or as a virtual sequencer in a sound card) is accessable as a virtual file (/dev/midi0, /dev/midi, /dev/sequencer, or whatever). However, I have no such MIDI devices (much less ports) at hand for development and testing. But if you have such devices (I'm thinking a Linuxer with a synth hooked to their MIDI port), and if you want to help me experiment with directly accessing them from Perl, then please email me. I already have a pretty good idea of how it should work -- but as always, the proof is as much in the pudding as the devil is in the details.

GOODIES

The bare module MIDI.pm doesn't do much more than use the component submodules. But it does provide some hashes you might find useful:

%MIDI::note2number and %MIDI::number2note

%MIDI::note2number correponds MIDI note numbers to a more comprehensible representation (e.g., 68 to 'G#4'); %MIDI::number2note is the reverse. Have a look at the source to see the contents of the hash.

%MIDI::patch2number and %MIDI::number2patch

%MIDI::patch2number correponds General MIDI patch numbers (0 to 127) to English names (e.g., 79 to 'Ocarina'); %MIDI::number2patch is the reverse. Have a look at the source to see the contents of the hash.

%MIDI::notenum2percussion and %MIDI::percussion2notenum

%MIDI::notenum2percussion correponds General MIDI Percussion Keys to English names (e.g., 56 to 'Cowbell') -- but note that only numbers 35 to 81 (inclusive) are defined; %MIDI::percussion2notenum is the reverse. Have a look at the source to see the contents of the hash.

BRIEF GLOSSARY

This glossary defines just a few terms, just enough so you can (hopefully) make some sense of the documentation for this suite of modules. If you're going to do anything serious with these modules, however, you should really invest in a good book about the MIDI standard -- see the References.

channel: a logical channel to which control changes and patch changes apply, and in which MIDI (note-related) events occur.

control: one of the various numeric parameters associated with a given channel. Like S registers in Hayes-set modems, MIDI controls consist of a few well-known registers, and beyond that, it's patch-specific and/or sequencer-specific.

delta time: the time (in ticks) that a sequencer should wait between playing the previous event and playing the current event.

meta-event: any of a mixed bag of events whose common trait is merely that they are similarly encoded. Most meta-events apply to all channels, unlike events, which mostly apply to just one channel.

opus: the term I prefer for a piece of music, as represented in MIDI. Most specs use the term "song", but I think that this falsely implies that MIDI files represent vocal pieces.

patch: an electronic model of the sound of a given notional instrument.

running status: a form of modest compression where an event lacking an event command byte (a "status" byte) is to be interpreted as having the same event command as the preceding event -- which may, in turn, lack a status byte and may have to be interpreted as having the same event command as its previous event, and so on back.

song: what some MIDI specs call a song, I call an opus.

sequencer: a device or program that interprets and acts on MIDI data. This prototypically refers to synthesizers or drum machines, but can also refer to more limited devices, such as mixers or even lighting control systems.

status: a synonym for "event".

sysex: a chunk of binary data encapsulated in the MIDI data stream, for whatever purpose.

text event: any of the several meta-events (one of which is actually called 'text_event') that conveys text. Most often used to just label tracks, note the instruments used for a track, or to provide metainformation about copyright, performer, and piece title and author.

tick: the timing unit in a MIDI opus.

variable-length encoding: an encoding method identical to what Perl calls the 'w' (BER, Basic Encoding Rules) pack/unpack format for integers.

REFERENCES

Christian Braut. The Musician's Guide to Midi. ISBN 0782112854.

I'll keep a list of other references and good stuff at the URL http://alf8.speech.cs.cmu.edu/~sburke/pub/perl_midi/

AUTHOR

Sean M. Burke sburke@netadventure.net