MixKey

MixKey 1.1.0 is a native Windows per-application audio controller. It changes the volume or mute state of Spotify, Discord, browsers, games, and other user applications through global keyboard shortcuts without bringing MixKey to the foreground. Focus Mode can apply a saved mute/maximize profile and later restore the exact per-session volume and mute state it captured.

MixKey targets Windows 11 x64 and is built with C++20, Win32, Windows Core Audio, Direct2D, and DirectWrite. It has no web runtime, service, account, telemetry, advertisements, or network dependency.

Hardware-, application-, and game-dependent behavior still requires the manual validation in docs/TESTING.md. An unchecked manual case is not a verified compatibility claim.

Features

• Discovers audio sessions on the default multimedia render endpoint through Windows session and endpoint notifications. There is no high-frequency polling and no visible manual refresh control.
• Groups packaged sessions by AUMID and package family, then desktop sessions by normalized executable path or a persistence-safe fallback. Volume and mute writes apply to every live session in the selected group.
• Filters Windows System Sounds, protected/system components, MixKey itself, and transient or unknown sessions before they reach the mixer or Focus Mode.
• Keeps configured applications visible while they are not running and reconnects them when an eligible audio session returns.
• Supports 1-25% per-application volume steps and independent decrease, increase, and mute/unmute shortcuts.
• Uses RegisterHotKey with no-repeat semantics. Optional Single-Key Game Mode provides a non-suppressing WH_KEYBOARD_LL fallback only for modifierless keys Windows cannot register normally. Every shortcut runs once per physical press and becomes eligible again after key-up.
• Rejects duplicate MixKey bindings, including conflicts with the Focus Mode shortcut, and rolls back when Windows refuses a registration.
• Captures exact Focus Mode state per live session, mutes checked applications, maximizes unchecked configured applications, and restores captured volume and mute properties when Focus Mode ends.
• Shows one non-activating, click-through, topmost overlay. Position, monitor, fade timing, size, opacity, content, style, and accent are configurable; repeated actions update that one card and restart its timer.
• Provides a responsive, clipped application-card viewport with a complete scrollbar. Cards reorganize into additional rows at compact widths while the header, Focus panel, Applications heading, and status bar remain unobscured.
• Persists Remove from mixer as a stable hidden-application identity. The Settings panel lists hidden applications with Restore and Restore all.
• Provides a notification-area icon, optional close-to-background behavior, opt-in current-user startup, and a single-instance guard.
• Stores validated JSON settings locally with delayed saves, write-through replacement, and recovery from a last-valid backup.

Requirements

To run

• Windows 11 x64 is the primary target.
• A normal, non-elevated interactive desktop session.
• An eligible application producing audio on the Windows default multimedia output device.

The executable uses Windows system APIs and the statically linked MSVC runtime; there is no separate application runtime or package manager requirement.

To build

• Windows 11 or Windows 10 build host.
• Visual Studio 2019 16.11 or Visual Studio 2022 Build Tools with the Desktop development with C++ workload.
• MSVC, a Windows 10/11 SDK, CMake 3.20 or newer, and CTest.

Build from source

Run from a Developer PowerShell for Visual Studio:

cmake -S . -B build -G "Visual Studio 17 2022" -A x64 -DBUILD_TESTING=ON
cmake --build build --config Release --parallel
ctest --test-dir build -C Release --output-on-failure

Visual Studio 2019 16.11 uses the same commands with its generator:

cmake -S . -B build -G "Visual Studio 16 2019" -A x64 -DBUILD_TESTING=ON
cmake --build build --config Release --parallel
ctest --test-dir build -C Release --output-on-failure

The executable is produced at build\Release\MixKey.exe. Warnings in project-owned code are treated as errors. Build directories and user configuration must not be committed.

Use MixKey

1. Start MixKey.exe. A second launch restores the existing instance instead of creating another audio controller.
2. Start playback in an application. Its eligible session appears automatically; no manual refresh is needed.
3. Use the application slider or visible Mute button to verify that the correct session group is selected.
4. Select the decrease, increase, or mute shortcut field and press the desired key or combination. Esc cancels capture; Backspace or Delete clears the binding.
5. Select Step to choose a 1-25% adjustment. Holding a shortcut does not repeat the action; release it before the next press.
6. Configure an inactive application with Add application, or use a card's ... menu to open its file location, reset its settings, or remove it from the mixer. MixKey always displays the detected application name; aliases are not supported.
7. Select Hidden applications beside Add application to restore one removed application or confirm Restore all. An active restored session reappears immediately without a restart or manual refresh.
8. Check Mute in Focus Mode for configured applications that should be muted. Configured unchecked applications are set to 100% and unmuted. The default Focus Mode shortcut is Ctrl+Shift+M.
9. Customize the overlay in Settings > Overlay customization. Preview overlay uses sample data only; Move overlay provides a cancellable, DPI-safe drag mode with Save position/Cancel and Enter/Escape support.
10. Select Run in background to hide the main window while leaving audio shortcuts, Focus Mode, and the tray icon active.

The main header contains Donate, Settings, and Run in background in that order. Donate opens MixKey's PayPal donation page in the default browser. A cached, DPI-specific local PayPal mark is drawn inside the Donate button. Settings contains General and Overlay customization; hidden applications use the lightweight Applications-header panel. Single-Key Game Mode permits one-key shortcuts such as Num 7 or M while another application is focused. The key is still sent normally to that application, so avoid movement keys such as W, A, S, and D.

Focus Mode safety

Focus Mode changes only configured, eligible, non-hidden applications. System Sounds, protected/system sessions, MixKey itself, transient sessions, and unrelated processes are excluded. Removing an application while Focus Mode is active drops its saved rule and pending snapshot without changing the external application.

On normal exit, MixKey attempts to restore an active Focus Mode snapshot before releasing Core Audio. A session unavailable at restoration time cannot be changed at that instant; if it returns while MixKey is still running, MixKey retries the pending restore.

Configuration migration

Configuration schema 6 keeps persisted overlay position, monitor selection, whole-second hold timing, size/scale, background opacity, content, style, and accent settings. Loading older schemas preserves valid application shortcuts (including mute when present), Focus selections, hidden applications, pinned applications, startup/background preferences, and stable identities. Migration also:

• removes saved System Sounds entries;
• ignores legacy alias fields and returns to the detected application name;
• discards legacy key-repeat and developer-metrics preferences;
• uses the existing center-right placement for older configurations; and
• ignores the former overlay-enabled and configurable fade properties;
• defaults a missing visible duration to 3 seconds, rounds legacy durations to whole seconds, and clamps them to 1-10 seconds; and
• defaults a missing monitor choice to Primary while preserving explicit modes.

Hidden identities take precedence over matching saved mixer entries. The store retains the previous valid primary as config.json.bak and writes the migrated configuration through a flushed temporary file plus atomic replacement.

Local data and privacy

MixKey is local and offline. It does not send telemetry, analytics, audio, settings, or keyboard content anywhere, and it does not record audio.

Data is stored under %LocalAppData%\MixKey\:

config.json
config.json.bak
logs\mixkey.log
logs\mixkey.log.1

Release logging is limited to MixKey warnings and errors. Debug builds may add internal diagnostics, but Release builds expose no performance-metrics setting or latency/memory readout. Logs rotate after approximately 256 KiB. Single-Key Game Mode compares only configured virtual keys and does not log typed content.

Known limitations

• Version 1.1 controls the Windows default multimedia output endpoint. The UI does not select a non-default endpoint.
• The overlay is an independent topmost desktop window. Windowed and borderless-fullscreen applications are supported; exclusive-fullscreen games may cover it while audio shortcuts continue to work.
• Windows, another application, or system policy may reserve a global shortcut.
• Registration and matching are virtual-key based. Stored scan-code metadata is not yet a layout-independent physical-key mode.
• Protected, system, transient PID-only, and otherwise unsafe sessions are intentionally absent rather than shown with unreliable controls.
• Grouped sessions display their mean volume when their levels differ. The next MixKey volume write gives every live session in that group one target value.
• Global hotkeys do not cross every Windows integrity boundary. MixKey requests asInvoker and should not normally be run as administrator.
• The owner-drawn UI is keyboard operable with a clean focus indicator, but it does not expose a complete UI Automation control tree. Screen-reader and assistive-technology validation remains incomplete.
• Normal exit restores an active Focus snapshot. A crash, forced termination, power loss, or process kill cannot run that cleanup.
• Repository-produced artifacts are not Authenticode signed.

Troubleshooting

An application is missing

Start playback and confirm the application uses the default multimedia output device shown in MixKey's footer. Restore it from Hidden applications beside Add application if it was removed. Windows System Sounds and protected/system or transient sessions are intentionally filtered.

A saved application says "Not running"

The saved identity has no matching live session on the current endpoint. Start playback and allow the Core Audio creation notification to reconnect it.

A shortcut cannot be saved

The shortcut conflicts with another MixKey action or Windows refused the registration. Clear the conflicting binding, try another combination, or enable Single-Key Game Mode before assigning a modifierless key.

The overlay is missing but audio changes

Test in a normal or borderless-fullscreen window. Exclusive-fullscreen rendering can cover independent desktop overlays. Also confirm overlay display is enabled in the local configuration.

Settings were reset or recovered

MixKey validates config.json, then tries config.json.bak. If neither is valid, it uses safe defaults. Preserve both files before editing them manually. Warnings are written to %LocalAppData%\MixKey\logs\mixkey.log.

Architecture and quality

MixKey runs one Win32 UI/message thread and receives coalesced Core Audio endpoint/session notifications without a polling service. AudioEngine owns session discovery, filtering, identity grouping, and exact Focus snapshots; HotkeyManager maps registered chords or the opt-in non-suppressing fallback to application commands. A layered Direct2D window renders the no-activate overlay, while the configuration layer validates strict JSON and performs delayed, atomic replacement with a known-good backup.

See:

• Architecture
• Automated and manual testing
• Performance measurement protocol
• Future Microsoft Store/MSIX packaging
• Security policy

Releases

Push a tag matching v* (for example, v1.1.0) after the build and test jobs are green. The release workflow performs a fresh x64 Release build, runs CTest, and publishes a ZIP containing only:

MixKey.exe
README.txt
LICENSE

Contributing

Keep changes native, dependency-light, offline, and within the safety boundary: no process injection, game hooks, input suppression, elevation requirement, or high-frequency polling. Build Release, run CTest, and document only manual tests actually performed.

License

MixKey is released under the MIT License.