Subsections


Other Commands and Directives

In addition to the ``Pattern'', ``Sequence'', ``Groove'' and ``Repeat'' and other directives discussed earlier, and chord data, MMA supports a number of directives which affect the flavor of your music.

The subjects presented in this chapter are ordered alphabetically.


AllTracks

Sometimes you want to apply the same command to all the currently defined tracks; for example, you might want to ensure that no tracks have SEQRND set. Yes, you could go though each track (and hope you don't miss any) and explicitly issue the command:

Bass SeqRnd Off ...
Chord SeqRnd Off

But,

AllTracks SeqRnd Off

is much simpler. Similarly, you can set the articulation for all tracks with:

AllTracks Articulate 80
You can even combine this with a BEGIN/END like:

Begin AllTracks
  Articulate 80
  SeqRnd Off
  Rskip 0
End

This command is handy when you are changing an existing GROOVE.

There are two forms of the ALLTRACKS command. The first, as discussed above, applies to all tracks that are currently defined. Please note that SOLO, MELODY and ARIA tracks are not modified.

The second form of the command lets you specify one or more track types. For example, you may want to increase the volume of all the DRUM tracks:

AllTracks Drum Volume +20

Or to set the articulation on BASS and WALK tracks:

AllTracks Bass Walk Articulate 55

If you specify track types you can use any of BASS, CHORD, ARPEGGIO, SCALE, DRUM, WALK, MELODY, SOLO and ARIA tracks.


Articulate

When MMA processes a music file, all the note lengths specified in a pattern are converted to MIDI lengths.

For example in:

Bass Define BB 1 4 1 100; 2 4 5 90; 3 4 1 80; 4 4 5 90

bass notes on beats 1, 2, 3 and 4 are defined. All are quarter notes. MMA , being quite literal about things, should make each note exactly 192 MIDI ticks long--which means that the note on beat 2 will start at the same time as the note on beat 1 ends.

However, that's not the way things work!

MMA has an ARTICULATE setting for each voice. This value is applied to shorten or lengthen the note length. By default, the setting is 90. Each generated note duration is taken to be a percentage of this setting, So, a quarter note with a MIDI tick duration of 192 will become 172 ticks long.

If ARTICULATE is applied to a short note, you are guaranteed that the note will never be less than 1 MIDI tick in length.

To set the value, use a line like:

Chord-1 Articulate 96

ARTICULATE values must be greater than 0 and less than or equal to 200. Values over 100 will lengthen the note. Settings greater than 200 will generate a warning.

You can specify a different ARTICULATE for each bar in a sequence. Repeated values can be represented with a ``/'':

Chord Articulate 50 60 / 30

Notes: The full values for the notes are saved with the pattern definition. The articulation adjustment is applied at run time. The ARTICULATE setting is saved with a GROOVE.

Articulate settings can easily be modified by prefacing the values with a ``+'' or ``-'' which will increment or decrement the existing values. For example:

Chord Articulate 80 85 90 95
Chord Articulate +10 -10

results in the CHORD ARTICULATE setting of: ``90 75 100 85''. Having fewer values that the current sequence size is fine. The inc/dec values get expanded to the sequence size and are applied to the existing settings.

ARTICULATE works differently for PLECTRUM tracks. Please refer to the documentation here.


CmdLine

This command permits the setting of options normally set on the command line inside a MMA script. For example:

CmdLine -b 5-9

sets the bars to generate in the exact same manner as the command line option (here). A number of the commands you can enter on a command line are not available. Examples include -G/g and all the documentation commands.


Copy

Sometimes it is useful to duplicate the settings from one voice to another. The COPY command does just that:

Bass-1 Copy Bass

will copy the settings from the Bass track to the Bass-1 track.

The COPY command only works between tracks of the same type.

The same settings which are saved/restored in a GROOVE are copied with this command; for details see the discussion here.

It is also possible to copy a track from another GROOVE, even if it has not been loaded or read into memory using extended groove name notation (again, see the groove discussion):

Chord-New Copy stdlib/rhumba:rhumbasus::chord-sus

In the above example, the ``::'' is used to separate the track name (chord-sus) from the groove name. What happens internally is:

  1. The current state is saved,
  2. The file containing the ``RhumbaSus'' groove is located and loaded,
  3. The ``Chord-Sus'' track data is copied into the current ``Chord-New'' track,
  4. The state is restored.

With COPY you can do mind-blasting things like:

bass copy ballad::bass
chord copy rhumbasus::chord-sus
C
Am
Dm
G7

which generates a song file with 2 tracks: a bass line from ``Ballad'' and sustained chords from ``RhumbaSus''.

A few caveats:

The OVERLAY GROOVE construct (here) is quite similar, but this command is more powerful.


Comment

As previously discussed, a comment in MMA is anything following a ``//'' in a line or enclosed in a ``/* */'' section. An alternate way of marking a comment is with the COMMENT directive. This is quite useful in combination the BEGIN and END directives. For example:

Begin Comment
    This is a description spanning
        several lines which will be
        ignored by MMA.
End

You could achieve the same with:

// This is a description spanning
// several lines which will be
// ignored by MMA.

or:

/* This is a description spanning
    several lines which will be
    ignored by MMA. */

or even:

Comment This is a description spanning
Comment several lines which will be
Comment ignored by MMA.

One minor difference between // or /* */ and COMMENT is that the first two are discarded when the input stream is read; the more verbose version is discarded during line processing. One possible upside of COMMENT is that it is displayed when processing a file with the -e command line option.

Quite often it is handy to delete large sections of a song with a BEGIN COMMENT/END on a temporary basis.


Debug

To enable you to find problems in your song files (and, perhaps, even find problems with MMA itself) various debugging messages can be displayed. These are normally set from the command line command line.

However, it is possible to enable various debugging messages dynamically in a song file using the DEBUG directive. In a debug statement you can enable or disable any of a variety of messages. A typical directive is:

Debug Debug=On Expand=Off Patterns=On

Each section of the debug directive consists of a mode and the command word ON or OFF. The two parts must be joined by a single ``=''. You may use the values ``0'' for ``Off'' and ``1'' for ``On'' if desired.

The available modes with the equivalent command line switches are:

Mode Command Line Equivalent
Debug -d debugging messages
Filenames -o display file names
Patterns -p pattern creation
Sequence -s sequence creation
Runtime -r running progress
Warnings -w warning messages
Expand -e display expanded lines
Plectrum   display Plectrum chord shapes
Roman   display Roman numeral chord conversions
Groove   issue a warning when a Groove is redefined

The modes and command are case-insensitive (although the command line switches are not). The options for PLECTRUM, GROOVE and ROMAN are not accessible from the command line.

The current state of the debug flags is saved in the variable $_Debug and the state prior to a change is saved in $_LastDebug.


Delay

The DELAY setting permits you to delay each note in a sequence. This can create interesting and, sometimes, beautiful effects. In most cases you should use this in a duplicate track with a lesser volume ... the effect is not meant to duplicate offsets defined in SEQUENCE definitions.

Solo Delay 8t -18t 8 -16

Assuming a 4 bar sequence, the above command would apply the following delays to each note:

  1. 8 MIDI ticks,
  2. a negative 18 MIDI ticks (a ``pushed'' note).
  3. a delay equal to a eighth note,
  4. a negative sixteenth note.

The DELAY setting can be negative (in this case the note is sounded in advance).29.1 You can have different delays for each bar in a sequence. The values for the delay are given in standard MMA note durations (see here for details). DELAY is saved in GROOVES.

See egs/delay for some sample files.29.2


Delete

If you are using a track in only one part of your song, especially if it is at the start, it may be wise to free that track's resources when you are done with it. The DELETE command does just that:

Solo Delete

If a MIDI channel has been assigned to that track, it is marked as ``available'' and the track is deleted. Any data already saved in the MIDI track will be written when MMA is finished processing the song file.


Direction

In tracks using chords or scales you can change the direction in which they are applied:

Scale Direction UP

The effects differ in different track types. For SCALE and ARPEGGIO tracks:

UP Plays in upward direction only
DOWN Plays in downward direction only
BOTH Plays upward and downward (default)
RANDOM Plays notes from the chord or scale randomly

When this command is encountered in a SCALE track the start point of the scale is reset.

A WALK track recognizes the following option settings:

BOTH The default. The bass pattern will go up and down a partial scale. Some notes may be repeated.
UP Notes will be chosen sequentially from an ascending, partial scale.
DOWN Notes will be chosen sequentially from a descending, partial scale.
RANDOM Notes will be chosen in a random direction from a partial scale.

All four patterns are useful and create quite different effects.

The CHORD tracks DIRECTION only has an effect when the STRUM setting has a non-zero value. In this case the following applies:

UP The default. Notes are sounded from the lowest tone to the highest.
DOWN Notes are sounded from the highest to the lowest.
BOTH The UP and DOWN values are alternated for each successive chord.
RANDOM A random direction is selected for each chord.

You can specify a different DIRECTION for each bar in a sequence. Repeated values can be represented with a ``/'':

Arpeggio Direction Up Down / Both

The setting is ignored by BASS, DRUM and SOLO tracks.


KeySig

The key signature is an underlining concept in all modern music. In MMA it will effect the notes used in SOLO or MELODY tracks, is a basic requirement for ROMAN numeral chords, and sets a MIDI Key Signature event.29.3 In most cases you should set the key signature in all your songs.

In addition, the CHORD track VOICING MODE=KEY option depends on the key being properly set via this command.

Setting the key signature is simple to do:

KeySig 2b

The argument consists of a single digit ``0'' to ``7'' followed by a ``b'' or ``&'' for flat keys or a ``#'' for sharp keys.

As a more musical alternate, you can use a pitch name like ``F'' or ``G#''.

The optional keywords ``Major'' or ``Minor'' (these can be abbreviated to ``Maj'' or ``Min'' ... and case doesn't count) can be added to this command. This will accomplish two things:

  1. The MIDI track Key Signature event will be set to reflect minor or major.

  2. If you are using a musical name the proper key (number of flats or sharps) will be used.

To summarize, the following are all valid KEYSIG directives:

KeySig 2# Major
KeySig 1b
KeySig 0b Min
KeySig F Min
KeySig A Major

Mallet

Some instruments (Steel-drums, banjos, marimbas, etc.) are normally played with rapidly repeating notes. Instead of painfully inserting long lists of these notes, you can use the MALLET directive. The MALLET directive accepts a number of options, each an OPTION=VALUE pair. For example:

Solo-Marimba Mallet Rate=16 Decay=-5

This command is also useful in creating drum rolls. For example:

Begin Drum-Snare2
  Tone SnareDrum1
  Volume F
  Mallet Rate=32 Decay=-3
  Rvolume 3
  Sequence z z z 1 1 100
End

The following options are supported:

Rate

The RATE must be a valid note length (i.e., 8, 16, or even 16.+8).

For example:

Solo-Marimba Mallet Rate=16

will set all the notes in the ``Solo-Marimba'' track to be sounded a series of 16th notes.

To disable this setting use a value of ``0''.

Decay

You can adjust the volume (velocity) of the notes being repeated when MALLET is enabled:

Drum-Snare Mallet Decay=-15

The argument is a percentage of the current value to add to the note each time it is struck. In this example, assuming that the note length calls for 4 ``strikes'' and the initial velocity is 100, the note will be struck with a velocity of 100, 85, 73 and 63.

Important: a positive value will cause the notes to get louder, negative values cause the notes to get softer.

Note velocities will never go below 1 or above 255. Note, however, that notes with a velocity of 1 will most likely be inaudible.

The decay option value must be in the range -50 to 50; however, be cautious using any values outside the range -5 to 5 since the volume (velocity) of the notes will change quite quickly. The default value is 0 (no decay).


Octave

When MMA initializes and after the SEQCLEAR command all track octaves are set to ``4''. This will place most chord and bass notes in the region of middle C.

You can change the octave for any voice with OCTAVE command. For example:

Bass-1 Octave 3

Sets the notes used in the ``Bass-1'' track one octave lower than normal.

The octave specification can be any value from 0 to 10. Various combinations of INVERT, TRANSPOSE and OCTAVE can force notes to be out of the valid MIDI range. In this case the lowest or highest available note will be used.

You can specify a different OCTAVE for each bar in a sequence. Repeated values can be represented with a ``/'':

Chord Octave 4 5 / 4

Octave settings can easily be modified by prefacing the values with a ``+'' or ``-'' which will increment or decrement the existing values. For example:

Bass Octave 2 3 4 5
Bass Octave +1 +2 -1 -3

results in the BASS OCTAVE setting of: ``3 5 3 2''. Having fewer values that the current sequence size is fine. The inc/dec values get expanded to the sequence size and are applied to the existing settings.

MMA 's octave numbering and schemes used to denote octaves on a piano keyboard or staff do not correspond. MMA is capable of generating a compete set of MIDI notes in the range 0 to 127--for this we need the first octave to be ``0''. If this is a problem, see the MOCTAVE command discussed in the next section.


MOctave

Rather than using MMA 's octave numbering from 0 to 10 you might want to match the standard MIDI implementation of -1 to 9. The operation of the command is identical to that of the OCTAVE, discussed above ... with the exception of the range.

The result of ``Octave 4'' and ``MOctave 5'' are identical.

Also, you cannot use the auto increment/decrement options that OCTAVE has (the problem is deciding what ``-1'' should mean).

Mixing of OCTAVE and MOCTAVE commands is fine. They both effect the same internal variables.


Off

To disable the generation of MIDI output on a specific track:

Bass Off

This can be used anywhere in a file. Use it to override the effect of a predefined groove, if you wish. This is simpler than resetting a voice in a groove. The only way to reset this command is with a ON directive.


On

To enable the generation of MIDI output on a specific track which has been disabled with an OFF directive:

Bass On

Attempts to enable tracks disabled with the -T command line option generate a warning (the command is ignored).

Print

The PRINT directive will display its argument to the screen when it is encountered. For example, if you want to print the file name of the input file while processing, you could insert:

Print Making beautiful music for MY SONG

No control characters are supported.

This can be useful in debugging input files, especially when combined with different system variables:

Print The volume for the bass is: $_Bass_Volume

The available system variables are detailed here.

PrintActive

The PRINTACTIVE directive will the currently active GROOVE and the active tracks. This can be quite useful when writing groove files and you want to modify and existing groove.

Any parameters given are printed as single comment at the end of the header line.

In addition to the track names, the listing included the currently assigned MIDI channel and the total number of MIDI events created.

This is strictly a debugging tool. No PRINTACTIVE statements should appear in finalized grooves or song files.

Restart

This command will reset a track (or all tracks) to a default state. You may find this particularly handy in SCALE and ARPEGGIO tracks when you want note selection to start in a particular place, not left over from previous bars.

Usage is simple:

Arpeggio Restart

or to do the whole lot:

Restart

You will find very few cases where the use of this command is necessary.


ScaleType

This option is only used by SCALE and ARIA tracks. A warning is generated if you attempt to use this command in other tracks.

By default, the SCALETYPE is set to AUTO. The permissible settings are:

CHROMATIC Forces use of a chromatic scale
AUTO Uses scale based on the current chord (default)
SCALE Same as ``Auto''
CHORD Uses the individual notes of the current chord (similar to ARPEGGIO tracks).

For more details on usage in ARIA tracks see here.

When this command is encountered in a SCALE track the start point of the scale is reset.


Seq

If your sequence, or groove, has more than one pattern (i.e., you have set SeqSize to a value other than 1), you can use this directive to force a particular pattern point to be used. The directive:

Seq

resets the sequence counter to 1. This means that the next bar will use the first pattern in the current sequence. You can force a specific pattern point by using an optional value after the directive. For example:

Seq 8

forces the use of pattern point 8 for the next bar. This can be quite useful if you have a multi-bar sequence and, perhaps, the eight bar is variation which you want used every eight bars, but also for a transition bar, or the final bar. Just put a SEQ 8 at those points. You might also want to put a SEQ at the start of sections to force the restart of the count.

If you have enable sequence randomization with the SEQRND ON command, the randomization will be disabled by a SEQ command.29.4 However, settings of track SEQRND will not be effected. One difference between SEQRND OFF and SEQ is that the current sequence point is set with the latter; with SEQRND OFF it is left at a random point.

Note: Using a value greater than the current SEQSIZE is not permitted.

This is a very useful command! For example, look at the four bar introduction of the song ``Exactly Like You'':

Groove BossanovaEnd
seq 3
1 C
seq 2
2 Am7
seq 1
3 Dm7
seq 3
4 G7 / G7#5

In this example the four bar ``ending groove'' has been used to create an interesting introduction.


Strum

When MMA generates a chord,29.5 all the notes are played at the same time.29.6

To make the notes in a chord sound like something a guitar or banjo might play, use the STRUM directive. For example:

Chord-1 Strum 5

sets the strumming factor to 5 for track Chord-1. The strum factor is specified in MIDI ticks. Usually values around 10 to 15 work just fine. The valid range for STRUM is -300 to 300 (just under the duration of a quarter note).

In the previous example the first note in the chord will be played on the beat indicated by the pattern definition, the second note will be played 5 ticks later, etc.

You can specify a different STRUM for each bar in a sequence. Repeated values can be represented with a ``/''. Assuming that there are four bars in the current sequence:

Chord Strum 20 5 / 10

To make the effect of STRUM more random (and human) you can set a range for the delay. For example:

Chord Strum 20,25

will cause MMA to select a value between 20 and 25 ticks for each successive note. You can have a different range for each bar in your sequence. In most cases a small range is adequate. Large values can create ``odd'' effects. Note that the syntax calls for exactly two values and a comma, no spaces are permitted.

STRUM can be used in all tracks except for DRUM. Since tracks other than CHORD only generate single notes, the command will only effect notes added via a HARMONY or HARMONYONLY directive. Judicious use of STRUM can add depth and a ``cascading'' effect.

STRUM can be applied to a PLECTRUM track. See PLECTRUM STRUM

Notes:


StrumAdd

When a chord is strummed using the STRUM setting discussed above, the space between the various notes in constant. However, you can modify that with the STRUMADD command:

Chord Strum 10
Chord StrumAdd 5

The value specified is added to each successive offset. Without the STRUMADD directive the notes would be generated at offsets 0, 10, 20, etc. However, with this option, the notes will now be placed at 0, 15, 35, 60, 90, etc.29.7

The easy way to imagine this is to picture a guitar player strumming a chord. Without the STRUMADD option his hand moves at a steady speed; with it his hand can slow down (positive values) or speed up (negative values).

The effects of ADD are cumulative and can add up rather quickly. Experiment with small values; large values can easily move notes into the next measure.

This is something you probably don't want to use all the time, but it is handy for dramatic chords on an opening, etc.

Note: you can use negative values in which case the distance between notes will reduce.


Synchronize

The MIDI tracks generated by MMA are perfectly ``legit'' and should be playable in any MIDI file player. However, there are a few programs and/or situations in which you might need to use the SYNCHRONIZE options.

First, when a program is expecting all tracks to start at the same location, or is intolerant of ``emptiness'' at the start of a track, you can add a ``tick note'' at the start of each track.29.8

Synchronize START

will insert a one tick note on/off event at MIDI offset 1. You can also generate this with the ``-0'' command line option.

You can set the tone and velocity used for this using the SETSYNCTONE command (below).

Second, some programs think (wrongly) that all tracks should end at the same point.29.9 Adding the command:

Synchronize END

will delete all MIDI data past the end of the last bar in your input file and insert MIDI ``all notes off'' events at that point. You can also generate this effect with the ``-1'' command line option.

The commands can be combined in any order:

Synchronize End Start

is perfectly valid.

SetSyncTone

The tone used for the synchronization tone is, by default, a MIDI ``80'' with a velocity of ``90''. You can change this to any desired combination:

SetSyncTone Tone=88 Velocity=1

The tone must be in the range 0 to 127; the velocity must be 1 to 127 (a velocity of 0 is treated as note off event and not permitted). A velocity of ``1'' will be inaudible on most systems and is useful to pad the start of a composition (use a bar with a ``z!'' chord).

The command VOLUME is an alias for VELOCITY.


Transpose

You can change the key of a piece with the ``Transpose'' command. For example, if you have a piece notated in the key of ``C'' and you want it played back in the key of ``D'':

Transpose 2

or

Transpose Up Major 2

will raise the playback by 2 semi-tones. Since MMA 's author plays tenor saxophone

Transpose -2

which puts the MIDI keyboard into the same key as the horn, is not an uncommon directive

You can use any value between -12 and 12. All tracks (with the logical exception of the drum tracks) are effected by this command.

As an alternative, you can set TRANSPOSE using interval notation. This consists of three parts: the direction, quality and number. The direction must be ``up'' or ``down''. Quality must be ``Perfect'', ``Major'', etc. as detailed in the table below. Number must be the single digits ``0'' to ``8'' or the expanded names ``Unison'', ``Second'', ``Third'', ``Fourth'', ``Fifth'', ``Sixth'', ``Seventh'', and ``Octave''. All names can be any mixture of upper and lower case letters.

The following table lists the permitted intervals and the equivalent semi-tone adjustments.

Quality Number Semitones
Perfect Unison 0
Diminished Second 0
Augmented Unison 1
Minor Second 1
Major Second 2
Diminished Third 2
Augmented Second 3
Minor Third 3
Major Third 4
Diminished Fourth 4
Augmented Third 5
Perfect Fourth 5
Augmented Fourth 6
Diminished Fifth 6
Perfect Fifth 7
Diminished Sixth 7
Augmented Fifth 8
Minor Sixth 8
Major Sixth 9
Diminished Seventh 9
Augmented Sixth 10
Minor Seventh 10
Major Seventh 11
Diminished Octave 11
Perfect Octave 12

Finally, TRANSPOSE has a modifier ADD which forces the current value to be incremented or decremented instead of being replaced. To force this, simply place the single word ADD (upper or lowercase is fine) as the first word on the command line. So,

Transpose Add 4

will increment the current transposition setting by 4 semi-tones. And,

Transpose Add Down Perfect Fourth

will decrement the current setting by 5 semi-tones.

The result for this option must be in the range -12 to 12.

Unify

The UNIFY command is used to force multiple notes of the same voice and pitch to be combined into a single, long, tone. This is very useful when creating a sustained voice track. For example, consider the following which might be used in real groove file:

Begin Bass-Sus
Sequence 1 1 1 90 &sstarf#star; 4
Articulate 100
Unify On
Voice TremoloStrings
End

Without the UNIFY ON command the strings would be sounded (or hit) four times during each bar; with it enabled the four hits are combined into one long tone. This tone can span several bars if the note(s) remain the same.

The use of this command depends on a number of items:

You can specify a different UNIFY for each bar in a sequence. Repeated values can be represented with a ``/'':

Chord Unify On / / Off

But, you probably don't want to use this particular feature.

Valid arguments are ``On'' or ``1'' to enable; ``Off'' or ``0'' to disable.

Note: Notes generated with the UNIFY setting on may be lost if you use the -b or -B command line options. MMA doesn't ``keep'' notes which were turned on before the specified range.


Footnotes

... advance).29.1
A single leading ``-'' and ``+'' sign is striped from the specified note duration.
... files.29.2
This command was conceived to be used in SOLO tracks. If you find a good use for it in other tracks, please let the author know.
... event.29.3
For the most part, MIDI Key Signature events are ignored by playback programs. However, they may be used in other MIDI programs which handle notation.
... command.29.4
A warning message will also be displayed.
... chord,29.5
In this case we define ``chord'' as two or more notes played at the same time.
... time.29.6
An exception to this are notes generated if RTIME 13.3 and/or RDURATION 13.4 are set.
... etc.29.7
These values are MIDI ticks from the current pointer position. Other settings such as RTIME will change the exact location.
... track.29.8
Timidity truncates the start of tracks up to the first MIDI event when playing a file or splitting out single tracks.
... point.29.9
Seq24 does strange looping if all tracks don't end identically.
Bob van der Poel 2017-03-25