Subsections

Overview and Introduction

Musical MIDI Accompaniment, MMA ,^1.1 generates standard MIDI^1.2 files which can be used as backup tracks for a soloist plus much, much more! It was written especially for me—I am an aspiring saxophonist and wanted a program to “play” the piano and drums so I could practice my jazz solos. With MMA I can create a track based on the chords in a song, transpose it to the correct key for my instrument, and play my very bad improvisations until they get a bit better.

I also lead a small combo group which is always missing at least one player. With MMA generated tracks the group can practice and perform even if a rhythm player is missing. This all works much better than I expected when I started to write the program ... so much better that I have used MMA generated tracks for live performances with great success.

Around the world musicians are using MMA for practice, performance and in their studios. Much more than ever imagined when this project was started!

This is a large and complex program! And the documentation is long. The author has tried to not get complex about things, but in many cases that is impossible. At a minimum you should have a good, quick read of this document and the accompanying tutorial before deciding if MMA is (or is not) for you.

License, Version and Legalities

The program MMA was written by and is copyright Robert van der Poel, 2003—2019.

This program, the accompanying documentation, and library files can be freely distributed according to the terms of the GNU General Public License (see the distributed file “COPYING”).

If you enjoy the program, make enhancements, find bugs, etc. send a note to me at Bob van der Poel ; or a postcard (or even money) to 5570 Cory Road, Wynndel, BC, Canada V0B 2N1.

The current version of this package is maintained at: http://www.mellowood.ca/mma/.

This document reflects version 20.12.4 of MMA .

I have done everything I can to ensure that the program functions as advertised, but I assume no responsibility for anything it does to your computer or data.
Sorry for this disclaimer, but we live in paranoid times. This manual most likely has lots of errors. Spelling, grammar, and probably a number of the examples need fixing. Please give me a hand and report anything ... it'll make it much easier for me to generate a really good product for all of us to enjoy.

About this Manual

This manual was written by the program author—and this is always a very bad idea. But, having no volunteers, the choice is no manual at all or my bad perspectives.^1.3

MMA is a large and complex program. It really does need a manual; and users really need to refer to the manual to get the most out of the program. Even the author frequently refers to the manual. Really.

I have tried to present the various commands in a logical and useful order. The table of contents should point you quickly to the relevant sections.

Typographic Conventions

The name of the program is always set in the special logo type: MMA .
MMA commands and directives are set in small caps: DIRECTIVE.
Important stuff is emphasized: important.
Websites look like this: http://www.mellowood.ca/mma/index.html
Filenames are set in bold typewriter font: filename.mma
Lines extracted from a MMA input file are set on individual lines:

A command from a file
Commands you should type from a shell prompt (or other operating system interface) have a leading $ (to indicate a shell prompt) and are shown on separate lines:

$ enter this
Examples that show how not to do something are flagged with a ¡¡Wrong!! .

L^ATEX and HTML

The manual has been prepared with the L^ATEX typesetting system. Currently two versions of the manual are available: the primary version is a PDF file intended for printing or on-screen display (generated with dvipdf); the secondary version is in HTML (transformed with L^ATEX2HTML) for electronic viewing. If other formats are needed ... please offer to volunteer.

Music Notation

The various snippets of standard music notation in this manual have been prepared with the MUP program. I highly recommend this program and use it for most of my notation tasks. MUP is freely available from Arkkra Enterprises, http://www.Arkkra.com/.

Installing MMA

MMA is a Python program developed with version 2.7 of Python. At the very least you will need this version (or later) of Python or any of the Python 3.x versions.

To play the MIDI files you'll need a MIDI player. Aplaymidi, tse3play, and many others are available for Linux systems. For Windows and Mac systems I'm sure there are many, many choices.

You'll need a text editor like vi, emacs, etc. to create input files. Don't use a word processor!

MMA consists of a variety of bits and pieces:

The executable Python script, mma,^1.4 must somewhere in your path. For users running Windows or Mac, please check MMA website for details on how to install on these systems. As distributed the file “mma.py” (and, when installed) “mma” are executable scripts with the correct permissions already set (this has no effect for Windows).
A number of Python modules (all are files ending in “.py”). These should all be installed under the directory /usr/local/share/mma/MMA. See the enclosed file INSTALL for some additional commentary.
A number of library files defining standard rhythms. These should all be installed under the directory /usr/local/share/mma/lib/stdlib. In addition, the library files depend on files in /usr/local/share/mma/includes.

The scripts cp-install or ln-install will install MMA properly on most Linux systems. Both scripts assume that main script is to be installed in /usr/local/bin and the support files in /usr/local/share/mma. If you want an alternate location, you can edit the paths in the script. The only supported alternate to use is /usr/share/mma.

The difference between the two scripts is that ln-install creates symbolic links to the current location; cp-install copies the files. Which to use it up to you, but if you have unpacked the distribution in a stable location it is probably easier to use the link version.

In addition, you can run MMA from the directory created by the untar. This is not recommended, but will show some of MMA 's stuff. In this case you'll have to execute the program file mma.py.

To run either install script, you should be “root” (or at least, you need write permissions in /usr/local/). Use the “su” or “sudo” command for this.

If you want to install MMA on a platform other than Linux, please get the latest updates from our website at www.mellowood.ca/mma.

Running MMA

For details on the command line operations in MMA , see the “running” section.

To create a MIDI file you need to:

Create a text file (also referred to as the “input file”) with instructions which MMA understands. This includes the chord structure of the song, the rhythm to use, the tempo, etc. The file can be created with any suitable text editor.^1.5
Process the input file. From a command line the instruction:

$ mma myfile <ENTER>

will invoke MMA and, assuming no errors are found, create a MIDI file myfile.mid.
Play the MIDI file with any suitable MIDI player.
Edit the input file again and again until you get the perfect track.
Share any patterns, sequences and grooves with the author so they can be included in future releases!

An input file consists of the following information:

MMA directives. These include TEMPO, TIME, VOLUME, etc. Directives.
PATTERN, SEQUENCE and GROOVE detailed in Patterns, Sequences, and Grooves.
Music information. See Musical Data.
Comment lines and blank lines. See below.

Items 1 to 3 are detailed later in this manual. Please read them before you get too involved in this program.

Comments

Proper indentation, white space and comments are a good thing—and you really should use them. But, in most cases MMA really doesn't care:

Any leading space or tab characters are ignored,
Multiple tabs and other white space are treated as single characters,
Any blank lines in the input file are ignored.

Each line is initially parsed for comments. A comment is anything following a “//” (2 forward slashes).^1.6

Multi-line or block comments are also supported by MMA . A block comment is started by a “/*” and terminated by a “*/”.^1.7 Nesting of block comments is not supported and will generate unexpected results.

Both simple and block comments are stripped from the input stream.

Lines starting with the COMMENT directive are also ignored (but not stripped). See the comment discussion for details.

Theory Of Operation

To understand how MMA works it's easiest to look at the initial development concept. Initially, a program was wanted which would take a file which looked something like:

Tempo 120
Fm
C7
...

and end up with a MIDI file which played the specified chords over a drum track.

Of course, after starting this “simple” project a lot of complexities developed.

First, the chord/bar specifications. Just having a single chord per bar doesn't work—many songs have more than one chord per bar. Second, what is the rhythm of the chords? What about bass line? Oh, and where is the drummer?

Well, things got more complex after that. At a bare minimum, the program or interface should have the ability to:

Specify multiple chords per bar,
Define different patterns for chords, bass lines and drum tracks,
Have easy to create and debug input files,
Provide a reusable library that a user could simply plug in or modify.

From these simple needs MMA was created.

The basic building blocks of MMA are PATTERNs. A pattern is a specification which tells MMA what notes of a chord to play, the start point in a bar for the chord/notes, and the duration and the volume of the notes.

MMA patterns are combined into SEQUENCEs. This lets you create multi-bar rhythms.

A collection of patterns can be saved and recalled as GROOVEs. This makes it easy to pre-define complex rhythms in library files and incorporate them into your song with a simple two word command.

MMA is bar based.^1.8 This means that MMA processes your song one bar at a time. The music specification lines all assume that you are specifying a single bar of music. Just like in “real” music the number of beats per bar can be changed at any point, percussion notes can occur at any point and chords can be changed at any point.

To make the input files look more musical, MMA supports REPEATs and REPEATENDINGs. However, complexities like D.S. and Coda are not internally supported (but can be created by using the GOTO command).

MIDI File Format

The files generated are standard MIDI. A few points of interest:

By default the generated files are “type 2”. You can change this to “type 1” using the SMF option (see here).
Each of MMA 's tracks are generated as a separate MIDI track.
A comment advertising the creator of the file is inserted into to the META data. Details here.
The length of the generated file in seconds in saved in a META text field labeled “DURATION:”. A custom MIDI file player could use this to easily view the length of the file. This data is placed in the beginning of the MIDI file, before the individual music tracks.

Case Sensitivity

Just about everything in a MMA file is case insensitive.

This means that the command:

Tempo 120

could be entered in your file as:

TEMPO 120

or even

TeMpO 120

for the exact same results.

Names for patterns, and grooves are also case insensitive.

The only exceptions are the names for chords, notes in SOLOs, and filenames. In keeping with standard chord notation, chord names are in mixed case; this is detailed in Musical Data. Filenames are covered in Paths and Filenames.

Script Conventions

A number of the commands available to MMA have builtin options. This section attempts to summarize conventions which may or may not be noted in the relevant sections of the manual. In most cases, this list highlights seldom used items:

True and False

When a function relies on a “TRUE” or “FALSE” setting, you can also use “ON”, “OFF” or “1”, “0” for the identical result. There are a few exceptions and they are noted in the option's description.

Option Pairs

Many option settings rely on a function which parses off options in the format “Option=Value”. Unless otherwise noted, the options can be placed anywhere in the command line. In a few cases the options must be placed at the start of the line so that more option pairs can be passed to a future command.

In all cases, the text “–” (two minus signs) will terminate the scan for more options.

Footnotes

...,^1.1: Musical MIDI Accompaniment and the short form MMA in the distinctive script are names for a program written by Bob van der Poel. The “MIDI Manufacturers Association, Inc.” uses the acronym MMA, but there is no association between the two.
... MIDI ^1.2: MIDI is an acronym for Musical Instrument Digital Interface.
... perspectives.^1.3: The problem, all humor aside, is that the viewpoints of a program's author and user are quite different. The two “see” problems and solutions differently, and for a user manual the programmer's view is not the best.
...mma,^1.4: In the distribution this is mma.py. It is renamed to save a few keystrokes when entering the command.
... editor.^1.5: MMA is pretty open about the “encoding” of the file, but to keep Python 3.x happy you should use “cp1252” (a standard Windows format). If it's a problem, check here. for details on the MMA_ENCODING environment variable.
... slashes).^1.6: The first choice for a comment character was a single “#”, but that sign is used for “sharps” in chord notation.
... “*/”.^1.7: These symbols are used in many other languages, most notably “C”.
... based.^1.8: We really should use the term “measure” to indicate the musical data which, on sheet music, appears between two bar lines, but to stay consistent with modern conventions and MMA 's command set we use the term “bar”.