Subsections

- Command Line Options
- Lines and Spaces
- Programming Comments

#
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. This is done deliberately so that you can add a number of times together. Converting the time to minutes and seconds is left as an exercise for the user.

# Command Line Options

The following command line options are available:

Option | Description
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.
-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.
-m 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 ignored2.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.
- | 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 Latex 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.
-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.

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 places. 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. If you need faster results, you're welcome to recode 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.
...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.