Skip to content

Mac audio: a 5 ms device buffer, as on iOS (underruns heard as clicks) - #262

Closed
parsifal295 wants to merge 1 commit into
seedds:mainfrom
parsifal295:mac-audio-buffer
Closed

parsifal295 wants to merge 1 commit into
seedds:mainfrom
parsifal295:mac-audio-buffer

Conversation

@parsifal295

@parsifal295 parsifal295 commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

On the Mac, the output unit now asks the device for about 5 ms per callback. This matches what front_ios.m already asks of the iOS audio session (setPreferredIOBufferDuration:0.005).

The problem. By default the Mac's output asks for 512 device frames per callback. That is 10.7 ms at 48 kHz; when the device runs at 44.1 kHz it becomes 557 frames of the 48 kHz stream. The renderer does not always have that much queued, so the callback runs dry and the rest is padded with zeros. It sounds like clicks, or "clipping". Unicorn Overlord (Asian release 1.05) on a MacBook Pro's speakers, from the log's audio #0 device callbacks lines:

  • at 48 kHz: 250–290 underruns in every 2000 callbacks (0.1–0.2 s of zeros);
  • at 44.1 kHz: about 1,000 in every 2000 (0.7–0.9 s).

Whether a game underruns depends on how much it keeps queued. 13 Sentinels queues about as many blocks (2.8 at callback, Unicorn Overlord 3.0), but larger ones, and had no underrun at 512 frames. So the symptom is per game, while the cause is the host's: a device period longer than what some games keep ahead. A shorter period costs the games that were fine nothing; 13 Sentinels stays at 0.

It is the iOS problem in docs/reference/audio.md ("RemoteIO's default I/O buffer duration"), at a smaller default.

The fix. au_buffer in hle_audio.c sets kAudioDevicePropertyBufferFrameSize to the device's rate / 200 (240 frames at 48 kHz, 220 at 44.1 kHz):

  • when the unit is created;
  • again from a kAudioOutputUnitProperty_CurrentDevice listener, since the default output unit follows the system's default device and the new device has its own buffer.

The buffer is the process's own, so other apps keep theirs. The DM_DBG_AU_FRAMES=N diagnostic still asks for N frames, and the line it logged is now logged for every unit (audio device buffer: 240 frames at 48000 Hz). iOS is unchanged.

Docs: docs/reference/audio.md "The Mac's default I/O buffer" (symptom index regenerated) and Unicorn Overlord's note (Found on this game).

Related PRs

Checked

  • Unicorn Overlord's Mac app, MacBook Pro speakers at 48 kHz, with DM_AUDIO_MUTE=1 (the real output path, silenced), 10,000 callbacks per run:
    • the default 512 frames, two runs: 249–289 underruns per 2000;
    • DM_DBG_AU_FRAMES=240: 0;
    • this change with no switch: 0.
  • 13 Sentinels' Mac app, the same setup: DM_DBG_AU_FRAMES=512 and this change, 0 underruns each.
  • The host builds; the host unit tests pass (GAME=010069401ADB8000); the docs check passes.
  • Not checked: a device at 44.1 kHz after the change, and switching the output device while playing (the listener).

…ePropertyBufferFrameSize: 240 frames at 48 kHz, 220 at 44.1 kHz), as front_ios.m asks of the iOS audio session, set when the unit is created and again when the default output moves to another device (au_buffer in hle_audio.c). With the Mac's default 512-frame buffer (10.7 ms at 48 kHz; 557 frames of the 48 kHz stream when the device runs at 44.1 kHz) the renderer does not always have that much queued: Unicorn Overlord (Asian release 1.05) on a MacBook Pro's speakers underran on 250-290 of every 2000 callbacks at 48 kHz (0.1-0.2 s of zeros, heard as clicks) and on about 1,000 at 44.1 kHz; at 240 frames, 0 in 10,000. It depends on how much the game queues: 13 Sentinels (2.8 blocks queued at callback, Unicorn Overlord 3.0, its blocks larger) had no underrun at 512 frames and has none at 240. The buffer is the process's own; DM_DBG_AU_FRAMES=N still asks N frames. docs/reference/audio.md "The Mac's default I/O buffer" (symptom index regenerated) and Unicorn Overlord's note (Found on this game).

## Checked
- Unicorn Overlord's Mac app, MacBook Pro speakers at 48 kHz, DM_AUDIO_MUTE=1 (the real output path, silenced), 10,000 callbacks each: the default 512 frames, two runs, 249-289 underruns per 2000; DM_DBG_AU_FRAMES=240 and then this change with no switch, 0.
- 13 Sentinels' Mac app, the same setup: DM_DBG_AU_FRAMES=512 and this change, 0 underruns each.
- The host builds; the host unit tests pass (GAME=010069401ADB8000); the docs check passes.
- Not checked: a device at 44.1 kHz after the change, and switching the output device while playing (the listener that sets the buffer again).
seedds added a commit that referenced this pull request Oct 26, 2026
Apply PR #262's device-buffer fix for clicks caused by audio underruns.
Reconfigure on both output-device and hardware sample-rate changes, respect
the device's frame range, and read back the actual buffer size. Avoid
rewriting unchanged sizes when buffer changes notify the format listener.
Remove listeners before teardown, including failed initialization, so they
cannot configure a device that the AudioUnit has already released.

Add hardware-independent regression coverage for switching, rate changes,
scope filtering, limits, synchronous notifications, diagnostic overrides,
absent devices, and listener cleanup. Record the original gameplay evidence
and the additional silent Core Audio validation in the audio reference.

Validation: full host tests, Mac host build, docs checks, and the iOS source
compile check (178 files) passed. Silent USB/speaker switching and speaker
rates of 44.1/96/48 kHz verified 221/480/240 frames. HDMI switching and
gameplay listening after these listener changes remain unvalidated.

Co-authored-by: parsifal295 <[email protected]>
@seedds

seedds commented Oct 26, 2026

Copy link
Copy Markdown
Owner

Thanks @parsifal295 for the measured underrun evidence and the 5 ms buffer fix. Integrated this into main in 40b643b, with you credited as coauthor.

The update also addresses two behaviors reproduced during review:

  • Changing the same output device's sample rate did not notify CurrentDevice, leaving its frame count unchanged. The host now listens for output-format changes too. Silent playback on the Mac mini's speakers verified 221 frames at 44.1 kHz, 480 at 96 kHz, and 240 at 48 kHz.
  • Disposing an AudioUnit notified the still-registered device listener after its device had gone, logging status 560947818 (!obj). Both listeners are now removed before teardown, including failed initialization.

Buffer requests respect the device's supported range, unchanged sizes are not rewritten when a buffer change itself triggers a format notification, and the log reads back the actual size. Added regression coverage for these paths, the diagnostic override, absent devices, and listener cleanup.

Validation passed: full host test suite, Mac host build, documentation checks, and compilation of all 178 iOS source files. A silent Core Audio probe also verified default-output switching between USB at 48 kHz and the speakers at 44.1 kHz with callbacks continuing. The original system default and device sample rates were restored.

HDMI switching remains unvalidated because the listed HDMI output was not retained as the system default. Gameplay listening after the listener changes has not been repeated; the gameplay underrun measurements remain the evidence reported in this PR. Neither additional listener issue was demonstrated to cause the original audible clicks.

Closing this PR because its change and these follow-up fixes are integrated directly on main.

@seedds seedds closed this Oct 26, 2026
Know-It-All-Brother pushed a commit to Know-It-All-Brother/nxnative that referenced this pull request Nov 9, 2026
Apply PR seedds#262's device-buffer fix for clicks caused by audio underruns.
Reconfigure on both output-device and hardware sample-rate changes, respect
the device's frame range, and read back the actual buffer size. Avoid
rewriting unchanged sizes when buffer changes notify the format listener.
Remove listeners before teardown, including failed initialization, so they
cannot configure a device that the AudioUnit has already released.

Add hardware-independent regression coverage for switching, rate changes,
scope filtering, limits, synchronous notifications, diagnostic overrides,
absent devices, and listener cleanup. Record the original gameplay evidence
and the additional silent Core Audio validation in the audio reference.

Validation: full host tests, Mac host build, docs checks, and the iOS source
compile check (178 files) passed. Silent USB/speaker switching and speaker
rates of 44.1/96/48 kHz verified 221/480/240 frames. HDMI switching and
gameplay listening after these listener changes remain unvalidated.

Co-authored-by: parsifal295 <[email protected]>
ltrdpper pushed a commit to ltrdpper/BananaNative that referenced this pull request Nov 16, 2026
…ion: program 1 from dump folders, an edition switch on the game's card, one save' (seedds#262) from Wick3dPhant0m/BananaNative:wonder-support into android

Reviewed-on: https://git.eden-emu.dev/moceure/BananaNative/pulls/262
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants