MIDI Scripter (v0.5.0) ReadmeMIDI Scripter (v0.5.0) Readme
Copyright © 2005 Emanuel Borsboom
Thanks to Philip Bennefall for the idea.
Home Page: http://www.epiphyte.ca/code/midi_scripter.html
Table of ContentsTable of Contents
- Requirements and Setup
- Input Song File Format
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.
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.
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/.
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).
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!
Specifies the tempo in beats per minute (BPM). The default is 120. This is a global value (it affects all tracks).
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.
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_Channelin place of the number 10.
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.
Specifies the channel's volume. Value may be between 0 and 127.
Specifies the default note velocity (how hard the note is hit, so how loud it is). Value may be between 1 and 127.
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.
Sets the pan position of the channel. Number between 0 and 127. 0=left, 127=right, 64=center
Sets the reverb of the channel. Number between 0 and 127. 0=no reverb, 127=maximum reverb
Sets the chrous of the channel. Number between 0 and 127. 0=no chorus, 127=maximum chorus
note note, length
Plays a note.
noteis a MIDI note number. You should use constants like
Bf3(B-flat an octave below middle-C), or
Cs5(C-sharp an octave above middle-C) for this. These constants range from
lengthis 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.
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 for the specified duration. This does nothing, but the next command will take affect after the duration.
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, ..., note]
note_off note, Velocity => velocity
note_off [note, note, ..., note], Velocity => velocity
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
endare played with portamento. The only commands that may appear within are
speedchanges 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.
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
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.
Rewinds the time line. The opposite of rest. Specified in beats.
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
doand the following
end. May be nested. The track's timeline begins where the
start_track Channel => channel do ... end
Start a track, specifying the default channel it will use.
Disable or enable whether subsequent tracks will have their own MIDI sequence tracks.
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.
Add a Midilib event object to the control track.
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
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
See the file example.song, and the files which it loads: melody.track, chords.track, and drums.track.
Copyright © 2005 Emanuel Borsboom
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.