Running MMA

MMA is a command line program. To run it, simply type the program name followed by the required options. For example,

$ mma test

processes the file test^2.1 and creates the MIDI file test.mid.

When MMA is finished it displays the name of the generated file, the number of bars of music processed and an estimate of the song's duration. Note:

• The duration is fairly accurate, but it does not take into account any mid-bar TEMPO changes.
• The report shows minutes and hundredths of minutes in a MM.dd format (this is convenient if you want to add a number of times together). In addition, the report shows the number of minutes and seconds in a MM:SS format.

Command Line Options

The following command line options are available:

Debugging and other aids to figuring out what's going on.

-b Range List

Limit generation to specified range of bars. The list of bar numbers is in the format N1-N2 or N1,N2,N3 or any combination (N1-N2,N3,N4-N5). Only those bars in the specified range will be compiled. The bar numbers refer to the “comment” bar number at the start of a data line ... note that the comment numbers will vary from the actual bar numbers of the generated song. ^2.2

-B Range List

Same as -b (above), but here the bar numbers refer to the absolute bar numbers in the generated file.

-c

Display the tracks allocated and the MIDI channel assignments after processing the input file. No output is generated.

-d

Enable LOTS of debugging messages. This option is mainly designed for program development and may not be useful to users.^2.3

-e

Show parsed/expanded lines. Since MMA does some internal fiddling with input lines, you may find this option useful in finding mismatched BEGIN blocks, etc.

-I Name

Display a help or usage message for a plugin. MMA will attempt to find and load the plugin Name and display its usage message (a “not found” message will be displayed if the plugin doesn't have a printUsage method).

-II

Ignore permission test for loading PLUGINS. Use of this option is not recommended, but it can be quite useful when writing and testing a plugin.

-o

A debug subset. This option forces the display of complete filenames/paths as they are opened for reading. This can be quite helpful in determining which library files are being used.

-p

Display patterns as they are defined. The result of this output is not exactly a duplicate of your original definitions. Most notable are that the note duration is listed in MIDI ticks, and symbolic drum note names are listed with their numeric equivalents.

-r

Display running progress. The bar numbers are displayed as they are created complete with the original input line. Don't be confused by multiple listing of “*” lines. For example the line

33 Cm * 2

would be displayed as:

88: 33 Cm *2
89: 33 Cm *2

This makes perfect sense if you remember that the same line was used to create both bars 88 and 89.

See the -L option, below for an alternate report.

-L

This command option will save the bar numbers (here) you supply at the start of lines and print this as a list at the end of the compile process. This is very handy if you have multiple repeats and/or GOTOs and need to determine what you might have done wrong. Lines without labels are displayed as ”?”.

-s

Display sequence info during run. This shows the expanded lists used in sequences. Useful if you have used sequences shorter (or longer) than the current sequence length.

-v

Show program's version number and exit.

-w

Disable warning messages.

Commands which modify MMA 's behavior.

-0

Generate a synchronization tick at the start of every MIDI track. Note that the option character is a “zero”, not a “O”. For more details see SYNCHRONIZE, here.

-1

Force all tracks to end at the same offset. Note that the option character is a “one”, not an “L”. For more details see SYNCHRONIZE, here.

-i BARS

Set the maximum number of bars which can be generated. The default setting is 500 bars (a long song!^2.4). This setting is needed since you can create infinite loops by improper use of the GOTO command. If your song really is longer than 500 bars use this option to increase the permitted size.

-M x

Generate type 0 or 1 MIDI files. The parameter “x” must be set to the single digit “0” or ”1”. For more details, see the MIDISMF section here.

-n

Disable generation of MIDI output. This is useful for doing a test run or to check for syntax errors in your script.

-P

Play and delete MIDI file. Useful in testing, the generated file will be played with the defined MIDI file player (see section here). The file is created in the current directory and has the name “MMAtmpXXX.mid” with “XXX” set to the current PID.

-S

Set a macro. If a value is needed, join the value to the name with a '='. For example:

$ mma myfile -S tempo=120

will process the file myfile.mma with the variable $Tempo set with the value “120”. You need not specify a value:

$ mma myfile -S test

just sets the variable $test with no value.

-T TRACKS

Generate only data for the tracks specified. The tracks argument is a list of comma separated track names. For example, the command “mma mysong -T drum-hh,chord” will limit the output to the Drum-HH and Chord tracks. This is useful in separating tracks for multi-track recording.

-V

Play a short audio preview of a GROOVE in the MMA library. For complete details on this command see section here.

Maintaining MMA 's database.

-g

Update the library database for the files in the LIBPATH. You should run this command after installing new library files or adding a new groove to an existing library file. If the database (stored in the files in each library under the name .mmaDB) is not updated, MMA will not be able to auto-load an unknown groove. Please refer to the detailed discussion here for details.

The current installation of MMA does not set directory permissions. It simply copies whatever is in the distribution. If you have trouble using this option, you will probably have to reset the permissions on the lib directory.

MMA will update the groove database with all files in the current LIBPATH. All files must have a “.mma” extension. Any directory containing a file named MMAIGNORE will be ignored.^2.5 Note, that MMAIGNORE consists of all uppercase letters and is usually an empty file.

-G

Same as the “-g” option (above), but the uppercase version forces the creation of a new database file—an update from scratch just in case something really goes wrong.

File commands.

-i

Specify the RC file to use. See details here.

-f FILE

Set output to FILE. Normally the output is sent to a file with the name of the input file with the extension “.mid” appended to it. This option lets you set the output MIDI file to any file name. No extension is appended when using -f, you'll need to include that yourself.

-

A single “-” on the command line tells MMA to use STDIN for input. Use of this option makes the use of the -f option (above) necessary ... otherwise MMA would not know where to save the generated MIDI data.

The following commands are used to create the documentation. As a user you should probably never have a need for any of them.

-Dk

Print list of MMA keywords. For editor extension writers.

-Dxl

Expand and print DOC commands used to generate the standard library reference for L^ATEX processing. No MIDI output is generated when this command is given. Doc strings in RC files are not processed. Files included in other files are processed.

-Dxh

Same as -Dxl, but generates HTML output. Used by the mma-libdoc.py tool.

-Dgh

Generate HTML output for Groove specified on the command line. If the specified groove name has a '/' the first part of the name is assumed to be a file to read using USE. Used by the mma-libdoc.py tool.

-Djs

Generate JSON output for the specified GROOVE. See -DGH, above, for more details.

-Dbo

Generate a list of defined groove names and descriptions from a file specified on the command line. Used by the mma-gb.py tool.

-Ds

Generates a list of sequence information. Used by the mma-libdoc.py tool.

Some Miscellaneous and/or Seldom Used Commands.

-xNoCredit

Suppresses the insertion of “Generated my MMA” in Midi Meta data. Please don't use this ... it is nice for MMA to get credit. Details here.

-xChords List

Checks the list of chords and verifies that MMA recognizes them. Details here.

-xCheckFile FILE

Parses the filename and verifies each chord found. Chords are listed in alphabetical order as an aid to see which chords are in the file. Does not verify other commands and syntax in the file. Details here.

-xGrooves [NAME]

Lists all the GROOVE names in the MMA database. Details here.

-xPrint VAR

Lists the value of system variables at initialization. Details here.

-xCSplit

Create separate files for each MIDI track. Details here.

-xTSplit

Create separate files for each MIDI track. Details here.

A number of the above command line options are also available from the CMDLINE option detailed here.

Lines and Spaces

When MMA reads a file it processes the lines in various passes. The first reading strips out blank lines and comments of the “//” type.

On the initial pass though the file any continuation lines are joined. A continuation line is any line ending with a single “ \”—simply, the next line is concatenated to the current line to create a longer line.

Unless otherwise noted in this manual, the various parts of a line are delimited from each other by runs of white space. White space can be tab characters or spaces. Other characters may work, but that is not recommended, and is really determined by Python's definitions.

Programming Comments

MMA is designed to read and write files (including a file piped to it via stdin). However, it is not a filter.^2.6

As noted earlier in this manual, MMA has been written entirely in Python.There were some initial concerns about the speed of a “scripting language” when the project was started, but Python's speed appears to be entirely acceptable. On my long-retired AMD Athlon 1900+ system running Mandrake Linux 10.1, most songs compiled to MIDI in well under one second. A more current system, an Intel i5-8400 @ 2.80GHz, does it in just over one tenth of a second. If you need faster results, you're welcome to re-code this program into C or C++, but it would be cheaper to buy a faster system, or spend a bit of time tweaking some of the more time intensive Python loops.

Footnotes

...^2.1

Actually, the file test or test.mma is processed. Please read section file extensions.

... song.^2.2

Use of this command is not recommended for creating production MIDI files. A great deal of “unused” data is included in the files which may create timing problems. The command is designed for quick previews and debugging.

... users.^2.3

A number of the debugging commands can also be set dynamically in a song. See the debug section here for details.

... song!^2.4

500 bars with 4 beats per bar at 200 BPM is about 10 minutes.

... ignored.^2.5

Sub-directories in a directory with a MMAIGNORE are processed ... they need additional MMAIGNORE entires to ignore.

... filter.^2.6

It is possible that filter mode for output could be added to MMA , but I'm not sure why this would be needed.