[WIP] Overhaul audio section

Author: ISSOtm

custom/style.css

@@ -142,3 +142,11 @@ code {
 .rust {
   --c-warning-text: #ad8e00;
 }
+
+/* Avoid text being squished too much in fractions */
+math[display="block"], mfrac {
+  font-size: 2rem;
+}
+mfrac msup :not(:first-child) {
+  font-size: 1.8rem;
+}

src/Audio.md

@@ -0,0 +1,110 @@
+# Audio Overview
+
+Game Boy audio is sometimes called "8-bit", but this doesn't mean much: the term is used to designate audio similar to that produced by 8-bit consoles.
+
+A better description would be "chiptune": tunes produced by a chip.
+This section describes how audio is generated on the Game Boy.
+
+## Architecture
+
+{{#include imgs/apu_overview.svg:2:}}
+
+The Game Boy has four sound generation units, called **channels** 1 through 4, notated "CH1", "CH2", etc.
+Unlike some other sound chips, such as the SNES' S-DSP or the Atari 5200's POKEY, each sound channel is specialized in a way largely different from the other channels.
+
+Each channel generates an electronic signal; these signals are then mixed into two new channels (for stereo: one for the left ear, one for the right ear), which are then individually amplified, and then output either to the headphone jack, or the speaker[^speaker_mono].
+
+Channels 1 and 2, the "pulse channels", produce [pulse (rectangular) waves](https://en.wikipedia.org/wiki/Pulse_wave).
+Channel 3, the "wave" channel, produces arbitrary user-supplied waves.
+Channel 4 is the "[noise](https://en.wikipedia.org/wiki/Noise_in_music)" channel, producing a pseudo-random wave.
+
+The VIN channel is a signal received directly from the cartridge, allowing external hardware to supply a fifth sound channel.
+No licensed games used this feature, and it was omitted from the Game Boy Advance.
+
+::: tip POCKET MUSIC
+
+Despite some online claims, *Pocket Music* does not use VIN.
+It refuses to run on the GBA for a different reason: the developer couldn't figure out how to silence buzzing associated with sample playback on the wave channel.
+
+:::
+
+[^speaker_mono]:
+The speaker merges back the two channels, losing the stereo aspect entirely.
+
+## Common concepts
+
+### APU
+
+The Game Boy's sound chip is called the <abbr title="Audio Processing Unit">APU</abbr>.
+
+The APU runs off the same master clock as the rest of the Game Boy, which is to say, it is fully synced with the CPU and [PPU](<#Rendering Overview>).
+This also means that the APU runs about 2.4% faster on the SGB1, increasing frequencies by as much and thus sounding slightly higher-pitched.
+The SGB2 rectifies this issue.
+
+The APU processes a lot of events at a fixed rate dependent on the event's type.
+Thus, the APU interfaces use **durations** instead of frequencies, which may be confusing as signal theory and music are more typically based on the latter.
+Thus, durations will be expressed from their frequencies: for example, a "256 Hz tick" means "1 ∕ 256th of a second".
+
+The length of APU ticks is not affected by [CGB double speed](<#FF4D — KEY1 (CGB Mode only): Prepare speed switch>), so the APU works just the same regardless of CPU speed.
+
+::: warning
+
+The Game Boy's APU is actually full of tricky details; this chapter will mostly describe the intended / common behavior, and often paper over bugs & quirks.
+Readers wishing to learn more should read the [APU details](<#Audio details>) chapter.
+
+:::
+
+### Triggering
+
+**Triggering** a channel causes it to turn on if it wasn't[^trig_dac_off], and to start playing its wave from the beginning[^pulse_restart].
+Most changes to a channel's parameters take effect immediately, but some require re-triggering the channel.
+
+### Volume & envelope
+
+The volume can be controlled in two ways: there is a "master volume" control[^vol_knob] (which has separate settings for the left and right outputs), and each channel's volume can be individually set as well (CH3's less precisely than the others).
+
+Additionally, an [**envelope**](https://en.wikipedia.org/wiki/Envelope_(music)) can be configured for all channels except CH3, which allows automatically adjusting the volume over time.
+The parameters that can be controlled are how many times the envelope will be stepped, in which direction, and how long between steps.
+All envelopes are ticked at 64 Hz, and every 1–7 of those ticks, the volume will be increased or decreased.
+
+### Length timer
+
+All channels can be individually set to automatically shut themselves down after a certain amount of time.
+
+If the functionality is enabled, a channel's **length timer** ticks up[^len_cnt_dir] at 256 Hz (tied to [DIV-APU](<#DIV-APU>)) from the value it's initially set at.
+When the length timer reaches 64, the channel is turned off.
+
+### Frequency
+
+Music notes and audio waves are typically manipulated in terms of **frequency**[^pitch], i.e. how often the signal repeats per second.
+However, as explained above, the Game Boy APU primarily works with durations; thus, **wavelengths** will be used instead of frequency.[^len_raw]
+
+::: warning
+
+The term "wavelength" throughout this document does *not* designate the inverse of the frequency, but instead a quantity akin to it.
+See the description of each NRx3 register for more information.
+
+:::
+
+---
+
+[^trig_dac_off]:
+If the channel's DAC is off (TODO: link to explanation), the channel will not turn on.
+
+[^pulse_restart]:
+Except for pulse channels, whose index into their waves is only ever reset by turning the APU off.
+This is not noticeable when playing sound, and only matters for "advanced" APU usage.
+
+[^vol_knob]:
+This is separate from the physical volume knob located on the side of the console.
+
+[^len_cnt_dir]:
+Internally, the length timer is inverted when written, and *that* ticks down until it reaches 0.
+But the effect is as if the counter ticked up.
+
+[^pitch]:
+There is also **pitch**, which is merely a measure of how we perceive frequency.
+The higher the frequency, the higher the pitch; therefore, pitch will be omitted from the rest of the document.
+
+[^len_raw]:
+Actually, the APU interfaces don't work with any wavelengths either, but with values that are more akin to wavelengths than frequencies.