Audio

Working on assembly/audio/. Read files directly for API; this skill captures non-obvious invariants and derived lookup data only.

Non-Obvious Invariants

• Channel buffer size = 128 (AudioData.HalfBufferSize = AudioOutBuffer.BufferSize >> 1). Render(start, end) indices are 0–127. To advance N samples call Render(0, 128) × ceil(N/128).
• Phase NOT reset on trigger — only Reset() (called by AudioRender.Init()) zeroes phase. Re-trigger restores envelope and re-enables; phase continues.
• NR13/NR14 PeriodHigh write does NOT update sweepShadowPeriod — shadow only updated by trigger and sweep ticks.
• Envelope changes only visible at segment boundaries (≤128 samples). TickSamples runs after each segment; GetCurrentEnvelopeVolume() is sampled once per segment start.
• MixChannels formula: (nibble / 7.5) - 1.0 maps 0–15 → -1…+1; divided by active channel count.

CH1 Sweep: Critical Order of Operations

On trigger (step≠0): immediate sweepCalcNewPeriod() overflow check before any tick. If result >2047 → disable(). This means high-period + large-step combos disable on trigger, not on first tick.

On tick (pace≠0):

1. newPeriod = shadow ± (shadow >> step). Overflow → disable, return.
2. If step≠0: write back to shadow+frequencyBits, then second overflow check on updated shadow — can disable even when step 1 passed.

Pace=0: timer still runs (effectivePace=8 per obscure spec), but no frequency update on tick.

Negate-then-clear: clearing NR10 negate bit after subtract mode was used in current trigger cycle → immediate disable() (checked in HandleSweepEvent).

Duty Cycle Lookup (PulseChannel)

Output: phase >= waveHighRatio ? volume : 0

Names are counterintuitive: "VeryHigh" = mostly LOW (only top 12.5% of phase is high).

Timing Reference (at SAMPLE_RATE=44100)

CH3 length: round((256 − timer) × 44100/256).

Test Period Reference

Sweep safety with step=1 (add): trigger immediate check requires period + period/2 ≤ 2047 → period ≤ 1364. Use step=4 for high-frequency sweep tests.

Uint4Array — Channel Buffer Storage

Buffer in each channel is Uint4Array: two 4-bit samples packed per byte.

• length = internal.length × 2 (128-sample buffer → 64 bytes internal)
• get(i): byte = i>>1; shift = (i%2)<<2 (0 for even, 4 for odd); return (byte >> shift) & 0xF
• set(i, v): masks out target nibble, ORs in v << shift; asserts v ≤ 0xF
• wrap(buffer, byteOffset, length): zero-copy view over existing ArrayBuffer; length is byte count, not nibble count → Uint4Array.wrap with 64 gives 128-element array

Non-obvious: even index → low nibble (bits 3:0); odd index → high nibble (bits 7:4). Order is little-nibble-first within each byte.

When reading Buffer[i] expect u8 in range 0–15 (raw volume, not scaled). Scaling happens in MixChannels at render time.

Test Setup Pattern

// from assembly/tests/pulseChannelTests.ts and audioRegisterTests.ts
function initAudio(): void {
    setTestRom([0x00]);               // resets emulator + channel phases via AudioRender.Init()
    AudioRender.Prepare(0);           // resets event queue only
    MemoryMap.GBstore<u8>(0xFF26, 0x80); flushAudioEvents();
}
// Register writes require flushAudioEvents() to reach channels.
// Direct render: AudioRender.channel1.Render(0, 128)
// Check vol:     AudioRender.channel1.GetCurrentEnvelopeVolume()  (public)
// Check active:  AudioRender.channel1.Enabled  (getter)
// Buffer read:   AudioRender.channel1.Buffer[i]  → u8, 0 or volume (Uint4Array)

For existing test examples: assembly/tests/pulseChannelTests.ts, assembly/tests/audioRegisterTests.ts. Pan Docs: use gameboy-docs skill → Audio.md, Audio_details.md, Audio_Registers.md.

$ARGUMENTS