FEAT(windows client): Add support for the Universal Mute button

[citelao]

Today, Mumble does not support the Universal Mute button in Windows, which additionally means that physical mute buttons in newer laptops cannot mute Mumble. This change adds support for these button (and the Windows-wide shortcut Win+Alt+K) by using the Windows VOIP API.

What changed?

• Add a UniversalMuter on Windows builds that wraps the WinRT Windows.ApplicationModel.Calls.VoipCallCordinator' APIs.
• Use this UniversalMuter to read/write mute state during calls.
• Documented a bit more on how to build on Windows, especially using the pre-made vcpkg triplets.

A bit of background: I've wanted to implement this for a while now. I wrote the most popular StackOverflow question about the Universal Mute API while I worked at Microsoft (I had no affiliation with writing the API), wrote a simple C# demo app for it, and I wrote a Rust plugin for Mumble that does the same thing.

I used Claude Code to help generate this work.

Checks

Deployed locally on Windows 11.

• When first launched, no call is in progress.
• Upon joining a channel, the Universal Mute button lights up.
• Upon joining a channel, the Universal Mute button reflects my initial mute state.
• When the Universal Mute button is pressed, toggles mute/unmute in Mumble.
• When Mumble is muted/unmuted, the Universal Mute button reflects the new state.
• When Mumble is deafened/undeafened, the Universal Mute button reflects the new state.
• Upon leaving a call, the Universal Mute button turns off.
• State stays consistent even after hammering the button.
• My commits follow the commit guidelines

Happy to address any feedback!

[coderabbitai]

Walkthrough

This pull request introduces Windows-specific WinRT universal mute functionality and updates build documentation. A new win-universal-mute CMake option enables the UniversalMuter class, which integrates with WinRT VoIP call coordination APIs to synchronize mute state. The implementation registers event handlers for mute state changes and manages call lifecycle events. Additionally, documentation files are updated with expanded build instructions for Windows, including examples using vcpkg pre-built environments, PowerShell guidance, and a new common build errors reference section.

Suggested reviewers

• Krzmbrzl
• davidebeatrici

🚥 Pre-merge checks | ✅ 2

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and specifically summarizes the main feature being added: Windows Universal Mute button support.
Description check	✅ Passed	The PR description provides comprehensive information about the changes, including motivation, implementation details, testing verification, and compliance with commit guidelines.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ 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 and usage tips.}

Tip

CodeRabbit can use Trivy to scan for security misconfigurations and secrets in Infrastructure as Code files.

Add a .trivyignore file to your project to customize which findings Trivy reports.

[coderabbitai]

Actionable comments posted: 5

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/mumble/MainWindow.cpp (1)

2748-2780: ⚠️ Potential issue | 🟠 Major

Universal mute only stays in sync for one mute code path.

Lines 2774-2779 mirror the state only when the change flows through MainWindow::on_qaAudioMute_triggered(). MainWindow::on_qaAudioDeaf_triggered() still sets Global::get().s.bMute directly at Lines 2811-2815, and src/mumble/AudioWizard.cpp does the same at Lines 174-176, 319-337, and 433-435. After self-deafen or audio-wizard transitions, the Windows coordinator keeps the old mute state. Please move the coordinator update into a shared helper and call it from every bMute write.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/mumble/MainWindow.cpp` around lines 2748 - 2780, The universal mute
coordinator update is only applied in MainWindow::on_qaAudioMute_triggered;
extract the m_universalMuter setMuted()/setUnmuted() logic behind a new shared
helper (e.g., updateUniversalMuteState(bool muted) as a static/global helper or
a member on a suitable central class) and call it whenever Global::get().s.bMute
is written. Update MainWindow::on_qaAudioMute_triggered to call the helper
instead of directly touching m_universalMuter, and modify
MainWindow::on_qaAudioDeaf_triggered and the bMute assignments in
AudioWizard.cpp (the blocks around the lines noted) to invoke this helper after
changing Global::get().s.bMute so the Windows coordinator (m_universalMuter
under USE_WIN_UNIVERSAL_MUTE) stays in sync across all code paths.

🧹 Nitpick comments (1)

docs/dev/build-instructions/build_windows.md (1)

9-9: Consider using a more flexible Python version.

The command hardcodes Python 3.13, which may not be available on all systems or may become outdated. Consider using Python.Python.3 to install the latest Python 3.x version, or provide guidance for users to choose an appropriate version.

📝 Suggested alternative

-You'll also need Python (`winget install --id=Python.Python.3.13 -e`).
+You'll also need Python (`winget install --id=Python.Python.3 -e` for the latest 3.x version).

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/dev/build-instructions/build_windows.md` at line 9, Replace the
hardcoded Python installer reference "winget install --id=Python.Python.3.13 -e"
with a more flexible instruction: either recommend using the generic package id
"Python.Python.3" to install the latest Python 3.x, or instruct users to select
an appropriate installed Python 3.x version (e.g., via winget search or manual
download). Update the line containing the exact command string in
build_windows.md to present the alternative command and a brief note advising
users to pick a suitable Python 3.x if 3.13 is unavailable.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/dev/build-instructions/build_static.md`:
- Around line 69-71: The fenced code block containing the cmake invocation
("cmake -G Ninja \"-DVCPKG_TARGET_TRIPLET=...\" \"-DCMAKE_BUILD_TYPE=Release\"
..") is labeled with "bash" but uses Windows backslash paths; change the code
block language identifier from "bash" to a Windows-appropriate one such as
"powershell" (or "cmd") so the snippet for the cmake command displays correct
syntax highlighting.

In `@docs/dev/build-instructions/build_windows.md`:
- Line 21: The vcvars64.bat path in the cmd invocation uses an invalid Visual
Studio version "18"; update the path string referencing "vcvars64.bat" to point
to a valid VS install (e.g., use "17" or "2022") or replace the hardcoded path
with the documented vswhere-based lookup used earlier in the file so the command
dynamically locates the correct "VC\Auxiliary\Build\vcvars64.bat" before calling
it.

In `@src/mumble/CMakeLists.txt`:
- Around line 662-671: The MSVC-specific link and delay-load settings for WinRT
are being applied unconditionally; wrap the calls that add runtimeobject.lib and
the LINK_FLAGS delay-load (the target_link_libraries(mumble_client_object_lib
PUBLIC runtimeobject.lib) and set_property(... "/DELAYLOAD:runtimeobject.dll")
lines) in an if(MSVC) ... endif block so they only apply when using MSVC,
leaving the rest of the win-universal-mute handling (target_sources and
target_compile_definitions for mumble_client_object_lib /
USE_WIN_UNIVERSAL_MUTE) unchanged.

In `@src/mumble/UniversalMute.cpp`:
- Around line 76-91: The callback registered in handler currently calls
impl->coordinator->NotifyMuted()/NotifyUnmuted() immediately after queuing the
state-change validation, which can notify Windows before the queued
MainWindow::on_qaAudioMute_triggered() slot validates or rejects the change;
remove these immediate Notify* calls from the lambda and instead ensure
NotifyMuted()/NotifyUnmuted() is invoked only after the queued validation and
state update succeed (for example, from the success path inside
MainWindow::on_qaAudioMute_triggered() or after setMuted()/setUnmuted()
complete), so that weakImpl, handler, MainWindow::on_qaAudioMute_triggered, and
setMuted/setUnmuted are the loci of the state-change and notification
sequencing.
- Around line 38-56: The call to RoGetActivationFactory in
tryCreateCallCoordinator requires the Windows Runtime to be initialized on the
calling thread; initialize WinRT before that call (either ensure the main thread
calls RoInitializeEx/Windows::Foundation::Initialize at startup or call
RoInitializeEx(RO_INIT_MULTITHREADED) at the start of tryCreateCallCoordinator),
check the HRESULT and proceed only on success, and if you initialize inside
tryCreateCallCoordinator ensure you call RoUninitialize on error or when done;
update the function to perform this initialization check/cleanup before invoking
RoGetActivationFactory.

---

Outside diff comments:
In `@src/mumble/MainWindow.cpp`:
- Around line 2748-2780: The universal mute coordinator update is only applied
in MainWindow::on_qaAudioMute_triggered; extract the m_universalMuter
setMuted()/setUnmuted() logic behind a new shared helper (e.g.,
updateUniversalMuteState(bool muted) as a static/global helper or a member on a
suitable central class) and call it whenever Global::get().s.bMute is written.
Update MainWindow::on_qaAudioMute_triggered to call the helper instead of
directly touching m_universalMuter, and modify
MainWindow::on_qaAudioDeaf_triggered and the bMute assignments in
AudioWizard.cpp (the blocks around the lines noted) to invoke this helper after
changing Global::get().s.bMute so the Windows coordinator (m_universalMuter
under USE_WIN_UNIVERSAL_MUTE) stays in sync across all code paths.

---

Nitpick comments:
In `@docs/dev/build-instructions/build_windows.md`:
- Line 9: Replace the hardcoded Python installer reference "winget install
--id=Python.Python.3.13 -e" with a more flexible instruction: either recommend
using the generic package id "Python.Python.3" to install the latest Python 3.x,
or instruct users to select an appropriate installed Python 3.x version (e.g.,
via winget search or manual download). Update the line containing the exact
command string in build_windows.md to present the alternative command and a
brief note advising users to pick a suitable Python 3.x if 3.13 is unavailable.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 33f64653-2433-42c1-87ec-51ba512c3e44

📥 Commits

Reviewing files that changed from the base of the PR and between f2a0d8e and 8ea7308.

📒 Files selected for processing (10)

• docs/dev/build-instructions/build_static.md
• docs/dev/build-instructions/build_windows.md
• docs/dev/build-instructions/common_build_errors.md
• docs/dev/build-instructions/faq.md
• src/mumble/CMakeLists.txt
• src/mumble/MainWindow.cpp
• src/mumble/MainWindow.h
• src/mumble/Messages.cpp
• src/mumble/UniversalMute.cpp
• src/mumble/UniversalMute.h

[maxer137]

Is this divergence from build_static.md intentional? This seems to introduce a separate set of Windows-specific instructions that could drift over time (e.g. different or missing CMake flags like the bundled-cli11/spdlog ones). It’s also no longer system-agnostic due to hardcoded paths that most users won’t have.
Additionally, stating we only support static builds at the top and then having a separate guide here feels a bit inconsistent. Should we condense this somehow?

[citelao]

Any divergence is unintentional, but I honestly found the full build_static.md guidance confusing. I hoped to summarize the most important information in this build_windows.md file, similar to the Mac & Linux guidance. It really took me a long time to understand what actually amounts to ~3 commands.

I'm happy to try a different approach, or at least reduce/clarify the user-specific directories and minimize any divergence.

[Krzmbrzl]

I would indeed prefer to not duplicate information. Linux and MacOS have dedicated instructions because they support non-static builds. Windows doesn't.

However, I am definitely open to changing/improving the instructions for static builds. Do you recall what it was that you struggled with specifically?

[citelao]

I took another pass at the revision; hopefully this should make static building & Windows building easier for new folks to understand. Most importantly:

• Included an example at the beginning of the guidance, to show it's not too tough.
• Emphasized pre-built vcpkg.
• Extracted Windows-specific stuff to Visual Studio page, since it makes more sense there.
• Clarified/emphasized the CMake generator commands by adding newlines.
• Added a "build" step, just to make end-to-end clear.

Thoughts?

[citelao]

I'm also happy to move these docs changes into a separate PR.

[citelao]

@Krzmbrzl @maxer137 let me know if there's anything else I can do!

[maxer137]

I think it could be helpful to split this PR into separate commits or even separate PRs, as you suggested, for clarity.

1. Mute-button support
2. Language updates (the automated one)
3. Windows build documentation

I don’t use Windows myself, so I’m unable to test the universal mute button 😅, but I didn't see anything that looked extremely out of the ordinary. The only thing that made me look up was "muting your mic in Mumble also mutes the mic globally in Windows," but it seems that is intended from watching the global mute button in action.

For the docs, I appreciate the expansion on setup_visual_studio. I remember trying to compile it on Windows in the past and running into some struggles with the compilers, so this should help future contributors a lot. Splitting it from the Windows caveats is a worthy change.

[maxer137]

Since the steps are explained in more detail later in the document, this summary feels a bit redundant.
Perhaps it could be shortened to a one-line overview or removed entirely to avoid repeating information, so readers aren’t presented with the same instructions twice.

[maxer137]

Just to clarify. Are these flags required for all OSes or only for Windows?

[citelao]

I believe they are required for all OSes? They are present in set_environment_variables.sh. Honestly, I think they may be required for all builds now, but I haven't built on other OSes.

[maxer137]

This change, to me, reads a bit like a promotional note. I’m not sure if that was the intention, but my initial impression when reading it was that it stood out from the otherwise neutral tone of the documentation. 😬

[citelao]

Given that I no longer work at Microsoft, I hope it's not a promotional note :).

I added the for free bit because historically Visual Studio has required payment (the tools are still not libre use). I'll simply remove that phrase though.

[maxer137]

I think this section could be streamlined. Currently it repeats most of the full build instructions (and uses ninja in the example again). The main difference for pre-built environments seems to be fetching the environments and the CMake flags; perhaps this section could focus only on those points rather than duplicating all the steps. This would reduce redundancy and make it easier for readers to see what’s different, especially since additional dependencies are discussed later.

[citelao]

I'll take another pass!

[citelao]

@maxer137, I'll separate the PRs. Good suggestion.

[citelao]

@maxer137, pushed a new, scoped PR. I'll handle adding translatable strings & doc updates in separate PRs.

I don’t use Windows myself, so I’m unable to test the universal mute button 😅, but I didn't see anything that looked extremely out of the ordinary. The only thing that made me look up was "muting your mic in Mumble also mutes the mic globally in Windows," but it seems that is intended from watching the global mute button in action.

I appreciate it! I can send you a video, but indeed the universal mute button & Mumble's button stay in sync. The Universal Mute button doesn't actually change any global system state; it simply reflects the state of a "VOIP call" on the system, initiated & managed by an application. Notice that OBS is still using the microphone, even though Mumble is muted:

Apps like Teams (and now Mumble) call this WinRT API to signal that they have started a VOIP call, then hook up MuteStateChanged handlers. This causes the Universal Mute button to appear (otherwise you get a generic "mic in use" icon).

Clicking that button doesn't actually do anything directly: it sends a MuteStateChanged event to the app, but the app can do whatever it wants. To be explicit: that Universal Mute button only sends a signal to the app, it does not actually mute any microphones. Likewise, when the app mutes itself (or decides it's handled the MuteStateChanged event), it signals the WinRT VOIP call with NotifyMuted or NotifyUnmuted. This changes the state of the Universal Mute button, but, again, does nothing else.

In fact, I wrote a demo that doesn't even use the microphone! See also https://stackoverflow.com/questions/74683703/how-do-i-support-call-mute-universal-mute-in-my-app-for-windows-11-22h2. (In case you're wondering, if there are multiple VOIP Calls at once, e.g. Teams + Mumble, the Universal Mute button behaves strangely & chooses the most recent one).

For the docs, I appreciate the expansion on setup_visual_studio. I remember trying to compile it on Windows in the past and running into some struggles with the compilers, so this should help future contributors a lot. Splitting it from the Windows caveats is a worthy change.

I hope so! It really was super simple to get development working, so I hope I can pay it forward for folks.

[maxer137]

@maxer137, I'll separate the PRs. Good suggestion.

😅 I think the translation PR and the mute PR do need to be one and the same PR. The translation commit is just an automated script anyway. Just a split between docs and the mute feature should be sufficient.

Other than that, I think this looks good to me. Then again, I can't compile and test it because I don't have Windows.

[citelao]

@maxer137 done, I hope 😅!

[citelao]

@maxer137, anything holding this back?

[maxer137]

@maxer137, anything holding this back?

I’m not a maintainer 😅. I just reviewed your PR because I saw some things that seemed odd to me.

A maintainer of the mumble project has to review your work now and accept the changes.

[citelao]

@maxer137 oh, well in that case, thanks for volunteering your time to review :)