MIDI File Generator (v0.3) Readme

Overview
Requirements and Setup
1. Windows
2. Other
Usage
Input Song File Format
1. Basic Commands
2. Advanced Commands
Constants
Examples

Overview

This program generates a MIDI file from simple commands in text files. It was specifically created for someone who is visually impaired, so it is intended to be accessible to anyone.

Requirements and Setup

The first thing to do is unzip the distribution you downloaded (whether binary or source). Then, follow the platform-specific instructions below.

Windows

The easiest way to setup the program on Windows requires no installation at all. If you downloaded the win32 binary zip file, just unzip it and you're done.

If for some reason you don't want to use the binary, you must install the Ruby interpreter and the wxRuby library. The easiest way to do that is to use the "One-Click Ruby Installer" at http://rubyforge.org/frs/download.php/2407/ruby182-14.exe, and then the "wxRuby One Click Installer" at http://rubyforge.org/frs/download.php/1984/wxruby-0.6.0-mswin.exe.

Other

This program should run on any platform that supports Ruby and wxWidgets. It has been tested with Ruby 1.8.2, wxWidgets 2.4.2, and wxRuby 0.6.0. First, you must install Ruby, which you can download from http://ruby-lang.org/. Then, install wxRuby, which you can download from http://wxruby.rubyforge.org/. wxRuby requires wxWidgets, which is available at http://wxwidgets.org/.

Usage

To start the program on Windows (if you are using the win32 binary package), simply run MidiFileGenerator.exe (for example, by double clicking on it in Windows Explorer).

Otherwise, run MidiFileGenerator.rbw. For example, type "ruby MidiFileGenerator.rbw" on the command-line.

Once it's running, it's a snap to use - just select your input file, then your output file, and then click "Generate MIDI File". If you want to listen to the MIDI file immediately after generating it, click "Generate and Play" instead.

For playing the MIDI file to work, you must have your MIDI player configured correctly. The default should work if you are running Windows and have Windows Media Player installed.

You can also specify the input and output files on the command-line, in which case the GUI is skipped. For example:

ruby MidiFileGenerator.rbw example.song example.mid

Input Song File Format

Each input song file is, in fact, a Ruby program. It is interpreted in an environment that has a bunch of simple commands defined for generating a MIDI sequence. The input is divided into tracks. Each track has an independent timeline. Most commands affect only the current track, but there are some commands that affect all tracks. Each track is normally stored in a separate file, and the main input file specifies where to load them. Comments are started with # and continue until the end of the line. You may use any valid Ruby expression in the file. Commands are case sensitive!

Basic Commands

tempo <bpm>
Specifies the tempo in beats per minute (BPM). The default is 120. This is a global value (it affects all tracks).
load_track "<filename>"
Load a track from the given filename. The track's timeline begins at the time that load_track occurrs. May be nested. The filename can be absolute, or relative to the current file.
load_track "<filename>", Channel => <channel>
Load a track from the given filename and sets the default channel.
channel <channel number>
The MIDI channel to use for MIDI events. Each instrument should be on its own channel, but multiple tracks may use the same channel Channel 1 is the first channel. Note: Channel 10 is reserved for the drum track. You should use the constant Drum_Channel in place of the number 10.
program <program number>
Set the MIDI program (patch) number controller. Use this to set the instrument on the channel. See the program numbers table below for a list of pre-defined constants that should use.
volume <volume>
Specifies the channel's volume. Value may be between 0 and 127.
velocity <velocity>
Specifies the default note velocity (how hard the note is hit, so how loud it is). Value may be between 1 and 127.
pan <pan>
Sets the pan position of the channel. Number between 0 and 127. 0=left, 127=right, 64=center
reverb <reverb>
Sets the reverb of the channel. Number between 0 and 127. 0=no reverb, 127=maximum reverb
chorus <chorus>
Sets the chrous of the channel. Number between 0 and 127. 0=no chorus, 127=maximum chorus
note <note>, <length>
Plays a note. <note> is a MIDI note number. You should use constants like C3 (middle-C), Bf2 (B-flat an octave below middle-C), or Cs4 (C-sharp an octave above middle-C) for this. These constants range from Af0 to Gs7. <length> is the duration in number of beats. This can be specified as a number (where 1.0 is one beat), or using one of the constants in the lengths table below. The next command will take affect after the note has completed.
note [<note>, <note>, ..., <note>], <length>
Plays multiple notes at the same time.
note <note>, <length>, Velocity => <velocity>
note [<note>, <note>, ..., <note>], <length>, Velocity => <velocity>
Plays note(s) and over-rides the default velocity.
drum <note>
Plays a drum note. This should only be used on channel 10. See the drum notes table below fot a list of pre-defined constants that you should use. The next command takes affect at the same time as the drum.
drum <note>, Length => <length>
Some drum instruments work like other instruments and can have a duration, and this version of the command allows you to specify it. The next command takes affect after the drum note has completed.
rest <length>
Rest for the specified duration. This does nothing, but the next command will take affect after the duration.

Advanced Commands

note_on <note>
note_on [<note>, <note>, ..., <note>]
note_on <note>, Velocity => <velocity>
note_on [<note>, <note>, ..., <note>], Velocity => <velocity>
Start note(s). The note(s) will play until the a note_off command with the same note number is encountered. This has no duration, so the next command take affect immediately.
note_off <note-number>
note_off [<note>, <note>, ..., <note>]
note_off <note>, Velocity => <velocity>
note_off [<note>, <note>, ..., <note>], Velocity => <velocity>
End note(s).
rewind <length>
Rewinds the time line. The opposite of rest. Specified in beats.
time <time>
Sets the track's timeline to an absolute time value from the beginning of the song. Specified in beats. 0.0 is the beginning of the song.
start_track
Start a track without loading a file. The track is everything between the start_track and the following end_track. May be nested. The track's timeline begins where the start_track occurrs.
start_track Channel => <channel>
Start a track, specifying the default channel it will use
end_track
End the current track
event <event>
Add a Midilib event object to the track. See http://midilib.rubyforge.org/ for the events. The delta_time of the event is ignored, and the timeline of the track is used instead. Use the event_channel function to get the channel number to use in the event.
control_event <event>
Add a Midilib event object to the control track.

Constants

Program Numbers

#PIANO                           
Acoustic_Grand = 1
Bright_Acoustic = 2
Electric_Grand = 3
Honky_Tonk = 4
Electric_Piano_1 = 5
Electric_Piano_2 = 6
Harpsichord = 7
Clavinet = 8

#CHROMATIC PERCUSSION
Celesta = 9
Glockenspiel = 10
Music_Box = 11
Vibraphone = 12
Marimba = 13
Xylophone = 14
Tubular_Bells = 15
Dulcimer = 16

#ORGAN                          
Drawbar_Organ = 17
Percussive_Organ = 18
Rock_Organ = 19
Church_Organ = 20
Reed_Organ = 21
Accoridan = 22
Harmonica = 23
Tango_Accordian = 24

#GUITAR
Nylon_String_Guitar = 25
Steel_String_Guitar = 26
Electric_Jazz_Guitar = 27
Electric_Clean_Guitar = 28
Electric_Muted_Guitar = 29
Overdriven_Guitar = 30
Distortion_Guitar = 31
Guitar_Harmonics = 32

#BASS
Acoustic_Bass = 33
Electric_Bass_Finger = 34
Electric_Bass_Pick = 35
Fretless_Bass = 36
Slap_Bass_1 = 37
Slap_Bass_2 = 38
Synth_Bass_1 = 39
Synth_Bass_2 = 40

#SOLO_STRINGS
Violin = 41
Viola = 42
Cello = 43
Contrabass = 44
Tremolo_Strings = 45
Pizzicato_Strings = 46
Orchestral_Strings = 47
Timpani = 48

#ENSEMBLE
String_Ensemble_1 = 49
String_Ensemble_2 = 50
SynthStrings_1 = 51
SynthStrings_2 = 52
Choir_Aahs = 53
Voice_Oohs = 54
Synth_Voice = 55
Orchestra_Hit = 56

#BRASS
Trumpet = 57
Trombone = 58
Tuba = 59
Muted_Trumpet = 60
French_Horn = 61
Brass_Section = 62
SynthBrass_1 = 63
SynthBrass_2 = 64

#REED
Soprano_Sax = 65
Alto_Sax = 66
Tenor_Sax = 67
Baritone_Sax = 68
Oboe = 69
English_Horn = 70
Bassoon = 71
Clarinet = 72

#PIPE
Piccolo = 73
Flute = 74
Recorder = 75
Pan_Flute = 76
Blown_Bottle = 77
Skakuhachi = 78
Whistle = 79
Ocarina = 80

#SYNTH_LEAD
Lead_1= 81
Lead_2 = 82
Lead_3 = 83
Lead_4 = 84
Lead_5 = 85
Lead_6 = 86
Lead_7 = 87
Lead_8 = 88

#SYNTH_PAD
Pad_1 = 89
Pad_2 = 90
Pad_3 = 91
Pad_4 = 92
Pad_5 = 93
Pad_6 = 94
Pad_7 = 95
Pad_8 = 96

#SYNTH_EFFECTS
FX_1 = 97
FX_2 = 98
FX_3 = 99
FX_4 = 100
FX_5 = 101
FX_6 = 102
FX_7 = 103
FX_8 = 104

#ETHNIC
Sitar = 105
Banjo = 106
Shamisen = 107
Koto = 108
Kalimba = 109
Bagpipe = 110
Fiddle = 111
Shanai = 112

#PERCUSSIVE
Tinkle_Bell = 113
Agogo = 114
Steel_Drums = 115
Woodblock = 116
Taiko_Drum = 117
Melodic_Tom = 118
Synth_Drum = 119
Reverse_Cymbal = 120

#SOUND_EFFECTS
Guitar_Fret_Noise = 121
Breath_Noise = 122
Seashore = 123
Bird_Tweet = 124
Telephone_Ring = 125
Helicopter = 126
Applause = 127
Gunshot = 128

Drum Notes

Acoustic_Bass_Drum = 35
Bass_Drum_1 = 36
Side_Stick = 37
Acoustic_Snare = 38
Hand_Clap = 39
Electric_Snare = 40
Low_Floor_Tom = 41
Closed_Hi_Hat = 42
High_Floor_Tom = 43
Pedal_Hi_Hat = 44
Low_Tom = 45
Open_Hi_Hat = 46
Low_Mid_Tom = 47
Hi_Mid_Tom = 48
Crash_Cymbal_1 = 49
High_Tom = 50
Ride_Cymbal_1 = 51
Chinese_Cymbal = 52
Ride_Bell = 53
Tambourine = 54
Splash_Cymbal = 55
Cowbell = 56
Crash_Cymbal_2 = 57
Vibraslap = 58
Ride_Cymbal_2 = 59
Hi_Bongo = 60
Low_Bongo = 61
Mute_Hi_Conga = 62
Open_Hi_Conga = 63
Low_Conga = 64
High_Timbale = 65
Low_Timbale = 66
High_Agogo = 67
Low_Agogo = 68
Cabasa = 69
Maracas = 70
Short_Whistle = 71
Long_Whistle = 72
Short_Guiro = 73
Long_Guiro = 74
Claves = 75
Hi_Wood_Block = 76
Low_Wood_Block = 77
Mute_Cuica = 78
Open_Cuica = 79
Mute_Triangle = 80
Open_Triangle = 81

Lengths

Whole
Half
Quarter
Eighth
Sixteenth
Thirtysecond
Sixtyfourth
Dotted_Whole
Dotted_Half
Dotted_Quarter
Dotted_Eighth
Dotted_Sixteenth
Dotted_Thirtysecond
Dotted_Sixtyfourth
Whole_Triplet
Half_Triplet
Quarter_Triplet
Eighth_Triplet
Sixteenth_Triplet
Thirtysecond_Triplet
Sixtyfourth_Triplet
Dotted_Whole_Triplet
Dotted_Half_Triplet
Dotted_Quarter_Triplet
Dotted_Eighth_Triplet
Dotted_Sixteenth_Triplet
Dotted_Thirtysecond_Triplet
Dotted_Sixtyfourth_Triplet

Examples

See the file example.song, and the files which it loads: melody.track, chords.track, and drums.track.