# Stream Deck integration — handoff

## Summary

The Elgato Stream Deck plugin (`streamdeck-plugin/`) controls Paarrot via the local HTTP API: toggle mute/deafen, switch channels, send messages, and show status. It is a separate package from the main app but ships in the same monorepo.

## User-facing behavior

- User installs `.streamDeckPlugin` or copies `com.paarrot.streamdeck.sdPlugin` into Stream Deck plugins folder
- Requires Paarrot desktop running with API on `http://127.0.0.1:33384`
- Actions: Toggle Mute, Toggle Deafen, Change Channel, Send Message, Get Status

## Architecture

```
Stream Deck button press
  → com.paarrot.streamdeck.sdPlugin/plugin/index.js
    → fetch http://127.0.0.1:33384/...
      → Paarrot Electron API (see local-api handoff)
```

## Key files

| Path | Role |
|------|------|
| `streamdeck-plugin/com.paarrot.streamdeck.sdPlugin/manifest.json` | Plugin manifest |
| `streamdeck-plugin/com.paarrot.streamdeck.sdPlugin/plugin/index.js` | Action implementations |
| `streamdeck-plugin/com.paarrot.streamdeck.sdPlugin/plugin/index.html` | Property inspector UI |
| `streamdeck-plugin/build.js` | Build `.streamDeckPlugin` bundle |
| `streamdeck-plugin/validate.js` | Manifest validation |
| `streamdeck-plugin/README.md` | User install guide |
| `streamdeck-plugin/QUICKSTART.md` | Dev quickstart |

## Data model

None — stateless HTTP client. Channel list and status come from Paarrot API responses.

## Dependencies

- Elgato Stream Deck software 6.0+
- Paarrot local API (port 33384)
- Node build tooling in `streamdeck-plugin/package.json`

## Integration points

- **local-api**: sole backend; breaking API changes require Stream Deck plugin update
- Icons: `streamdeck-plugin/.../images/paarrot.svg`, `status.svg`

## Testing

### Manual

1. Run Paarrot; confirm `/health` responds.
2. Load plugin in Stream Deck developer mode.
3. Map Toggle Mute to a key; join a call; press key.
4. Map Change Channel; verify room switch in Paarrot.

### Automated

- `node streamdeck-plugin/validate.js`

## Known issues & gotchas

- Plugin repo README still references placeholder GitHub URLs in places — update on publish
- No auth on API; same machine trust model
- Deafen/mute only meaningful during active calls

## Future work

- Auto-discover rooms without manual room id entry in property inspector
- Connection status indicator on Stream Deck key

## Related docs

- [local-api HANDOFF](../local-api/HANDOFF.md)
- [API.md](../../API.md)
- [streamdeck-plugin/README.md](../../../../streamdeck-plugin/README.md)

## Add your extra things here

- Bundle id: `com.paarrot.streamdeck`
- Build output: `.streamDeckPlugin` via `npm run build` in `streamdeck-plugin/`