cinny-desktop/streamdeck-plugin/README.md

Paarrot Stream Deck Plugin

Control your Paarrot desktop app directly from your Elgato Stream Deck! Toggle mute, deafen, switch channels, and send quick messages with the press of a button.

Features

• Toggle Mute - Mute/unmute your microphone with visual feedback
• Toggle Deafen - Deafen/undeafen (mute speakers) with visual feedback
• Change Channel - Switch between rooms/channels instantly
• Send Message - Send predefined messages to the current room
• Get Status - Display current mute/deafen status

Requirements

• Elgato Stream Deck (any model)
• Stream Deck software version 6.0 or later
• Paarrot desktop app running with API server enabled
• Windows 10+ or macOS 10.14+

Installation

Method 1: Install from Release (easiest)

1. Download the latest .streamDeckPlugin file from the Releases page
2. Double-click the file to install
3. Stream Deck software will open and install the plugin automatically

Method 2: Manual Installation

1. Download or clone this repository
2. Copy the com.paarrot.streamdeck.sdPlugin folder to:
   • Windows: %APPDATA%\Elgato\StreamDeck\Plugins\
   • macOS: ~/Library/Application Support/com.elgato.StreamDeck/Plugins/
3. Restart the Stream Deck software

Method 3: Developer Mode

1. Open Stream Deck software
2. Open the Plugins view
3. Enable "Developer Mode" in settings
4. Drag the com.paarrot.streamdeck.sdPlugin folder into the Stream Deck window

Setup

1. Ensure Paarrot API is Running

Make sure your Paarrot desktop app is running with the API server enabled on port 33384. You can test this by visiting:

http://127.0.0.1:33384/health

You should see:

{
  "status": "ok",
  "app": "Paarrot API",
  "version": "1.0.0"
}

2. Add Actions to Stream Deck

1. Open Stream Deck software
2. Find "Paarrot" in the actions list
3. Drag actions onto your Stream Deck buttons
4. Configure actions as needed (see below)

Actions

Toggle Mute

What it does: Toggles your microphone mute status

Configuration: No configuration needed

Visual Feedback:

• Gray microphone icon = unmuted
• Red X over microphone = muted

Usage: Press to toggle between muted and unmuted. The button automatically updates to show the current state.

---

Toggle Deafen

What it does: Toggles deafen status (mutes speakers and microphone)

Configuration: No configuration needed

Visual Feedback:

• Gray speaker icon = not deafened
• Red X over speaker = deafened

Usage: Press to toggle between deafened and not deafened. The button automatically updates to show the current state.

---

Change Channel

What it does: Switches to a different room/channel

Configuration:

1. Drag action to a button
2. Click the button in Stream Deck to open settings
3. Select a channel from the dropdown OR enter a room ID manually
4. Click away to save

Usage: Press to instantly switch to the configured channel.

Tips:

• Channels are grouped by server in the dropdown
• Use manual room ID for rooms not in the list
• Room ID format: !abc123:matrix.org

---

Send Message

What it does: Sends a predefined message to the currently active room

Configuration:

1. Drag action to a button
2. Click the button in Stream Deck to open settings
3. Type your message in the text area
4. Click away to save

Usage: Press to send the message to whichever room is currently active.

Example Messages:

• "BRB!" - Be right back
• "AFK for 5 minutes"
• "On my way!"
• "Thanks everyone!"
• "GG!" - Good game

---

Get Status

What it does: Displays current mute/deafen status on the button

Configuration: No configuration needed

Visual Feedback:

• Shows "OK" when not muted or deafened
• Shows "M" when muted
• Shows "D" when deafened
• Shows "MD" when both muted and deafened

Usage: Button automatically updates every second. Press to force an immediate update.

Troubleshooting

Plugin not showing up

• Restart Stream Deck software
• Check that the plugin folder is in the correct location
• Ensure folder is named exactly com.paarrot.streamdeck.sdPlugin

Actions not working

• Verify Paarrot is running
• Test API at http://127.0.0.1:33384/health
• Check console for errors (View > Open Console in Stream Deck)
• Ensure port 33384 is not blocked by firewall

Button states not updating

• Check that Paarrot API is responding
• Try pressing the action to force an update
• Check Stream Deck console for connection errors

"No channels available" in dropdown

• Ensure you're logged into Paarrot
• Verify you've joined at least one room
• Try entering the room ID manually instead

Actions show red X (alert)

This means the API call failed. Common causes:

• Paarrot app not running
• API server not started
• Network/firewall blocking localhost connections
• Invalid room ID or message configuration

Development

Building from Source

No build step required! The plugin uses vanilla JavaScript.

File Structure

com.paarrot.streamdeck.sdPlugin/
├── manifest.json                 # Plugin metadata and action definitions
├── plugin/
│   ├── index.html               # Plugin entry point
│   └── index.js                 # Main plugin logic
├── propertyinspector/
│   ├── change-channel.html      # Channel selector UI
│   └── send-message.html        # Message input UI
└── images/                       # Action icons
    ├── mute-off.svg
    ├── mute-on.svg
    ├── deafen-off.svg
    ├── deafen-on.svg
    ├── change-channel.svg
    ├── send-message.svg
    ├── status.svg
    ├── toggle-mute.svg
    ├── toggle-deafen.svg
    ├── plugin-icon.svg
    └── category-icon.svg

Modifying the Plugin

1. Make changes to the files
2. Restart Stream Deck software to reload the plugin
3. Test your changes

API Endpoints Used

• GET /health - Check API is running
• GET /status - Get current mute/deafen state
• POST /mute/toggle - Toggle mute
• POST /deafen/toggle - Toggle deafen
• POST /channel - Change channel
• POST /message/current - Send message
• GET /channels - Get channel list

Support

If you encounter issues:

1. Check the troubleshooting section above
2. Enable Stream Deck console logging (View > Open Console)
3. Check Paarrot's console for API errors
4. File an issue on GitHub with logs and details

License

This plugin is provided as-is. See LICENSE file for details.

Credits

Created for Paarrot desktop app.

Icons designed specifically for this plugin.

Version History

1.0.0 (Initial Release)

• Toggle Mute action
• Toggle Deafen action
• Change Channel action with dropdown
• Send Message action
• Get Status action
• Auto-updating button states
• Visual feedback for all actions