Music Macro Language

Music Macro Language (MML) is a music description language used for sequencing music on computers and video game systems. Music is written as strings of letters and numbers representing notes, durations and control parameters, which are then interpreted or compiled for the target system's sound hardware.

The designation is documented in print by May 1982, in a description of the OKI if-800. Microsoft source code from 1983 labels the BASIC PLAY implementation "MUSIC MACRO LANGUAGE", and NEC documentation from 1986 describes the channel strings of CMD PLAY as "MML (Music Macro Language)".

History

Origins of the term

The designation Music Macro Language (MML) is documented in published sources by May 1982. In that month's issue of BYTE, an article on Japanese personal computers described the OKI if-800 using the term for its music-string syntax. The article states that "another sublanguage called MML (Music Macro Language) is used".

Microsoft documentation for GW-BASIC later described the syntax used by the PLAY statement as "a music macro language" embedded in a string expression. The notation is treated as a non-MIDI music code in Beyond MIDI: The Handbook of Musical Codes.

Music-string notation itself predates GW-BASIC. Contemporaneous BASIC documentation, such as the OKI BASIC manual, describes the PLAY statement for musical sequences but does not use the term "Music Macro Language".

Microsoft BASIC and NEC documentation

Microsoft's 1983 GW-BASIC source code labels the PLAY implementation "PLAY - MUSIC MACRO LANGUAGE". The implementation supplies a table of music commands to a shared macro-language driver, which the source identifies as supporting the Microsoft graphics and sound macro languages.

By 1986, NEC's PC-8801mkIIMR N88-BASIC / N88-日本語BASIC Reference Manual documented the extended CMD PLAY statement and called its channel strings "MML (Music Macro Language)". The manual gives command tables and explanations for notes, duration, octave, tempo, rests, volume, articulation, timbre selection and FM/SSG-related parameters.

Neither the originator of the term nor any direct relationship between the OKI if-800 implementation and the Microsoft implementation is identified in these sources.

Dedicated music drivers and compilers

During the 1980s MML was also used as input to dedicated music-development systems, and not only as an argument to a BASIC statement. Tanaka describes the PC-8801 sound system SPLIT in connection with MML-based music development and compilation, and states that general distribution of SPLIT began at the summer Comic Market on 14 August 1988 and that twelve releases followed through 1991.: 126–127, 133–134  The same source discusses FMP and PMD within the history of MML-based Japanese personal computer music systems.: 130–131 

Background

Early automatic music generation functions were used in arcade video games. Early examples of arcade video game music include Gun Fight (1975) and Circus (1977).[citation needed] The appearance of Space Invaders by Taito in Japanese amusement arcades in 1978 marked a considerable expansion of the domestic video game market.[citation needed]

Music in these systems was generally implemented as proprietary game software.[citation needed] The Intel 8253 programmable interval timer, released by Intel in 1978, provided one hardware approach to programmable tone generation; its Mode 3 square-wave generator was used for music in the kit computer MZ-40K (Microcomputer Doctor (マイコン博士, Maikon Hakase)) by Sharp Corporation, manufactured in Japan in May 1978.[citation needed] Another microcomputer, the Hitachi BASIC MASTER MB-6880 (ベーシックマスター, Bēshikku Masutā), used a 5-bit digital-to-analog converter for automated music reference signals, together with methods of generating music under BASIC software control. That machine was assembled by Hitachi and made in Japan in September 1978. The MZ-40K documentation included program sources for some software routines.[citation needed]

Music-string notation and MML syntax

Sharp MZ BASIC music-string notation

On the MZ-80K and related Sharp MZ systems, music-string facilities were provided through the SP-1002 monitor IOCS routine and the SP-5001 BASIC operating system, using the BASIC statements MUSIC, TEMPO and BEEP. The MZ-80K was an 8-bit machine with a Z80 processor, made by Sharp Corporation in Japan in 1978, and it used Intel 8253 hardware with memory-mapped I/O.

Syntax

Page 110 of a Sharp Corporation MZ-80 BASIC manual, describing the MUSIC statement and its music-string notation.

The music string is supplied to the MUSIC statement. Notes are specified within a three-octave range, and a piece is a sequence of single monophonic tones.

"+" (or, in some older code, "￣") indicates the upper octave, and "−" (or, in some older code, "_") the lower octave. The characters C, D, E, F, G, A and B correspond to the degrees of the scale. A semitone is indicated by following the note with a "#" character. Note names are followed by a tone length, given as a number from 0 to 9; R indicates a rest and is likewise followed by a number from 0 to 9. The resulting duration is the internal value multiplied by the TEMPO value. Tone length 0 corresponds to a demisemiquaver (SP-1002 internal value 1) and 9 to a whole note (SP-1002 internal value 32). Music is played by a call to the routine at address $0030 of the SP-1002 IOCS.

The sound length
ValueLength
0 1/32
1 1/16
2 dotted 1/16
3 1/8
4 dotted 1/8
5 1/4
6 dotted 1/4
7 1/2
8 dotted 1/2
9 1

The statement TEMPO n accepts values from 1 to 9, 1 being the slowest; TEMPO 4 corresponds approximately to T = 120.

Example

The following is a transcription of the Japanese song "tōryanse" in the MUSIC-statement notation of the MZ-731 with SHARP S-BASIC 1Z-007B (upward compatible with SP-5001).

10 TEMPO 4
20 A$="E5R1E3R0D3R0E3R0E1R0D1R0-B4R1"
30 B$="F3R0F1R0F1R0A3R0F1R0E1R0F1R0E1R0D1R0D1R0E4R1"
40 C$="C3R0C1R0C1R0E3R0C1R0-B1R0C1R0-B1R0-A1R0-A1R0-B4R1"
50 D$="E1R0E1R0E1R0E1R0E1R0E1R0D1R0E1R0E1R0E1R0D1R0-A1R0-A1R0-B4R1"
60 E$="-A1R0-B1R0C1R0D1R0E1R0F1R0E1R0F3R1A3R1B1R0A1R0F3R0E3R0E1R0D1R0E4R1"
100 MUSIC A$+B$+B$
110 MUSIC C$+C$+B$
120 MUSIC C$+D$+E$

MML in BASIC PLAY implementations

MML of the kind found in PLAY statements originated in Microsoft BASIC and was widely used on 8-bit and 16-bit Japanese personal computers, where BASIC was generally supplied in ROM. The NEC PC-6001 of 1981 combined Microsoft BASIC with a programmable sound generator, and the notation was particularly widespread on NEC machines such as the PC-8801. The designation MML is documented for personal computer music strings by May 1982 in the description of the OKI if-800, and Microsoft's 1983 GW-BASIC source code labels its PLAY implementation "PLAY - MUSIC MACRO LANGUAGE", routing its command table through a shared macro-language driver. NEC documentation likewise records BASIC music-string implementations: the PC-6001mkII N60m-BASIC manual documents PLAY with up to three simultaneous parts, and the 1986 PC-8801mkIIMR reference manual calls the CMD PLAY channel strings "MML (Music Macro Language)" while documenting extensions for programmable sound hardware.

Following the 2001 release of mck (Music Creation Kit), which compiles MML into music for the Nintendo Entertainment System, awareness and use of MML increased. The notation remains in use among Japanese electronic musicians and among musicians who write chiptunes.

Syntax

In the Microsoft and NEC implementations, a PLAY or CMD PLAY statement takes an argument containing the music data as a string. Microsoft's 1983 source shows a command-table parser for the PLAY string, and NEC's 1986 manual documents the MML commands accepted by CMD PLAY. The format is textual, letters and numbers describing the musical notes to be played, but implementations differ in their command sets and in the extensions they add for audio synthesis parameters or for common musical figures such as arpeggios.

Elements common to many implementations are listed below; individual dialects may omit, rename or extend them, and requirements such as letter case also vary.

  • cdefgab – The letters a to g correspond to the musical pitches and cause the corresponding note to be played. Sharp notes are produced by appending a + or #, and flat notes by appending a -. The length of a note is specified by appending a number representing its length as a fraction of a whole note; for example, c8 represents a C eighth note, and f+2 an F♯ half note.
  • p – A pause or rest, sometimes also r. IBM Personal Computer BASIC Version 1.10 uses P, as do GW-BASIC-compatible speaker interfaces such as the Linux and BSD speaker devices. The length of the rest is specified in the same manner as the length of a note; for example, r1 produces a whole rest.
  • o – Followed by a number, selects the octave in which the instrument plays.
  • >, < – Step up or down by one octave.
  • l – Followed by a number, specifies the default length used by notes or rests that do not define one explicitly. For example, l8 g a b g l16 g a b g produces four eighth notes followed by four sixteenth notes.
  • v – Followed by a number, sets the volume of the instrument. The permitted range depends on the sound hardware. Some implementations also allow an ADSR envelope to be applied to the amplitude of each note.
  • t – Followed by a number, sets the tempo in beats per minute. On hardware with more than one sound channel it is often possible to set each channel to a different tempo.

Most implementations add further keywords and symbols for system-specific extensions.

Example

The following is an MML transcription of Dance of the Cuckoos, with white space added for clarity; some MML interpreters require it to be removed before playback.

t104
l4
>
c16f16
a>c8<a c16f16
a>c8<a c8
b-8>c8<b-8 g c8
a8>c8<a8 f c16f16
a>c8<a c16f16
a>c8<a c8
b-8>c8<b-8 g >c8
<f2

The following is a transcription of "tōryanse" in the N60-BASIC of the PC-6001 (NEC PC-6000 series), given for comparison with the Sharp MZ MUSIC example above.

10 A$="o4e2r32e4r32d4r32e4r32e8r32d8r32o3b2r16"
20 B$="o4f4r32f8r32f8r32a4r32f8r32e8r32f8r32e8r32d8r32d8r32e2r16"
30 C$="o4c4r32c8r32c8r32e4r32c8r32o3b8r32o4c8r32o3b8r32a8r32a8r32b2r16"
40 D$="o4e8r32e8r32e8r32e8r32e8r32e8r32d8r32"
50 E$="o4e8r32e8r32e8r32d8r32o3a8r32a8r32b2r16"
60 F$="o3a8r32b8r32o4c8r32d8r32e8r32f8r32e8r32"
70 G$="o4f4r32a4r32b8r32a8r32f4r32"
80 H$="e4r32e8r32d8r32e2r16"
100 PLAY "t120"
110 PLAY A$
120 PLAY B$
130 PLAY B$
140 PLAY C$
150 PLAY C$
160 PLAY B$
170 PLAY C$
180 PLAY D$
190 PLAY E$
200 PLAY F$
210 PLAY G$
220 PLAY H$

SMX

Standard Musical Expression (SMX) is a music-string format used by the PLAY statement of Microsoft QBASIC, BASICA and GW-BASIC. In Beyond MIDI, MML is listed among the non-MIDI codes for sound representation and control, whereas SMX is listed among the interchange codes. Microsoft's own GW-BASIC source calls the implementation a music macro language. The version used by GW-BASIC is part of the modern BSDs, including FreeBSD, NetBSD, OpenBSD and MirOS; the language is described in speaker(4).

BASIC music-string comparison

The following examples give the same melody, "Twinkle, Twinkle, Little Star", in two BASIC music-string syntaxes: the MUSIC notation of Sharp MZ BASIC and the PLAY notation of NEC N60-BASIC.

Sharp MZ BASIC (SP-5030)

Characteristics:

Example

10 TEMPO 4
20 A$="C3C3G3G3A3A3G6"
30 A$=A$+"F3F3E3E3D3D3C6"
40 A$=A$+"G3G3F3F3E3E3D6"
50 A$=A$+"G3G3F3F3E3E3D6"
60 A$=A$+"C3C3G3G3A3A3G6"
70 A$=A$+"F3F3E3E3D3D3C6"
80 MUSIC A$

The musical data is built up step by step as a BASIC string variable, extended by concatenation (A$=A$+"...") before being passed to the MUSIC command for playback.

NEC PC-6001 (N60-BASIC)

The PC-6001mkII N60m-BASIC manual describes PLAY as a statement for generating music and documents the use of up to three simultaneous parts.

Characteristics:

Example

10 PLAY "T120 O4 L4"
20 PLAY "C C G G A A G2"
30 PLAY "F F E E D D C2"
40 PLAY "G G F F E E D2"
50 PLAY "G G F F E E D2"
60 PLAY "C C G G A A G2"
70 PLAY "F F E E D D C2"

Example 2

100 PLAY "t120v14l4o5s11","v13l4o4","v15l4o3"
110 PLAY "ccgg","eeo5cc","cccc"
120 PLAY "aagr","o5ddco4r","ffgr"
130 PLAY "ffee","aagg","ffee"
140 PLAY "ddcr","ffer","ddcr"
150 PLAY "ggff","o5cco4bb","cccc"
160 PLAY "eedr","aagr","ccgr"
170 PLAY "ggff","o5cco4bb","cccc"
180 PLAY "eedr","a8b8o5c8o4b8gr","ffgr"
190 PLAY "ccgg","eeo5cc","cccc"
200 PLAY "aagr","ddco4r","ffgr"
210 PLAY "ffee","aagg","ffee"
220 PLAY "ddcr","ffgr","ddcr"

NEC PC-8801mkIIMR (N88-BASIC Version 2.0)

NEC's 1986 reference manual documents the extended CMD PLAY statement and defines its channel strings as MML. The extended statements are enabled with NEW CMD.

NEW CMD

The following three-channel example shows CMD PLAY syntax with FM timbre selection:

100 CMD PLAY "t120@5v15l4o5","@7v14l4o4","@4v15l4o4"
110 CMD PLAY "ccgg","ee>cc","cccc"
120 CMD PLAY "aagr","ddc<r","ffgr"
130 CMD PLAY "ffee","aagg","ffee"
140 CMD PLAY "ddcr","ffer","ddcr"
150 CMD PLAY "ggff",">cc<bb","cccc"
160 CMD PLAY "eedr","aagr","ccgr"
170 CMD PLAY "ggff",">cc<bb","cccc"
180 CMD PLAY "eedr","a8b8>c8<b8gr","ffgr"
190 CMD PLAY "ccgg","ee>cc","cccc"
200 CMD PLAY "aagr","ddc<r","ffgr"
210 CMD PLAY "ffee","aagg","ffee"
220 CMD PLAY "ddcr","ffgr","ddcr"

Early BASIC music-string implementations of this kind relied in part on the surrounding program structure, whereas later systems placed more of the musical control parameters inside the music string itself. The conventions they established, such as note letters, octave control and tempo parameters, were carried over into the music drivers and composition environments developed for programmable sound hardware on platforms including the NEC PC-8801 and PC-9801, among them the Professional Music Driver.: 126–131 

Languages, platforms and software

MML is a family of related text-based music notations rather than a single fixed language. Implementations range from BASIC PLAY and MUSIC statements to dedicated music drivers, compilers, operating system sound interfaces, chiptune tools, ringtone formats and in-game score systems, and commonly add commands suited to the target hardware.: 126–131 

See also

References

  1. 1 2 3 Kocher, Christopher P.; Keith, Michael (May 1982). "Six Personal Computers from Japan". BYTE. Vol. 7, no. 5. p. 66. Retrieved 2026-08-17. Another sublanguage called MML (Music Macro Language) is used.
  2. 1 2 3 4 5 6 Microsoft Corporation. "GWSTS.ASM". GitHub. Microsoft. Retrieved 2026-08-17. PLAY - MUSIC MACRO LANGUAGE
  3. 1 2 3 4 5 6 7 日本電気株式会社 (1986). PC-8801mkIIMR N88-BASIC / N88-日本語BASIC REFERENCE MANUAL (in Japanese). 日本電気株式会社. pp. 4-9 – 4-17. Retrieved 2026-08-17 – via Internet Archive.
  4. 1 2 Microsoft GW-BASIC User's Guide and Reference (PDF). Microsoft. 1989. Retrieved 2026-08-17.
  5. 1 2 3 4 5 6 7 Selfridge-Field, Eleanor, ed. (1997). Beyond MIDI: The Handbook of Musical Codes. Cambridge, MA: MIT Press. ISBN 978-0-262-19394-8.
  6. ↑ IF800によるBASICテキスト (in Japanese). コロナ社. 1982. pp. 137–139. Retrieved 2026-08-17.
  7. 1 2 Microsoft Corporation. "MACLNG.ASM". GitHub. Microsoft. Retrieved 2026-08-17.
  8. 1 2 3 4 田中, 治久 (May 2017). チップチューンのすべて [All About Chiptune] (in Japanese). 東京: 誠文堂新光社. ISBN 978-4-416-61621-5.
  9. 1 2 Nagai, Kunihiko; Takezawa, Teruhiro; Yoshimura, Kazuma; Tajima, Katsutoshi (1979-04-26). "Hitachi Hyoron April 1979 Special Features: A micro-computer, the application method". Hitachi (in Japanese). Archived from the original on 2015-05-08. Retrieved 2013-08-26.
  10. 1 2 "SHARP MZ.org MZ-80K monitor sub $0030". Archived from the original on 2015-09-26. Retrieved 2012-09-19.
  11. ↑ Ohishi, Nobuaki. "Nibbles lab. SHARP Museum, MZ-80K Photo and Catalog". Retrieved 2012-09-20.
  12. 1 2 3 SHARP Corporation (1978). MZ-80 BASIC SP-5030 マニュアル (in Japanese). SHARP Corporation. p. 110.
  13. ↑ "SHARP MZ.org MZ-80K monitor sub $0030". Archived from the original on 2015-09-26. Retrieved 2012-09-19.
  14. ↑ "SHARP MZ.org MZ-700 monitor sub $0030". Archived from the original on 2015-05-09. Retrieved 2012-09-19.
  15. ↑ Motoi, Kenkichi (2012-09-19). "Viewpoint of the eye. She said "you playing" I'm crying". Awamomo Office (in Japanese). Retrieved 2026-08-16. Licensed #AAAP, including Creative Commons CC-BY-SA and the GNU Free Documentation License.
  16. 1 2 3 4 日本電気株式会社. PC-6001mkII N60m-BASICマニュアル (in Japanese). 日本電気株式会社. pp. 3-112 – 3-113.
  17. 1 2 "VORC Internet Chiptune Encyclopedia – mck". Archived from the original on 2008-01-03. Retrieved 2008-02-13.
  18. 1 2 3 "VORC Internet Chiptune Encyclopedia – MML". Archived from the original on 2007-11-23. Retrieved 2008-02-13.
  19. ↑ "VORC: VGM or Chiptune of The Year 2001". 2001-12-31. Retrieved 2008-02-13.
  20. ↑ Johnson, Jeremiah. "MCK/MML Beginners Guide". Archived from the original on 2007-12-14. Retrieved 2008-02-13.
  21. ↑ "IBM BASIC manual, Second Edition (May 1982), Version 1.10" (PDF). Archived from the original (PDF) on 2015-06-15. Retrieved 2016-03-26.
  22. 1 2 3 "speaker(4) manual page". MirBSD. Archived from the original on 2019-04-03. Retrieved 2026-08-17.
  23. ↑ Programmed by MOTOI Kenkichi, 11 November 2024. Licensed #AAAP, including Creative Commons CC-BY-SA and the GNU Free Documentation License.
  24. ↑ "Beyond MIDI: The Handbook of Musical Codes – Table of Contents". Center for Computer Assisted Research in the Humanities. Retrieved 2026-08-17.
  25. ↑ "FreeBSD speaker(4) manual page". Retrieved 2026-08-17.
  26. ↑ QBasic manual. Microsoft Corporation. 1991.
  27. ↑ IBM Personal Computer BASIC manual. IBM Corporation. 1982.
  28. ↑ BASICA manual. Microsoft Corporation. 1982.
  29. ↑ Microsoft Corporation. Microsoft QuickBASIC 4.5, 2nd Edition Manual. Microsoft Corporation. Retrieved 2026-08-17 – via Internet Archive.
  30. ↑ Raymond, Eric S. (1995-05-07). "Eric Raymond's Open-Source Works". Retrieved 2020-07-03.
  31. ↑ Koshiro, Yūzō. "Yuzo Koshiro Interview" (Interview). Interviewed by Kikizo Games. Retrieved 2008-02-13.
  32. ↑ Szczepaniak, John. "Retro Japanese Computers: Gaming's Final Frontier". Hardcore Gaming 101. Retrieved 2011-03-29. Reprinted from Retro Gamer, 2009
  33. ↑ "ツールのお部屋" (in Japanese). Retrieved 2019-12-01.
  34. ↑ "VORC Internet Chiptune Encyclopedia – ppmck". Archived from the original on 2006-10-12. Retrieved 2008-02-13.
  35. ↑ Swimm, Peter (2009-12-21). "XPMCK – Cross Platform Music Compiler Kit updated". True Chip Till Death. Retrieved 2011-12-29.
  36. ↑ "着信メロディは再び自分で作る時代に？──MIDIファイルやWAVファイルを着メロに変換" (in Japanese). ITmedia. 2001-04-03. Retrieved 2008-02-13.
  37. ↑ "ANSI Music – The Technical Details". Retrieved 2009-01-16.
  38. ↑ "PLAYX (E500)" (in Japanese). Archived from the original on 2016-03-03. Retrieved 2016-03-03. See also ja:ポケットコンピュータの製品一覧.
  39. ↑ "Macrotune". Retrieved 2016-03-03.
  40. ↑ "FlopPI-Music". Retrieved 2016-04-08.
  41. ↑ "3MLE" (in Japanese). Retrieved 2016-03-03.