(fix): automatic music muting on macOS

[DarthMDev]

Adds the missing macOS audio monitor so game music mutes while other apps have active audio output. Supports macOS 14.2+ and ignores the game’s own audio.

Summary by CodeRabbit

• New Features

  • Added macOS support for detecting external audio playback and automatically attenuating game music.
  • Added platform-specific status messages and guidance in the audio settings menu.
  • Detection requires macOS 14.2 or later and excludes the game’s own audio output.

• Documentation

  • Expanded music ducking documentation with Windows, Linux, and macOS behavior, including silent audio streams that may keep music muted.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 7b4f188f-2d38-46d4-8d37-95cea7496c23

📥 Commits

Reviewing files that changed from the base of the PR and between a135beb and fee4e35.

📒 Files selected for processing (9)

• README.md
• runtime/CMakeLists.txt
• runtime/cmake/PublicProducts.cmake
• runtime/include/external_audio_macos.h
• runtime/include/music_attenuation.h
• runtime/src/external_audio_macos.cpp
• runtime/src/music_attenuation.cpp
• runtime/src/settings_overlay.cpp
• runtime/tests/macos_external_audio_tests.cpp

Included review availability: Your plan provides up to 4 included reviews per hour; 3 remain after this review.

---

📝 Walkthrough

Walkthrough

The runtime adds macOS Core Audio detection for external playback. It polls other audio processes, excludes the game process, updates music attenuation state, adds platform-specific UI text, links CoreAudio, and adds focused macOS tests.

Changes

macOS external audio detection

Layer / File(s)	Summary
Core Audio query implementation runtime/include/external_audio_macos.h, runtime/src/external_audio_macos.cpp	Defines MacOSAudioStatus and QueryMacOSExternalAudio(). The query checks runtime support, handles process-list races and failures, excludes the game process, and detects external output activity.
Monitoring and attenuation integration runtime/src/music_attenuation.cpp, runtime/include/music_attenuation.h, runtime/src/settings_overlay.cpp, README.md	Adds a macOS polling monitor that updates shared availability and playback state. The settings overlay and documentation describe macOS 14.2 or later behavior.
Framework wiring and validation runtime/cmake/PublicProducts.cmake, runtime/CMakeLists.txt, runtime/tests/macos_external_audio_tests.cpp	Links CoreAudio into macOS targets, registers a dedicated test executable, and tests unsupported systems, process changes, size races, failures, and recovery.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Merge Risk: ⚪ Minimal · up to fee4e

This adds macOS external-audio detection to mute game music while other apps produce output, including safe fallback behavior on unsupported or failing systems. No actionable current-head merge risk remains.

Sequence Diagram(s)

sequenceDiagram
  participant StartMonitor
  participant MonitorMacOSAudio
  participant QueryMacOSExternalAudio
  participant CoreAudio
  participant MusicAttenuationState
  StartMonitor->>MonitorMacOSAudio: start detached monitor
  loop every 250 milliseconds
    MonitorMacOSAudio->>QueryMacOSExternalAudio: query external output
    QueryMacOSExternalAudio->>CoreAudio: enumerate and inspect processes
    CoreAudio-->>QueryMacOSExternalAudio: availability and playback data
    QueryMacOSExternalAudio-->>MonitorMacOSAudio: MacOSAudioStatus
    MonitorMacOSAudio->>MusicAttenuationState: publish playing and available flags
  end

Loading

Suggested reviewers: patchzyy

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 7.14% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 14 functions across 6 files. (3 skipped: 3…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding automatic music muting on macOS.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 7.14% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 14 functions across 6 files. (3 skipped: 3 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[patchzyy]

Can anyone else with a mac machine confirm this PR is functional?

[DarthMDev]

I mean i can confirm it works on my machine.

[patchzyy]

This is in #228