Fuck it, we're doing it live

1 files changed, 355 insertions, 0 deletions

diff --git a/doc/esf.txt b/doc/esf.txt
new file mode 100644
index 0000000..a7b833e
--- /dev/null
+++ b/doc/esf.txt
@@ -0,0 +1,355 @@
+=============================================================================
+
+OVERVIEW
+
+    ESF stands for "Echo Stream Format". This is the format in which BGM and
+    SFX sequences are stored. Essentially this is the music arrangement data.
+    The format is mostly the same for both BGM and SFX, with just a few
+    exceptions.
+
+FORMAT
+
+    ESF is a streamed format (think MIDI without the useless complexity).
+    It's stored as a sequence of events, where each event takes up between
+    one and three bytes. An event could be something like "note on", "set
+    volume", "stop", etc.
+
+CHANNEL LOCKING
+
+    When both BGM and SFX are being played, it's likely that some channels
+    may get used by both. In this case, Echo will give the SFX privilege over
+    those channels.
+    
+    This is achieved by channel "locking". When the SFX starts, it first
+    locks the channels it needs to use. When the SFX ends, those channels get
+    unlocked. BGM won't play on the locked channels while the SFX is playing.
+
+=============================================================================
+
+EVENT LIST
+
+    $00nn ..... Note on FM channel #1
+    $01nn ..... Note on FM channel #2
+    $02nn ..... Note on FM channel #3
+    $04nn ..... Note on FM channel #4
+    $05nn ..... Note on FM channel #5
+    $06nn ..... Note on FM channel #6
+    $08nn ..... Note on PSG channel #1
+    $09nn ..... Note on PSG channel #2
+    $0Ann ..... Note on PSG channel #3
+    $0Bnn ..... Note on PSG channel #4
+    $0Cnn ..... Note on PCM channel
+    
+    $10 ....... Note off FM channel #1
+    $11 ....... Note off FM channel #2
+    $12 ....... Note off FM channel #3
+    $14 ....... Note off FM channel #4
+    $15 ....... Note off FM channel #5
+    $16 ....... Note off FM channel #6
+    $18 ....... Note off PSG channel #1
+    $19 ....... Note off PSG channel #2
+    $1A ....... Note off PSG channel #3
+    $1B ....... Note off PSG channel #4
+    $1C ....... Note off PCM channel
+    
+    $20nn ..... Set volume FM channel #1
+    $21nn ..... Set volume FM channel #2
+    $22nn ..... Set volume FM channel #3
+    $24nn ..... Set volume FM channel #4
+    $25nn ..... Set volume FM channel #5
+    $26nn ..... Set volume FM channel #6
+    $28nn ..... Set volume PSG channel #1
+    $29nn ..... Set volume PSG channel #2
+    $2Ann ..... Set volume PSG channel #3
+    $2Bnn ..... Set volume PSG channel #4
+    
+    $30nnnn ... Set frequency FM channel #1
+    $31nnnn ... Set frequency FM channel #2
+    $32nnnn ... Set frequency FM channel #3
+    $34nnnn ... Set frequency FM channel #4
+    $35nnnn ... Set frequency FM channel #5
+    $36nnnn ... Set frequency FM channel #6
+    $38nnnn ... Set frequency PSG channel #1
+    $39nnnn ... Set frequency PSG channel #2
+    $3Annnn ... Set frequency PSG channel #3
+    $3Bnn ..... Set noise type PSG channel #4
+    
+    $40nn ..... Set instrument FM channel #1
+    $41nn ..... Set instrument FM channel #2
+    $42nn ..... Set instrument FM channel #3
+    $44nn ..... Set instrument FM channel #4
+    $45nn ..... Set instrument FM channel #5
+    $46nn ..... Set instrument FM channel #6
+    $48nn ..... Set instrument PSG channel #1
+    $49nn ..... Set instrument PSG channel #2
+    $4Ann ..... Set instrument PSG channel #3
+    $4Bnn ..... Set instrument PSG channel #4
+    
+    $E0 ....... [SFX] Lock FM channel #1
+    $E1 ....... [SFX] Lock FM channel #2
+    $E2 ....... [SFX] Lock FM channel #3
+    $E4 ....... [SFX] Lock FM channel #4
+    $E5 ....... [SFX] Lock FM channel #5
+    $E6 ....... [SFX] Lock FM channel #6
+    $E8 ....... [SFX] Lock PSG channel #1
+    $E9 ....... [SFX] Lock PSG channel #2
+    $EA ....... [SFX] Lock PSG channel #3
+    $EB ....... [SFX] Lock PSG channel #4
+    
+    $F0nn ..... Set parameters FM channel #1
+    $F1nn ..... Set parameters FM channel #2
+    $F2nn ..... Set parameters FM channel #3
+    $F4nn ..... Set parameters FM channel #4
+    $F5nn ..... Set parameters FM channel #5
+    $F6nn ..... Set parameters FM channel #6
+    
+    $FC ....... [BGM] Go to loop
+    $FD ....... [BGM] Set loop point
+    $FEnn ..... Delay ticks
+    $FF ....... Stop playback
+
+=============================================================================
+
+$00nn: Note on FM channel #1
+$01nn: Note on FM channel #2
+$02nn: Note on FM channel #3
+$04nn: Note on FM channel #4
+$05nn: Note on FM channel #5
+$06nn: Note on FM channel #6
+
+    These events do a "note on" at the specified FM channel. The event is
+    followed by a byte, which indicates which note to play. The value is as
+    follows, where "octave" ranges from 0 to 7 and "semitone" ranges from 0
+    to 11:
+    
+        32 * octave + 2 * semitone + 1
+
+$08nn: Note on PSG channel #1
+$09nn: Note on PSG channel #2
+$0Ann: Note on PSG channel #3
+
+    These events do a "note on" at the specified square wave PSG channel.
+    The event is followed by a byte, which indicates which note to play. The
+    value is as follows, where "octave" ranges from 0 to 5 and "semitone"
+    ranges from 0 to 11:
+    
+        24 * octave + 2 * semitone
+
+$0Bnn: Note on PSG channel #4
+
+    This event does a "note on" at the noise PSG channel. The event is
+    followed by a byte, which indicates what kind of noise to play. The
+    following values are valid:
+    
+        $00 ... Periodic noise, high pitch
+        $01 ... Periodic noise, medium pitch
+        $02 ... Periodic noise, low pitch
+        $03 ... Periodic noise, PSG3 frequency
+        $04 ... White noise, high pitch
+        $05 ... White noise, medium pitch
+        $06 ... White noise, low pitch
+        $07 ... White noise, PSG3 frequency
+    
+    When using values $03 and $07, the third square wave PSG channel controls
+    the noise frequency. You can change this frequency using the events to
+    change the frequency of that channel (usually you'd use event type $3A).
+
+$0Cnn: Note on PCM channel
+
+    This event does a "note on" at the PCM channel. More specifically, it
+    starts playback of a PCM sample. This event is followed by a byte, that
+    specifies an index in the pointer list indicating where's the sample
+    data. Samples are stored as EWF (Echo Waveform Format).
+    
+    NOTE: FM channel #6 will be disabled. That channel will be re-enabled
+    when PCM playback is over (either because the waveform is over or because
+    the channel is stopped explicitly).
+
+=============================================================================
+
+$10: Note off FM channel #1
+$11: Note off FM channel #2
+$12: Note off FM channel #3
+$14: Note off FM channel #4
+$15: Note off FM channel #5
+$16: Note off FM channel #6
+$18: Note off PSG channel #1
+$19: Note off PSG channel #2
+$1A: Note off PSG channel #3
+$1B: Note off PSG channel #4
+
+    These events do a "note off" at the specified channel.
+
+$1C: Note off PCM channel
+
+    This event does a "note off" at the PCM channel. This means that any PCM
+    playback is immediately stopped. FM channel #6 is immediately enabled as
+    well.
+
+=============================================================================
+
+$20nn: Set volume FM channel #1
+$21nn: Set volume FM channel #2
+$22nn: Set volume FM channel #3
+$24nn: Set volume FM channel #4
+$25nn: Set volume FM channel #5
+$26nn: Set volume FM channel #6
+
+    These events set the volume of a specific FM channel. The event is
+    followed by a byte, which indicates the new volume. A value of $00 is the
+    loudest, a value of $7F is the quietest.
+
+$28nn: Set volume PSG channel #1
+$29nn: Set volume PSG channel #2
+$2Ann: Set volume PSG channel #3
+$2Bnn: Set volume PSG channel #4
+
+    These events set the volume of a specific PSG channel. The event is
+    followed by a byte, which indicates the new volume. A value of $00 is the
+    loudest, a value of $0F is the quietest.
+
+=============================================================================
+
+$30nnnn: Set frequency FM channel #1
+$31nnnn: Set frequency FM channel #2
+$32nnnn: Set frequency FM channel #3
+$34nnnn: Set frequency FM channel #4
+$35nnnn: Set frequency FM channel #5
+$36nnnn: Set frequency FM channel #6
+
+    These events set the raw frequency of a specific FM channel, without
+    triggering a new note. Meant for note slides. The following two bytes
+    specify the new frequency in the same format as the YM2612 expects. The
+    first byte is register +$A4, the second byte is register +$A0.
+    
+    Echo uses the following frequency values for each semitone:
+    
+        C  - 644 | E  - 810 | G# - 1021
+        C# - 681 | F  - 858 | A  - 1081
+        D  - 722 | F# - 910 | A# - 1146
+        D# - 765 | G  - 964 | B  - 1214
+
+$38nnnn: Set frequency PSG channel #1
+$39nnnn: Set frequency PSG channel #2
+$3Annnn: Set frequency PSG channel #3
+
+    These events set the raw frequency of a specific square wave PSG channel,
+    without triggering a new note. Meant for note slides. The following two
+    bytes specify the new frequency, the first byte containing the four least
+    significant bits (LSB aligned), and the next byte containing the six most
+    significant bits (LSB aligned too).
+
+    Echo uses the following frequency values for each semitone:
+    
+           |Oct.0|Oct.1|Oct.2|Oct.3|Oct.4|Oct.5
+        ---|-----|-----|-----|-----|-----|-----
+        C  | 851 | 425 | 212 | 106 |  53 |  26
+        C# | 803 | 401 | 200 | 100 |  50 |  25
+        D  | 758 | 379 | 189 |  94 |  47 |  23
+        D# | 715 | 357 | 178 |  89 |  44 |  22
+        E  | 675 | 337 | 168 |  84 |  42 |  21
+        F  | 637 | 318 | 159 |  79 |  39 |  19
+        F# | 601 | 300 | 150 |  75 |  37 |  18
+        G  | 568 | 284 | 142 |  71 |  35 |  17
+        G# | 536 | 268 | 134 |  67 |  33 |  16
+        A  | 506 | 253 | 126 |  63 |  31 |  15
+        A# | 477 | 238 | 119 |  59 |  29 |  14
+        B  | 450 | 225 | 112 |  56 |  28 |  14
+
+$3Bnn: Set noise type PSG channel #4
+
+    This event works like event $0Bnn, but it doesn't trigger a note attack
+    (i.e. instrument envelope won't be reset, note won't start playing if it
+    wasn't already).
+
+=============================================================================
+
+$40nn: Set instrument FM channel #1
+$41nn: Set instrument FM channel #2
+$42nn: Set instrument FM channel #3
+$44nn: Set instrument FM channel #4
+$45nn: Set instrument FM channel #5
+$46nn: Set instrument FM channel #6
+
+    These events are used to set the instrument to be used by a specific FM
+    channel. The event is followed by a byte, which has an index in the
+    pointer list that indicates where's the FM instrument data. Instruments
+    are stored as EIF (Echo Instrument Format).
+
+$48nn: Set instrument PSG channel #1
+$49nn: Set instrument PSG channel #2
+$4Ann: Set instrument PSG channel #3
+$4Bnn: Set instrument PSG channel #4
+
+    These events are used to set the instrument to be used by a specific PSG
+    channel. The event is followed by a byte, which has an index in the
+    pointer list that indicates where's the PSG instrument data. Instruments
+    are stored as EEF (Echo Envelope Format).
+
+=============================================================================
+
+$E0: Lock FM channel #1 [SFX ONLY]
+$E1: Lock FM channel #2 [SFX ONLY]
+$E2: Lock FM channel #3 [SFX ONLY]
+$E4: Lock FM channel #4 [SFX ONLY]
+$E5: Lock FM channel #5 [SFX ONLY]
+$E6: Lock FM channel #6 [SFX ONLY]
+$E8: Lock PSG channel #1 [SFX ONLY]
+$E9: Lock PSG channel #1 [SFX ONLY]
+$EA: Lock PSG channel #1 [SFX ONLY]
+$EB: Lock PSG channel #1 [SFX ONLY]
+
+    These events are used to "lock" specific channels. When a channel is
+    locked, BGM can't mess up with it. All channels used by a SFX must be
+    locked before they're used. Channels get unlocked when the SFX stream is
+    over.
+    
+    To lock the PCM channel, you need to lock FM channel #6 (event $E6). Echo
+    will behave accordingly.
+
+=============================================================================
+
+$F0: Set parameters FM channel #1
+$F1: Set parameters FM channel #2
+$F2: Set parameters FM channel #3
+$F4: Set parameters FM channel #4
+$F5: Set parameters FM channel #5
+$F6: Set parameters FM channel #6
+
+    These events set up some miscellaneous parameters for the FM channels.
+    The event is followed by a byte, which speficies the new parameters to be
+    used. The format of this byte is as follows:
+    
+        Bit 7 ..... 1 to enable left speaker, 0 to mute it
+        Bit 6 ..... 1 to enable right speaker, 0 to mute it
+        Bit 5-0 ... Must be 0
+
+=============================================================================
+
+$FC: Go to loop [BGM ONLY]
+$FD: Set loop point [BGM ONLY]
+
+    This event are used in BGM streams to loop music. Put event $FD where the
+    loop starts, and then end the stream using event $FC (don't use event
+    $FF). This will tell Echo to loop the song instead of stopping playback.
+
+$FEnn: Delay ticks
+
+    This event is used for timing. It tells Echo to wait a specific amount of
+    ticks before continuing with the stream. A byte follows this event, it's
+    the amount of ticks to wait. If it's $00, then Echo waits 256 ticks
+    instead.
+    
+    If you need to wait more than 256 ticks, you can trigger this event
+    several times in a row. For example, to wait 320 ticks, use this event
+    twice: $FE00FE40 --> 256 ticks + 64 ticks = 320 ticks.
+    
+    One tick lasts 1/60th of a second.
+
+$FF: Stop playback
+
+    This event indicates the end of the stream and tells Echo to stop
+    playback from this stream. If the stream was a SFX, then any locked
+    channels will be unlocked as well.
+
+=============================================================================