Game Boy APU Frame Sequencer: Length, Sweep, and Envelope Timing

The Game Boy Audio Processing Unit is not a set of static frequency registers that directly generate four ideal waveforms. Channel timers, length counters, volume envelopes, frequency sweep, and the frame sequencer interact over emulated time. A game can depend on those transitions for note duration, volume changes, channel retrigger behavior, and even audio-related side effects. If an emulator updates all sound registers only once per video frame, it can produce plausible music while missing the hardware’s timing contract.

The four sound channels have different generation rules: two pulse channels, with sweep available on channel 1; one programmable wave channel; and one noise channel. The frame sequencer clocks slower envelope and length units, while each channel’s own timer advances at a higher rate derived from the base clock. These are separate layers of timing. An emulator should schedule channel edges precisely enough for its audio model and apply frame-sequencer events at the documented steps.

Frame-sequencer cadence

The frame sequencer advances at 512 Hz on the standard Game Boy timing model, producing an eight-step sequence. Length counters are clocked on alternating even steps (0, 2, 4, and 6); the channel 1 frequency sweep is clocked on step 2; volume envelopes are clocked on step 7. This yields distinct effective update rates: length at 256 Hz, sweep at 128 Hz when enabled, and envelope at 64 Hz. The sequence is shared state that advances independently of a particular channel trigger.

Do not replace the sequence with three unrelated periodic timers that begin at different phases. Register writes and channel triggers can occur between sequencer steps, so phase affects when a length decrement or envelope update happens next. The underlying divider and model-specific behavior determine that phase. Tests should cover writes immediately before and after each frame-sequencer event rather than checking only long-term average frequency.

When a length counter expires while the channel’s length-enable behavior is active, the channel can be disabled. The exact edge behavior when enabling length or changing a counter near a sequencer step is a common source of off-by-one audio bugs. Check the hardware documentation and known tests for the target DMG/CGB revision; do not infer the behavior from how a modern audio API expresses a duration.

Pulse sweep and overflow behavior

Channel 1 includes a frequency sweep unit. The sweep register specifies a pace, direction, and shift amount. At a sweep clock, the unit derives a candidate frequency by adding or subtracting a shifted version of the current frequency. If the candidate exceeds the channel’s supported range, the channel is disabled. There is also an overflow check associated with triggering or subsequent sweep calculation, so checking only when a nonzero periodic timer fires can miss a hardware-visible disable.

The “period zero” case is easy to mishandle. Pan Docs describes the sweep and envelope timer treatment of zero as a period of eight for timer operation, while the enable conditions for actual sweep calculations involve other fields such as shift. Keep the timer value, sweep-enabled condition, shadow frequency, and second overflow check as distinct state. A single integer countdown named sweep_period is not enough to express all of that behavior.

Sweep negate mode has an additional write-history nuance on known hardware revisions: switching from subtraction to addition after a subtraction calculation can disable the channel. This is often called the negate-use behavior. Treat model differences explicitly and cite the relevant hardware test coverage; do not apply one revision’s quirk to every device without evidence.

Envelope clocks and channel triggers

Pulse and noise channels have volume envelopes that change volume at frame-sequencer events according to initial volume, direction, and period. A zero programmed period has special timer interpretation; it does not simply mean “update continuously.” Envelope state includes current volume and an internal timer, and trigger operations initialize channel state according to hardware rules.

Triggering a channel is not equivalent to resetting every internal counter indiscriminately. The channel’s length counter, frequency timer, envelope, sweep, and waveform position have specific write and trigger interactions. Model these registers and internal states separately. If a game’s sound changes after writing a frequency high byte with the trigger bit, compare each state transition with the hardware behavior rather than adding a general “restart waveform” shortcut.

The wave channel adds Wave RAM access restrictions and a sample position that are not present on the pulse channels. The noise channel uses a linear-feedback shift register and divisor/shift parameters rather than a periodic waveform table. The frame sequencer clocks selected units, but each channel’s output timer and waveform generator continue to evolve between those clocks.

Power state and model-specific behavior

The master sound enable register controls APU power and exposes channel activity flags. Turning the APU off changes which registers are writable and resets some internal state, with details that vary by model and are documented separately from the nominal channel formulas. Do not assume clearing master power preserves every channel register or waveform phase. Test power-off/on sequences independently from warm reset and emulator state restoration.

DMG, CGB, and later Game Boy models can differ in sound behavior, register readback, and waveform access. Pan Docs separates many model-specific observations and test results. A core should represent hardware revision differences intentionally, especially if it claims compatibility with multiple consoles. If a behavior is uncertain, expose it as an identified model difference rather than silently using a DMG rule on CGB.

Build timing tests instead of tuning by ear

Use deterministic register-write tests and capture the sequence of channel events. A length test should initialize a known length, enable length timing, and compare shutdown against frame-sequencer phase. An envelope test should record each volume step over several 64 Hz clocks. A sweep test should cover addition, subtraction, zero period, shift zero, overflow, trigger-time overflow, and negate-use behavior. Keep the CPU write timestamp and sequencer step in the trace.

For audio output, compare at the emulated sample boundary and document resampling separately. A host audio callback can buffer or resample samples; that does not explain a channel register updating at the wrong emulated cycle. Validate channel state first, then compare output after the emulator’s mixing and resampling path. A waveform that sounds acceptable at one sample rate can still contain incorrect timing or state transitions.

Useful checks include known test ROMs, hardware captures when available, and differential comparison across established emulator implementations. Record the exact ROM hash, Game Boy model, audio configuration, emulator revision, and test result. Avoid relying on commercial music as the only test because an arrangement may not exercise a specific edge case.

Save states and deterministic replay

A save state taken mid-note may need to preserve frame-sequencer position, pending channel timer values, sweep shadow/negate state, envelope countdown, waveform index, noise LFSR, and audio resampler state. Restoring only register values can produce a click or shift the next envelope update. Decide whether the emulator promises audio-continuous restore or only game-state restore, then test and document the boundary.

Netplay and replay systems require deterministic APU state evolution. Host audio buffering must not feed back into emulated channel timers. Keep emulated clocks independent of wall-clock audio callback cadence, and ensure frame-rate adjustment does not silently change the 512 Hz sequencer’s relative phase.

The Game Boy frame sequencer is a small state machine with large audible and software-visible consequences. Preserve its shared phase, separate it from channel timers, and verify edge cases at register-write boundaries. That approach produces timing evidence that is more useful than repeatedly adjusting a global audio latency slider.

Related:

Sources: