MIDI Scripter (v0.5.0) ReadmeMIDI Scripter (v0.5.0) Readme

Home Page: http://www.epiphyte.ca/code/midi_scripter.html

Table of ContentsTable of Contents

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

OverviewOverview

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 SetupRequirements 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 (and will run in command-line mode without 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/.

UsageUsage

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

Otherwise, run MidiScripter.rb. For example, type "ruby MidiScipter.rb" 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. Note that while the MIDI player is running, MIDI Scripter will be unresponsive until you exit it.

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 (and wxRuby is not required). For example:

ruby MidiScripter.rb example.song example.mid

By default, the input files are run in safe mode, which prevents them from accessing your system. If you want the input file to be able to access your system, you can run the program in unsafe mode by adding the --unsafe command-line argument. For example:

ruby MidiScripter.rb --unsafe

ruby MidiScripter.rb --unsafe example.song example.mid

Warning: this will allow the input file to do things like erase your hard drive or send e-mails, so only use it for songs from people you trust!

Input Song File FormatInput Song File Format

Each input song file is, in fact, a Ruby (www.ruby-lang.org) 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. Value between 0 and 127. See the General MIDI program numbers table below for a list of pre-defined constants that you can 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.
transpose semitones
Transposes subsequent notes by the specified number of semitones. You can use, for example, transpose F3-C3, to transpose everything up 5 semitones (the difference between F3 and C3). A value of 0 means no transpose.
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 C4 (middle-C), Bf3 (B-flat an octave below middle-C), or Cs5 (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 General MIDI drum notes table below for a list of pre-defined constants that you can 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.
drum note, Velocity => velocity
drum note, Length => length, Velocity => velocity
Plays a drum note and over-rides the default velocity.
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
note_off [note, note, ..., note]
note_off note, Velocity => velocity
note_off [note, note, ..., note], Velocity => velocity
End note(s).
bank bank-number
bank bank-number, fine-bank-number
Set the bank number, to access more programs/drums.
start_porta speed do ... end
Portamento effect. The commands between do and end are played with portamento. The only commands that may appear within are note and speed. speed changes the speed of the portamento affect. The speed is specified in number of semitones per beat.

Note: This portamento is implemented using the pitch wheel control. In order for it to sound correct, your MIDI device must support the pitch wheel bend range registered parameter (most do, but if it doesn't, it won't sound right). This does not use the MIDI portamento effect, because it works on so few devices.
pitch amount
Sets the pitch wheel control. The amount is a floating point value between -1.0 and +1.0. By default, -1.0 means pitch is adjusted down two semitones, +1.0 means the pitch is adjusted up two semitones, and 0 means there is no adjustment. The range can be changed using the pitch_range command.
pitch_range range
Sets the range of the pitch wheel in semitones.
pitch_bend start-amount end-amount length
Sweeps the pitch wheel from start-amount to end-amount, taking length beats to do so.
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 do ... end
Start a track without loading a file. The track is everything between the do and the following end. May be nested. The track's timeline begins where the start_track occurrs.
start_track Channel => channel do ... end
Start a track, specifying the default channel it will use.
disable_midi_tracks
enable_midi_tracks
Disable or enable whether subsequent tracks will have their own MIDI sequence tracks.
event event
Add a Midilib event object to the track. See http://midilib.rubyforge.org/ for the events, and http://www.borg.com/~jglatt/tech/midispec.htm for explanation of their meaning. 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.

ConstantsConstants

General MIDI Program Numbers

	#PIANO                           
Acoustic_Grand = 0
Bright_Acoustic = 1
Electric_Grand = 2
Honky_Tonk = 3
Electric_Piano_1 = 4
Electric_Piano_2 = 5
Harpsichord = 6
Clavinet = 7
	#CHROMATIC PERCUSSION
Celesta = 8
Glockenspiel = 9
Music_Box = 10
Vibraphone = 11
Marimba = 12
Xylophone = 13
Tubular_Bells = 14
Dulcimer = 15
	#ORGAN                          
Drawbar_Organ = 16
Percussive_Organ = 17
Rock_Organ = 18
Church_Organ = 19
Reed_Organ = 20
Accoridan = 21
Harmonica = 22
Tango_Accordian = 23
	#GUITAR
Nylon_String_Guitar = 24
Steel_String_Guitar = 25
Electric_Jazz_Guitar = 26
Electric_Clean_Guitar = 27
Electric_Muted_Guitar = 28
Overdriven_Guitar = 29
Distortion_Guitar = 30
Guitar_Harmonics = 31
	#BASS
Acoustic_Bass = 32
Electric_Bass_Finger = 33
Electric_Bass_Pick = 34
Fretless_Bass = 35
Slap_Bass_1 = 36
Slap_Bass_2 = 37
Synth_Bass_1 = 38
Synth_Bass_2 = 39
	#SOLO_STRINGS
Violin = 40
Viola = 41
Cello = 42
Contrabass = 43
Tremolo_Strings = 44
Pizzicato_Strings = 45
Orchestral_Strings = 46
Timpani = 47
	#ENSEMBLE
String_Ensemble_1 = 48
String_Ensemble_2 = 49
SynthStrings_1 = 50
SynthStrings_2 = 51
Choir_Aahs = 52
Voice_Oohs = 53
Synth_Voice = 54
Orchestra_Hit = 55
	#BRASS
Trumpet = 56
Trombone = 57
Tuba = 58
Muted_Trumpet = 59
French_Horn = 60
Brass_Section = 61
SynthBrass_1 = 62
SynthBrass_2 = 63
	#REED
Soprano_Sax = 64
Alto_Sax = 65
Tenor_Sax = 66
Baritone_Sax = 67
Oboe = 68
English_Horn = 69
Bassoon = 70
Clarinet = 71
	#PIPE
Piccolo = 72
Flute = 73
Recorder = 74
Pan_Flute = 75
Blown_Bottle = 76
Skakuhachi = 77
Whistle = 78
Ocarina = 79
	#SYNTH_LEAD
Lead_1= 80
Lead_2 = 81
Lead_3 = 82
Lead_4 = 83
Lead_5 = 84
Lead_6 = 85
Lead_7 = 86
Lead_8 = 87
	#SYNTH_PAD
Pad_1 = 88
Pad_2 = 89
Pad_3 = 90
Pad_4 = 91
Pad_5 = 92
Pad_6 = 93
Pad_7 = 94
Pad_8 = 95
	#SYNTH_EFFECTS
FX_1 = 96
FX_2 = 97
FX_3 = 98
FX_4 = 99
FX_5 = 100
FX_6 = 101
FX_7 = 102
FX_8 = 103
	#ETHNIC
Sitar = 104
Banjo = 105
Shamisen = 106
Koto = 107
Kalimba = 108
Bagpipe = 109
Fiddle = 110
Shanai = 111
	#PERCUSSIVE
Tinkle_Bell = 112
Agogo = 113
Steel_Drums = 114
Woodblock = 115
Taiko_Drum = 116
Melodic_Tom = 117
Synth_Drum = 118
Reverse_Cymbal = 119
	#SOUND_EFFECTS
Guitar_Fret_Noise = 120
Breath_Noise = 121
Seashore = 122
Bird_Tweet = 123
Telephone_Ring = 124
Helicopter = 125
Applause = 126
Gunshot = 127

General MIDI 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

ExamplesExamples

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

LicenseLicense

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.