README

   1 mumble
   2 Julian Squires <tek@wiw.org> / 2004
   3
   4
   5 Mumble is a package for converting text representations of music into
   6 data for specific playroutines.  The format, described in this
   7 document is a variant on the (popular?) Music Macro Language (or MML)
   8 format.
   9
  10 I started writing this package so I could convert some of my older
  11 songs (written in MML, for the NES) to a new Atari ST playroutine I
  12 was writing.  Along the way, I realized that this was my opportunity
  13 to make some changes to the input format, and start using a single
  14 source for output for various playroutine targets.
  15
  16 This format may not be ideal for formats with more than about eight
  17 channels, but I rarely work with more than five, anyway.
  18
  19
  20 PLAYROUTINES (REPLAYS) SUPPORTED
  21
  22 * YMamoto -- my primitive Atari ST YM-2149 playroutine.
  23
  24 REPLAYS I PLAN TO WRITE MYSELF AND SUPPORT
  25
  26 * nes (soon)
  27 * some kind of opl[23] playroutine.
  28 * a SID replay.
  29 * some snes spc replay
  30
  31 UNSUPPORTED REPLAYS I'D LIKE TO SUPPORT
  32
  33 * hubbard -- Rob Hubbard's "Monty on the Run" playroutine.
  34 * mod -- Protracker-style 4-channel MODs. (no specific replay)
  35 * ahx, fc
  36 * mck
  37 * something on the atari 800XL
  38
  39
  40 USING MUMBLE FROM THE LISP REPL
  41
  42 You should be able to just:
  43 > (asdf:oos 'asdf:load-op 'mumble)
  44 > (mumble:compile-mumble "my-file.mbl" "my-file.out-ext")
  45 and everything should work.
  46
  47
  48 INPUT FORMAT BASICS
  49
  50 I'll just describe significant differences from MML here, for the
  51 moment.  (See various documents on the MML format available in the NES
  52 scene.)  All of this syntax might change at any time.  (Sorry.)
  53
  54 The biggest obvious change is that the "l" command is gone, and now
  55 note duration is relative to the previous note duration input for the
  56 channel in question.  Lilypond has this behavior, and I find it pretty
  57 nice (also, it should make it easier for me to typeset the music in my
  58 chiptunes).  Unfortunately it's probably the most annoying thing about
  59 converting old MML files over to mumble.  I will probably add a
  60 compatibility flag once I get sufficiently annoyed.
  61
  62 You can put "|" in the input and it will be ignored; I find it makes
  63 things a lot cleaner, as I can keep track of my barlines in the input.
  64
  65 Generic macro dispatch is done with the "@" prefix, more in the style
  66 of CL's "#" macro dispatch (partially because I've had some thoughts
  67 of changing things to use CL readtables instead of doing all the
  68 parsing myself).
  69
  70 @a => arpeggio.  Followed by digits indicating arpeggio number,
  71       or 0 for arpeggio off.
  72 @b => pitch macro (mnemonic: bend).
  73 @d => volume macro? (mnemonic: dynamics).  For scripting time
  74       signatures/repeated rhythmic accents, etc.
  75 @i => instrument.  An instrument is, broadly, a snapshot of partial
  76       channel state; what that means depends on the replay.
  77 @t => tempo macro?  For scripting rallentendos and accelerandos.
  78 @v => (software) volume envelope.
  79 @~ => vibrato.
  80
  81
  82 Playroutine-specific commands are done with the "%" prefix, which
  83 means that the old MML use of "%" to specify an absolute number of
  84 ticks for a note is no longer supported.
  85
  86 For example, I'll show a few "%" commands from my YM playroutine
  87 support, and from my NES playroutine support.
  88
  89 YM:
  90
  91 %e[uo4] => set hardware envelope to follow current notes at {unison,
  92            octave, 4th below}.
  93 ... envelope sweep, noise carrier, AM sample playback
  94
  95 NES:
  96
  97 ... timbre switching; channel A hardware sweep; looped noise...
  98
  99 SID:
 100
 101 ... timbre switching/PWM; filter control; hard reset control...
 102
 103 The general idea is that one should be able to write a tune, and adapt
 104 it to various platforms primarily by changing the "%" commands; "@"
 105 commands should be basically common to all replays.  (I'm also going
 106 to think more about this and possibly support some kind of conditional
 107 compilation or option to ignore certain commands when using a certain
 108 replay.)
 109
 110 Some playroutines require use of instruments for most effects, while
 111 others don't use instruments at all.  Playroutine outputs that don't
 112 use instruments should silently translate instrument use to
 113 appropriate commands.
 114
 115 The old data skip command, "!", has become a dispatch for general
 116 structural commands:
 117
 118 !loop => song loop (formerly "L").
 119 !end => end of track (kind of like the old "!").
 120
 121
 122
 123 CAVEATS
 124
 125 Dots in durations must follow an integer duration value.  (You can't
 126 write, for example, "a4 b. c8")
 127
 128 Repeats ("[abcabc]42") are always unfolded during parsing, to keep
 129 basic output routines simpler.  It's my belief that the output routine
 130 code can do its own repeat optimization if it wants to, and it can do
 131 it better than a human.  Repeats should be inserted to keep the
 132 original clean and readable.
 133
 134
 135 IDEAS
 136
 137 Tempo macros, for defining rallentendos, accellerandos, fermatas, et
 138 cetera.
 139
 140 Large-scale volume macros, to define time signatures, et cetera.
 141
 142 The playroutine output code is responsible for complaining to the user
 143 if a feature is not supported (for example, using vibrato outside of
 144 an instrument definition; or defining more than 32 instruments); but
 145 the events that trigger these complaints should have original file
 146 information with them so that line and ideally character positions can
 147 be reported back to the user.