Next: Creating Effects Up: Reference Manual Previous: Documentation Strings
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.
But, 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 three locations:
If, when initializing itself, MMA cannot find one of the above directories, it will terminate with an error message.
If you are using MMA on a Windows platform please see the comments about the default paths (here).
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:
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.
On Unix-like systems all filenames may be prefaced with tilde or a tilde with a user name. All file operations in MMA honor this convention. This includes the setting of library and include paths.
The result of this operation is system dependent. See the entry for os.path.expanduser in the Python library reference.
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.
The search for library files can be set with the LibPath variable. To set LIBPATH:
| SetLibPath PATH |
You can have only one path in the SETLIBPATH directive.
When MMA starts up it sets the library path to the first valid directory in the list:
The last choice lets you run MMA directly from the distribution directory.
You are free to change this to any other location in a RCFile.
LIBPATH is used by the routine which auto-loads grooves from the library, and the USE directive. The -g command line option is used to maintain the library database).
The current setting can be accessed via the macro $_LibPath.
The sub-directory containing the current library files to automatically load is determined by the current setting of AUTOLIBPATH. Please see the library file discussion here for details.
You can change the automatic include directory by resetting this variable. It must be a sub-directory of LIBPATH for it to work.
The command to reset the variable is:
| SetAutoLibPath mydir |
The current setting can be accessed via the macro $_AutoLibPath. By default the setting is ``stdlib''.
Any existing GROOVE definitions are deleted from memory when this command is issued (this it to avoid name conflicts between libraries).
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''. You can change this to anything you want.
| SetMIDIplayer /usr/local/kmid |
You will probably want to use this command in an RC file.
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 with no spaces in it. 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.
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 directory (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.
The search for include files can be set with the INCPATH variable. To set INCPATH:
| SetIncPath PATH |
You can have only one path in the SETINCPATH directive.
When MMA initializes it sets the include path to first found directory in:
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.
The current setting can be accessed via the macro $_IncPath.
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:
Let's examine each feature in a bit more detail.
When a USE directive is issued, eg:
| use stdlib/swing |
MMA first attempts to locate the file ``stdlib/swing'' in the directory 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:
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.
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.
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.
When MMA starts it checks for initialization files. Only the first found file is processed. The following locations/files are checked (in order):
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:
| include ~/.mmarc |
to force the inclusion of your global stuff,
By default, no RC files are installed. You may want to create an empty ~/.mmarc file to eliminate a warning message.
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.
Included in this distribution are a number of predefined patterns, sequences and grooves. They are in different files in the ``lib'' directory.
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''.
The basic MMA distribution comes with a set of pattern 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.
If you are creating a set of alternate grooves to duplicate the existing library you might do the following:
| SetAutoLibPath bvdp |
You will have to update the MMA database with the -g or -G command line options for this to work. If you elect this route, please note that the files in the standard library will not be available, but you can use both with something like this:
|
Groove Metronome2-4
z * 2 SetAutoLibPath bvdp Groove BossaNova // the bossa from lib/bvdp, not stdlib! chords ... |
The nice thing about this method is that you can have multiple sets of library files all using the same GROOVE names. To create a different version you just need to change the SETAUTOLIBPATH variable in your song file ...or, for a collection of songs put the variable in your MMARC file.
For those who ``really need to know'', here are the steps that MMA takes when it encounters a GROOVE command:
The database is a file .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. If there are sub-directories the entries for them will be stored in the database file for the main tree.
By using a USE directive or by resetting AUTOLIBDIR you force the loading of your set of grooves.
To make MMA as platform independent as possible a number of additional paths have been defined. When starting up, in addition to the standard Linux paths discussed above, the following are also checked:
bob 2008-09-28