This page goes deeper than the sound unit summary. The bits of every register are on the register bit layouts page. The text is our own wording of the raw Pan Docs Markdown (CC0, read 2026-11-19, kept in the site’s sample sources with SHA-256 in the sample README); each section names its file. The sources are Pan Docs, the gbdev wiki (Gameboy sound hardware), the SameBoy source (apu.c, apu.h) and the blargg sound test readmes and register test; each section names the ones it uses. We ran no ROM and no emulator, and we had no hardware. What blargg’s tests, SameBoy and the wiki report about real consoles is stated on this page as their statement, not as something we measured. Pan Docs itself says its Audio chapter describes the intended behaviour and leaves out bugs and quirks, which are in Audio details and in the obscure behaviour section below.
From generator to speaker
Source: Audio_details.md and Audio.md.
Each of the four channels is a generator circuit followed by a DAC. The generator makes a digital value 0 to 15 ($0–$F). The DAC turns that linearly into an analogue value between −1 and 1 (the unit is arbitrary). The four analogue outputs go into the mixer, which adds them, as chosen by NR51, into a left and a right output. Each of those has a range of −4 to 4, four times that of one channel. VIN, the cartridge’s analogue input, acts as a fifth channel here, with its control bits in NR50 and not NR51.
Both outputs are then scaled by the master volume in NR50 and by the volume knob if the console has one. The NR50 step never silences a sound that is not silent already. The knob can. Each output then goes through a high-pass filter (HPF), which keeps pulling the signal towards analogue 0.
The APU runs on the console’s master clock, so about 2.4 % fast on the SGB1 (higher pitch; the SGB2 corrects it). Its timing is not changed by Color double speed.
Our own drawing of this signal path (Pan Docs has a more detailed picture, which we did not copy):
The frame sequencer (“DIV-APU”)
Source: Audio_details.md.
The DIV-APU counter increases each time bit 4 of DIV (bit 5 in double speed) goes from 1 to 0. That is 512 times a second, in either speed. Writing to DIV while that bit is 1 clears DIV and so makes the bit fall, which makes the counter increase early. Events happen every N ticks:
| Event | Every N ticks | Rate |
|---|---|---|
| Envelope step | 8 | 64 Hz |
| Length timer tick | 2 | 256 Hz |
| Channel 1 sweep | 4 | 128 Hz |
Writing to DIV makes these rates different from the figures. NR52 bit 7 (turning the APU off) does not reset the DIV-APU counter, and it does not affect wave RAM (Audio_Registers.md).
The eight steps
Pan Docs gives only the rates. The gbdev wiki (Frame Sequencer) gives the step table: the sequencer has eight steps, 0 to 7, advanced 512 times a second. Which units are clocked on each step:
| Step | Length timer (256 Hz) | Envelope (64 Hz) | Channel 1 sweep (128 Hz) |
|---|---|---|---|
| 0 | clock | – | – |
| 1 | – | – | – |
| 2 | clock | – | clock |
| 3 | – | – | – |
| 4 | clock | – | – |
| 5 | – | – | – |
| 6 | clock | – | clock |
| 7 | – | clock | – |
So the length timer is clocked on steps 0, 2, 4 and 6, the sweep on 2 and 6, the envelope on 7. SameBoy’s GB_apu_div_event has the same spacing: it uses its event counter AND 7 equal to 7 for the envelope, AND 3 equal to 3 for the sweep and AND 1 equal to 1 for the length timers, so the length is every 2nd event, the sweep every 4th and the envelope every 8th. SameBoy starts its counter and splits the envelope into a countdown and a later second event, so we do not map its counter value onto the wiki’s step numbers; the step numbers on this page are the wiki’s. The “next step” in the obscure behaviour list below means the step the sequencer will perform next, in this table’s numbering. Two ticks per length clock is the “every 2 ticks” of the table above. When the APU is switched on, the next step is 0 (wiki, Power Control).
Triggering, length timers and envelopes
Source: Audio.md, Audio_Registers.md, Audio_details.md.
- Triggering (bit 7 of NRx4) turns a channel on and starts its wave from the beginning. If the channel’s DAC is off the write has no effect. Pulse channels are the exception to the restart: their position in the wave is reset only by turning the APU off. Most parameter changes act at once. Some need a retrigger, for example a write to NRx2 while the channel is on.
What a trigger does, from Pan Docs (the NRx4 register entries) and the gbdev wiki (Trigger Event): the channel is turned on; if its length timer has run out it is reloaded (64, or 256 on channel 3); the period divider is reloaded from NRx3 and NRx4 (the wiki calls it the frequency timer); on channels 1, 2 and 4 the envelope timer is reset and the volume is loaded from the initial volume in NRx2; the noise LFSR is reset (Pan Docs: to 0; the wiki: all bits 1 with the output inverted, which is the same thing); the wave position is set to 0 but the sample buffer is not refilled; channel 1 runs the sweep trigger steps below. If the DAC is off the channel is switched off again at once. Pan Docs’ channel 3 entry says “volume is set to NR32 initial volume”, but NR32 has no initial volume (only the output level); that is Pan Docs’ wording, and the wiki’s list has no such step for channel 3. - Turning a channel off happens when its DAC is switched off, when its length timer runs out, or (channel 1 only) when the sweep overflows the period. The envelope reaching volume 0 does not turn the channel off. The low four bits of NR52 report whether the generators are on, not the DACs, and writing to them does nothing.
- Length timer. If enabled in NRx4, it counts up from the value set in NRx1 (inside, Pan Docs says it is inverted when written and counts down to 0, with the same effect) at 256 Hz. At 64 (channels 1, 2 and 4) or 256 (channel 3) the channel is turned off. A higher starting value gives a shorter sound. On trigger, if the timer has run out, it is reloaded.
- Envelope (channels 1, 2 and 4, NRx2): the top four bits are the starting volume, bit 3 the direction (1 = louder), and the low three bits the pace. The envelope ticks at 64 Hz and changes the volume every “pace” ticks. A pace of 0 switches the envelope off. The initial volume bits are readable but are not updated by the envelope. When a tick would take the volume above 15 or below 0 the volume stays as it is, and the envelope makes no further changes until the channel is triggered again (gbdev wiki, Volume Envelope; SameBoy locks the envelope in exactly these two cases: volume 15 while adding, volume 0 while subtracting). The wiki’s to-do list adds that using a period of 0 and then switching to another period also causes an extra clock in some cases; the wiki gives no further detail, so we cannot say when. It is a separate point from the obscure-list rule that a period of 0 acts as 8.
- Master volume (NR50, 3 bits per side): 0 counts as 1 (very quiet) and 7 as 8 (no reduction). It never mutes.
DACs and the mixer filter
Source: Audio_details.md.
- The DAC of channel x is on if and only if
NRx2 & $F8is not 0. Channel 3 uses bit 7 of NR30 instead. The envelope changes the volume, not NRx2, so it never switches a DAC off. - With the DAC on, digital 0 to 15 maps linearly to analogue 1 to −1. The slope is negative: digital 0 is analogue 1, not −1.
- With the DAC off, the output fades to analogue 0, which is “digital 7.5”. How it fades is not entirely predictable and differs between models.
- A channel is switched on by a trigger write unless its DAC is off. The opposite does not hold. A channel that is off outputs digital 0, which a DAC that is on turns into analogue 1.
- Pops. Turning a DAC on or off, adding or removing a channel in NR51, or changing the volume in NR50, changes the constant (DC) level and makes a pop, which the filter then smooths away. To avoid it a sound driver should not switch DACs off: write
$08to NRx2 (silent, DAC still on), then$80to NRx4 to retrigger and reload NRx2. - The high-pass filter removes constant offsets: from inactive channels with their DAC on, and from lopsided waveforms. It is stronger on the Advance than on the Color, and stronger on the Color than on the DMG. A stronger filter pulls faster towards 0 and tends to distort waves.
Period and frequency
Source: Audio_Registers.md.
Channels 1, 2 and 3 have an 11-bit “period value”: the low 8 bits in NRx3 and the top 3 bits in the low bits of NRx4. The period divider is an up-counter. When it is clocked while it holds 2047 ($7FF), it overflows and is reloaded from NRx3/NRx4. So the value acts as a negative number in 11-bit two’s complement, and a higher value gives a shorter period and a higher frequency.
| Channel | Divider clock | Wave length | Sample rate | Tone frequency |
|---|---|---|---|---|
| 1, 2 (pulse) | 1048576 Hz (once per 4 dots) | 8 samples | 1048576 ÷ (2048 − period) Hz | 131072 ÷ (2048 − period) Hz |
| 3 (wave) | 2097152 Hz (once per 2 dots) | 32 samples | 2097152 ÷ (2048 − period) Hz | 65536 ÷ (2048 − period) Hz |
| 4 (noise) | see noise | LFSR | 262144 ÷ (divider × 2shift) Hz | — |
Pan Docs’ examples: a pulse period value of $500 (−$300, 768 clocks per sample) gives a sample rate of 1365.3 Hz and a tone of 170.67 Hz; $740 (192 clocks) gives 5461.3 Hz and 682.67 Hz, which is two octaves above $500. For the wave channel the same values give 85.333 Hz and 341.33 Hz. For equal period values the wave channel is one octave below a pulse channel.
Wave sample rates. The wave channel’s divider runs at 2097152 Hz, so its sample rate is 2097152 ÷ (2048 − period). For $500 (768 clocks per sample) that is 2730.7 Hz; for $740 (192 clocks) it is 10923 Hz (Pan Docs gives these two rates in the NR33 and NR34 text; we checked them: 2097152 ÷ 768 = 2730.67 and 2097152 ÷ 192 = 10922.67). Both are 32 samples per cycle, which gives the 85.333 Hz and 341.33 Hz tones above (2730.67 ÷ 32 and 10922.67 ÷ 32).
Delay. A period change (NRx3, NRx4) takes effect only after the current sample ends, on a pulse channel, and after the next time wave RAM is read, on channel 3 (Pan Docs cites the SameSuite tests channel_1_freq_change and channel_3_freq_change_delay).
Channel 1: pulse with sweep
Source: Audio_details.md and Audio_Registers.md (NR10).
The sweep unit has a sweep timer, an enabled flag and a “shadow register” that holds the current period. The timer is clocked at 128 Hz by the DIV-APU.
On a trigger
- The period value is copied to the shadow register.
- The sweep timer is reset.
- The enabled flag is set if the sweep pace or the step is not 0, and cleared if both are 0.
- If the step is not 0, a frequency calculation and an overflow check are done at once.
The calculation
A frequency calculation shifts the shadow register right by the step, negates it if the direction bit says subtraction, and adds it to the shadow register. In the form Pan Docs gives for NR10: Lt+1 = Lt ± Lt ÷ 2step. The overflow check computes the new period and disables channel 1 if it is above 2047 ($7FF). That happens in addition mode even when the pace is 0 and the iterations are off.
When the sweep timer is clocked, with the enabled flag set and a pace that is not 0, a new period is calculated and checked. If it is 2047 or less and the step is not 0, it is written back to the shadow register and to NR13/NR14, and a calculation and overflow check are run once more at once with the new value. That second result is not written back.
- The period can be changed through NR13 and NR14 while the sweep runs, but the shadow register is not changed, so the next sweep update loses the change. Triggering the channel avoids it.
- The pace written to NR10 is not read again until an iteration finishes or the channel is retriggered. Writing 0 turns iterations off at once; they restart when it is set to something else.
- A period of 0 can never be changed by the sweep, and the sweep cannot underflow the period, so a decreasing sweep cannot turn the channel off.
Pulse channels (1 and 2)
Source: Audio_details.md and Audio_Registers.md.
A pulse channel keeps a “duty step” counter that indexes the chosen waveform. It advances at the channel’s sample rate, 8 times the tone frequency. The counter cannot be reset except by turning the APU off. Retriggering resets the channel’s “duty step timer”, so retriggering often enough stops the duty step ever advancing. A pulse channel that has just started always outputs digital 0 first.
The duty step patterns
The four waveforms, one digital output per duty step, step 0 on the left and step 7 on the right. A 1 is the high level, a 0 the low level. The counter runs through the eight steps again and again. The patterns are the gbdev wiki’s table and SameBoy’s duties[] array (both agree). Pan Docs draws the same waveforms as pictures; we drew ours from the step strings.
| NRx1 bits 7–6 | Duty | Steps 0 to 7 | Drawing |
|---|---|---|---|
| 00 | 12.5 % | 00000001 | |
| 01 | 25 % | 10000001 | |
| 10 | 50 % | 10000111 | |
| 11 | 75 % | 01111110 |
The duty setting also changes the phase, which is hardly noticeable except next to other channels. The patterns show why: they do not all start at the same point of the cycle. There is no audible difference between 25 % and 75 %: 01111110 is 10000001 with the two levels swapped.
Where the pattern bit is 0 the envelope outputs 0, otherwise it outputs the current volume (gbdev wiki, Volume Envelope). A pulse channel plays digital 0 first after power-on (see the obscure behaviour list).
Channel 3: wave
Source: Audio_details.md and Audio_Registers.md.
- Channel 3 plays 32 samples of 4 bits from wave RAM (
$FF30–$FF3F, 16 bytes), upper nibble of each byte first. - A “sample index” counter steps at 32 times the tone frequency. Each step reads one nibble.
- The channel keeps a one-sample buffer and outputs it continuously. A trigger does not clear or refresh the buffer, so the last sample ever read is output until the next read. The buffer is cleared only when the APU is turned on, so a freshly powered channel outputs digital 0.
- First sample. At a trigger the index is reset, but wave RAM is not refilled. The first sample played is therefore the old one in the buffer, and the next is the lower nibble of the first byte, index 1. Sample 0 (the upper nibble of
$FF30) is not played until the wave loops. - Output level (NR32 bits 6–5): 00 mute, 01 100 %, 10 50 % (shift right once), 11 25 % (shift right twice). The shift acts on the digital value, not the analogue one. That only matters when the level is changed during playback: the shifted digital values lean towards 0, which leans the analogue output towards 1, and the filter smooths it over time, not instantly.
- The channel has no envelope. Its length timer counts to 256.
Wave RAM access while the channel plays
While channel 3 is active, accesses to wave RAM misbehave:
- On the Advance, reads return
$FFand writes are ignored. - On monochrome consoles, wave RAM can only be reached on the same cycle as the channel reads it. Otherwise reads return
$FFand writes are ignored. - On the other consoles, the CPU reaches the byte the channel is reading, whatever address it uses. For example, while the channel reads one of the first two samples, the CPU really accesses
$FF30. Pan Docs explains that the channel has priority over the CPU for choosing among the 16 bytes, so the CPU sees the same byte at every address. - With the DAC on but the channel not active, wave RAM can be accessed normally. This matters on the Advance, whose mixer acts as if DACs were always on. Pan Docs advises turning the DAC off (NR30) before writing wave RAM.
Wave RAM corruption (monochrome only)
Retriggering channel 3 on a monochrome console just as it is about to read a byte corrupts wave RAM. Pan Docs’ obscure-behaviour list gives the rule: if the channel was reading one of the first four bytes, only the first byte is rewritten with the byte being read. If it was reading one of the later 12 bytes, the first four bytes are rewritten with the four aligned bytes that contain the byte being read (bytes 4–7, 8–11 or 12–15). Example: reading byte 9 rewrites bytes 0–3 with bytes 8–11. To avoid it, stop the wave by writing 0 and then $80 to NR30 before triggering again. Pan Docs says Duck Tales runs into this part of the way through most songs. Elsewhere Pan Docs calls the corruption “generally unpredictable”, so treat this rule as a description of observed cases.
Channel 4: noise
Source: Audio_details.md and Audio_Registers.md.
The generator is a 16-bit linear-feedback shift register (LFSR): 15 bits of state and one temporary bit for the next input. Each time it is clocked, at 262144 ÷ (divider × 2shift) Hz (NR43; divider 0 counts as 0.5; a shift of 14 or 15 gives no clocks at all):
- Bit 0 and bit 1 are compared. If they are the same (XNOR), 1 is written to bit 15, otherwise 0.
- If NR43 selects 7-bit (“short”) mode, bit 15 is also copied to bit 7.
- The whole register is shifted right. The bit shifted out of bit 0 chooses between 0 and the current envelope volume as the output.
Our own drawing of one clock (the 16 boxes are bits 15 to 0; Pan Docs has its own figure):
The LFSR is set to 0 on every trigger. Lock-up: if the active part of the register is all 1s, only 1s are produced and the channel stays silent until retriggered. It does not happen in normal use. It can be made to happen by switching from 15-bit to 7-bit mode when the low 7 bits are all 1s, which occurs fairly soon after a trigger.
PCM12 and PCM34
Source: Audio_details.md. Two read-only registers, present on the Color and later, show the generators’ digital outputs. Pan Docs says they are not in any known Nintendo manual and that they are useful for testing the APU. $FF76 (PCM12): the low nibble copies channel 1’s digital output, the high nibble channel 2’s. $FF77 (PCM34): the same for channels 3 and 4. The registers are on registers/#ff76.
Game Boy Advance audio
Source: Audio_details.md.
- The Advance mixes digitally, not with analogue circuits, then converts to analogue and adds an offset (Pan Docs points to the SOUNDBIAS register in GBATEK).
- It has no DACs. They are emulated so that a DAC that is off acts like a DAC that is on and receives 0.
- Channel 3’s DAC output is inverted, so the channel gives a loud spike when disabled. Pan Docs advises disconnecting it with NR51 before touching wave RAM.
- The extra features of the Advance (more wave RAM, digital FIFOs and so on) are not available to Color programs.
Reading the registers back
Sources: the gbdev wiki (Register Reading), Shay Green’s (blargg’s) dmg_sound test 01-registers.s and SameBoy’s read_mask table in Core/apu.c. All three give the same values, and they are the same for the whole audio chapter. When a register is read, the value last written is ORed with a mask. The bits of the mask are the bits that cannot be read back (write-only, unused, and the length, which is a counter). The unused bits always read 1. The table lists the mask, then what that means for the bits.
| Register | Address | OR mask |
|---|---|---|
| NR10 | $FF10 | $80 |
| NR11 | $FF11 | $3F |
| NR12 | $FF12 | $00 |
| NR13 | $FF13 | $FF |
| NR14 | $FF14 | $BF |
| NR21 | $FF16 | $3F |
| NR22 | $FF17 | $00 |
| NR23 | $FF18 | $FF |
| NR24 | $FF19 | $BF |
| NR30 | $FF1A | $7F |
| NR31 | $FF1B | $FF |
| NR32 | $FF1C | $9F |
| NR33 | $FF1D | $FF |
| NR34 | $FF1E | $BF |
| NR41 | $FF20 | $FF |
| NR42 | $FF21 | $00 |
| NR43 | $FF22 | $00 |
| NR44 | $FF23 | $BF |
| NR50 | $FF24 | $00 |
| NR51 | $FF25 | $00 |
| NR52 | $FF26 | $70 |
$FF27to$FF2Fare unused and always read$FF.- Wave RAM (
$FF30–$FF3F) has no mask: it reads back what was written (but see the access rules while the channel plays). - NR52 is special: the mask
$70is ORed with bit 7 (APU on) and the four channel-on bits, not with a written value. Blargg’s test 3 writes$00and$FFto NR52 and expects$70and$F0back with every channel off. - So NR10 reads back with bit 7 set, NR11 and NR21 with the length bits (5 to 0) set, NR14, NR24, NR34 and NR44 with only bit 6 (length enable) readable, NR30 with only bit 7, NR32 with only bits 6 and 5, and NR43, NR50, NR51 fully readable.
- Pan Docs’ power-on values of these registers (
$80,$BF,$3F,$F3,$7F,$9Fand so on) are values already ORed with the masks, which is why they fit.
Power on, power off and wave RAM at start-up
Sources: Pan Docs (NR52 and Power Up Sequence), the gbdev wiki (Power Control) and SameBoy’s GB_apu_init and register write code.
- Turning the APU off (NR52 bit 7 = 0): Pan Docs says it uses about 16 % less power, clears all the APU registers and makes them read-only until the APU is turned on again, except NR52. All of NR10 to NR51 are written with 0 at that moment (wiki). The wave RAM is not affected and can always be read and written, and the 512 Hz timer that feeds the frame sequencer is not affected either.
- Monochrome models: the four length registers (NR11, NR21, NR31, NR41) can still be written while the APU is off, and the length counters keep their values (wiki: “on the DMG, length counters are unaffected by power”; SameBoy does the same on every non-Color model). On the Color the length counters are zero at power-up (wiki, Differences).
- Turning the APU on: the frame sequencer is reset so that the next step is step 0, the pulse duty units go back to the first step of the pattern, and the wave channel’s sample buffer is reset to 0 (wiki). SameBoy does the same by clearing its whole APU state when NR52 bit 7 goes from 0 to 1. One quirk is only in SameBoy: if bit 4 of DIV (bit 5 in double speed) is 1 at that moment, the first frame sequencer event is skipped.
- Disagreement about the step counter. Pan Docs says turning the APU off does not affect “the DIV-APU counter”. The wiki and SameBoy reset the step to 0 when the APU is turned on. These are probably two views of different things: the 512 Hz timer (unaffected by NR52) and the step number (reset on power-on). Neither source says so. We state both; the page does not claim they agree.
- Wave RAM contents at power-up (before the boot ROM runs), from the wiki: on the DMG they are somewhat random, but the same pattern for each unit; one unit gave
84 40 43 AA 2D 78 92 3C 60 59 59 B0 34 B8 2E DA. The game R-Type does not initialise wave RAM and relies on them. On the Color the values are always00 FF 00 FF 00 FF 00 FF 00 FF 00 FF 00 FF 00 FF. Pan Docs’ Power Up Sequence lists no wave RAM values; the wiki is the only source here, and we do not know the contents for other models.
VIN voltage levels
Source: the gbdev wiki (Vin Mixing). When VIN is enabled in NR50 it is mixed in before the master volume. On the DMG and the MGB 0.847 volts is equivalent to 0 on a channel DAC and 3.710 volts to 15, with the values between spread linearly. On the Color the range is 1.920 volts to 2.740 volts, a quarter of the DMG range (the span is 0.820 V against 2.863 V, which is 0.29, so “a quarter” is the wiki’s rounding), so a signal on VIN is much louder on the Color. With nothing connected VIN floats at the middle voltage, which is silence. Pan Docs says only that VIN is a fifth channel with its enable bits in NR50 and that Pocket Music does not use it.
Models tested and how they differ
Source: the gbdev wiki (the list near the top, and Differences). The wiki says it tested the following consoles: DMG-CPU-03 (the original Game Boy), DMG-CPU-05, DMG-CPU-06, MGB-LCPU-01 (Game Boy Pocket), CGB-CPU-02, CGB-CPU-04 and CGB-CPU-05 (Game Boy Color). It found these differences:
| Behaviour | DMG-03, DMG-05, DMG-06, MGB-01 | CGB-02 | CGB-04 | CGB-05 |
|---|---|---|---|---|
| Wave RAM access while the channel plays | only on the cycle the channel reads it | any time (at the byte the channel is reading) | ||
| Retriggering the wave channel without disabling it first | rewrites the first four bytes of wave RAM | behaves normally | ||
| Length counters and power off | kept, and writable while off | always zero at power-up | ||
| Extra length clock on an NRx4 write | the new length enable must be on | the new enable state does not matter | the new length enable must be on | |
| Volume change by writing NRx2 (“zombie” mode) | $x0 to $xx and $x7 to $xx are “very screwey” | as in the obscure list below | if the mode is not changed, only $x8 to $xx changes the volume; the mode change is also a little different | |
Pan Docs names only the CGB-02, CGB-04 and CGB-05 (and the Advance) in its obscure list. SameBoy treats models up to the CGB-C and from the CGB-D on differently for NRx2 writes (see the zombie mode section). Models not in the wiki’s list (the SGB, the SGB2, the Advance, other Color revisions) are not covered by any source we have read, except where the page says otherwise.
“Zombie” mode on the DMG
Pan Docs and the wiki call the volume change by an NRx2 write while a channel plays “zombie” mode, and give exact rules only for the CGB-02 and CGB-04 (the obscure list). For the monochrome models the sources say:
- The wiki (Differences): on the DMG-03, DMG-05, DMG-06 and MGB-01 the changes from
$x0to any value and from$x7to any value are “very screwey”. Its obscure list says the DMG has “crazy behavior in some cases” and that the only useful consistent behaviour is adding with period 0: write$V8to set the starting volume V, then$08to raise the volume by one. - SameBoy (
nrx2_glitch,Core/apu.c): its comment says that on models before the Color some of the cases are non-deterministic, “$x0 writes” in particular, while “$x8” writes always work as expected, and that it suspects writes to and from$xFare deterministic. SameBoy emulates the glitch for the models up to the CGB-C as two writes in a row: first$FFover the old value, then the new value over$FF. From the CGB-D on it applies the plain old-to-new rule. The envelope is blocked from ticking when the volume is at 15 while adding or at 0 while subtracting.
Blargg’s dmg_sound readme has nothing on it. The hardware results for the monochrome models are therefore not known to us beyond the wiki’s “very screwey” list and SameBoy’s comment. SameBoy itself, however, gives a result for every old and new pair: a fixed rule, written out below. It is a model made by one author, not a measurement of every unit.
SameBoy’s rule, exactly
Source: nrx2_glitch and _nrx2_glitch, Core/apu.c lines 511 to 569, called from the NR12/NR22 write (line 1892) and the NR42 write (line 2185). It runs only when the channel is playing and the new value does not switch the DAC off (a new value with its top five bits all 0 just stops the channel, line 1884). Step is one run of _nrx2_glitch(volume, value, old_value). Models up to the CGB-C (that is, every monochrome model and the early Colors) do two steps: step ($FF, old) and then step (new, $FF). The CGB-D and later do one step (new, old).
- If the envelope clock is running (the source’s
clockflag), the volume countdown is set to the low 3 bits of the step’s value. - tick is true if the value’s pace (bits 2 to 0) is not 0, the old value’s pace is 0 and the envelope is not locked.
- invert is true if bit 3 (direction) of the value and of the old value differ.
- If the low four bits of both are
8and the envelope is not locked, tick is true. - If invert: when the value’s direction is up, then (old pace 0 and not locked) gives volume = volume XOR 15, otherwise volume = (14 − volume) AND 15, and tick is cleared. When the value’s direction is down, volume = (16 − volume) AND 15.
- If tick: the volume goes up by 1 (direction up) or down by 1 (direction down), AND 15. Otherwise, if the value’s pace is 0 and the envelope clock is running, the clock is stopped.
The envelope is “locked” once a clock has run to the end while the volume was 15 and adding, or 0 and subtracting (set_envelope_clock, lines 498 to 509). The source comment says some of these cases are non-deterministic on real monochrome units: that is not coded, and every old/new pair gets one fixed result. The results below were worked out by running these steps (script scripts/gb/fix10-zombie-examples.mjs) with volume 5, the envelope clock stopped and not locked:
| Old | New | Two steps (up to CGB-C) | One step (CGB-D and later) |
|---|---|---|---|
$08 | $08 | 6 | 6 |
$00 | $08 | 10 | 10 |
$08 | $00 | 10 | 11 |
$38 | $30 | 10 | 11 |
$30 | $38 | 10 | 10 |
$0F | $08 | 5 | 5 |
The first row is the dependable trick of the obscure list ($V8 then $08 adds 1). What is still unknown is how often real units follow this model: the wiki’s “very screwey” changes from $x0 and $x7 and SameBoy’s non-deterministic $x0 writes are not reproduced by any fixed rule.
The DAC fade
Pan Docs says a disabled DAC fades to analogue 0 (“digital 7.5”) and that the fade is not entirely deterministic and varies between models. It gives no time or shape. The only number we found is in SameBoy, which does not claim to measure a real console in general: Core/apu.h defines DAC_DECAY_SPEED and DAC_ATTACK_SPEED as 20000, in units of “1 / length in seconds”. So its fade, in either direction, takes 1 ÷ 20000 s = 50 µs, smoothed by a curve, for the Color and the monochrome models alike. The fade constants and the lines that use them (apu.c lines 332 to 352, applied when the model is the CGB-E or older) carry no comment about where the numbers come from. The comment “TODO: only measured on one DMG (CPU revision unconfirmed); … assumed shared by all pre-CGB models” is elsewhere in Core/apu.c, in six places: the delay of the DAC output on monochrome models (line 325, the delay_dac flag in render); the rule that the last DAC to go off disconnects the mixer at once, without waiting for the fade, with the coupling capacitor then held while no DAC is on (line 390); the sampling of the square duty on the frequency clock (line 474); the latching of the noise feedback (line 867); the square duty sequencer running until the DAC goes off (line 1020); and the reconnecting of a DAC at full level to the held capacitor (line 2285). So the one-DMG measurement is claimed by SameBoy for those behaviours of the monochrome models, not for the 50 µs fade. This is a model made by one emulator author, not a specification. The wiki and the blargg readme say nothing about the fade.
The high-pass filter charge factor
The filter code in Pan Docs and the wiki (see the obscure list below) uses the factor 0.999958 for one output sampled at 4194304 Hz on the DMG, and 0.998943 for the MGB and the Color. For another sample rate the factor is 0.999958(4194304 ÷ rate) (0.996 at 44100 Hz). SameBoy does not use 0.998943 at all. In GB_set_sample_rate and GB_set_sample_rate_by_clocks it computes pow(0.999958, cycles per sample) for every model; the number 0.998943 does not appear in Core/apu.c. The two sources disagree for the MGB and the Color, and none of our sources says which is right. This page follows Pan Docs and the wiki where it gives the factors for a given model, and notes SameBoy’s single value as the emulator choice. For the DMG all three agree on 0.999958.
The gbdev wiki’s own open points
The wiki page (revision 998 of its Gameboy sound hardware article, last changed 25 November 2020) ends with a To Do list of six points. Each is something the wiki’s author had not worked out; we have no source that does:
- Using an envelope or sweep period of 0 and then switching to another period also causes an extra clock in some cases.
- Frequency sweep has some really intricate behaviour when the sweep register is rewritten.
- The noise channel’s frequency timer is more complex than described: a trigger does more than reload it, and it may have several dividers of which only some are reset.
- The behaviour of triggers and register writes within a few clocks of frame sequencer events has yet to be determined.
- How the noise LFSR is built, with regard to mode changes, is to be worked out.
- The exact timing of the DMG wave channel issues is to be documented.
These six are the wiki’s list of six; SameBoy’s source has code for some of them (for example NR10 rewrites and NR43 mode-change glitches, with comments saying parts are “TODO” or non-deterministic) but no description we could cite as a rule. SameBoy’s NR10 rewrite code and the Color double-speed envelope delay are written out in their own section as SameBoy’s model; the other points stay unknown here.
Double speed on the Color: delayed envelope and NR10 rewrites
Source: SameBoy Core/apu.c and Core/timing.c (saved in samples/gb/sources/sameboy-core). The wiki’s open point 2 (“frequency sweep has some really intricate behaviour when rewriting the sweep register”) only names the problem; the blargg readmes do not mention it. SameBoy has code for it, with comments saying much of it is the author’s own units. Pan Docs has none of this.
The envelope tick on the CGB-D and CGB-E in double speed
- In
GB_apu_div_event(line 706) the envelope step is the one with(div_divider & 7) == 7. On every model, a channel whose envelope clock is not running gets its volume countdown lowered by 1 (modulo 8) at that step (lines 723 to 734). - The envelope tick itself (
tick_square_envelopeandtick_noise_envelope, volume up or down by 1) runs at once, in the same step, on all models except one case. If the model is the CGB-D or the CGB-E and the CPU is in double speed, the step only setspending_envelope_tick(lines 736 to 738). - The tick then runs from the DIV loop in
timing.c(lines 313 to 321): that loop adds 4 to the DIV counter, then sleeps 4 cycles, and whenpending_envelope_tickis set it callsGB_apu_delayed_envelope_tick, which clears the flag and runs the same ticks for the channels whose envelope clock is running (apu.clines 686 to 704). So on those two revisions the envelope tick comes one step of that loop (4 cycles of the CPU clock, one M-cycle) after the frame sequencer step, and on the other Colors and in normal speed it comes at once. The size of the delay is our reading of the loop; the source states no number. - In double speed every envelope tick also clears bits of the PCM12 and PCM34 read-back masks (
pcm_mask,apu.clines 578 to 598 and 623 to 625). The masks are set back to$FFat the start of the next frame sequencer step (lines 692 and 709). Channel 2 has a special case on the CGB-0: mask$1Finstead of$3Fwhen the volume is 1 and the direction is up. The comment calls the CGB-0 behaviour instance specific and non-deterministic, and says the author’s unit sometimes yields 1 for the 8 to 7 and 4 to 3 steps.
NR10 rewrites while a sweep calculation is pending
nr10_write_glitch (line 1223) runs on an NR10 write when either square_sweep_calculate_countdown (the delayed calculation, loaded from the NR10 step bits, lines 672 and 680) or its reload timer is not 0 (line 1854). A comment says all of it is still to be checked in the APU “odd” mode. lf_div is the half-rate phase flag of the APU clock. Two cases:
Models up to the CGB-C (lines 1226 to 1270):
- If the reload timer is 1 and
lf_divis 0: in double speed only, the countdown is replaced bycorruption[countdown AND 7]. Outside double speed nothing is done in this branch. - Else if the reload timer is above 1: in double speed only, the countdown becomes the new NR10 step (value AND 7).
- Else if the countdown is not 0: a “zombie step” (the countdown is lowered by 1, and when it reaches 1 or less it is set to 0 and the calculation is finished at once) is taken if the old NR10 step is 0 and
lf_divdiffers from the double-speed flag, or if the old step is not 0, the CPU is in double speed and the countdown is 1. The source comment says “No clue why 1 is a special case here”.
The table used (line 1231) is the one from two of the author’s CGB-C units and his CGB-A. The other tables are in comments (lines 1232 to 1237). * marks a result that is non-deterministic on that unit. Index = countdown value before the write; entry = countdown after.
| Unit (source comment) | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 |
|---|---|---|---|---|---|---|---|---|
| Two CGB-C and the CGB-A (used, line 1231) | 7 | 7 | 5 | 7 | 3 | 3 | 5 | 7 |
| Another CGB-C and Coffee Bat’s CGB-C (line 1232) | 7 | 7 | 1 | 3 | 3 | 3 | 5 | 7 |
| The author’s CGB-B (line 1233) | 7 | 1 | 1 | 3 | 3 | 5 | 5 | 7 |
| The author’s CGB-0 (line 1234) | 7 | 7 | 1 | * | 3 | 3 | 5 | 7 |
| PinoBatch’s CGB-B (line 1236) | 7 | 5 | 1 | 3 | 3 | 1 | 5 | 7 |
| GenericHeroGuy’s CGB-C (line 1237) | 7 | 5 | 1 | 3 | 3 | * | 5 | 7 |
Two things are marked as open in the source: how the corruption affects the real frequency calculation (“TODO”, lines 1240, 1248), and the value 1 needing special handling, which does not occur on the unit emulated (line 1243). The six tables disagree, so the result depends on the unit, as the source comment says.
CGB-D and later, and the monochrome models (lines 1271 to 1289; the else of the model test):
- If the reload timer is 2 (the countdown has just reloaded): the countdown is loaded again from the new step. If that step is 0, the reload timer is cleared.
- If the new step is not 0, the old step was 0,
lf_divis 0 and the countdown is above 1: the countdown is lowered by 1 and, if it becomes 0, the calculation finishes at once (“another odd glitch”, marked TODO).
Related, in the same file: the old direction bit is taken as “subtract” on models up to the CGB-C when the overflow check after an NR10 write is made (lines 1857 to 1866), and the delay after a trigger is 6 plus or minus lf_div depending on the model and speed (line 1954). These tables and rules are SameBoy’s model of the author’s units, not a measurement of every console.
Obscure behaviour
Source: Audio_details.md, “Obscure Behavior”. The conditions are Pan Docs’ own wording as nearly as we can give it in short form.
- The envelope and sweep timers treat a period of 0 as 8.
- Just after power-on, the first duty step of channels 1 and 2 after their first trigger is played as if it were 0, and duty clocking is off until that first trigger.
- Triggering channel 3: the first sample played is the one still in the high nibble of the sample buffer, and the next is the second nibble of the wave table, because the first byte is not loaded on a trigger as it should be. The first nibble of the table plays only when the wave loops.
- Triggering channels 1 and 2 does not change the low two bits of the frequency timer.
- Extra length clock. If NRx4 is written when the next DIV-APU step is one that does not clock the length timer, and the length timer was previously disabled and is now enabled and is not zero, it is decremented once. If that makes it zero and the trigger bit is clear, the channel is turned off. On the CGB-02 only the earlier “disabled” state matters; the current enable state does not. This breaks at least one game (Prehistorik Man) and was fixed on the CGB-04 and CGB-05.
- If a channel is triggered when the next DIV-APU step is one that does not clock the length timer, and length is enabled and being set to 64 (256 for the wave channel) because it was zero, it is set to 63 (255) instead.
- If a channel is triggered when the next DIV-APU step will clock the envelope, the envelope timer is reloaded with a value one greater than it would have been.
- A noise clock shift of 14 or 15 gives the LFSR no clocks.
- Sweep direction. Clearing the direction bit in NR10 after at least one sweep calculation has been made in subtraction mode since the last trigger turns the channel off at once. This stops a sweep that lowers the frequency and then raises it without a trigger between.
- “Zombie” mode. The volume can be changed by writing NRx2 while a channel plays. The result depends on the old and new values and on whether the envelope has stopped updating. The CGB-02 and CGB-04 are the most consistent. If the old envelope pace was 0 and the envelope is still updating, the volume goes up by 1; otherwise, if the envelope was in decrease mode, it goes up by 2. If the direction was changed, the volume becomes 16 minus the volume. Only the low 4 bits are kept. Other models behave differently, especially the DMG, which Pan Docs says has “crazy behavior in some cases”. The one dependable trick: set the starting volume V with
$V8in NRx2 before triggering, then write$08to raise the volume by 1 as the sound plays (15 writes lower it by 1). This works on every unit tested. - DACs off and the filter. When all four DACs are off, the master volume units are cut off from the output and the level is 0. When any DAC is on, a high-pass filter capacitor is connected. Pan Docs gives a C routine for one DMG output at 4194304 Hz, which in words is: if any DAC is on, the output is the input minus the capacitor value, and the capacitor then becomes the input minus the output times a charge factor; if no DAC is on, the output is 0. The factor is 0.999958 for the DMG and 0.998943 for the MGB and Color. For another sample rate use 0.999958(4194304 ÷ rate), which is 0.996 at 44100 Hz.
Sources
- Raw Pan Docs Markdown (CC0), read 2026-11-19, in
samples/gb/sources/pandocswith SHA-256 in the sample README:Audio.md,Audio_Registers.md,Audio_details.md. - gbdev wiki, Gameboy sound hardware (revision 998,
samples/gb/sources/sameboy-core/wiki-Gameboy_sound_hardware.html, fetched from gbdev.gg8.se 2026-11-19); blargg’sdmg_soundandcgb_soundreadmes and01-registers.s(samples/gb/sources/blargg); SameBoyCore/apu.candCore/apu.h(MIT,samples/gb/sources/sameboy-core). SHA-256 of each file is in the sample README. - Audio, Audio Registers, Audio Details – Pan Docs
Not described
Known, not yet covered
- Nothing known is left. The signal path, the LFSR and the four duty waveforms are drawn from the text, and the read-back masks, the frame sequencer steps, power-on behaviour, wave RAM at power-up, envelope stop, VIN levels, tested models, wave sample rates, trigger effects and the charge-factor disagreement are all written above.
Unknown
- The six open points of the gbdev wiki (period 0 extra clock, sweep rewrite details, the noise frequency timer, writes close to frame sequencer events, the noise LFSR on mode changes, DMG wave timing). No source describes them.
- “Zombie” mode on the monochrome models: what real units do for each old/new NRx2 pair. SameBoy gives a fixed result for every pair (the two-writes rule above); only the hardware results are unknown. The wiki and SameBoy say that
$x0and$x7changes are unreliable and$x8reliable; blargg’s readmes have nothing on it. - How the NR10 rewrite corruption and the delayed envelope tick on the Color behave on units other than the author’s, and what the corruption does to the real frequency calculation. SameBoy’s tables are one author’s units (six tables, they differ), and its own comments mark parts as TODO.
- The real fade of a disabled DAC. Pan Docs and the wiki give no figures; SameBoy’s 50 µs model is one emulator author’s choice, with no source given for the constants, and is not a specification.
- Which charge factor is right for the MGB and the Color: 0.998943 (Pan Docs, wiki) or SameBoy’s 0.999958 for all models.
- Wave RAM contents at power-up on models other than the DMG example and the Color pattern, and the models not in the wiki’s tested list (SGB, SGB2, Advance, other Color revisions).
- Whether the frame sequencer step is reset on power-on (wiki, SameBoy) or the DIV-APU counter is left alone (Pan Docs); the sources do not say how the two statements fit.
- Whether any of this is right on real consoles, as far as the sources do not already say so. We ran no ROM and no emulator and had no hardware. What blargg’s tests, SameBoy and the wiki say about real consoles is stated as their statement, and we cannot confirm it ourselves.