[Audio 10/10] Loose ends (#2337)

* Introduce afile_sizes, generate headers of sizes for soundfonts and sequences

* Initial tools/audio README

* Versioning for samplebank extraction

* Clean up the disassemble_sequence.py runnable interface

* Add static assertions for maximum bank sizes

* Boost optimization for audio tools

* Samplebank XML doc

* Soundfont XML doc

* More docs in sampleconv for vadpcm

* Various tools fixes/cleanup

* VADPCM doc

* Try to fix md formatting

* VADPCM doc can come later

* Fix merge with PR 9

* Fix blobs from MM

* Try to fix bss

* Try fix bss round 2

* Fix sampleconv memset bug

* Suggested documentation tweaks

3 files changed, 396 insertions, 0 deletions

diff --git a/docs/audio/Samplebank_XML.md b/docs/audio/Samplebank_XML.md
new file mode 100644
index 000000000..b9c027bcb
--- /dev/null
+++ b/docs/audio/Samplebank_XML.md
@@ -0,0 +1,77 @@
+# Samplebank XML Format Specification
+
+Samplebank XMLs describe a samplebank file that contains compressed waveform data. It specifies which sample files to include as well as certain global properties such as the index of this samplebank.
+
+---
+
+```xml
+<SampleBank
+    Name="<C Indentifier>"
+    Index="<uint>"
+    Medium="<Medium>"
+    CachePolicy="<CachePolicy>"
+    BufferBug="[bool]"
+>
+```
+Begins a new samplebank.
+
+**Attributes**
+
+- **Name**: The name of the samplebank.
+- **Index**: The index of the samplebank for the samplebank table. Must be a unique index for all samplebanks and pointers.
+- **Medium**: The storage medium, from the `SampleMedium` enum.
+- **CachePolicy**: The cache policy, from the `AudioCacheLoadType` enum.
+- <ins>[Optional]</ins> **BufferBug**: Whether this samplebank suffers from a buffer clearing bug present in the original audio tools. For matching only.
+
+**Tags**
+
+-
+    ```xml
+    <Pointer
+        Index="<uint>"
+    />
+    ```
+    Create an alternate index that refers to this samplebank.
+
+    **Attributes**
+
+    - **Index**: The alternative index, must be unique among all samplebanks and pointers.
+
+    ---
+
+-
+    ```xml
+    <Sample
+        Name="<C Identifier>"
+        Path="<Path>"
+    />
+    ```
+    Adds a **compressed** sample file to the samplebank. The sample should be single-channel and big-endian, in a format that is recognizable by the audio driver such as: pcm16, vadpcm, or half-frame vadpcm.
+
+    **Attributes**
+
+    - **Name**: Name of this sample. Must be a valid C language identifier.
+    - **Path**: Path to aifc file relative to the project root (typically in `$(BUILD_DIR)/assets/audio/samples/`)
+
+    ---
+
+-
+    ```xml
+    <Blob
+        Name="<C Identifier>"
+        Path="<Path>"
+    />
+    ```
+    Adds a binary blob to the samplebank. Intended for matching only when data cannot be identified.
+
+    **Attributes**
+
+    - **Name**: Name of this blob. Must be a valid C language identifier.
+    - **Path**: Path to binary file, relative to the project root (typically in `$(BUILD_DIR)/assets/audio/samples/`)
+
+    ---
+
+```xml
+</SampleBank>
+```
+---
diff --git a/docs/audio/Soundfont_XML.md b/docs/audio/Soundfont_XML.md
new file mode 100644
index 000000000..c2d8a572e
--- /dev/null
+++ b/docs/audio/Soundfont_XML.md
@@ -0,0 +1,319 @@
+# Soundfont XML Format Specification
+
+Soundfont XMLs describe the layout of a single soundfont. These package raw samples together into instruments, of which there are three kinds:
+- **Effects**: These are simple sound effects that just play a single sample without any modulation.
+- **Drums**: These define a MIDI-style percussion key map.
+- **Instruments**: These are instruments that may be played at any key with up to three voices and may be modulated by an envelope.
+
+In the specification, `Note Name`s can be either a MIDI note name e.g. `C4` or it may be a **Zelda64** note number, which are related to MIDI note numbers ($n$) by $(n - 21) \mod 128$.
+
+---
+
+```xml
+<Soundfont
+    Name="<C Identifier>"
+    Index="<uint>"
+    Medium="<Medium>"
+    CachePolicy="<CachePolicy>"
+    SampleBank="<Path>"
+    Indirect="[uint]"
+    SampleBankDD="[Path]"
+    IndirectDD="[uint]"
+    LoopsHaveFrames="[bool]"
+    PadToSize="[uint]"
+    NumInstruments="[uint]"
+>
+```
+Begins a new soundfont.
+
+**Attributes**
+- **Name**: Soundfont symbol name. Must be a valid C identifier.
+- **Index**: Soundfont index. Must be an integer.
+- **Medium**: Storage medium. Must be an enum name from `SampleMedium`.
+- **CachePolicy**: Cache policy. Must be an enum name from `AudioCacheLoadType`.
+- **SampleBank**: Path to samplebank xml used by this soundfont.
+- <ins>[Optional]</ins> **Indirect**: Pointer index if the samplebank is referenced indirectly.
+- <ins>[Optional]</ins> **SampleBankDD**: Path to samplebank xml used for DD medium.
+- <ins>[Optional]</ins> **IndirectDD**: Pointer index if the DD samplebank is referenced indirectly.
+- <ins>[Optional]</ins> **LoopsHaveFrames**: Whether loops in this soundfont store the total frame count of the sample. Must be a boolean.
+- <ins>[Optional]</ins> **PadToSize**: For matching only. Specifies the total file size the result output should be padded to.
+- <ins>[Optional]</ins> **NumInstruments**: For matching only. Specifies the total number of instrument pointers. Usually this is automatically assigned based on `max(program_number) + 1` but some vanilla banks don't match this way.
+
+**Tags**
+
+-
+    ```xml
+    <Envelopes>
+    ```
+    Lists envelopes defined in this soundfont.
+
+    **Attributes**
+
+    N/A
+
+    **Tags**
+
+    -
+        ```xml
+        <Envelope
+            Name="<C Identifier>"
+            Release="<u8>"
+        >
+        ```
+        Starts a new envelope.
+
+        **Attributes**
+
+        - **Name**: Unique name for this envelope. Must be a valid C identifier.
+        - **Release**: Release rate index (into `gAudioCtx.adsrDecayTable`) for this envelope
+
+        **Tags**
+
+        -
+            ```xml
+            <Point
+                Delay="<s16>"
+                Arg="<s16>"
+            />
+            ```
+            Add a point to the envelope at (delay, arg)
+
+            **Attributes**
+
+            - **Delay**: Duration until the next point
+            - **Arg**: Value of the envelope at this point
+
+            ---
+
+        -
+            ```xml
+            <Disable/>
+            ```
+            Insert a ADSR_DISABLE command
+
+            ---
+
+        -
+            ```xml
+            <Hang/>
+            ```
+            Insert a ADSR_HANG command
+
+            ---
+
+        -
+            ```xml
+            <Goto
+                Index="<uint>"
+            />
+            ```
+            Insert a ADSR_GOTO command
+
+            **Attributes**
+
+            - **Index**: Index of the envelope point to jump to
+
+            ---
+
+        ```xml
+        </Envelope>
+        ```
+        ---
+
+    ```xml
+    </Envelopes>
+    ```
+    ---
+
+-
+    ```xml
+    <Samples
+        IsDD="[Bool]"
+        Cached="[Bool]"
+    >
+    ```
+    Begins a list of samples used in this Soundfont.
+
+    **Attributes**
+
+    - <ins>[Optional]</ins> **IsDD**: Whether all the samples in the list are on the Disk Drive. The sample data will come from the samplebank `SampleBankDD`. **Default is `false`.** **NOTE this is not fully implemented, it should always be `false`.**
+    - <ins>[Optional]</ins> **Cached**: Whether all the samples in the list should be added to the `usedSamples` cache. **Default is `false`.**
+
+    **Tags**
+
+    -
+        ```xml
+        <Sample
+            Name="<C Identifier>"
+            SampleRate="[Sample Rate]"
+            BaseNote="[Note Name]"
+            IsDD="[Bool]"
+            Cached="[Bool]"
+        />
+        ```
+        Declares a sample used in this soundfont.
+
+        **Attributes**
+
+        - **Name**: The name of this sample. A sample with this name must be present in the samplebank used by the soundfont.
+        - <ins>[Optional]</ins> **SampleRate**: An overriding sample rate for this sample. **Default comes from the sample file.**
+        - <ins>[Optional]</ins> **BaseNote**: An overriding root key for this sample. **Default comes from the sample file.**
+        - <ins>[Optional]</ins> **IsDD**: Whether this sample is on the Disk Drive. The sample data will come from the samplebank `SampleBankDD`. **Default is `false`.** **NOTE this is not fully implemented, it should always be `false`.**
+        - <ins>[Optional]</ins> **Cached**: Whether this sample should be added to the `usedSamples` cache. **Default is `false`.**
+
+        ---
+
+    ```xml
+    </Samples>
+    ```
+    ---
+
+-
+    ```xml
+    <Effects>
+    ```
+    Begins a list of sound effects to define for this soundfont. Sound effects correspond to simple sounds that cannot be played at different keys.
+
+    **Attributes**
+
+    N/A
+
+    **Tags**
+
+    -
+        ```xml
+        <Effect
+            Name="<C Identifier>"
+            Sample="<Sample Name>"
+            SampleRate="[Sample Rate]"
+            BaseNote="[Note Name]"
+        />
+        ```
+        Defines a single sound effect.
+
+        **Attributes**
+        - **Name**: The name of the sound effect, the name is made available in sequence files in the form `SF{n}_{name}` where `n` is the index of this soundfont and `name` is this name. For example, if `n=0` and `name=ExampleEffect` the name to use in sequence files is `SF0_ExampleEffect`.
+        - **Sample**: The name of the sample associated with this effect.
+        - <ins>[Optional]</ins> **SampleRate**: An overriding sample rate for this effect. **Default comes from the sample definition.**
+        - <ins>[Optional]</ins> **BaseNote**: An overriding root key for this effect. **Default comes from the sample definition.**
+
+        ---
+
+    ```xml
+    </Effects>
+    ```
+    ---
+
+-
+    ```xml
+    <Drums>
+    ```
+    Begins the percussion definitions for this soundfont. Percussion corresponds to the MIDI notion of percussion, where single samples are mapped across a range of keys.
+
+    **Attributes**
+
+    N/A
+
+    **Tags**
+
+    -
+        ```xml
+        <Drum
+            Name="<C Identifier>"
+            Note="[Note Name]"
+            NoteStart="[Note Name]"
+            NoteEnd="[Note Name]"
+            Pan="<u8>"
+            Envelope="<Envelope Name>"
+            Release="[u8]"
+            Sample="<Sample Name>"
+            SampleRate="[Sample Rate]"
+            BaseNote="[Note Name]"
+        />
+        ```
+        Defines a single percussion range.
+
+        **Attributes**
+        - **Name**: The name of this sound. Definitions are emitted for sequence files in the form `SF{n}_{name}_{note}` for every note covered by this sound.
+        - <ins>[Optional]</ins> **Note**: The key to map this sound to. Should not overlap with other definitions. **If this field is left unspecified, `NoteStart` and `NoteEnd` become required.**
+        - <ins>[Optional]</ins> **NoteStart**: The first key that is mapped to this sound. Should not overlap with other definitions. **If this field is left unspecified, `Note` becomes required. If this field is specified, `NoteEnd` must also be specified.**
+        - <ins>[Optional]</ins> **NoteEnd**: The last key that is mapped to this sound. Should not overlap with other definitions. **If this field is left unspecified, `Note` becomes required. If this field is specified, `NoteStart` must also be specified.**
+        - **Pan**: The stereo weight for this sound. Center=`64`.
+        - **Envelope**: The envelope to modulate the volume over time with. Must be defined in the `Envelopes` list.
+        - <ins>[Optional]</ins> **Release**: An override for the envelope release rate. **Default is the release rate specified in the envelope definition**
+        - **Sample**: The name of the sample to use.
+        - <ins>[Optional]</ins> **SampleRate**: An overriding sample rate for this sound. **Default comes from the sample definition.**
+        - <ins>[Optional]</ins> **BaseNote**: An overriding root key for this sound. **Default comes from the sample definition.**
+
+        ---
+
+    ```xml
+    </Drums>
+    ```
+    ---
+
+-
+    ```xml
+    <Instruments>
+    ```
+    Begins the instrument definitions for this soundfont. Instruments correspond to the MIDI notion of instruments, with up to 3 samples (voices) per instrument that must map to contiguous ranges of notes.
+
+    **Attributes**
+
+    N/A
+
+    **Tags**
+
+    -
+        ```xml
+        <Instrument
+            ProgramNumber="<>"
+            Name="<C Identifier>"
+            Envelope="<Envelope Name>"
+            Release="[u8]"
+
+            Sample="<Sample Name>"
+            SampleRate="[Sample Rate]"
+            BaseNote="[Note Name]"
+
+            RangeLo="[Note Name]"
+            SampleLo="[Sample Name]"
+            SampleRateLo="[Sample Rate]"
+            BaseNoteLo="[Note Name]"
+
+            RangeHi="[Note Name]"
+            SampleHi="[Sample Name]"
+            SampleRateHi="[Sample Rate]"
+            BaseNoteHi="[Note Name]"
+        />
+        ```
+        Defines an instrument.
+
+        **Attributes**
+        - **ProgramNumber**: MIDI Program Number for this instrument. Must be in the range `0 <= n <= 125`
+        - **Name**: The name of this instrument.
+        - **Envelope**: Envelope to use, identified by name.
+        - <ins>[Optional]</ins> **Release**: Release rate index override. **Default release rate comes from the chosen envelope.**
+        - **Sample**: The name of the middle sample to use for this instrument.
+        - <ins>[Optional]</ins> **SampleRate**: Sample rate override for the middle sample. **Default is sourced from the sample properties.**
+        - <ins>[Optional]</ins> **BaseNote**: Base note override for the middle sample. **Default is sourced from the sample properties.**
+        - <ins>[Optional]</ins> **RangeLo**: The largest note for SampleLo. SampleLo will be used instead of Sample for keys in the range [0, RangeLo]. **If left unspecified, SampleLo must not be specified. If specified, SampleLo must be specified.**
+        - <ins>[Optional]</ins> **SampleLo**: The name of the low sample to use for this instrument.
+        - <ins>[Optional]</ins> **SampleRateLo**: Sample rate override for the low sample. **Default is sourced from the sample properties.**
+        - <ins>[Optional]</ins> **BaseNoteLo**: Base note override for the low sample. **Default is sourced from the sample properties.**
+        - <ins>[Optional]</ins> **RangeHi**: The smallest note for SampleHi. SampleHi will be used instead of Sample for keys in the range [RangeHi, 127]. **If left unspecified, SampleHi must not be specified. If specified, SampleHi must be specified.**
+        - <ins>[Optional]</ins> **SampleHi**: The name of the high sample to use for this instrument.
+        - <ins>[Optional]</ins> **SampleRateHi**: Sample rate override for the high sample. **Default is sourced from the sample properties.**
+        - <ins>[Optional]</ins> **BaseNoteHi**: Base note override for the high sample. **Default is sourced from the sample properties.**
+
+        ---
+
+    ```xml
+    </Instruments>
+    ```
+    ---
+
+```xml
+</Soundfont>
+```
+---
diff --git a/docs/audio/build_flowchart.png b/docs/audio/build_flowchart.png
new file mode 100644
index 000000000..9ef26221e
--- /dev/null
+++ b/docs/audio/build_flowchart.png