Date: Wed, 14 Aug 1996 14:01:36 -0700
To: tghack-list@cpac.washington.edu
From: David Shadoff <daves@interlog.com>
X-Software: MLF v2.3, Copyright 1995, 1996 by Bt
X-Original-Id: <199608142101.RAA03979@gold.interlog.com>
Subject: CDROM Music Bytecode

Hi guys...

I have some information about the useful "music language" supported by
the CDROM system card (and likely a common HuCard-based API).

First of all, since I'm not a musician (and didn't even take it way
back in high school), I will likely get some stuff wrong.  Please don't
flame me for this; correct me, since I have no other way of learning
this properly.

First, the data all has to be in the area of MMR's 4&5 ($8000-$BFFF),
and can use 2 segments.  The MMR's 4&5 are 'swapped-out' during the
music interrupt, and restored at RTI time.  It *is* important that
these "relative" memory locations are used (ie. the music code is
*NOT* fully-relocatable), since there will "gosub" and "goto"-like
constructs within the language; they will use memory pointers for
this.

Furthermore, when you 'play a track', you submit the address of a
'header' to the PSG_BIOS.  This header takes the following format:

db voices
dw start_voice1
dw start_voice2
etc. ...

Where 'voices' is a bitmap of which of the 6 voices are in use
(least-significant 6 bits; other bits *may* represent noise, LFO).
The following words are addresses (LSB first) of the various voice
tracks in use (only specify as many as are in use).

I will document the 'develo' system music notation (and how it relates
to this byte-code) in a separate note to follow.


Here is a summary of the 'voice-track' info:

In general, you will specify note/duration pairs, except for "pseudo-ops".
Separate voices will be specified by separate sequences of numbers.
(The above-mentioned 'track header' will specify which voice follows
which code...)

The notes are as follows:

$00 = rest
$10 = 'C' (I imagine that an 'octave' is assumed to start at 'C')
$20 = 'C+'
$30 = 'D'
$50 = 'E'
$60 = 'F'
$70 = 'G-' (or 'F+')
$80 = 'G'
$90 = 'G+'
$A0 = 'A'
$C0 = 'B'

Sorry, but I don't have confirmation on other values (I assume that 'B-'
is $B0, and other flats/sharps fill in the blanks....)

The durations are as follows:
$C0 = whole note, and smaller values are shorter durations
(ie. $60 = 1/2 note... $6 = 1/32 note, etc.)

Here is a partial list of the 'pseudo-ops' (pseudo-ops are values
$D0 and above...):

$D0       = (unsure)
$D1-$D6   = octave 1-6 (may also have octaves 0 and/or 7)
$D7       = (unsure)
$D8       = octave up
$D9       = octave down
$DA       = 'tie' (not sure what this means, but I'm not a musician)
            I suspect it is used to 'slur' two consecutive notes together.
$DB xx    = set tempo.
            Not sure of range, but 75 ($4B) is an example.
$DC xx    = set volume.
            This is a 'per-voice' setting.
$DD xx    = 'pan port'.
            The values appear to be 0-15 on each of 2 channels (balance).
$DE-$E4   = (unknown)
$E5 xx    = not sure.. Japanese katakana states 'o n tsu yo ku'
$E6 xx    = set envelope.
            I suspect there are 'canned' choices on the CD card, but
            I'm not sure.
$E7-$EB   = (unknown)
$EC xx    = 'Descend' ?  Japanese katakana states 'de chi yu-n"
$ED-$EE   = (unknown)
$EF xx xx = 'Jump' to location
$F0 xx xx = 'Gosub' to location
$F1       = 'Return' to calling music code
$F2-$FE   = (unknown)
$FF       = 'data end'