Differences

This shows you the differences between two versions of the page.

--- x68000:mxdrv_mml_mdx_tutorial [2016/01/24 12:34] – created exodusmodules
+++ x68000:mxdrv_mml_mdx_tutorial [2016/11/14 13:10] – [Making a PDX File] exodusmodules
@@ Line 1: / Line 1: @@
-====== MXDRV MML/MDX Tutorial ======
+====== x68k Music: MXDRV MML/MDX Tutorial and Documentation ======
 So, you've been enlighted with the knowledge of a little machine called the
 Sharp x68000.
@@ Line 29: / Line 29: @@
 LOL
-====== x68k Sound Information ======
+===== 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
@@ Line 36: / Line 36: @@
 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 system the PCM8 expansion or PCM8. There is also a software called PCM8
+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 in addition to the normal FM Synthesis and ADPCM.
+MXDRV allows you to use PCM8/Mercury expansion in addition to the normal FM Synthesis and ADPCM.
 ====== Required/Optional Tools and Information Links ======
@@ Line 129: / Line 129: @@
 	http://woolyss.com/chipmusic-mml.php
 	This page has a great deal of MML editors and compilers (though none for the x68k).
-	It MML bundles for various text editors at the bottom of the page (including
+	It has MML syntax highlighters for various text editors at the bottom of the page (including
-	Notepad++), but it was made for PPMCK mml. However, you can still use it.
+	Notepad++), but they were made for PPMCK mml. However, you can still use them.
 ====== General MML Information ======
@@ Line 150: / Line 150: @@
 techniques.
-====== General MML Macros and Syntax ======
+===== 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
@@ Line 338: / Line 338: @@
 	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:
+. I'm assuming you know a bit about synthesis and envelopes here, and
+. 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 */
+, 14, 0, 15,  4, 13, 0, 1,  0, 0, 0,
+, 9, 0, 10,  1, 0, 0, 4,  0, 0, 0,
+, 9, 0, 10,  1, 0, 0, 1,  0, 0, 0,
+, 9, 0, 10,  1, 0, 0, 1,  0, 0, 0,
+		/* CON FL OP */
+, 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.
+< # < 255
+	@v#
+	Set fine volume (for a single channel)
+< # < 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,
+	comments, and metadata 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
+= 3.9kHz
+= 5.2kHz
+= 7.8kHz
+= 10.4kHz
+= 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
+= 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:
+<file>
+#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 */
+, 14, 0, 15,  4, 13, 0, 1,  0, 0, 0,
+, 9, 0, 10,  1, 0, 0, 4,  0, 0, 0,
+, 9, 0, 10,  1, 0, 0, 1,  0, 0, 0,
+, 9, 0, 10,  1, 0, 0, 1,  0, 0, 0,
+		/* CON FL OP */
+, 4, 15
+	}
+A t140 v8 o4 @0 L c4 c4 e8 e8 e-4
+</file>
+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.
+====== Compiling Your 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:
+. A Sharp x68000 emulator - run68k is easy as it emulates human68k, although you
+could use a full Sharp x68k emulator
+. A Sharp x68k MDX compiler - mxc.x from MDX_TOOL is the one I use
+. 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:
+<file>run68 \directory\for\MDX_TOOL\mxc \tune\location\songname.mml</file>
+In a full Sharp x68k emulator or real x68k environment, you can run mxc.x directly:
+<file>mxc songname.mml</file>
+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:
+<file>wav2adp \directory\to\dubstep\somewav.wav</file>
+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:
+<file>
+#ex-pdx 1
+@0
+=some.pcm
+=some.pcm
+=some.pcm
+</file>
+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):
+<file>mkpdx \directory\to\mypdl.pdl</file>
+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:
+<file>#pcmfile "mypdx.pdx"</file>
+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.
+<file>P v8 n21,8 n21,8 ;plays pcm at note 21 with eighth note duration twice</file>