skip to navigation
skip to content

MMLlib 0.3.0.post1

Modern library for handling Music Macro Language

MMLlib - Modern library for handling Music Macro Language


MMLlib is a pure Python implementation of functionality related to the Music Macro Language as implemented by Microsoft® GW-BASIC® and compatibles, which is its most common form, also implemented by the PC speaker driver in Linux and BSD, with a number of extensions and changes:

  • | denotes a bar line, ignored by the Linux/BSD driver
  • support for multiple (parallel) instrument tracks
  • a per-file header with work metadata (optional)
  • lines starting with a # are comments
  • the alias ~ is not supported

The library currently contains functions to:

  • parse an (extended) MML file into metadata and individual tracks
  • a duration estimate and the number of tracks is added to the metadata
  • return a list of tuples (frequency, duration) to play (in a threaded interpreter, such as Floppi-Music)
  • bar lines are indicated separately as integer 1
  • return an event-oriented list of measures / bars across all tracks; each measure has a duration and a list of time-fixed tone on/off events; facilitates playing in non-threaded interpreters and, possibly, MIDI export
  • export (extended) MML to MusicXML
  • which can be imported by e.g. MuseScore to…
    • double-check the MML score for mistakes in a visual representation
    • play, arrange, etc. the music
    • beautify the score to print it as sheet music
    • export into other formats or share on their website
  • check tracks for synchronisation error
  • missing tracks, i.e. with 0 bars
  • missing bars (can only be detected at the end, of course)
  • missing notes within a bar, relative to other tracks


Some example extended MML files are contained within the examples/ directory, in lieu of better documentation for the extended format, in addition to the MML format documentation.

Projects using MMLlib

Floppi-Music has MML as input format for floppy drive music on Raspberry Pi and uses MMLlib for processing. Floppi-Music is also the origin of MMLlib.

Description of the (extended) music macro language

Based on and .

Symbols of MML

 A-G are notes. # or + following a note produces a sharp; - produces a flat.
L(n):Sets the length of each note. L4 is a quarter note, L1 is a whole note, and so on. n may be from 1 to 64. Length may also follow the note to change the length for that note only. A16 is equivalent to L16A. Default is L4.
ML:Music legato. Each note plays the full period set by L.
MN:Music normal. Each note plays seven-eighths of the time determined by L (length).
MS:Music staccato. Each note plays three-quarters of the time determined by L.
N(n):Play note n. n may range from 0 to 84. In the 7 possible octaves, there are 84 notes. n set to 0 (or omitted) indicates a rest.
O(n):Octave 0 sets the current octave. There are 7 octaves (0 through 6). Default is 4. Middle C is at the beginning of octave 2.
P(n):Pause. n may range from 1-64; the current L value is used if omitted.
T(n):Tempo. T sets the number of L4s in a minute. n may range from 32-255. Default is 120.
. (period):A period after a note increases the playing time of the note by 3/2 times the period determined by L (length of note) times T (tempo). Multiple periods can appear after a note, and the playing time is scaled accordingly. For example, A. will cause the note A to play one and half times the playing time determined by L (length of the note) times T (the tempo); two periods placed after A (A..) will cause the note to be played at 9/4 times its ascribed value; an A with three periods (A…) at 27/8, etc. Periods may also appear after a P (pause), and increase the pause length as described above.
>:A greater-than symbol raises the current octave by one.
<:A less-than symbol lowers the current octave by one.
|:Optionally used as a synchronisation mark for multi-track music. This is a proprietary extension in the Floppi-Music project.


Lines starting with # are comments. At the beginning of the file, comments may be used to encode metadata. This is yet to be specified. The current implementation parses key/value pairs separated by a colon and a space, strips both key and value, lower-cases the key and adds it to a dictionary.

The MusicXML export currently specifically recognises these keys:

  • Title, Copyright, Encoder (person), Source
  • Composer, Lyrics, Arranger, Translator xor Artist (deprecated, only one)

Any other key is treated as miscellaneous field.


The voices of a song are interleaved. They are grouped per notation system, and the notation systems are seperated by empty lines.

Changelog for MMLlib


  • Enable Python 3 compatibility.
  • Add new mmllint script.
  • Include example MML songs.
  • Add first parts of test suite.
  • Some bugfixes.


  • Add mml2musicxml script.


  • Separate from Floppi-Music.
File Type Py Version Uploaded on Size
MMLlib-0.3.0.post1-py2-none-any.whl (md5, pgp) Python Wheel 2.7 2017-01-29 20KB
MMLlib-0.3.0.post1-py3-none-any.whl (md5, pgp) Python Wheel 3.5 2017-01-29 20KB
MMLlib-0.3.0.post1.tar.gz (md5, pgp) Source 2017-01-29 25KB