# Time-stamp: "2002-11-16 02:11:47 MST"
require 5;
package MIDI;
use strict;
use vars qw($Debug $VERSION %number2note %note2number %number2patch
%patch2number %notenum2percussion %percussion2notenum);
use MIDI::Opus;
use MIDI::Track;
use MIDI::Event;
use MIDI::Score;
# Doesn't use MIDI::Simple -- but MIDI::Simple uses this
$Debug = 0; # currently doesn't do anything
$VERSION = 0.80;
# MIDI.pm doesn't do much other than 1) 'use' all the necessary submodules
# 2) provide some publicly useful hashes, 3) house a few private routines
# common to the MIDI::* modules, and 4) contain POD, glorious POD.
=head1 NAME
MIDI - read, compose, modify, and write MIDI files
=head1 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');
=head1 DESCRIPTION
This suite of modules provides routines for reading, composing, modifying,
and writing MIDI files.
From FOLDOC (C):
=over
B
Emultimedia, file formatE (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. [...]
=back
=head1 COMPONENTS
The MIDI-Perl suite consists of these modules:
L (which you're looking at), L, L,
L, L, and
L. All of these contain documentation in pod format.
You should read all of these pods.
The order you want to read them in will depend on what you want to do
with this suite of modules: if you are focused on manipulating the
guts of existing MIDI files, read the pods in the order given above.
But if you aim to compose music with this suite, read this pod, then
L and L, and then skim the rest.
(For your reference, there is also a document in pod format which is
not itself an actual module: L. It is an old version
of the MIDI file specification.)
=head1 INTRODUCTION
This suite of modules is basically object-oriented, with the exception
of MIDI::Simple. 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 L).
Furthermore, for some purposes it's useful to analyze the totality of
a track's events as a "score" -- where a score consists of notes where
each event is a list consisting of a command, a time offset from the
start of the track, and some number of parameters. This is the level
of abstraction that MIDI::Score and MIDI::Simple deal with.
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.
=head1 TO DO
Maybe have a MIDI cookbook of commonly used short scripts?
B: Currently this suite can only read/write MIDI data from/to
MIDI I. 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 (C, C,
C, or whatever). However, I have no such MIDI devices
(much less ports) at hand for development and testing. But if I
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.
=head1 GOODIES
The bare module MIDI.pm doesn't I much more than C