Subsections


Low Level MIDI Commands

The commands discussed in this chapter directly effect your MIDI output devices.

Not all MIDI devices are equal. Many of the effects in this chapter may be ignored by your devices. Sorry, but that's just the way MIDI is.


Channel

As noted in Tracks and Channels MMA assigns MIDI channels dynamically as it creates tracks. In most cases this works fine; however, you can if you wish force the assignment of a specific MIDI channel to a track with the CHANNEL command.

You cannot assign a channel number to a track if it already defined (well, see the section CHSHARE, below, for the inevitable exception), nor can you change the channel assignments for any of the DRUM tracks.

Let us assume that you want the Bass track assigned to MIDI channel 8. Simply use:

Bass Channel 8

Caution: If the selected channel is already in use an error will be generated. Due to the way MMA allocates tracks, if you really need to manually assign track it is recommended that you do this in a MMARC file.

You can disable a channel at any time by using a channel number of 0:

Arpeggio-1 Channel 0

will disable the Arpeggio-1 channel, freeing it for use by other tracks. A warning message is generated. Disabling a track without a valid channel is fine. When you set a channel to 0 the track is also disabled. You can restart the track with the ON command (here).

You don't need to have a valid MIDI channel assigned to a track to do things like: MIDIPAN, MIDIGLIS, MIDIVOLUME or even the assignment of any music to a track. MIDI data is created in tracks and then sent out to the MIDI buffers. Channel assignment is checked and allocated at this point, and an error will be generated if no channels are available.

It's quite acceptable to do channel reassignments in the middle of a song. Just assign channel 0 to the unneeded track first.

MIDI channel settings are not saved in GROOVEs.

MMA inserts a MIDI ``track name'' meta event when the channel buffers are first assigned at a MIDI offset of 0. If the MIDI channel is reassigned, a new ``track name'' is inserted at the current song offset.

A more general method is to use CHANNELPREF detailed below.

You can access the currently assigned channel with the $_TRACK_CHANNEL macro.

ChannelPref

If you prefer to have certain tracks assigned to certain channels you can use the CHANNELPREF command to create a custom set of preferences. By default, MMA assigns channels starting at 16 and working down to 1 (with the expectation of drum tracks which are all assigned channel 10). If, for example, you would like the Bass track to be on channel 9, sustained bass on channel 3, and Arpeggio on channel 5, you can have a command like:

ChannelPref Bass=9 Arpeggio=5 Bass-Sus=3

Most likely this will be in your MMARC file.

You can use multiple command lines, or have multiple assignments on a single line. Just make sure that each item consists of a trackname, an ``='' and a channel number in the range 1 to 16.

If a channel has already been assigned this command will probably be ignored. It should be used before any MIDI data is generated.


ChShare

MMA is fairly conservative in its use of MIDI tracks. ``Out of the box'' it demands a separate MIDI channel for each of its tracks, but only as they are actually used. In most cases, this works just fine.

However, there are times when you might need more tracks than the available MIDI channels or you may want to free up some channels for other programs.

If you have different tracks with the same voicing, it's quite simple. For example, you might have an arpeggio and scale track:

Arpeggio Sequence A16 z
Arpeggio Voice Piano1
Scale Sequence z S8
Scale Voice Piano1

In this example, MMA will use different MIDI channels for the Arpeggio and the Scale. Now, if you force channel sharing:

Scale ChShare Arpeggio

both tracks will use the same MIDI channel.

This is really foolproof in the above example, especially since the same voice is being used for both. Now, what if you wanted to use a different voice for the tracks?

Arpeggio Sequence A16 z
Arpeggio Voice Piano1 Strings
Scale Sequence z S8
Scale ChShare Arpeggio

You might think that this would work, but it doesn't. MMA ignores voice changes for bars which don't have a sequence, so it will set ``Piano1'' for the first bar, then ``Strings'' for the second (so far, so good). But, when it does the third bar (an ARPEGGIO) it will not know that the voice has been changed to ``Strings'' by the Scale track.

So, the general rule for track channel sharing is to use only one voice.

One more example which doesn't work:

Arpeggio Sequence A8
Scale Sequence S4
Arpeggio Voice Piano1
Scale Voice Piano1
Scale ChShare Arpeggio

This example has an active scale and arpeggio sequence in each bar. Since both use the same voice, you may think that it will work just fine ... but it may not. The problem here is that MMA will generate MIDI on and off events which may overlap each other. One or the other will be truncated. If you are using a different octave, it will work much better. It may sound okay, but you should probably find a better way to do this.

When a CHSHARE directive is parsed the ``shared'' channel is first checked to ensure that it has been assigned. If not currently assigned, the assignment is first done. What this means is that you are subverting MMA 's normal dynamic channel allocation scheme. This may cause is a depletion of available channels.

Please note that that the use of the CHSHARE command is probably never really needed, so it might have more problems than outlined here. If you want to see how much a bother channel sharing becomes, have a look at the standard library file frenchwaltz.mma. All this so the accordion bass can use one channel instead of 6. If I were to write it again I'd just let it suck up the MIDI channels.

For another, simpler, way of reassigning MIDI tracks and letting MMA do most of the work for you, refer to the DELETE command.

ChannelInit

In order to properly configure a MIDI device, it is often convenient to send arbitrary commands to selected tracks before any musical data is played. One way to do this in MMA is with the MIDI command. One problem with using MIDI is that you really don't know track assignments until after the compilation is completed ... so you end up sending data to the meta track and effect all the tracks in your file.

The CHANNELINIT command delays any action until the specified MIDI channel is assigned to a track. A simple example is to set the drum set pan:

ChannelInit Channels=10 MidiPan 20

In this case we know that all the drum channels are assigned to channel 10. When the first note data is written to any of the drum tracks, the MIDIPAN command is inserted. The action is only preformed one time.

The author likes to set all channels, with the exception of the keyboard channel 1, to a volume of 80.

ChannelInit channels=2-16 MidiVolume m

If the CHANNELS option is not specified all channels (1-16) will be effected.

The command will be processed only when the channel is assigned to a track ... if the channel is not used the data is discarded.

The CHANNELS option takes a list of channels, each with a single comma separator (3,4,5) and/or a range separated by a single hyphen (2-6). Duplicate channels are ignored.

ForceOut

Under normal conditions MMA only generates the MIDI tracks it thinks are valid or relevant. So, if you create a track but insert no note data into that track it will not be generated. An easy way to verify this is by creating file and running MMA with the -c command line option. Lets start off by creating a file you might think will set the keyboard channel on your synth to a TenorSax voice:

Begin Solo-Keyboard
  Channel 1
  Voice TenorSax
  MIDIVolume 100
End

If you test this you should get:

$ mma test -c
  
File 'test' parsed, but no MIDI file produced!
 
Tracks allocated:
 SOLO-KEYBOARD
 
Channel assignments:
1 SOLO-KEYBOARD

So, a MMA track will be created. But if you compile this file and examine the resulting MIDI file you will find that the voice has not been set.24.1

To overcome this, insert the FORCEOUT command at the end of the track setup.

For example, here is a more complete file which will set the keyboard track (MIDI channel 1) to TenorSax with a volume of 100, play a bar of accompaniment, set a Trumpet voice with a louder volume, play another bar, and finally reset the keyboard to the default Piano voice. A cool way to program your keyboard for different voicing changes so you can have more fun doing play-a-longs.

Groove BossaNova
 
Begin Solo
  Channel 1
  Voice TenorSax
  MIDIVolume 100
  ForceOut
End
 
1 C
 
Begin Solo
  Voice Trumpet
  MIDIVolume 120
  ForceOut
End
 
2 G
 
Begin Solo
  Voice Piano1
  MIDIVolume 127
  ForceOut
End

Note: The same or similar results could be accomplished with the MIDI command; however, it's a bit harder to use and the commands would be in the Meta track.


MIDI

The complete set of MIDI commands is not limitless--but from this end it seems that adding commands to suit every possible configuration is never-ending. So, in an attempt to satisfy everyone, a command which will place any arbitrary MIDI stream in your tracks has been implemented. In most cases this will be a MIDI ``Sysex'' or ``Meta'' event.

For example, you might want to start a song off with a MIDI reset:

MIDI 0xF0 0x05 0x7e 0x7f 0x09 0x01 0xf7

The values passed to the MIDI command are normal integers; however, they must all be in the range of 0x00 to 0xff. In most cases it is easiest to use hexadecimal numbers by using the ``0x'' prefix. But, you can use plain decimal integers if you prefer.

In the above example:

  0xF0
Designates a SYSEX message

  0x05
The length of the message

  0x7e
... The actual message

Another example places the key signature of F major (1 flat) in the meta track:24.2

MIDI 0xff 0x59 0x02 0xff 0x00

Some cautions:

Cautions aside, includes/init.mma has been included in this distribution. I use this without apparent problems; to use it add the command line:

MMAstart init

in your MMARC file. The file is pretty well commented and it sets a synth up to something reasonably sane.

If you need a brief delay after a raw MIDI command, it is possible to insert a silent beat with the BEATADJUST command. See the file includes/reset.mma for an example.


MIDIClear

As noted earlier in this manual you should be very careful in programming MIDI sequences into your song and/or library files. Doing damage to a synthesizer is probably a remote possibility ... but leaving it in a unexpected mode is likely. For this reason the MIDICLEAR command has been added as a companion to the MIDIVOICE and MIDISEQ commands.

Each time a MIDI track (not necessary the same as a MMA track) is ended or a new GROOVE is started, a check is done to see if any MIDI data has been inserted in the track with a MIDIVOICE or MIDISEQ command. If it has, a further check is done to see if there is an ``undo'' sequence defined via a MIDICLEAR command. That data is then sent; or, if data has not be defined for the track, a warning message is displayed.

The MIDICLEAR command uses the same syntax as MIDIVOICE and MIDISEQ; however, you cannot specify different sequence for different bars in the sequence:

Bass-Funky MIDIClear 1 Modulation 0; 1 ReleaseTime 0

As in MIDIVOICE and MIDISEQ you can include sequences defined in a MIDIDEF (see below). The <beat>offsets are required, but ignored.


MIDICue

MIDI files can contain ``cue points'' to be used as pointers to sections of the file. In MMA you can insert these in the meta-track:

MidiCue Begin slow portion of song

or in a specified track:

Chord MidiCue Chords get louder here

Not all MIDI sequencers or editors recognize this event.

The text for this command is queued until the track is created. If the specified track is never created the text is discarded.


MIDICopyright

Inserting a copyright message into a MIDI file may be a good idea, and it's simple enough to do.

MidiCopyright (C) Bob van der Poel 2044

will insert the message ``(C)..'' as the first item in the first track of the generated file.24.3You can have any number of MIDICOPYRIGHT messages in your file. They will be inserted sequentially at the head of the file. Command placement in your input file has no effect on the positioning.


MIDIDef

To make it easier to create long sets of commands for MIDISEQ and MIDICLEAR you can create special macros. Each definition consists of a symbolic name, a beat offset, a controller name and a value. For example:

MIDIdef Rel1 1 ReleaseTime 50; 3 ReleaseTime 0

creates a definition called ``Rel1'' with two controller events. The controller names can be a single value or a permitted symbolic name (here).

You can have multiple controller events. Just list them with ``;'' delimiters.


MIDICresc and MIDIDecresc

Much like the CRESC and DECRESC (here) commands, these commands change volume over a set number of bars. However, unlike the previously mentioned commands, these commands utilize the MIDI Channel Volume settings (here) or, if used in a non-track area, the MIDI device's master volume.

The two commands are identical, with the exception that MIDICRESC prints a warning if the second argument is smaller than the first and MIDIDECRESC prints a warning if the second argument is larger than the first.

For tracks, the first two arguments are MIDI values in the range 0 to 127. The third argument is the number of bars to apply the command over. MMA distributes the needed values evenly over the bar range. MMA assumes that your song will be long enough for the specifed bar count; if the song is too short you will end up with volume settings past the end of the song (the MIDI file will be expanded for this).

To change the MIDI channel volume of the Bass track over three and a half bars:

Bass MidiCresc 50 100 3.5

The volume arguments for this command can also be set using the standard volume mnemonics ``m'', ``p'', etc. (see here).

For example:

Chord MidiDecresc mf pp 2

When used in a non-track area the values for volumes range from 0 to 1638324.4 and can be set as a value or via the standard ``m'', ``mp'', etc. mnemonics.

MMA keeps track of channel settings, so you can skip the initial volume:

Bass MidiCresc ffff 1

For non-track usage the volume range is from 0 to 16383. In addition, the command takes an optional STEP setting. By default a step rate of ``10'' is used, but this might be too course or fine for your song. Setting a larger value will generate fewer commands. MMA tracks the master volume so the initial setting is optional (it is assumed to be set to the maximum value at startup). Examples:

MidiCresc mp mf 3

MidiDecresc p 2 Step=5

Please read the discussion for MIDIVOLUME (here) for more details.


MIDIFile

This option controls some fine points of the generated MIDI file. The command is issued with a series of parameters in the form ``MODE=VALUE''. You can have multiple settings in a single MIDIFILE command.

MMA can generate two types of SMF (Standard MIDI Files):

0.
This file contains only one track into which the data for all the different channel tracks has been merged. A number of synths which accept SMF (Casio, Yamaha and others) only accept type 0 files.

1.
This file has the data for each MIDI channel in its own track. This is the default file generated by MMA .

You can set the filetype in an RC file (or, for that matter, in any file processed by MMA ) with the command:

MidiFile SMF=0

or

MidiFile SMF=1

You can also set it on the command line with the -M option. Using the command line option will override the MIDISMF command if it is in a RC file.

By default MMA uses ``running status'' when generating MIDI files. This can be disabled with the command:

MidiFile Running=0

or enabled (but this is the default) with:

MidiFile Running=1

Files generated without running status will be about 20 to 30% larger than their compressed counterparts. They may be useful for use with brain-dead sequencers and in debugging generated code. There is no command line equivalent for this option.

MIDIGlis

This sets the MIDI portamento24.5 (in case you're new to all this, portamento is like glissando between notes--wonderful, if you like trombones! To enable portamento:

Arpeggio MIDIGlis 30

The parameter can be any value between 1 and 127. To turn the sliding off:

Arpeggio MIDIGlis 0

This command will work with any track (including drum tracks). However, the results may be somewhat ``interesting'' or ``disappointing'', and many MIDI devices don't support portamento at all. So, be cautious. The data generated is not sent into the MIDI stream until musical data is created for the relevant MIDI channel.

MIDIWheel

Many MIDI synths have a nice little knob or wheel on one side which is used to adjust the pitch.24.6 The effect is known as ``pitch bend''.

When a MIDI controller is in default mode this controller is set to a a value of 0x2000 (decimal 8192). Increasing the value raises the pitch; lowering does the opposite.

In MMA the command effects only one track at time. A number of settings are generated depending on the various parameters. The command is used in a command like:

Solo MidiWheel Duration=4 Offset=2 Start=1000 End=9000

The following options, all are in option=value pairs, are recognized:

CYCLE
If you use the START/END options below the wheel will be adjusted from one value to the other over the DURATION period of time. If you enable CYCLE it runs from START to END and then back to START .... To enable this option use ``CYCLE=ON'' and ``CYCLE=OFF'' to disable (probably never needed).

DURATION
The duration for the effect in beats. This value must be greater than 0. You can append a single ``m'' or ``M'' to the end of the value to specify bars. So ``DURATION=8'' and ``DURATION=2M'' would be the same (assuming 4/4 time.

END
The last value to use. This must be an integer between 0 and 16383.24.7 If you set an END value, you must also set the START, below.

OFFSET
An optional offset (in beats) to start the operation. By default this is set to ``0'' (the current song position). You can use any value (include negative values which will cause the operation to take place before the current position). Partial beats can be set using a decimal number (eg 1.5). You can specify the offset in measures (or partial measures) by appending a single ``m'' or ``M'' to the value.

RATE
The duration of each plus specified as a note duration. If, for example, you have have DURATION of ``1'' and a RATE of 8 (an eighth note), the effect will pulse 4 times. (See here for details on how to specify a note duration). Using smaller note durations will give a faster pulse. Use this in conjunction with the CYCLE option, above.

RESET
By default a value of 0x2000 is sent at the conclusion of the commands. This resets the controller to the default state. You can override this by using the option ``Reset=No''; you can also use ``Reset=Yes'' to match the default.

You can also use a RESET without an option to force an immediate controller reset. In this case the command is translated to SET=CENTER. It can be useful to use this at the start or end of a song which may be in an unknown pitch bend.

SET
This option takes a single value in the range 0 ... 16383 and sets the pitch bend controller to that value. You can use the OFFSET setting in combination with this. Any other options will be parsed, but ignored (a warning is issued).

START
The first value to use. Like END, the range is 0 to 16383. If you use a START value, you must also use an END, above.

STEP
An optional step rate. By default, a step rate of 10 is used. For very short or long effect durations or ranges you may wish to change this. Small values (ie, 1, 2, 3) will generate more commands and, in theory, will give a more gradual change; large values will generate less commands and a courser change. In our testing we find very little difference in different settings. Note: you can use a large setting to force only one value being written into the MIDI file--an instant pitch change.

When setting START, END or SET you can use the special value ``Center'' as a mnemonic for ``0x2000''. This value represents the controller in the centered or default position.

A short example:

Begin Solo
    Octave 6
    Articulate 100 // force full value of the note
    Voice Strings
    Riff 1+1e ;
End
 
Solo MidiWheel Duration=1b offset=2 cycle=on \
   Start=9000 End=7000 Step=2 Rate=8
z * 2 // 2 bars for the solo note

Not all MIDI devices support this option. The actual results are highly controller dependent.


MIDIInc

MMA has the ability to include a user supplied MIDI file at any point of its generated files. These included files can be used to play a melodic solo over a MMA pattern or to fill a section of a song with something like a drum solo.

When the MIDIINC command is encountered the current line is parsed for options, the file is inserted into the stored MIDI stream, and processing continues. The include has no effect on any song pointers, etc. Optionally, the MIDI data can be pushed into a SOLO or MELODY track and further processed by that track's optional settings (see the file egs/midi-inc/README-riffs for a detailed tutorial on this option).

MIDIINC has a number of options, all set in the form OPTION=VALUE. Following are the recognized options:

FILE
The filename of the file to be included. This must be a complete filename. The filename will be expanded by the Python os.path.expanduser() function for tilde expansion. No prefixes or extensions are added by MMA . Examples: FILE=/home/bob/midi/myfile.mid. or FILE=~/sounds/myfile.mid.

VOLUME
An adjustment for the volume of all the note on events in the included MIDI file. The adjustment is specified as a percentage with values under 100 decreasing the volume and over 100 increasing it. If the resultant volume (velocity) is less than 1 a velocity of 1 will be used; if it is over 127, 127 will be used. Example: VOLUME=80.

STRETCH
This option is used to ``stretch'' or ``compress'' a file to match the timing of the MMA track. Values in the range of 1 to 500 are accepted. They specify, in percentage terms, the size of adjustment. For example, STRETCH=200 will double the duration of the imported file. This is useful when the time signature of the current MMA file and the imported file differ. See the discussion for a similar SOLO command here.

OCTAVE
Octave adjustment for all notes in the file. Values in the range -4 to 4 are permitted. Notes in drum tracks (channel 10) will not be effected. Example: OCTAVE=2. Note: specifying an octave does not set the selected track to that octave; it just adjusts notes by 12 (or 24, etc) pitches up or down.

TRANSPOSE
Transposition adjustment settings in the range -24 to 24 are permitted. If you do not set a value for this, the global transpose setting will be applied (excepting channel 10, drum, notes). Example: TRANSPOSE=-2. Having different values for the global and import TRANSPOSE is fine and should work as expected.

You should note that when you are using the TRACK RIFF (see below) and TRANSPOSE options together you will end up with two levels of tranposition: one from the MIDIINC and a second when the SOLO or MELODY data generated is parsed. This may not be what you want.

LYRIC
This option will copy any Lyric events to the MMA meta track. The valid settings are ``On'' or ``Off''. By default this is set to ``Off''. Example: LYRIC=ON.

TEXT
This option will copy any Text events to the MMA meta track. The valid settings are ``On'' or ``Off''. By default this is set to ``Off''. Example: TEXT=ON.

START
Specifies the start point of the file to be included in beats. For example, START=22 would start the include process 22 beats into the file. The data will be inserted at the current song position in your MMA file. The value used must be greater or equal to 0.

END
Specifies the end point of the file to be included in beats. For example, END=100 would discard all data after 100 beats in the file. The value used must be greater than the START position.

Time Values
For START and END (above) the offsets can be specified as a number representing the number of the beat to start or end the import; a number with a ``m'' or ``M'' appended for the number of the measure; or a number with a ``t'' or ``T'' to specify the number of MIDI ticks. Assuming a ``TIME 4'' setting, ``5'', ``1M'' and ``768t'' are identical. In all cases you can use a fractional value: the middle of bar 2 is 2.5m.

Verbose
Print additional debugging information about the operation. To enable use VERBOSE=ON; to duplicate the default use VERBOSE=OFF

REPORT
Parse the MIDI file and print a summary report on the terminal. The MIDI data is note inserted, nor is an output MIDI file created. To enable, include REPORT=ON; to duplicate the default use REPORT=OFF. The most useful information generated are the note start data which you can use with STRIPSILENCE.

STRIPSILENCE
By default, MMA will strip off any silence at the start of an imported MIDI track. You can avoid this behaviour by setting STRIPSILENCE=OFF, or set a specific amount to strip with the STRIPSILENCE=VALUE option. To duplicate the default, use STRIPSILENCE=ON.

A problem with deleting silence is that different tracks in your file may have different ``start'' points. If you are having a problem with included data not starting where you think it should, examine the file with the REPORT or VERBOSE option(s), above, and set the STRIPSILENCE factor manually. Eg:

MidiInc File=myfile.mid Solo=1 StripSilence=2345

IGNOREPC
A MIDI file being imported may contain Program Change commands (voice changes). By default MMA will strip these out so that the voices set in the MMA track are used. However, you can override this by setting IGNOREPC=FALSE. To duplicate the default, use IGNOREPC=TRUE.24.8

TRACK
A trackname must be set into which notes are inserted. You can set more than one track/channel if you wish. For example, if you have the option DRUM=10 any notes in the MIDI file with a channel 10 setting would be inserted into the MMA DRUM track. Similarity, SOLO-TENOR=1 will copy notes from channel 1 into the SOLO-TENOR track. If the track doesn't exist, it will be created. Note: this means that the channel assignment in your included file and the new MMA generated file will most likely be different.

Riff
To convert the data in the imported track into data that a SOLO or MELODY track can process append the keyword RIFF to the channel number with a comma. The note on/off data will be converted into RIFF commands and pushed into the specified track. An imported RIFF will inherit VOICE, HARMONY and other track parameters.

Sequence
Imported data can also be converted into a SEQUENCE for a SOLO or MELODY track. Simply append the keyword SEQUENCE to the channel number with a comma (just like RIFF, above). This can be useful in importing drum tracks from existing MIDI files. You will need to play with the START and END settings to limit the size of the imported section so that it matches your sequence size.

Because the MIDI data is converted to numeric pitch values (not mnuemoic values like ``a'', ``b'', etc.), data imported into a MELODY or SOLO track as a RIFF or SEQUENCE is not be effected by the track's OCTAVE setting.

Print
Further, you can append the keyword PRINT. The generated RIFFs or SEQUENCEs will not be inserted into the track but displayed on your computer monitor. This can be useful for debugging or to generate lines which can be edited and inserted into a song file.

It is recommended that you not use the RIFF and SEQUENCE options in production code. With the PRINT option you can easily capture data and incorporate that directly into your files without concern for missing or changing include files.

At least one TRACK option is required to include a MIDI file. It is up to the user to examine existing MIDI files to determine the tracks being used and which to include into MMA 's output.

A short example which you could insert into a MMA file is really this simple:

MIDIinc File=test.mid Solo-Piano=1 Drum=10 Volume=70

This will include the MIDI file ``test.mid'' at the current position and assign all notes in channel 1 to the Solo-Piano track and the notes from channel 10 to the Drum track. The volumes for all the notes will be adjusted to 70% of that in the original.

Slighty more complicated (and probably silly):

MidiInc File=test.mid Lyric=On Solo-Piano=1,Riff Solo-harmony=1,riff Drum=10 Solo-Guitar=3

Will import the existing file ``test.mid'' and:

Lyrics
will be read and inserted into the meta track,
Solo-Piano
Data from channel 1 will be converted and inserted into the SOLO-PIANO track as a series of RIFFs.
Solo-Harmony
Data from channel 1 (again!) will be converted and inserted into the SOLO-HARMONY track as a series of RIFFs.
Drum
Channel 10 data will be copied into the DRUM track.
Solo-Guitar
Channel 3 data will be copied into the SOLO-GUITAR track. Track settings (ie, Articulate, Harmony) will not be applied.

More complete examples of usage are shown in the directory egs/midi-inc in the distribution.

A few notes:

For short snippets of MIDI you can insert individual events using the MIDINOTE command (here).

MIDIMark

You can insert a MIDI Marker event into the Meta track with this command. The mark can be useful in debugging your MIDI output with a sequencer or editor which supports Mark events (most do).

MidiMark Label

will insert the text ``Label'' at the current position. You can add an optional negative or positive offset in beats:

MidiMark 2 Label4

will insert ``Label4'' 2 beats into the next bar.

Note: the ``mark'' inserted can only be a single word. If you need a longer message see MIDICUE or MIDITEXT.


MIDINote

It is relatively easy to insert various melody and harmony notes into a song with SOLO and other tracks. However, there are times when you may wish to insert a set of notes complete with MIDI timing and velocities. These values can be hand generated or created by an external program.

The MIDINOTE command is used to insert one or more MIDI note on/off, controller or pitch bend events directly into a track. If you have a large segment of MIDI data to insert you will probably want to generate a MIDI file and insert it into your song with the MIDIINC command (here). MIDINOTE is more suited for short segments.

Setting Options

MIDINOTE has a number of settings which modify its behavior. These options can be different for each track and are set on a track-by-track basis. Options are reset to their defaults with the SEQCLEAR command (except for SOLO tracks). They are not saved or modified by GROOVE commands.

MIDINOTE takes various options in the OPTION=VALUE notation. Please note that options can appear on a line by themselves, or can be mixed into a data/command line. The order is not important--all option pairs are parsed out of an input line before the actual data is read. The following options are supported:

Transpose=On/Off
By default MIDINOTE ignores the global TRANSPOSE setting. If enabled, each note will be adjusted by the global setting. Careful with this: TRANSPOSE is a global setting which effects all tracks; MIDINOTE TRANSPOSE effects only the specified track.

Offsets=Beats/Ticks
By default a MIDI tick offset into the current position in the file is used. However, you can change this to ``Beats'' so that conventional MMA beat offset are used (see example below).

Duration=Notes/Ticks
By default the note duration is specified using MIDI ticks. Setting the value to ``Notes'' enables the use of conventional MMA note durations (which are converted, internally, to MIDI ticks.

Articulate=On/Off
This option is OFF by default. If enabled the current ARTICULATE (details here) setting is applied to each event if the duration is set to Notes. Setting this option to ``off'' causes each note to have its full value. If using ``ticks'' (the default) for the duration this command is ignored.

Octave=Value
Octave adjustment will increase/decrease by the set number of octaves for each note entered in a NOTE command. Values in the range -4 to 4 are permitted. Notes in drum tracks (channel 10) will not be effected. This has no effect on the underlying track's octave. Any generated notes outside of the valid MIDI range of 0 to 127 will be adjusted to fit the range.

Volume=Value
Use this option to adjust the volume (velocity) of the notes set with a NOTE command (useful if you have played a melody on a keyboard and it is too loud/soft). The value is a percentage adjustment factor and, by default, is set to 100. Values greater than 100 will make notes louder and values less than 100 will make them softer. Using very large factors will cause all notes to have maximum velocity (127); small factors will cause minimum velocity. Generated values less than 1 are magically set to 1; values greater than 127 are set to 127. The adjustment factor must be greater than 0.

Adjust=Value
This option is set to 0 by default. If a value is set all future Tick Offsets in MIDINOTE directives will be adjusted by that value. This can be quite useful if you have a set of note on/off events parsed from an existing MIDI file. Using the ADJUST value can shift the series back and forth in your song file. The setting has no effect when using Beat offsets.

To duplicate the default settings you might use a line like:

Chord-Piano MidiNote Offsets=Ticks Duration=Ticks Articulate=Off Transpose=Off Adjust=0 Volume=100 Octave=0

You can insert MIDI events directly into any track with a command line like:

Solo MidiNote Note 1 c#+ 100 4

The valid commands are NOTE (note on/off event), CTRL (controller event) and PB (pitch bend event), PBR (series/range of pitch bend events), CHAT (a channel aftertouch event) and CHATR (series/range of channel aftertouch events). Following is a detailed command set for each option:

Note Events

A MIDINOTE NOTE event is specified with the ``Note'' keyword; however, the keyword doesn't need to be used. So:

Solo MidiNote 1 65 100 4

and
Solo MidiNote Note 1 65 100 4

are equivalent.

After the command you need to specify the offset, pitch, velocity and duration of the desired note.

Offset
The offset into the current bar. The exact format depends of the global setting use (Ticks or Beats). When using Ticks (the default) the offset is simply inserted into the current bar at the given offset. To insert an event at the start of the current bar use ``0''. If using Beats, you can use any valid offset used in defining patterns (here). Values less than 1 will place the event before the current bar. Note: when using Tick offsets they will be adjusted by the global ADJUST setting.

Note
The next field represents the MIDI note or pitch or a set of notes (a chord). Notes can be specified with their MIDI value (0 to 127) or using standard notation pitch mnemonics.

A single note is specified with a MIDI value or mnemonic; a chord (multiple notes) is specified by appending each desired note with a single comma. For example, to insert a C Major chord you could use the line:

Solo MidiNote Note 1 c,e,g 90 192

Pitch names are used just like you would in a SOLO or MELODY track (here). The permitted syntax is limited to the letters 'a', 'b', 'c', 'd', 'e', 'f' or 'g' followed by an optional '&', '#' or 'n' and a number of '-'s or '+'s. When a note pitch is specified by name the OCTAVE setting for the track is honored. The current KEYSIG is applied to each chord. Accidentals, whether set explicitly or from a key signature, do not apply to successive chords.24.9They do apply to successive notes in a chord, irrespective of octave. So, the chord ``a#,a+,a++'' would have all three ``a''s sharp.

For DRUM tracks and SOLO or MELODY tracks which have the ``DrumType'' attribute set, you can use drum tone mnemonics (here). The special tone ``*'' can be used to select the tone. In the case of MELODY and SOLO tracks the current default tone is used (here); for DRUM tracks the currently selected TONE (here). Use of the special ``*'' is useful when you have a series of drum events--changing only the TONE is much easier than changing a number of MIDINOTE commands.

Velocity
The ``volume'' of the note is set with a MIDI velocity in the range 0 to 127. Notes with the velocity of 0 will, probably, not sound.

Duration
The length of the note is set in either MIDI ticks for MMA note durations, depending on the global ``Duration'' setting. When using Ticks remember that 192 MIDI ticks equals a quarter note. If you have enabled the Articulate setting and are using Note durations the duration will be adjusted.

Controller Events

A MIDI controller event can be directly inserted at any point in our song using a MIDINOTE CONTROLLER command. For example:

Solo MidiNote Ctrl 3 Modulation 90

will insert a Modulation control event. The necessary values are:

Offset
Same as for Note. See above for details.

Controller
This can be a value in the range 0 to 127 specifying the MIDI controller or a symbolic name. See the appendix , here, for a list of defined names.

Datum
The ``parameter'' value for the controller. Must be in the range 0 to 127.

Pitch Bend

A MIDI Pitch Bend event can be directly inserted at any point in our song using a MIDINOTE PB command. For example:

Solo MidiNote PB 3 934

Offset
Same as for Note. See above for details.

Value
The value for a pitch bend event must be in the range -8191 to +8192.24.10 The exact effect of different values is device dependant; however, -8191 sets the pitch bend to ``as low as possible'', 8192 sets it ``as high as possible'', and 0 resets the pitch to neutral.

Pitch Bend Range

This command is just like PITCH BEND, described above, with the added feature of creating a series of events over a period of time. This makes it easy to create various ``swoops'' and ``slides'' in your song. As always, the example:

Solo MidiNote PBR 20 3,4 0,1000

Count
This sets the total number of events to insert. Each event will be distributed over the specifed offset range.

Offset Range
Two values joined with a single comma. Both values and the comma must be present. The first value is the first event offset to use, the second is the last. Events will be evently distributed over the two offsets. Each offset has the same format as as for Note.

Value Range
Two values joined with a single comma. Both values and the comma must be present. The first value is the initial pitch bend setting; the second is the final. The values will be incremented (or decremented) for each event offset according to the count value. See PITCH BEND, above, for the range rules.

Channel Aftertouch

MIDI channel aftertouch events can be directly inserted in a MMA song using the MIDINOTE CHAT command. For example:

Solo MidiNote ChAT 3 50

Offset
Same as for Note. See above for details.

Value
The value for a channel aftertouch event must be in the range 0 to 127. The exact effect of this command is highly specific to different synths; however, it applies to all currently sounding note events on the specified channel. On some hardware (or software) the command is ignored; on others it effects the volume or vibrato.

Channel Aftertouch Range

Just like CHANNEL AFTERTOUCH, described above, with the added feature of creating a series of events over a period of time. Example:

Solo MidiNote ChATR 20 3,4 0,100

Count
This sets the total number of events to insert. Each event will be distributed over the specifed offset range.

Offset Range
Two values joined with a single comma. Both values and the comma must be present. The first value is the first event offset to use, the second is the last. Events will be evently distributed over the two offsets. Each offset has the same format as as for Note.

Value Range
Two values joined with a single comma. Both values and the comma must be present. The first value is the initial pitch bend setting; the second is the final. The values will be incremented (or decremented) for each event offset according to the count value. See CHANNEL AFTERTOUCH, above, for the range rules.

------------

MIDIPan

In MIDI-speak ``pan'' is the same as ``balance'' on a stereo. By adjusting the MIDIPAN for a track you can direct the output to the left, right or both speakers. Example:

Bass MIDIPan 4

This command is only available in track mode. The data generated is not sent into the MIDI stream until musical data is created for the relevant MIDI channel.

The value specified must be in the range 0 to 127 (or a mnemonic list below), and must be an integer.

A variation for this command is to have the pan value change over a range of beats or measures:

Solo MidiPan 10 120 4

in this case you must give exactly 3 arguments:

  1. The initial pan value (0 to 127),
  2. The final pan value (0 to 127),
  3. The number of beats to apply the pan over. By appending a ``M'' to the beat count MMA will calculate the pan over a number of measures.

Using a beat count you can create interesting effects with different instruments moving between the left and right channels.

MIDIPAN is not saved or restored by GROOVE commands, nor is it effected by SEQCLEAR. A MIDIPAN is inserted directly into the MIDI track at the point at which it is encountered in the music file. This means that the effect of MIDIPAN will be in use until another MIDIPAN is encountered.

MIDIPAN can be used in MIDI compositions to emulate the sound of an orchestra. By assigning different values to different groups of instruments, you can get the feeling of strings, horns, etc. all placed in the ``correct'' position on the stage.

MIDIPAN can be used for much cruder purposes. When creating accompaniment tracks for a mythical jazz group, you might set all the bass tracks (Bass, Walk, Bass-1, etc) set to aMIDIPAN 0. Now, when practicing at home you have a ``full band''; and the bass player can practice without the generated bass lines simply by turning off the left speaker.

Because most MIDI keyboard do not reset between tunes, there should be a MIDIPAN to undo the effects at the end of the file. Example:24.11

Include swing
Groove Swing
Bass MIDIPan 0
Walk MIDIPan 0
1 C
2 C
...
123 C
Bass MIDIPan 64
Walk MIDIPan 64

To make setting easier and more consistent the following mnemonic values may be used (case can be upper, lower or mixed):

Symbolic Name Actual Value
Left100 0
Left90 6
Left80 13
Left70 19
Left60 25
Left50 31
Left40 39
Left30 44
Left20 50
Left10 57
Center 64
Right10 70
Right20 77
Right30 83
Right40 88
Right50 96
Right60 102
Right70 108
Right80 114
Right90 121
Right100 127

MIDISeq

It is possible to associate a set of MIDI controller messages with certain beats in a sequence. For example, you might want to have the Modulation Wheel set for the first beats in a bar, but not for the third. The following example shows how:

Seqsize 4
Begin Bass-2
Voice NylonGuitar
Octave 4
Sequence { 1 4 1 90; 2 4 3 90; 3 4 5 90; 4 4 1+ 90}
MIDIDef WheelStuff 1 1 0x7f ; 2 1 0x50; 3 1 0
MidiSeq WheelStuff
Articulate 90
End

C * 4

The MIDISEQ command is specific to a track and is saved as part of the GROOVE definition. This lets style file writers use enhanced MIDI features to dress up their sounds.

The command has the following syntax:

TrackName MidiSeq <Beat> <Controller> <Datum> [ ; ...]

where:

Beat
is the Beat in the bar. This can be an integer (1,2, etc.) or a floating point value (1.2, 2.25, etc.). It must be 1 or greater and less than the end of bar (in 4/4 it must be less than 5).

Controller
A valid MIDI controller. This can be a value in the range 0x00 to 0x7f or a symbolic name. See the appendix , here, for a list of defined names.

Datum
All controller messages use a single byte ``parameter'' in the range 0x00 to 0x7f.

You can enter the values in either standard decimal notation or in hexadecimal with the prefixed ``0x''. In most cases, your code will be clearer if you use values like ``0x7f'' rather than the equivalent ``127''.

The MIDI sequences specified can take several forms:

  1. A simple series like:

    MIDISeq 1 ReleaseTime 50; 3 ReleaseTime 0

    in this case the commands are applied to beats 1 and 3 in each bar of the sequence.

  2. As a set of names predefined in an MIDIDEF command:

    MIDISeq Rel1 Rel2

    Here, the commands defined in ``Rel1'' are applied to the first bar in the sequence, ``Rel2'' to the second. And, if there are more bars in the sequence than definitions in the line, the series will be repeated for each bar.

  3. A set of series enclosed in { } braces. Each braced series is applied to a different bar in the sequence. The example above could have been does as:

    MIDISeq { 1 ReleaseTime 50; 3 ReleaseTime 0 } \
    { 2 ReleaseTime 50; 4 ReleaseTime 0 }

  4. Finally, you can combine the above into different combinations. For example:

    MIDIDef Rel1 1 ReleaseTime 50
    MIDIDef Rel2 2 ReleaseTime 50
    MIDISeq { Rel1; 3 ReleaseTime 0 } { Rel2; 4 ReleaseTime 0 }

You can have specify different messages for different beats (or different messages/controllers for the same beat) by listing them on the same MIDISEQ line separated by ``;''s.

If you need to repeat a sequence for a measure in a sequence you can use the special notation ``/'' to force the use of the previous line. The special symbol ``z'' or ''-'' can be used to disable a bar (or number of bars). For example:

Bass-Dumb MIDISeq 1 ReleaseTime 20 z / FOOBAR

would set the ``ReleaseTime'' sequence for the first bar of the sequence, no MIDISeq events for the second and third, and the contents of ``FOOBAR'' for the fourth.

To disable the sending of messages just use a single ``-'':

Bass-2 MidiSeq - // disable controllers

MIDISplit

For certain post-processing effects it is convenient to have each different drum tone in a separate MIDI track. This makes it easier to apply an effect to, for example, the snare drum. Just to make this a bit more fun you can split any track created by MMA .

To use this feature:

MIDISplit <list of channels>

So, to split out just the drum channel24.12 you would have the command:

MIDISplit 10

somewhere in your song file.

Alternately, you can use a track name. In this case the track, if not already extant, will be created and the MIDI channel will be assigned. So, rather than using a channel number, you can do something like:

MIDISplit Drum

When processing MMA creates an internal list of MIDI note-on events for each tone or pitch in the track. It then creates a separate MIDI track for each list. Any other events are written to another track.

Notes:


MIDIText

This command inserts an arbitrary text string into a MIDI track at the current file position:

Chord-Sus MidiText I just love violins.

will insert the text event24.13 ``I just love violins.'' into the CHORD-SUS track.

Please note that if the specified track does not exist the text will be queued. If the track is never created, the command is ignored.

You can also insert text into the Meta track:

MidiText A message in the Meta Track

Since the Meta track always exists, no queueing is done.

MIDITname

When creating a MIDI track, MMA inserts a MIDI Track Name event at the start of the track. By default, this name is the same as the associated MMA track name. You can change this by issuing the MIDITNAME command. For example, to change the CHORD track name you might do something like:

Chord MidiTname Piano

Please note that this only effects the tracks in the generated MIDI file. You still refer to the track in your file as CHORD.

You can also use this command to rename the automatic name inserted into the Meta track. When MMA starts it inserts a Track Name event based on the filename at offset 0 in the Meta Track. For example, if you have a MMA input file ``dwr.mma'' the a ``Meta SeqName'' event ``dwr'' will be inserted. A command like:

MidiTName My version of ``Dancing with Roses''

anywhere in the input file will remove the original text and insert a new event in its place.24.14

MIDIVoice

Similar to the MIDISEQ command discussed in the previous section, the MIDIVOICE command is used to insert MIDI controller messages into your files. Instead of sending the data for each bar as MIDISEQ does, this command just sends the listed control events at the start of a track and then, if needed, at the start of each bar.

Again, a short example. Let us assume that you want to use the ``Release Time'' controller to sustain notes in a bass line:

Seqsize 4
Begin Bass-2
Voice NylonGuitar
MidiVoice 1 ReleaseTime 50
Octave 4
Sequence { 1 4 1 90; 2 4 3 90; 3 4 5 90; 4 4 1+ 90 }
Articulate 60
End

C * 4

should give an interesting effect.

The syntax for the command is:

Track MIDIVoice <beat> <controller> <Datum> [; ...]

This syntax is identical to that discussed in the section for MIDISEQ, above. The <beat>value is required for the command--it determines if the data is sent before or after the VOICE command is sent. Some controllers are reset by a voice, others not. My experiments show that BANK should be sent before, most others after. Using a ``beat'' of ``0'' forces the MidiVoice data to be sent before the Voice control; any other ``beat'' value causes the data to be sent after the Voice control. In this silly example:

Voice Piano1
MidiVoice {0 Bank 5; 1 ReleaseTime 100}

the MIDI data is created in an order like:

0 Param Ch=xx Con=00 val=05
0 ProgCh Ch=xx Prog=00
0 Param Ch=xx Con=72 val=80

All the MIDI events occur at the same offset, but the order is (may be) important.

By default MMA assumes that the MIDIVoice data is to be used only for the first bar in the sequence. But, it's possible to have a different sequence for each bar in the sequence (just like you can have a different VOICE for each bar). In this case, group the different data groups with {} brackets:

Bass-1 MIDIVoice {1 ReleaseTime 50} {1 ReleaseTime 20}

This list is stored with other GROOVE data, so is ideal for inclusion in a style file.

If you want to disable this command after it has been issued you can use the form:

Track MIDIVoice - // disable

Some technical notes:


MIDIVolume

MIDI devices equipped with mixer settings can make use of the ``Channel'' or ``Master'' volume settings.24.15

MMA doesn't set any channel volumes without your knowledge. If you want to use a set of reasonable defaults, look at the file includes/init.mma which sets all channels other than ``1'' to ``100''. Channel ``1'' is assumed to be a solo/keyboard track and is set to the maximum volume of ``127''.

You can set selected MIDIVOLUMEs:

Chord MIDIVolume 55

will set the Chord track channel. For most users, the use of this command is not recommended since it will upset the balance of the library grooves. If you need a track softer or louder you should use the VOLUME setting (which changes the MIDI velocities of each note) for the track.

The data generated is not sent into the MIDI stream until musical data is created for the relevant MIDI channel.

More sophisticated MIDI programs use MIDI volume changes in combination with velocity settings. If you are going to do a ``fancy arrangement'' you'll probably be better of using a dedicated sequencer/editor to make the track-by-track volume changes. On the other hand, you may find that using MIDIVOLUME, MIDICRESC and MIDIDECRESC (here) works just fine.

The volume arguments for this command can also be set using the standard volume mnemonics ``m'', ``p'', etc. (see here).

Caution: If you use the command with ALLTRACKS you should note that only existing MMA tracks will be effected.

This command can be used in a non-track setting as well. In this case the MIDI Master Volume is used and the volumes are in the range 0 to 16383.



Footnotes

... set.24.1
Depending on your initialization files, there may be other information MIDI in the track which is inserted into the output file.
... track:24.2
This is much easier to do with the KeySig command, here
... file.24.3
A copyright message is set as a meta-event with the coding <FF 02 Len Text>.
... 1638324.4
A 14 bit MIDI number, 0 to 0x3fff.
... portamento24.5
The name ``Glis'' is used because ``MIDIPortamento'' gets to be a bit long to type and ``MIDIPort'' might be interpreted as something to do with ``ports''.
... pitch.24.6
Most of the time it sounds awful, especially when the author of MMA is doing the twiddling.
... 16383.24.7
The values for the pitch bend are a 14 bit integer, hence the range 0 ... 0x3fff.
...IGNOREPC=TRUE.24.8
``On'' and ``1'' can be used instead of ``True''; ``Off'' and ``0'' can be used instead of ``False''.
... chords.24.9
The reason for this is that MMA doesn't really know when to stop applying an accidental in a set of MIDINOTE commands since they can easily span the current bar. It is thought best to honor a key signature, but to reset it for each chord. Not quite standard musical notation; but then MMA isn't notation.
... +8192.24.10
The number is a 14 bit value over 2 bytes. Internally MMA converts the argument to a value 0 to 16383.
... Example:24.11
This is much easier to do with the MMAStart and MMAEnd options (details).
... channel24.12
In MMA this will always be channel 10.
... event24.13
This is a meta-event <FF 01 len msg>
... place.24.14
A Track Name (SeqName) message is set as a meta-event with the coding <FF 03 Len Text>.
... settings.24.15
I discovered this on my keyboard after many frustrating hours attempting to balance the volumes in the library. Other programs would change the keyboard settings, and not being aware of the changes, I'd end up scratching my head.
Bob van der Poel 2017-03-25