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
  41 INPUT FORMAT BASICS
  42
  43 I'll just describe significant differences from MML here, for the
  44 moment.  (See various documents on the MML format available in the NES
  45 scene.)  All of this syntax might change at any time.  (Sorry.)
  46
  47 The biggest obvious change is that the "l" command is gone, and now
  48 note duration is relative to the previous note duration input for the
  49 channel in question.  Lilypond has this behavior, and I find it pretty
  50 nice (also, it should make it easier for me to typeset the music in my
  51 chiptunes).  Unfortunately it's probably the most annoying thing about
  52 converting old MML files over to mumble.  I will probably add a
  53 compatibility flag once I get sufficiently annoyed.
  54
  55 You can put "|" in the input and it will be ignored; I find it makes
  56 things a lot cleaner, as I can keep track of my barlines in the input.
  57
  58 Generic macro dispatch is done with the "@" prefix, more in the style
  59 of CL's "#" macro dispatch (partially because I've had some thoughts
  60 of changing things to use CL readtables instead of doing all the
  61 parsing myself).
  62
  63 @a => arpeggio.  Followed by digits indicating arpeggio number,
  64       or 0 for arpeggio off.
  65 @b => pitch macro (mnemonic: bend).
  66 @d => volume macro?  For scripting time signatures/repeated rhythmic
  67       accents, etc.
  68 @i => instrument.  An instrument is, broadly, a snapshot of partial
  69       channel state; what that means depends on the replay.
  70 @t => tempo macro?  For scripting rallentendos and accelerandos.
  71 @v => (software) volume envelope.
  72 @~ => vibrato.
  73
  74
  75 Playroutine-specific commands are done with the "%" prefix, which
  76 means that the old MML use of "%" to specify an absolute number of
  77 ticks for a note is no longer supported.
  78
  79 For example, I'll show a few "%" commands from my YM playroutine
  80 support, and from my NES playroutine support.
  81
  82 YM:
  83
  84 %e[uo4] => set hardware envelope to follow current notes at {unison,
  85            octave, 4th below}.
  86 ... envelope sweep, noise carrier, AM sample playback
  87
  88 NES:
  89
  90 ... timbre switching; channel A hardware sweep; looped noise...
  91
  92 SID:
  93
  94 ... timbre switching/PWM; filter control; hard reset control...
  95
  96 The general idea is that one should be able to write a tune, and adapt
  97 it to various platforms primarily by changing the "%" commands; "@"
  98 commands should be basically common to all replays.  (I'm also going
  99 to think more about this and possibly support some kind of conditional
 100 compilation or option to ignore certain commands when using a certain
 101 replay.)
 102
 103 Some playroutines require use of instruments for most effects, while
 104 others don't use instruments at all.  Playroutine outputs that don't
 105 use instruments should silently translate instrument use to
 106 appropriate commands.
 107
 108 The old data skip command, "!", has become a dispatch for general
 109 structural commands:
 110
 111 !loop => song loop (formerly "L").
 112 !end => end of track (kind of like the old "!").
 113
 114
 115
 116 CAVEATS
 117
 118 Dots in durations must follow an integer duration value.  (You can't
 119 write, for example, "a4 b. c8")
 120
 121 Repeats ("[abcabc]42") are always unfolded during parsing, to keep
 122 basic output routines simpler.  It's my belief that the output routine
 123 code can do its own repeat optimization if it wants to, and it can do
 124 it better than a human.  Repeats should be inserted to keep the
 125 original clean and readable.
 126
 127
 128 IDEAS
 129
 130 Tempo macros, for defining rallentendos, accellerandos, fermatas, et
 131 cetera.
 132
 133 Large-scale volume macros, to define time signatures, et cetera.
 134
 135 The playroutine output code is responsible for complaining to the user
 136 if a feature is not supported (for example, using vibrato outside of
 137 an instrument definition; or defining more than 32 instruments); but
 138 the events that trigger these complaints should have original file
 139 information with them so that line and ideally character positions can
 140 be reported back to the user.