Paths, Files and Libraries
Keywords: mma

Subsections

- - MMA Modules
  - Special Characters In Filenames
  - Tildes In Filenames
  - Filenames and the Command Line
- File Extensions
- Eof
- LibPath
- MIDIPlayer
- Groove Previews
- OutPath
- Include
- IncPath
- Use
- MmaStart
- MmaEnd
- RC Files
- Library Files
  - Maintaining and Using Libraries

#
Paths, Files and Libraries

This chapter covers MMA filenames, extensions and a variety of commands and/or directives which effect the way in which files are read and processed.

##
MMA Modules

First a few comments on the location of the MMA Python modules.

The Python language (which was used to write MMA ) has a very useful feature: it can include other files and refer to functions and data defined in these files. A large number of these files or modules are included in every Python distribution. The program MMA consists of a short “main” program and several “module” files. Without these additional modules MMA will not work.

The only sticky problem in a program intended for a wider audience is where to place these modules. Hopefully, it is a “good thing” that they should be in one of several locations. On a Linux (and Mac) system the following locations are checked:

- /usr/local/share/mma/MMA
- /usr/share/mma/MMA
- ./MMA

on Mac the same path as Linux is used, with the addition of:

- /Users/Shared/mma/MMA

and on a Windows system:

- c:\mma\MMA
- c:\Program Files\mma
- .\MMA

To make it possible to have multiple installations of MMA (most likely for testing), a check is made to see the modules are present in the home of the MMA executable. This is stored in the Python system variable sys.path[0].33.1

Additionally it is possible to place the modules in your python-site directory. If, when initializing itself, MMA cannot find the needed modules it will terminate with an error message.

MMA assumes that the default include and library directories are located in the above listed directories as well. If these can't be found a warning message will be displayed.

If you really need to, you can modify this in the main mma.py script.

## Special Characters In Filenames

In all the following sections we refer to various forms of “filename” and “path”. MMA parses files and uses various forms of “whitespace”33.2 to separate different parts of commands. This means that you cannot, easily, include space characters in a filename embedded in a MMA source file. But, you can, if needed. When MMA uses a path or filename it first transforms any sequences of the literal “\x20” into “space” characters.

If you are on a Windows or Mac platform you may need to use the space feature, if not for filenames, for paths.

For example:

SetMidiPlayer C:\Program\x20Files\Windows\x20Player

In this example we are setting our MIDI player to “C:\Program Files\Windows Player”. The “\x20”s are converted to space characters.

When running MMA on a Windows platform you don't need to use the rather ugly “\”s since Python will conveniently convert paths with normal “forward” slash characters to something Windows understands.

A common mistake made, especially by users on Windows platforms, is using quote characters to delimit a filename. Don't use quotation marks! MMA doesn't see anything special in quotes and the quote characters will be assumed to be part of a filename ... and it won't work.

## Tildes In Filenames

SetOutPath ~/music/midies

In this case the “~” is replaced with the path of the current user (for details see the Python documentation for os.path.expanduser()). The result of tilde expansions is system dependent and varies between Linux, Mac, and Windows. For details please refer to the Python documentation for os.path.expanduser().

The case of a filename is relevant if your system supports case-sensitive filenames. For example, on a Linux system the names “file.mid” and “File.MID” refer to different files; on a Windows system they refer to the same file. An overview of this can be found at `https://en.wikipedia.org/wiki/Filename#Letter_case_preservation`.

## Filenames and the Command Line

Please note that the above discussion, especially the parts concerning embedded spaces, applies only to file and path names in a MMA source file. If you want to compile a .mma file with a space character it is not a problem. From the command line:

$ mma "my file"

works just fine ... but note that we used quotation marks to tell the shell, not MMA , that “my file” is one name, not two.

#
File Extensions

For most files the use of a the file name extension “.mma” is optional. However, it is suggested that most files (with the exceptions listed below) have the extension present. It makes it much easier to identify MMA song and library files and to do selective processing on these files.

In processing an input song file MMA can encounter several different types of input files. For all files, the initial search is done by adding the file name extension “.mma” to file name (unless it is already present), then a search for the file as given is done.

For files included with the USE directive, the directory set with SETLIBPATH is first checked, followed by the current directory.

For files included with the INCLUDE directive, the directory set with SETINCPATH is first checked, followed by the current directory.

Following is a summary of the different files supported:

Song Files
  The input file specified on the command line should always be named with the “.mma” extension. When MMA searches for the file it will automatically add the extension if the file name specified does not exist and doesn't have the extension.

Library Files
  Library files really should all be named with the extension. MMA will find non-extension names when used in a USE or INCLUDE directive. However, it will not process these files when creating indexes with the “-g” command line option—these index files are used by the GROOVE commands to automatically find and include libraries.

RC Files
  As noted in the RC-File discussion (here) MMA will automatically include a variety of “RC” files. You can use the extension on these files, but common usage suggests that these files are probably better without.

MMAstart and MMAend
  MMA will automatically include files at the beginning or end of processing (start/end details). Typically these files are named MMASTART and MMAEND. Common usage is to not use the extension if the file is in the current directory; use the file if it is in an “includes” directory.

One further point to remember is that filenames specified on the command line are subject to wild-card expansion via the shell you are using.

# Eof

Normally, a file is processed until its end. However, you can short-circuit this behavior with the EOF directive. If MMA finds a line starting with EOF no further processing will be done on that file ... it's just as if the real end of file was encountered. Anything on the same line, after the EOF, is also discarded.

You may find this handy if you want to test process only a part of a file, or if you making large edits to a library file. It is often used to quit when using the LABEL and GOTO directives to simulate constructs like D.C. al Coda, etc.

#
LibPath

The search for library files can be set with the LibPath variable. To set LIBPATH:

SetLibPath PATH

You can have as many paths in the SETLIBPATH directive as you want.

When MMA starts up it sets the library path to the first valid directory in the list:

- /usr/local/share/mma/lib

- /usr/share/mma/lib

- ./lib

The last choice lets you run MMA directly from the distribution directory.

When MMA initializes it will force the directory stdlib to be the first directory in the list. It will also display a warming message if stdlib is not found. If the path is changed later by the user, the user's order will be honored. No check for stdlib being present is made.

You are free to change this to any other location(s) in a RCFile. Remember that the previous setting is lost. If you just want to add directories, use a macro. Example:

SetLibPath /mymma $_LibPath

will add the mymma directory in your HOME directory to the search path.

LIBPATH is used by the routine which auto-loads grooves from the library, and the USE directive. The -g and -G command line options are used to maintain the library database).

The current setting can be accessed via the macro $_LIBPATH.

One useful trick is to set the LIBPATH to limit GROOVE selection to a specific library. For example:

set c $_LibPath + casio setLibPath $c

Note that you need to do this in two steps since it's only the SET command that recognizes string concatenation.

A better way to have your own personal grooves checked first might be:

set c $_LibPath + mylib setLibPath $c $_LibPath

which is set mylib to be the first directory checked for a groove.

#
MIDIPlayer

When using the -P command line option MMA uses the MIDI file player defined with SETMIDIPLAYER to play the generated file. By default the program is set to “aplaymidi” on Linux, “open” on Mac, and an empty file on Windows. You can change this to a different player:

SetMIDIplayer /usr/local/kmid

You will probably want to use this command in an RC file.

It is permissible to include command options as well. So, for example, on Linux you might do:

SetMIDIplayer timidity -a

Command line options with an “=” are permitted, so long as they do not start with an alpha character. So,

SetMIDIplayer aplaymidi –port=12:3

will work.

To set to an empty name, just use the command with no arguments:

SetMIDIplayer

An empty filename On a Linux host will generate an error if you attempt to preview a file with the -P command line option; on Windows hosts the empty string instructs Windows to use the default player for the generated MIDI file.

There are two additional settings for the MIDI file player:

- In a Windows environment the player will be forked as a background process and MMA will wait for a set time.

- In a Unix environment the player will be forked in the foreground and MMA will wait for the player to terminate.

You can change the above behavior with the BACKGROUND and DELAY options.

SetMidiPlayer BackGround=1 Delay=4 myplayer -abc

In the above example the player is forced to play as a background process with a delay time of 4 seconds. The player name is set to “myplayer” with an option string of “-abc”.

and,

SetMidiPlayer BackGround=0 Delay=4

will set the player name to “” (which is only valid in a Windows environment) and force it to play in the foreground. In this case the delay setting will have no effect.

The BACKGROUND option can be set with “1” or “Yes” and unset with “0” or “No”. No other values are valid.

Note that when setting player options the player name is required (otherwise it is set to “”).

#
Groove Previews

MMA comes with well over 1500 (and increasing!) different grooves in its standard libraries. Determining which to use in your song can be quite a chore. For this reason a special “preview” command line option has been included. To use it, first decide on which GROOVE you'd like to listen to. Then, from a terminal or other command line interface, type a command like:

$ mma -V bolero

This will create a short (4 bar) file with a GROOVE BOLERO command and some chords. This file will then be played in the same manner as the -P command line option. If you don't hear the file being played or if you get an error message, please refer to the SETMIDIPLAYER section, above.

In addition to using a default set of chords, etc. you can customize the preview with some command line options. Note that each of these options can be placed anywhere on the line in any order. Nothing in the options (except chord names) is case sensitive. Each of the commands must have an = and contain no spaces:33.3

Count
  set the number of bars to create/play. The default is 4.

Chords
  set the chords to use. The chords must be in the form of a list with commas separating the chord names. For example:

  Chords=A,Gm,C,D7

  By default we use:

  Chords=I,vi,ii,V7

  A generic introduction notated in Roman numerals.

Any other MMA command can be inserted in a -V line. For example, to play a 4 bar sequence in the key of G with a tempo of 144:

$ mma -V mambo2 Chords=I,I,V7,III Tempo=144 KeySig=G

The supplied utility mma-gb.py makes extensive use of this command set.

With the extended GROOVE name extension, (more details) you can preview grooves from files not yet in the library (or database). Assuming you are working on a new library file in your current directory, just issue a command like:

$ mma -V ./newfile:newgroove

You can skip the leading “./” in the path, but it forces a bit more verbiage frm MMA .

#
OutPath

MIDI file generation is to an automatically generated filename (more details). If the OUTPATH variable is set, that value will be prepended to the output filename. To set the value:

SetOutPath PATH

Just make sure that “PATH” is a simple path name. The variable is case sensitive (assuming that your operating system supports case sensitive filenames). This is a common directive in a RC file (more details). By default, it has no value.

You can disable the OUTPATH variable quite simply: just issue the command without an argument.

If the name set by this command begins with a “.”, “/” or “ \” it is prepended to the complete filename specified on the command line. For example, if you have the input filename test.mma and the output path is ˜/mids —the output file will be /home/bob/mids/test.mid.

If the name doesn't start with the special characters noted in the preceding paragraph the contents of the path will be inserted before the filename portion of the input filename. Again, an example: the input filename is mma/rock/crying and the output path is “midi”—the output file will be mma/rock/midi/crying.mid.

The current setting can be accessed via the macro $_OutPath.

Note that this option is ignored if you use the -f command line option or if an absolute name for the input file (one starting with a “/” or a “~”) is used.

#
Include

Other files with sequence, pattern or music data can be included at any point in your input file. There is no limit to the level of includes.

Include Filename

A search for the file is done in the INCPATH directories (see below) and the current directory. The “.mma” filename extension is optional (if a filename exists both with and without the “.mma” extension, the file with the extension will be used).

The use of this command should be quite rare in user files; however, it is used extensively in library files to include standard patterns.

#
IncPath

The search for include files can be set with the INCPATH variable. To set INCPATH:

SetIncPath PATH

You can have as many paths in the SETINCPATH directive as you need.

When MMA initializes it sets the include path to first found directory in:

- /usr/local/share/mma/includes
- /usr/share/mma/includes
- ./includes

The last location lets you run MMA from the distribution directory.

If this value is not appropriate for your system, you are free to change it in a RC File. If you need to add a second directory to this list, remember that previous settings are lost. So, to add a local path you can do something like:

SetIncPath /mymma/incs $_IncPath

to insert a local path into the path.

The current setting can be accessed via the macro $_IncPath.

#
Use

Similar to INCLUDE, but a bit more useful. The USE command is used to include library files and their predefined grooves.

Compared to INCLUDE, USE has important features:

- The search for the file is done in the paths specified by the LibPath variable,

- The current state of the program is saved before the library file is read and restored when the operation is complete.

Let's examine each feature in a bit more detail.

When a USE directive is issued,

use stdlib/swing

MMA first attempts to locate the file “stdlib/swing” in the directories specified by LIBPATH or the current directory. As mentioned above, MMA automatically added the “.mma” extension to the file and checks for the non-extension filename if that can't be found.

If things aren't working out quite right, check to see if the filename is correct. Problems you can encounter include:

- Search order: you might be expecting the file in the current directory to be used, but the same filename exists in the LIBPATH, in which case that file is used.

- Not using extensions: Remember that files with the extension added are first checked.

- Case: The filename is case sensitive. The files “Swing” and “swing” are not the same. Since most things in MMA are case insensitive, this can be an easy mistake to make.

- Quotes: DO NOT put quotation marks around the filename!

As mentioned above, the current state of the compiler is saved during a USE. MMA accomplishes this by issuing a slightly modified DEFGROOVE and GROOVE command before and after the reading of the file. Please note that INCLUDE doesn't do this. But, don't let this feature fool you—since the effects of defining grooves are cumulative you really should have SEQCLEAR statements at the top of all your library files. If you don't you'll end up with unwanted tracks in the grooves you are defining.

In most cases you will not need to use the USE directive in your music files. If you have properly installed MMA and keep the database up-to-date by using the command:

$ mma -g

grooves from library files will be automatically found and loaded. Internally, the USE directive is used, so existing states are saved.

If you are developing new or alternate library files you will find the USE directive handy.

#
MmaStart

If you wish to process a certain file or files before your main input file, set the MMASTART filename in an RCFile. For example, you might have a number of files in a directory which you wish to use certain PAN settings. In that directory, you just need to have a file mmarc which contains the following command:

MmaStart setpan

The actual file setpan has the following directives:

Bass Pan 0 Bass1 Pan 0 Bass2 Pan 0 Walk Pan 0 Walk1 Pan 0 Walk2 Pan 0

So, before each file in that directory is processed, the PAN for the bass and walking bass voices are set to the left channel.

If the file specified by a MMASTART directive does not exist a warning message will be printed (this is not an error).

Also useful is the ability to include a generic file with all the MIDI files you create. For example, you might like to have a MIDI reset at the start of your files—simple, just include the following in your mmarc file:

MMAstart reset

This includes the file reset.mma located in the “includes” directory (IncludePath).

Multiple MMASTART directives are permitted. The files are processed in the order declared. You can have multiple filenames on a MMASTART line.

One caution with MMASTART files: the file is processed after the RC file, just before the actual song file.

#
MmaEnd

Just the opposite of MMASTART, this command specifies a file to be included at the end of a main input file. See the comments above for more details.

To continue this example, in your mmarc file you would have:

MmaEnd nopan

and in the file nopan have:

Bass Pan 64 Bass1 Pan 64 Bass2 Pan 64 Walk Pan 64 Walk1 Pan 64 Walk2 Pan 64

If the file specified by a MMAEND directive does not exist a warning message will be printed (this is not an error).

Multiple MMAEND directives are permitted and processed in the order declared. You can have multiple filenames on a MMAEND line.

#
RC Files

When MMA starts it checks for initialization files. Only the first found file is processed. The following locations/files are checked (in order):

1. mmarc — this is a normal file in the current directory.

2. ~/.config/mma/mmarc — a file in the user's home configuration directory.

3. ~/.mmarc — this is an “invisible” file in the user's home directory.

4. /usr/local/etc/mmarc

5. /etc/mmarc

Only the first found file will be processed. This means you can override a “global” RC file with a user specific one. If you just want to override some specific commands you might want to:

1. Create the file mmarc in a directory with MMA files,

2. As the first line in that file have the command:

   include ~/.mmarc

   to force the inclusion of your global stuff,

3. Now, place your directory specific commands in your custom RC file.

By default, no RC files are installed. If you have enabled debugging (-d) a warning message will be displayed if no RC file is found.

An alternate method for using a different RC file is to specify the name of the file on the command line by using the -i option (here). Using this option you can have several RC files in a directory and compile your songs differently depending on the RC file you specify.

The RC file is processed as a MMA input file. As such, it can contain anything a normal input file can, including music commands. However, you should limit the contents of RC files to things like:

SetOutPath SetLibPath MMAStart MMAEnd

A useful setup is to have your source files in one directory and MIDI files saved into a different directory. Having the file mmarc in the directory with the source files permits setting OUTPATH to the MIDI path.

#
Library Files

Included in this distribution are a number of predefined patterns, sequences and grooves. They are in different files in the “lib” directories.

The library files should be self-documenting. A list of standard file and the grooves they define is included in the separate document, supplied in this distribution as “mma-lib.ps”.

MMA maintains a database file in each directory found in the mma/lib directory structure. These are invisible files with the name .mmaDB. When MMA starts up it sets a path list containing the names of each directory found in mma/lib. When a GROOVE is needed MMA will look in the database files for each directory. The directory mma/lib/stdlib will be checked first.

##
Maintaining and Using Libraries

The basic MMA distribution comes with a set of pattern or style files which are installed in the mma/lib/stdlib directory. Each one of these files has a number of GROOVEs defined in them. For example, the file mma/lib/stdlib/rhumba.mma contains the grooves Rhumba, RhumbaEnd and many more.

If you are writing GROOVEs with the intention of adding them to the standard library you should ensure that none of the names you choose duplicate existing names already used in the same directory.33.4

If you are creating a set of alternate grooves to duplicate the existing library you might do the following:

1. Create a directory with your name or other short id in the mma/lib/ hierarchy. For example, if your name is “Bob van der Poel” you might create the directory mma/lib/bvdp. Alternately you might create a new directory in your own user tree and add that name to LIBPATH in your mmarc file (see above for details).

2. Place all your files (or modified files) in that directory.

3. Now, when your song wants to use a groove, you have two choices:

   - Include the file with the USE directive. For example, if you have created the file rock.mma and want to use the GROOVE rock8 you would place the directive USE BVDP/ROCK near the top of the song file. Note: it might not be apparent from the typeface here, but the filename here is all lowercase. In Unix/Linux case is important, so please make sure of the case of the filenames in commands like USE.

   - Alternately you can enable the groove using extended groove names with the directive GROOVE BVDP/ROCK:ROCK8.

4. Tell MMA about your new file(s) and GROOVES by updating the MMA database with the -g or -G33.5 command line options. If you elect this route, remember that the order for the paths in LIBPATH is important. If the filename or groove names duplicate material in the stdlib you may be better off forcing the include by doing a USE ... a trick to set things up so that stdlib is NOT searched first is to use the SETLIBPATH command in a mmarc file to set your collection to the top of the list. See here for details.

   Example: Assume you have created a new “bossanova” file. To force MMA to use this, a simple method is:

   - Create a user directory outside of the default MMA library tree. This is important! If you have both stdlib and mystuff directories in the default library path, stdlib will be searched first ... not what you want.

   - Let MMA know about your new collection by updating the mmarc file with an updated LIBPATH (see above).

   - Update the MMA database with the command:

     $ mma -g

     this needs to be done when you add new GROOVE names to your file.

For those who “really need to know”, here are the steps that MMA takes when it encounters a GROOVE command:

1. if the named groove has been loaded/created already MMA just switches to the internal version of that groove.

2. if the groove can't be found in memory, a search of the groove databases (created with the -g command line option) is done. If no database is in memory it is loaded from the directories pointed to by the LIBPATH variables. These databases are then searched for the needed GROOVE. The databases contain the filenames associated with each GROOVE and that file is then read with the same routines that USE uses.

The databases are files .mmaDB stored in each sub directory of LIBPATH. This is a “hidden” file (due to the leading “.” in the filename). You cannot change the name of this file. Sub-directores are processed in turn.

If a library file you create depends on GROOVES from another library file you will need to load that library file with a USE directive. This is due to limitation is the -g/-G update commands.

By using a USE directive you force the loading of your set of grooves.

#### Footnotes

... sys.path[0].33.1
  The system variable sys.path[] is a list. The first entry is not necessarily the same as “.”.
... “whitespace”33.2
  Whitespace is defined by Python to include space characters, tabs, etc. Again, refer to the Python documentation if you need details.
... spaces:33.3
  The reason for the “=” and the other restrictions are mainly to protect your arguments from the underlying shell.
... directory.33.4
  When you update the database with the MMA -g/G command a list of files containing duplicate groove definition names will be displayed. It would not be a big chore to verbosely display each and every duplication, but it would most likely generate too much noise to be useful.
... -G33.5
  -G forcefully deletes the existing database files to ensure a complete update.