README

   1
   2                           YMamoto Alpha Zero
   3                  Julian Squires <tek@wiw.org> / 2004
   4
   5                             ABOUT YMAMOTO
   6
   7 YMamoto is my first attempt at a reasonable music playroutine for the
   8 Atari ST.  The design goal is to allow the production of interesting
   9 music; I considered adding efficiency of {memory usage, song size,
  10 cycles per frame} to the set of goals, but I decided that aiming at
  11 any of these things directly would just cripple the main goal, until I
  12 am more familiar with the ST and the YM.
  13
  14 So, YMamoto, when finished, should be suitable at least for music
  15 disks and parts of demos where cycles aren't too scarce.
  16
  17
  18                    USING YMAMOTO IN ANOTHER PROGRAM
  19
  20 Call ymamoto_init with A0 pointing to the song data, and D0 set to the
  21 track index to play.  Note that the first track index is 1, not 0.
  22
  23 Call ymamoto_update once per frame until it returns $FFFF in D0.
  24
  25 FIXME: Eventually there will be a way to use trigger events to allow
  26 you to sync your effects to the music.
  27
  28
  29                          YMAMOTO DATA FORMAT
  30
  31 All relative pointers are to long aligned addresses, and hence the
  32 pointers are stored as shorts, and shifted left two bits to get the
  33 actual address.  These pointers are relative to the beginning of the
  34 song data, not their current position, and are always forward
  35 references, so they don't get sign extended when loaded from words.
  36
  37 SONG
  38
  39 pointer to arpeggio table (word, relative, >>2)
  40 pointer to volume envelope table (word, relative, >>2)
  41 pointer to vibrato table (word, relative, >>2)
  42 number of tracks (byte)
  43         Should always be >=1.
  44 offset to track 0 (word, relative, >>2)
  45 offset to track ...
  46
  47
  48 TRACK (long aligned)
  49
  50 channel A start point (word, relative, >>2)
  51 channel B start point (word, relative, >>2)
  52 channel C start point (word, relative, >>2)
  53
  54
  55 CHANNEL DATA STREAM (long aligned)
  56
  57 The two kinds of values possible in the channel data stream are notes
  58 and commands.  They can be determined by the value of their MSB, which
  59 is 0 for notes, and 1 for commands.
  60
  61 Notes are stored in the following inefficient way:
  62         0ddd dddd rnnn nnnn
  63                 d => duration, in frames-1, from 0 (1/50th of a second)
  64                      to 127 (2.56 seconds).
  65                 r => reserved (0).
  66                 n => tone, value from 0 = C0, 95 = B7.
  67                      126 = wait, 127 = rest (wait, silence channel).
  68                      Other values might be used for special purposes.
  69
  70 Global commands: (can occur in any channel; need only occur once)
  71         10rr rccc  xxxx xxxx
  72                 r => reserved.
  73                 c =>
  74 every track must end  \ 000 => track end (not followed by any data)
  75 with one of these.    / 001 => track loop
  76                         010 => trigger external event
  77                 x => command data
  78
  79 Channel commands:
  80         11cc cccc xxxx xxxx
  81
  82         1100 0001 aaaa aaaa
  83                 arpeggio.  0 = disable arpeggio.
  84         1100 0010 xxxx xxxx
  85                 set detune
  86         1100 0011 xxxx vvvv
  87                 set fixed volume
  88         1100 0100 eeee eeee
  89                 set software volume envelope.
  90                 0 = disable soft envelope.
  91         1100 0101 nnnn nnnn
  92                 enable/disable noise.
  93                 n = noise frequency, 0 to disable.
  94         1100 0110 xxxx xxxx
  95                 AM sample playback [reserved.]
  96         1100 0111 <envelope bytes would follow>
  97                 set hardware envelope [reserved.]
  98         1100 1000 xxxx xxoe
  99                 envelope-follow mode.
 100                 e = enable/disable;
 101                 o = one octave lower/same pitch.
 102         1100 1001 pppp pppp
 103                 pitch envelope.  0 = disable pitch envelope.
 104         1100 1010 ssss ssss
 105                 portamento.  s = speed.
 106         1100 1011 vvvv vvvv
 107                 vibrato.  0 = disable vibrato.
 108
 109
 110 Arpeggio and venv tables: (long aligned)
 111
 112 number of entries in table (byte)
 113 entry 1 length (byte)
 114 entry 1 loop point (byte)
 115 entry 1 data (length*byte)
 116 ...
 117
 118 Vibrato table: (long aligned)
 119
 120 number of entries in table (byte)
 121 entry 1 "length" (byte, always 3)
 122 entry 1 delay (byte)
 123 entry 1 depth (byte, 0 through 8)
 124 entry 1 speed (byte, 0 through 4)
 125 entry 1 oscillator mask (byte, 1<<speed)
 126
 127
 128
 129                       NOTES ON IMPROVING YMAMOTO
 130
 131 ENVELOPES
 132
 133 It might be nice to provide a means for sweeping the envelope, perhaps
 134 by a table driven method like arpeggios and vibratos.  Also, changing
 135 the shape on the fly, perhaps even with a separation timer.
 136
 137 STORAGE
 138
 139 I think I'm going to rewrite this as a byte-oriented format.  Word
 140 orientation seems to waste more than it gains (marginal theoretical
 141 speed improvements).  Also, I've been reading Rob Hubbard's replays
 142 lately, as well as various others, and I like some of his approaches a
 143 lot.
 144
 145 Notes could be stored as being relative to a base octave (set with
 146 separate commands), just as their duration could be stored as being
 147 relative to a base duration.  This would probably allow encoding most
 148 note data as single bytes.  (Tone value would need no more than five
 149 bits, to encode +15/-16 tones; duration could be just two bits,
 150 allowing access to the four most common durations.)
 151
 152 Obviously, a system for encoding loops and repeats would be good;
 153 especially something that took alternate endings into account, because
 154 that would seriously improve the value of repeats for a lot of my
 155 music.  Also, possibly a system based on windows (rather than
 156 "patterns" in the tracker sense) might be really handy for
 157 riff-oriented music.
 158
 159 Being able to define ``instruments'' that allowed voices to rapidly
 160 switch a variety of characteristics at once, might save some time and
 161 space.  (An instrument might define a base range, default staccato,
 162 default volume envelope, default vibrato, et cetera.)
 163
 164 We may need to increase the size of the relative offsets, though ``64k
 165 should be enough for anybody''; time will tell, as I write longer
 166 tunes.
 167
 168 Arpeggios (and other tables) could be stored aligned on 8 byte
 169 boundries, to make seeking into the arp table very quick.  For
 170 arpeggios longer than 8 bytes, you could just have ``double wide''
 171 arpeggios that take up 16 bytes.
 172
 173 DURATIONS
 174
 175 An alternate approach to duration is to fix the atomic duration (one
 176 frame), and have the music creation tool do all the duration
 177 calculations.  This is good for some kinds of music, but it means that
 178 one cannot switch a song between 50 and 60 Hz replay without
 179 recompiling it.  This is what we have now; the notes below apply to
 180 the previous system, which was replay-speed independant.
 181
 182 Duration modifiers are probably very rarely used together (tied,
 183 double dotted triplets for example); they can probably turn into
 184 something state based (which would allow us to accomidate stranger
 185 timings, like quintuplets).
 186
 187 This is the old duration format
 188                 T => 1 = tied with next note
 189                 D => duration modifier:
 190                         000 => normal
 191                         001 => dotted
 192                         010 => double dotted
 193                         100 => triplet time
 194                         (quintuplet time?  duplet time?)
 195                      NB that these may change from independant flags
 196                      into a single, 8 state value.
 197                 d => duration, value from 0 (whole note) to 7 (128th note).
 198
 199 Another thing is that, if we find we're already doing full divisions
 200 somewhere (because of quintuplets or whatever), we might as well just
 201 start representing durations as arbitrary fractions; this allows much
 202 more flexibility in some ways.
 203
 204 MISC.
 205
 206 It could be interesting to provide a sort of voice scheduling system,
 207 which tried to fit ``optional'' voices in on channels when the regular
 208 voice was silent (due to rests or staccato).  Maybe this is better
 209 placed in the music composition tool, though.
 210