# x68k Music: MXDRV MML/MDX Tutorial and Documentation

So, you've been enlighted with the knowledge of a little machine called the Sharp x68000. It was powerful, beautiful, and maybe even a tad expensive ( that didn't keep people from flocking to purchase one ).

You probably know that one of its major strong points were two sound chips called the YM2151 and the OKI MSM6258.

And as with any computer worth buying, if you're into composing music, then this computer will work for you. Especially since it's got FM audio + ADPCM. Sega Genesis? Who needs it?! It's got a system that will stomp it any day (and yes, I mean the SNES)!

But the blessed Japanese folks were the only ones who got ahold of this machine.

So, what if you wanted to, I dunno, compose music using the x68k's beautiful FM synthesis + ADPCM audio. MXDRV MML is the name of the game (not an actual game though).

The problem is that there's not a lot of documentation on it in English. So make sure you thank me well, and maybe give me a nice pat on the back (and send me lotsa money so I can buy some C64 peripherals, an Amiga 500, a Sharp x68k of my own, and every other vintage computer I'd like to get my bony hands on! Ooops! Forgot to mention the Compaq Presario 425!). Kidding about the money part, although that doesn't mean I won't accept money .

## x68k Sound Information

The Sharp x68000 has two chips for audio within the main unit. These two chips are the Yamaha YM2151 (a.k.a. OPM), and the OKI MSM6258, which are used for FM Synthesis and ADPCM sampled audio respectively.

The early models of the x68k have 8 channels of FM and 1 channel of ADPCM. Later Sharp decided to expand the ADPCM audio, and added 7 extra channels of ADPCM, dubbing the new ADPCM expansion the Mercury unit. There is also a software called PCM8 which uses software mixing to add more ADPCM channels, but from what I've tested of it, it's a CPU cycle thief. There are other software mixing ADPCM TSR drivers, but I haven't tried them.

MXDRV allows you to use PCM8/Mercury expansion in addition to the normal FM Synthesis and ADPCM.

# Required/Optional Tools and Information Links

Here are some useful links to tools and information that you might want to see.

The following tools are required to write MXDRV MML code:

Run68k - Sharp x68k command line emulator, necessary to run x68k programs from
term/cmd:
https://osdn.jp/projects/sfnet_run68/
Alternatively, you can use a full x68k emulator, but I have no idea how you
would handle file transfer that way. The command line emulator has access to
files on your hard drive, so you can run x68k command line programs from your
system'snative command line.
MDX_TOOL - x68k MXDRV tools, necessary to compile your MML->MDX:
http://nfggames.com/x68000/Mirrors/x68pub/x68tools/SOUND/MXDRV/MDX_TOOL.LZH
This archive contains mxc.x, the x68k MDX compiler. You will need to run it
with run68k and your MML file to compile to MDX.
There are other MDX compilers, but this is the one I use.
MKPDX
http://x.haun.org/software/mkpdx/mkpdx.txt
This tool is required to create PDX files. See the section on making a PDX for this.
It's a Win32 executable, so no emulator required (unless you're using Linux or Mac).
WAV2ADP
This tool is required to convert any .wav audio files you have lying around, that
you want to convert to ADPCM for use in a PDX. See the section on making a PDX for this.

GR_ALL.lzh - Battle Garegga MDX tunes:
http://kmkz.jp/mtm/mag/mus/mdxdat/GR_ALL.lzh
This archive contains all the MDX tunes from Battle Garegga, but I mainly linked to it
because it has a PDX file if you don't want to create your own. The PDX contains some nice
samples from synths and drum machines (the TR-909 and others) that Manabu Namiki didn't want, or
need to program as FM instruments.
VOPM - OPM Emulation VST, necessary for making your own FM patches:
http://www.geocities.jp/sam_kb/VOPM/
You can experiment with VOPM and make your own FM sounds, or rip them from other
FM tunes using mdxtools or .opm files from the internet. This is important
because if you don't have any FM patches, you won't be able to make music on an FM
chip lol.

Savihost - Standalone Virtual Instrument Host, necessary if you want to run VOPM without
a DAW:
http://www.hermannseib.com/english/savihost.htm

mdxtools - "A bunch of tools for handling the MDX music format (music for the
Sharp X68000 using the MXDRV sound driver).":
https://github.com/vampirefrog/mdxtools
You need these tools if you want to do things like rip FM patches from other MDX
tunes or decompile MDX. I've only gotten this toolkit to compile on Linux, which
shouldn't be too much of a problem for you if you don't use Linux (VM or dual boot).

opm2mml - A program to convert MiOPMdrv .opm banks to MXDRV mml:
This is a tool I coded in Java to do exactly what the description says. With it, you'll be able to
convert .opm banks to MML. You can find lots of .opm banks online, and you can rip them from software/games on
systems using the YM2151 or YM2612 chips. Even better, you can export VOPM preset banks to .opm, so you can use
your own patches. If, for whatever reason, you need a version in C++ or C because you don't use or like Java, then I may
port it to one of those languages. 

To play your compiled mdx tunes:

mxv - MXDRV World Vision, an MDX player:
The player requires the libraries X68Sound.dll and MXDRV.dll
X68Sound.dll - X68k YM2151 and OKI Emulation library, necessary for mxv:
mxdrv.dll - Mdx driver for Windows, necessary for mxv:

Alternatively, you can use the Winamp in_mdx.dll plugin in Winamp or XMPlay, or use the native MDX player for the X68k
Note that the Winamp plugin requires you to have mxdrv.dll and X68Sound.dll in the same directory as the player (Winamp or XMPlay)
Putting those libraries in the same directory as the plugin will not work if you put your plugins in subdirectories

The following tools and infos are optional:

PPMCK MML Beginner's guide:
http://www.nullsleep.com/treasure/mck_guide/

Notepad++ will make it a lot easier to write in MML in because you can define your own
language syntaxes. I might make an MXDRV MML user defined language someday, but not atm.

Woolyss chipmusic > MML - MML tools and editors
http://woolyss.com/chipmusic-mml.php
This page has a great deal of MML editors and compilers (though none for the x68k).
It has MML syntax highlighters for various text editors at the bottom of the page (including
Notepad++), but they were made for PPMCK mml. However, you can still use them.

# General MML Information

If you don't already know what MML is or how it works, then hold your \$400 studio headphones, because I'm about to explain. Well, only the basics, because a lot of general MML information is already documented in English.

MML, or Music Macro Language, is a programming language used for nothing other than composing music. Sounds a bit masochistic, but it's not as bad as you think, so keep reading.

The core of MML is rooted in traditional musical notation. So it's not like you'll be programming your music routines in assembly…bless Rob Hubbard's heart. But it also means that you'll be doing everything in textual format, unlike many other electronic composition methods.

As with any worthwhile electronic composition method, MML uses commands which allow things like portamento, ties, vibrato, and other important musical techniques.

## General MML Macros and Syntax

Get ready, because I'm about to get straight to the point with this one. If some of these terms are confusing you, then you might need to learn basic music theory.

Macro arguments in brackets are optional, and the brackets are NOT part of the command, with the only exception to this being the loop macro.

!

Ignore all following commands on the current channel
Sort of like commenting out code, although you can use ; or /* */ for that
@#

Select voice, where # = the desired voice(0 - 255)

The precondition here is that the voice must already be defined, else your
compiler will flip you the bird.
Assuming that you're writing this on an FM channel, using this command will
switch to the desired instrument denoted by num. There is a very
important variation of this syntax which I will discuss later.
#TITLE title

Sets the title of a tune

Ex. #title mytune
&

Tie macro
When this macro is used between notes, it will tie to the next note. For porta-
mento, you want to use the glide macro instead. This just 
( )

Decrement/Increment Volume, respectively.
( ~ lowers the volume of the current channel by one
) ~ raises the volume of the current channel by one 
_

Portamento to note
When specified directly after a note, this command will glide to the next note.
Note: the note to be glided to must not have a duration macro after it
Ex. c4_e
glides from c to e in a quarter note
< >

Decrement/Increment octave, respectively.
Where > increments the octave and < decrements it
Use these instead of o when you want to change the octave up or down by a value
of one.
.

Dotted note macro
Add half (of a note's duration) to a note's duration
Ex. c4.
A dotted quarter c note

[]#
Loop macro, loops the macros inside the brackets
The macros to be looped go inside the brackets and # is the number of times to
loop them.

Ex. [c4]3    ~ Plays c quarter note 3 times and exits the loop

/
Break a loop on the last iteration
This macro goes inside the brackets with the rest of the macros

Ex. [c4 / d4]4		~ Plays c quarter note four times, but d quarter only 3
times
;
Line comment
Use this to comment on a single line
/* */

Block comment
Use this to make a comment that extends multiple lines or to make single line
comments look nicer
chan

Specify the channel
Where chan is the corresponding letter for the channel. This macro must always
be at the beginning of a line in which you intend to coerce any digital farts
out of your poor x68k (or emulator).

Ex. A  		~ This sets the current channel to channel A
D#

Detune current voice
Where # is the value to detune by in 1/64 semitones
k#

Delay macro
Where # is the number of ticks to delay by
L
Set loop start
Use this command in a channel when you wish to loop everything after this
command
l[length]

Set the default note length.
Where length is the numerical value of the length in powers of two (ex. l4
sets default note length to quarter notes).

When a note is specified without a length after, the note will default
to this length. If this command is not set, the default length is set to 4,
a.k.a. a quarter note
MPwaveform,speed,depth
Set pitch LFO
Where waveform is the LFO waveform (0 = sawtooth, 1 = square, 2 = triangle),
speed is 1/4 of the LFO cycle in ticks, and depth is the
max amplitude of the LFO.
Useful for vibrato.

MPON
Turn pitch LFO on for current channel, only needed if you have turned the
pitch LFO off (setting the LFO automatically turns it on).

MPOF
Turn pitch LFO off for current channel. Only needed when it is already on.
n#,length

Play a note by its numerical value, with the length separated by a comma.
"length" is the length of the note in eights. See the next entry for proper
lengths.
Ex. n21,8
Play note 21 as an eigth note
note[accidental][length]

Play a note with the desired length.
Where "note" is the letter of the musical note you want to play (a-g),
"accidental" is the desired accidental (+ for sharp and - for flat),
and "length" is the length of the note in eights.
For the note lengths, you can use any standard note length:
1 - whole note
2 - half note
4 - quarter note
8 - eighth note
16 - sixteenth note
32 - thirty-second note

Any length not a power of 2 or > 32 is not supported and will cause your compiler to
question your sanity. When a length is not specified, the compiler will default
to the default length, which is by default a quarter note unless you specified
otherwise. Unless you specified the default length as something like 33, which
will mean that your compiler will complain that DE fault was yours...by default. :-P

Ex. c4 - play the note c as a quarter note
Ex. e-8 - play the note e flat as an eighth note
Ex. c - play the note c with whatever the default note length is
o#

Set the octave.
Where # is the desired octave (0 - 9)
q#

Note cutoff (stacatto)
Sets note duration (in eights) of cutoff. Range is 1 - 8 inclusive.
t#

Set the tempo
Where # = the number of quarter notes per second

Ex. t180
v#

Set the coarse volume, where # is a number between 0 and 15

## MXDRV MML Macros and Syntax

The following macros are MXDRV specific:

#PCMFILE "somefile.pdx"

Includes a PDX pcmfile, for pcm audio
This file will need to be in the same directory as your mdx when you want to
listen to your compiled code (with pcm samples)

Ex. #pcmfile "GR-PCM.pdx"
@#={
AR, DR, SR, RR, SL, OL, KS, ML, DT1, DT2, AME,
AR, DR, SR, RR, SL, OL, KS, ML, DT1, DT2, AME,
AR, DR, SR, RR, SL, OL, KS, ML, DT1, DT2, AME,
AR, DR, SR, RR, SL, OL, KS, ML, DT1, DT2, AME,
CON, FL, OP
}

Voice Definition macro
As the YM2151 is a four operator FM chip, in order to define the voices, you
must define each operator, and the voice's parameters.
Two things here:
1. I'm assuming you know a bit about synthesis and envelopes here, and
2. I'm not an expert on FM Synthesis :-P, but I will tell you what I know

AR = Attack Rate. How quickly you want the operator to reach full amplitude.

DR = Decay Rate. How quickly you want the operator to reach the sustain.

SR = Sustain Rate. How quickly you want the operator to reach the release after
a note off.

RR = Release Rate. How quickly you want the amplitude to reach zero after a
note off.

SL = Sustain Level. The amplitude of the operator during sustain.

OL = ?

KS = Key sync

ML = Phase multiplicity

DT1 = Detune in Hz from base note * ML

DT2 = Detune in semitones

AME = Enable amplitude modulation for current operator.
Setting this value to a 1 will enable the amplitude modulation for the
op and 0 will disable it.

CON = FM synthesis connection/algorithm, determines how the operators are routed.
You would want to play with VOPM to figure these out.

FL = Feedback level, setting this to higher values distorts the voice

OP = ? I always see this value set to 15, so I don't know what it does

Here's an example bass voice:
@2={
/* AR DR SR RR SL OL KS ML DT1 DT2 AME */
31, 14, 0, 15,  4, 13, 0, 1,  0, 0, 0,
31, 9, 0, 10,  1, 0, 0, 4,  0, 0, 0,
31, 9, 0, 10,  1, 0, 0, 1,  0, 0, 0,
31, 9, 0, 10,  1, 0, 0, 1,  0, 0, 0,
/* CON FL OP */
5, 4, 15
}

It will be easier for you to rip voices from other tunes or make them in VOPM
than to program them on the fly. See the resources for my program opm2mml which
will automatically convert MiOPMdrv (.opm) patches to MML for you.
@t#

Set the value of OPM register B, consequently setting the tempo
This is different from the t command, which is what you'd want to use normally.
0 < # < 255
@v#

Set fine volume (for a single channel)
0 < # < 255
This allows more precise control over the volume. For effects like fade-ins or
fade outs, you can use coarse volume instead (unless you find pain pleasurable)
A-H, P-W

Set channel
This macro must always appear at the very beginning of a line in which
you intend to sequence notes and macros. The exceptions are voice definitions,
Ex. A
sets channel to A (FM channel 1)

Ex. P
Sets channel to P (PCM channel 1)
F#

Change PCM frequency (pitch)
Range is 0-4 inclusive, default is 4

0 = 3.9kHz
1 = 5.2kHz
2 = 7.8kHz
3 = 10.4kHz
4 = 15.6kHz

This changes the frequency of the ADPCM samples being played back. Really wish
that the OKI had note sample pitching instead of this, but nope, it would have to be done
through software, and MXDRV doesn't have an implementation for this.

(One of the things on my bucket list is to make a chiptracker for the x68k which
allows pitched samples)
MAwaveform,speed,amplitude
Set amplitude LFO
Where waveform is the LFO waveform (0 = sawtooth, 1 = square, 2 = triangle),
speed is 1/4 of the LFO cycle in ticks, and amplitude is the max amplitude
of the LFO.

MAON
Turn amplitude LFO on for current channel, only needed if you have turned the
amplitude LFO off (setting the LFO automatically turns it on).

MAOF
Turn amplitude LFO off for current channel. Only needed when it is already on.
MD#
Set the delay from note on to LFO start(excluding OPM LFO)
Where # is the delay in ticks
MH#1,#2,#3,#4,#5,#6,#7

Set OPM LFO values
#1 = LFO Waveform (0 = sawtooth, 1 = square, 2 = triangle)
#2 = LFRQ
#3 = PMD
#4 = AMD
#5 = PMS
#6 = AMS
#7 = Key sync (0 = no sync, 1 = sync)

MHON
Turn OPM LFO on for current channel (setting OPM LFO automatically turns it on)

MHOF
Turn OPM LFO off for current channel.
p#

Set (hard) panning position
0 = no output, 1 = left, 2 = right, 3 = center
@q#

Note cutoff (stacatto) in ticks
Set the cutoff of a note, with duration in ticks.
S#

Sync send macro
Continue playback on channel if it is in sync wait mode
y[reg],[val]

Write OPM register reg with value val 
w#

Set OPM Noise frequency
W

Sync wait macro
Set current channel in sync wait mode, pausing playback of the channel

# Short Tutorial

So, now that you know all of the macros used in MXDRV mml, you need to know how to correctly use them to make an MDX tune.

Here is a short sample MML source code:

#title "Darude - Sandstorm" ;song name?
#pcmfile "SampleText.pdx"

;below is the instrument 0 definition
@0={
/* AR DR SR RR SL OL KS ML DT1 DT2 AME */
31, 14, 0, 15,  4, 13, 0, 1,  0, 0, 0,
31, 9, 0, 10,  1, 0, 0, 4,  0, 0, 0,
31, 9, 0, 10,  1, 0, 0, 1,  0, 0, 0,
31, 9, 0, 10,  1, 0, 0, 1,  0, 0, 0,
/* CON FL OP */
5, 4, 15
}
A t140 v8 o4 @0 L c4 c4 e8 e8 e-4

So here, I first set the title of the song to “Darude - Sandstorm”, using the title macro. I then specified the PCM file as “SampleText.pdx”, then defined instrument 0's FM parameters. Then on channel A, I set the song tempo to 140, set the channel volume to 8 (max volume), set the octave to 4, the instrument to 0. I then set the rest of the following code to loop, and played the notes c-quarter, c-quarter, e-eigth, e-eigth, and e-flat-quarter. When compiled into MDX and played back, it should play those notes a few times in a loop before stopping.

You can put spaces between some (but not all) macros to make your MML source code cleaner and more readable. I should have told you which ones you can and cannot in the documentation.

With the documentation on all the commands, this should show you how to code your MML tune.

So now that I've included a short sample tune (nothing special, just random notes), now you need to know how to compile it.

If you have all the required tools, you will need the following for compilation:

1. A Sharp x68000 emulator - run68k is easy as it emulates human68k, although you could use a full Sharp x68k emulator

2. A Sharp x68k MDX compiler - mxc.x from MDX_TOOL is the one I use

3. Your MML source code (go figure) as a .mml plain text file

From the command line, to compile your .mml tune to MDX, run the following command:

run68 \directory\for\MDX_TOOL\mxc \tune\location\songname.mml

In a full Sharp x68k emulator or real x68k environment, you can run mxc.x directly:

mxc songname.mml

If your code is syntactically correct, you should have a resulting .mdx file in the directory where your source was.

# Making a PDX File

To make a PDX, you first need to get some raw ADPCM files (.pcm extension).

You can either rip them from games with ADPCM chips, or convert wav files to the format with WAV2ADP (link in tools section).

To convert a wav to PCM, run the following in cmd or human68k:

wav2adp \directory\to\dubstep\somewav.wav

If you're using run68k, then just put “run68” at the beginning.

After you've got an ADPCM or two, you'll need to put all your pcm's into a PDX with mkpdx (link in tools as well). But first, you'll need to make a PDL file mapping all of the PCMs to the desired note values.

A PDL file is just a plain text file.

Example PDL:

#ex-pdx 1

@0
21=some.pcm
23=some.pcm
31=some.pcm

Here, I specify something important at the beginning: I am using ex-pdx.

Later after MXDRV was created, the PDX file format was extended so one could switch ADPCM banks for tons of PCM files in a single PDX. A single bank can have a maximum of 90 or so ADPCM binaries.

I then defined which ADPCM bank I want to define with “@0”. Then I set notes 21, 23, and 31 to “some.pcm”.

After you finish your PDL file, you'll need to make your PDX. Run the following in CMD (or just drag and drop your pdl on mkpdx):

mkpdx \directory\to\mypdl.pdl

The mkpdx binary I provided is for Win32, so you don't need to use an x68k emulator or DOSBox for it.

If your PDL file is syntactically correct, then mkpdx will spit out a PDX file in the same directory as your PDL.

Now you can use your PDX in your MML tunes by defining the following at the top:

#pcmfile "mypdx.pdx"

To use PCM in a MML tune, use channels P-W. It's easier to use the numerical note values for PCM than it is to use letter notes.

Ex.

P v8 n21,8 n21,8 ;plays pcm at note 21 with eighth note duration twice