Skip to content

README_V2.md

Latest commit

 

History

History
232 lines (173 loc) · 7.13 KB

README_V2.md

File metadata and controls

232 lines (173 loc) · 7.13 KB

SoundSwitch Mute Stream Deck Plugin v2.0

🎯 Direct Command Execution - No companion service needed!

A Stream Deck plugin that allows you to toggle mute/unmute functionality using SoundSwitch CLI with direct command execution.

✨ Features

  • 🔴 One-Click Toggle: Mute/unmute with a single button press
  • 🎨 Visual Feedback: Blue icon when unmuted, red icon when muted
  • ⚡ Direct Execution: No companion service - executes SoundSwitch.CLI.exe directly
  • 🔧 Auto-Discovery: Automatically finds SoundSwitch installation
  • 📝 Multiple Implementations: Batch file, PowerShell, and Node.js options
  • 🎛️ Modern Setup: React-based setup page with Tailwind CSS styling

🏗️ Architecture

This plugin uses direct command execution via Stream Deck's CodePath feature:

Stream Deck Button → soundswitch-toggle.cmd → SoundSwitch.CLI.exe → Visual Feedback

No HTTP server, no companion service, no complex setup!

📦 Installation

Prerequisites

  1. SoundSwitch: Download and install from soundswitch.aaflalo.me
  2. Stream Deck Software: Version 4.1 or later

Plugin Installation

  1. Download the latest .sdPlugin file from releases
  2. Double-click to install in Stream Deck software
  3. Drag "SoundSwitch Mute Toggle" action to any button
  4. Done! No additional setup required

🔧 How It Works

Command Execution Flow

  1. Button Press → Stream Deck executes soundswitch-toggle.cmd
  2. Auto-Discovery → Script finds SoundSwitch.CLI.exe in common locations:
    • C:\Program Files\SoundSwitch\SoundSwitch.CLI.exe
    • C:\Program Files (x86)\SoundSwitch\SoundSwitch.CLI.exe
    • %LOCALAPPDATA%\Programs\SoundSwitch\SoundSwitch.CLI.exe
  3. Execute Command → Runs SoundSwitch.CLI.exe mute -t
  4. Parse Output → Detects mute/unmute state from command output
  5. Visual Feedback → Updates button appearance based on state

Command Scripts Included

  • soundswitch-toggle.cmd - Primary batch file implementation
  • soundswitch-toggle.ps1 - PowerShell alternative
  • soundswitch-node.js - Node.js alternative (if Node.js is installed)

🎨 Button States

State Visual Description
Unmuted 🔵 Blue microphone icon Audio is active
Muted 🔴 Red microphone with slash Audio is muted

🛠️ Customization

Custom SoundSwitch Path

If SoundSwitch is installed in a non-standard location, you can:

  1. Modify the batch file: Edit soundswitch-toggle.cmd in the plugin directory
  2. Add custom path: Insert your path at the beginning of the PATHS array
  3. Or use arguments: Pass the path as an argument (advanced users)

Multiple Script Options

The plugin includes three implementation approaches:

REM Batch File (Default)
soundswitch-toggle.cmd

REM PowerShell (Alternative)
powershell -ExecutionPolicy Bypass -File soundswitch-toggle.ps1

REM Node.js (If Node.js installed)  
node soundswitch-node.js

To switch implementations, modify the CodePath in manifest.json.

🐛 Troubleshooting

Common Issues

❌ Button doesn't respond

  • Ensure SoundSwitch is installed and working
  • Test manually: Open Command Prompt and run: 
    "C:\Program Files\SoundSwitch\SoundSwitch.CLI.exe" mute -t

❌ "SoundSwitch not found" error

  • Check SoundSwitch installation path
  • Verify SoundSwitch.CLI.exe exists
  • Install SoundSwitch from official website

❌ Permission errors

  • Run Stream Deck as Administrator
  • Check Windows antivirus/security settings
  • Ensure SoundSwitch has audio device permissions

Testing SoundSwitch Installation

Run this in Command Prompt to test:

cd /d "%~dp0"
soundswitch-toggle.cmd

Expected output:

Found SoundSwitch at: C:\Program Files\SoundSwitch\SoundSwitch.CLI.exe  
Microfone (NVIDIA Broadcast) is now muted

💻 Development

Building from Source

# Clone repository
git clone https://github.com/leandro-menezes/stream-deck-mute-soundswitch
cd stream-deck-mute-soundswitch

# Install dependencies
npm install

# Build plugin
npm run build

# Package for distribution  
npm run package

Project Structure

src/
├── manifest.json                 # Plugin configuration
├── soundswitch-toggle.cmd        # Primary command script
├── soundswitch-toggle.ps1        # PowerShell alternative
├── soundswitch-node.js           # Node.js alternative
├── pi.html                       # Property inspector
├── setup.html                    # Setup page (React)
├── assets/                       # Icons and images
│   ├── muteIcon.svg             # Plugin icon
│   ├── muted.svg                # Red muted state
│   └── unmuted.svg              # Blue unmuted state
└── js/                          # JavaScript modules
    ├── main.js                  # Plugin logic
    ├── pi.js                    # Property inspector
    └── lib/streamDeck.js        # SDK wrapper

Command Script Development

The batch file uses this logic:

  1. Check for custom path argument
  2. Try default installation paths
  3. Execute SoundSwitch CLI command
  4. Return appropriate exit code
@echo off
REM Try multiple paths
for /L %%i in (0,1,3) do (
    call set "SOUNDSWITCH_PATH=%%PATHS[%%i]%%"
    if exist "!SOUNDSWITCH_PATH!" (
        "!SOUNDSWITCH_PATH!" mute -t
        exit /b %ERRORLEVEL%
    )
)

🔒 Security

  • No network access - All execution is local
  • Limited scope - Only executes SoundSwitch.CLI.exe
  • User privileges - Runs with current user permissions
  • No elevated access - Does not require Administrator rights

📋 Compatibility

  • Windows 10+ (SoundSwitch requirement)
  • Stream Deck Software 4.1+
  • SoundSwitch with CLI support
  • All Stream Deck devices (Original, Mini, XL, MK.2, +, Mobile)

🚀 Advantages of v2.0

✅ Compared to v1.0 (Companion Service):

  • No HTTP server - Eliminates port conflicts
  • No service installation - Simple double-click install
  • Lower resource usage - No background processes
  • Faster execution - Direct command execution
  • Easier debugging - Standard batch file execution
  • Better reliability - Fewer moving parts

✅ Compared to Other Solutions:

  • Native integration - Uses Stream Deck's built-in command execution
  • Auto-discovery - Finds SoundSwitch automatically
  • Multiple fallbacks - Batch/PowerShell/Node.js options
  • Visual feedback - Clear mute/unmute indication
  • Professional polish - Custom icons and proper SDK integration

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Test your changes with Stream Deck
  4. Submit a pull request

📜 License

MIT License - see LICENSE file for details.

🙏 Credits

  • SoundSwitch: soundswitch.aaflalo.me - Excellent audio device switching tool
  • Stream Deck SDK: Elgato's official development kit
  • ScriptDeck Plugin: Inspiration for direct command execution approach

⭐ If this plugin helps you, please give it a star on GitHub!