node-windows-audio-manager-switcher
Version:
Native Node.js C++ addon for managing Windows audio devices
310 lines (206 loc) • 9.22 kB
Markdown
# 🎧 Node Windows Audio Manager
> Native Node.js addon for managing **Windows audio playback devices**
> Powered by **C++ + Node-API (N-API)** and ships with **prebuilt binaries** for easy plug-and-play.
## 🚀 Features
- 🔍 List all active audio output devices (name, ID, isDefault)
- 🎚️ Set any device as the system's default playback device
- 🔇 Mute / unmute:
- ✅ Default output device
- ✅ Any specific device (by ID)
- ⚙️ Built with Windows Core Audio + COM API
- 💡 Prebuilt `.node` binaries — **no build tools required**
## 📦 Installation
```bash
npm install node-windows-audio-manager-switcher
```
✅ Works out of the box on Windows
✅ No Visual Studio or compilation needed
> 💬 If you modify native C++ code, see [Build From Source](#prebuilt-native-addon)
## 🧠 Usage Examples
### 🔍 List Playback Devices
```js
const { listDevices } = require('node-windows-audio-manager-switcher');
const devices = listDevices();
devices.forEach((device, index) => {
console.log(`${index + 1}. ${device.name} [${device.id}] Default: ${device.isDefault}`);
});
```
### 🎚️ Set Default Playback Device
```js
const { listDevices, setDefaultDevice } = require('node-windows-audio-manager-switcher');
const devices = listDevices();
const target = devices.find(d => d.name.includes("Speakers"));
if (target) {
const success = setDefaultDevice(target.id);
console.log(success ? "✅ Set as default!" : "❌ Failed to set device.");
}
```
### 🔇 Mute / Unmute Default Device
```js
const { setDefaultPlaybackMute } = require('node-windows-audio-manager-switcher');
setDefaultPlaybackMute(true); // Mute
setDefaultPlaybackMute(false); // Unmute
```
### 🔇 Mute / Unmute Specific Device by ID
```js
const { listDevices, muteDeviceById } = require('node-windows-audio-manager-switcher');
const target = listDevices()[0]; // Example: first device
muteDeviceById(target.id, true); // Mute
muteDeviceById(target.id, false); // Unmute
```
## 📘 API Reference
| Function | Description |
|----------|-------------|
| `listDevices()` → `{ name, id, isDefault }[]` | Lists all active output devices |
| `setDefaultDevice(deviceId)` → `boolean` | Sets the default playback device |
| `setDefaultPlaybackMute(mute)` → `boolean` | Mute/unmute the default device |
| `muteDeviceById(deviceId, mute)` → `boolean` | Mute/unmute a specific device |
## 📂 Project Structure
```bash
node-windows-audio-manager-switcher/
├── index.js # JS bindings to native addon
├── native/ # C++ source code (AudioSwitcher, DeviceUtils)
├── prebuilds/ # Precompiled binaries (.tar.gz)
├── build/ # Generated at install (addon.node)
├── test/ # Interactive example scripts
└── binding.gyp # node-gyp config file
```
## 🧪 Dev Commands
```bash
# Build from source (dev)
npm run dev:build
# Generate prebuilt binary (for npm publish)
npm run dev:prebuild
# Run example tests
npm run dev:test:devices
npm run dev:test:set-default
npm run dev:test:mute-default
npm run dev:test:unmute-default
npm run dev:test:mute-device
npm run dev:test:unmute-device
```
## Prebuilt Native Addon
No toolchain? No problem.
We use [`prebuild`](https://github.com/prebuild/prebuild) to compile and package `.node` binaries:
```bash
npx prebuild --backend=node-gyp -t 20.13.1 --strip --napi
```
At install, `prebuild-install` downloads the correct binary from the `prebuilds/` folder.
> 📦 Works seamlessly for Windows x64 and Node.js 20.x+
## ⚠️ Troubleshooting
| Problem | Solution |
|----------------------------------------------|--------------------------------------------------------------------------------------------|
| `node_api.h` not found | Make sure `node-addon-api` is installed: `npm install node-addon-api` |
| `addon.node` missing | Run `npm rebuild` or `npm run dev:build` |
| `CoCreateInstance` fails | Run your script with **Administrator privileges** (Right click > "Run as Administrator") |
| `prebuild` fails | Ensure Node.js version matches and all required build tools are installed |
| ❌ `WindowsTargetPlatformVersion` error | See **"Missing Windows SDK version" fix below** |
### 🛠️ Missing Windows SDK Version
You might see an error like:
```bash
The Windows SDK version 10.0.22621.0 was not found.
Install the required version of Windows SDK or change the SDK version...
```
This happens when your system **doesn't have the specific Windows SDK version** your build setup is looking for.
#### ✅ Solution 1: Let it use the latest installed SDK (Recommended)
Update your `binding.gyp` file and **remove the hardcoded SDK version**:
**Before (❌):**
```json
"msvs_windows_target_platform_version": "10.0.22621.0"
```
**After (✅):**
Just delete that line entirely.
Then rebuild everything:
```bash
npx node-gyp clean
npx node-gyp configure
npx node-gyp build
```
Node-gyp will now use **the latest installed SDK version** automatically.
#### ✅ Solution 2: Download the required SDK version
If you **want to use a specific SDK version** mentioned in the error (like `10.0.22621.0`), do this:
1. Visit the official Windows SDK archive:
👉 [https://developer.microsoft.com/en-us/windows/downloads/sdk-archive/](https://developer.microsoft.com/en-us/windows/downloads/sdk-archive/)
2. Download and install the **exact SDK version** shown in the error.
3. Once installed, re-run:
```bash
npm install
```
### 🔍 How to check installed SDKs
Run this in PowerShell:
```powershell
Get-ChildItem 'C:\Program Files (x86)\Windows Kits\10\Include' | Select-Object Name
```
You’ll see something like:
```bash
Name
----
10.0.19041.0
10.0.26100.0
```
Use one of these versions if you want to manually set it.
### 📌 Note on Prebuilt Binaries
This package ships with **prebuilt native binaries** for seamless installation — no C++ compiler, Visual Studio, or Windows SDK required!
✅ Just run:
```bash
npm install node-windows-audio-manager-switcher-switcher
```
> Under the hood, we use [`prebuild`](https://github.com/prebuild/prebuild) + [`prebuild-install`](https://github.com/prebuild/prebuild-install) to provide platform-specific `.node` binaries.
#### ℹ️ How It Works
- During `npm install`, `prebuild-install` checks for a compatible `.tar.gz` binary (based on your Node.js version and OS).
- If a matching binary is found (e.g. Node.js 20.x, Windows x64), it downloads and installs automatically.
- If **no matching binary** is available, it falls back to building from source — which requires **Visual Studio + Windows SDK**.
Here’s the updated section with a clean **batch-style** note and a list of supported versions so far:
#### 💡 Supported Node Versions
We currently provide prebuilt native binaries for the following Node.js versions:
| Node.js Version | ABI Version | Status |
|-----------------|-------------|------------|
| ✅ 22.x | `v127` | Supported |
| ✅ 21.x | `v130` | Supported |
| ✅ 20.x | `v115` | Supported |
| ✅ 19.x | `v111` | Supported |
| ✅ 18.x (LTS) | `v108` | Supported |
> 💡 **Note:** If you're using a different version of Node.js and encounter the message
> `prebuild-install warn install No prebuilt binaries found`, you can either:
>
> 1. **Switch to a supported version** (recommended), or
> 2. **Manually build from source** by running:
```bash
npm install --build-from-source
```
- _(More coming soon...)_
If you're using a newer Node.js version and see an install error like:
```bash
prebuild-install warn install No prebuilt binaries found (target=22.14.0 ...)
```
This means we haven't published a prebuilt binary for your Node version **yet**. You can either:
- ⚙️ Build from source (requires build tools), or
- 🧩 Downgrade to a supported Node.js version (e.g. Node 20.x)
## 🙌 Contributing
We welcome PRs and ideas! You can contribute by:
- 🎚️ Adding volume control APIs
- 🔁 Listening to real-time device change events
- ✅ Writing unit tests (e.g. with `jest` or `mocha`)
## ❤️ Credits
- Microsoft Core Audio APIs (`IMMDevice`, `IPolicyConfig`, `IAudioEndpointVolume`)
- [node-addon-api](https://github.com/nodejs/node-addon-api) (N-API C++ bindings)
- Inspiration: [tartakynov/audioswitch](https://github.com/tartakynov/audioswitch)