MIDI Scripter (v0.4) Readme

Copyright (c) 2005 Emanuel Borsboom. All rights reserved.
Thanks to Philip Bennefall for the idea.

Table of Contents

1. Overview
2. Requirements and Setup
   1. Windows
   2. Other
3. Usage
4. Input Song File Format
   1. Basic Commands
   2. Advanced Commands
5. Constants
   1. Program Numbers
   2. Drum Notes
   3. Lengths
6. 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 (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/.

Usage

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

ruby MidiScripter.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 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 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.

• 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).

• 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

• 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.

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.