[CharlieBaker2002]

Fixes #241. Should also resolve the "call audio is very quiet while FineTune runs" reports in #113, #156, #262, #360, #404 and #426 — see How it relates to other PRs below.

Problem

While a call app drives Apple's voice-processing IO (FaceTime's avconferenced, WhatsApp, …), coreaudiod ducks every other HAL client on the output device to a combined volume scalar of 0.178 (-15 dB). FineTune renders every tapped app through its own HAL client, so the whole mixer drops to ~18% for the length of the call. When FineTune taps the call app too, the call itself goes through that same client and gets ducked as well — that is the faint call audio in the issues above.

This is a long-standing macOS complaint with no setting to turn it off — e.g. the r/mac thread Possible to turn off audio ducking for FaceTime? (now archived) asks exactly that, and #241 asks FineTune for a toggle.

From coreaudiod's log on macOS 26.6.2 during a FaceTime call (FineTune 1.9.0 is pid 40318, avconferenced is pid 787):

HALS_Device::_GetCombinedVolumeScalar: BuiltInSpeakerDevice client 2458 (pid 40318) is not present, and is ducked with a combined volume scalar of 0.177828
HALS_Device::_GetCombinedVolumeScalar: BuiltInSpeakerDevice client 212 (pid 787) is present, and is ducked with a combined volume scalar of 1.000000

(@vfmatzkin's analysis in #113 found the same 0.177828 scalar.)

Fix

coreaudiod never ducks a client that holds a duck request of its own. Its log calls those clients "duckers" and gives them a scalar of 1.0 whatever anyone else requests. So FineTune now holds a request of 0.999 (-0.01 dB, inaudible) on every output device via AudioDeviceDuck:

AudioDeviceDuck(deviceID, 0.999, nil, 0)   // hold — FineTune becomes a "ducker"
AudioDeviceDuck(deviceID, 1.0,   nil, 0)   // release — exactly 1.0 withdraws the request

Everything FineTune replays stays at full volume; the call's ducking of audio that bypasses FineTune (ignored apps, system sounds) is untouched, and the call app's own audio is unaffected either way.

Three properties of the request make the implementation small. All three were checked against _UpdateClientVolumeScalarDucking in coreaudiod's log during a live FaceTime call, using a probe that renders through a private aggregate device exactly the way ProcessTapController does:

Scenario	Result
Request made on the real output device, IO running through a private aggregate (tap + output sub-device)	ducker, scalar 1.000
Request made before any IO proc or aggregate exists	still a ducker once IO starts
Aggregate torn down and recreated after the request	still a ducker

So the request is bound to the process ↔ device pair, not to an IO proc, and one request per output device from AudioEngine is enough — nothing in the real-time tap code changes.

What's in the diff

File	Change
Audio/Engine/CallDuckingGuard.swift	New. Resolves AudioDeviceDuck with dlsym, holds/releases requests per device, keeps a held set so repeated calls are no-ops. The duck function is injectable for tests.
Audio/Engine/AudioEngine.swift	Owns the guard. Holds on every output device at start, on device (re)connect, and as a cheap no-op safety net in the existing 2 s health-monitor loop (covers coreaudiod restarts). Releases on stop() and when the setting is turned off.
Settings/SettingsManager.swift	AppSettings.keepVolumeDuringCalls, default on; missing key decodes as on.
Views/Settings/Tabs/AudioTab.swift	Settings → Audio → Keep Volume During Calls toggle.
FineTuneTests/CallDuckingGuardTests.swift, AppSettingsKeepVolumeDuringCallsTests.swift	13 new test cases (bookkeeping, failure retry, release-on-disable, decoding default).
README.md, README.zh-CN.md, guide/troubleshooting.md	Feature bullet and a troubleshooting entry.

About AudioDeviceDuck

It is exported by CoreAudio but not declared in the public headers; WebKit and Chromium call it with the same signature (AudioDeviceID, Float32 level, const AudioTimeStamp*, Float32 ramp), and Mozilla's bindings note it has existed since macOS 10.13. It is resolved at runtime, so if a future macOS drops it the guard is a silent no-op and calls duck FineTune exactly as they do today. FineTune already relies on two SPIs of the same kind (TCCAccessRequest, responsibility_get_pid_responsible_for_pid). The technique is the one ShutTheDuckOff (GPL-3.0, same as FineTune) is built on; nothing was copied from it.

How it relates to other PRs

• feat(audio): Call Ducking Compensation — counter-boost other apps during VoIP calls #311 compensates ducking with a +12 dB counter-boost. This PR removes the ducking instead, so there is no boost, no limiter engagement and no residual level error. (feat(audio): Call Ducking Compensation — counter-boost other apps during VoIP calls #311 also states the ducking "cannot be disabled via any public API"; this PR shows a non-patching way that works with SIP on.)
• fix: exclude FaceTime/avconferenced from audio tapping to prevent volume ducking #157 (closed) excluded avconferenced by name. This PR deliberately has no app or daemon list: the exemption applies to whatever FineTune renders, so the "quiet call" symptom goes away for every present and future call app. Tapping a call app can still disturb its echo cancellation; the existing ignore feature covers that, and this PR composes with fix(audio): leave apps untapped while they capture input (fixes quiet call audio + echo) #413 (dynamic untap while an app captures input) if that lands.

Testing

• xcodebuild test -skip-testing:FineTuneUITests (the CI invocation): 978 passed, 0 failed on macOS 26.6.2 / Xcode 27.0 / Apple Silicon.
• Live FaceTime call with Spotify and Chrome playing, build installed in place of 1.9.0. coreaudiod's log for the new process (pid 47926) right after launch:

HALS_Device::_DuckClientVolumeScalar: client 2800 (pid 47926) ducking device <private> (107) to 0.999000 over (0.000000, 1)
HALS_Device::_UpdateClientVolumeScalarDucking: client 2800 (pid 47926) is a ducker so its ducked volume scalar on device <private> (107) is 1.000000
HALS_Device::_GetCombinedVolumeScalar: BuiltInSpeakerDevice client 2800 (pid 47926) is present, and is ducked with a combined volume scalar of 1.000000

Music stayed at full volume for the rest of the call and avconferenced kept its own 1.000 scalar. Relaunching during the same call with keepVolumeDuringCalls set to false in settings.json: no request is made and FineTune's client is ducked to 0.177828, i.e. exactly 1.9.0's behaviour; relaunching with it back on: ducker at 1.000 on all three output devices. The drop and recovery were audible. The runtime release path (setEnabled(false) → AudioDeviceDuck(…, 1.0)) is covered by the unit tests, and the probe confirmed that a 1.0 request turns the client back into a duckee (_DuckClientVolumeScalar: … unducking device … is a duckee … 0.177828).

• Nothing in the audio callback changed, so the RT-safety surface is untouched.

🤖 Generated with Claude Code