wow that took awhile

MUTE_CONTROL.md

@@ -0,0 +1,225 @@
+# Mute Control for Jackbox Announcements
+
+The bot supports muting Jackbox announcements without restarting. This is useful when you want to test the Jackbox API or run games without spamming the chat.
+
+## Features
+
+- ✅ Start the bot muted
+- ✅ Toggle mute/unmute while running
+- ✅ Works in terminal and Docker
+- ✅ Vote detection still works (votes are sent to API even when muted)
+- ✅ Only Jackbox announcements are muted (IRC ↔ Kosmi relay still works)
+
+## Starting Muted
+
+### Terminal
+```bash
+./matterbridge -conf matterbridge.toml -muted
+```
+
+### Docker
+Update `docker-compose.yml`:
+```yaml
+services:
+  kosmi-irc-relay:
+    command: ["/app/matterbridge", "-conf", "/app/matterbridge.toml", "-muted"]
+```
+
+Or run with override:
+```bash
+docker-compose run --rm kosmi-irc-relay /app/matterbridge -conf /app/matterbridge.toml -muted
+```
+
+## Toggling Mute While Running
+
+The bot listens for the `SIGUSR1` signal to toggle mute status.
+
+### Terminal (Local Process)
+
+**Find the process ID:**
+```bash
+ps aux | grep matterbridge
+# or
+pgrep matterbridge
+```
+
+**Toggle mute:**
+```bash
+kill -SIGUSR1 <pid>
+```
+
+**Example:**
+```bash
+$ pgrep matterbridge
+12345
+
+$ kill -SIGUSR1 12345
+# Bot logs: 🔇 Jackbox announcements MUTED
+
+$ kill -SIGUSR1 12345
+# Bot logs: 🔊 Jackbox announcements UNMUTED
+```
+
+### Docker
+
+**Find the container name:**
+```bash
+docker ps
+```
+
+**Toggle mute:**
+```bash
+docker kill -s SIGUSR1 <container_name>
+```
+
+**Example:**
+```bash
+$ docker ps
+CONTAINER ID   IMAGE              COMMAND                  NAMES
+abc123def456   kosmi-irc-relay    "/app/matterbridge -…"   kosmi-irc-relay
+
+$ docker kill -s SIGUSR1 kosmi-irc-relay
+# Bot logs: 🔇 Jackbox announcements MUTED
+
+$ docker kill -s SIGUSR1 kosmi-irc-relay
+# Bot logs: 🔊 Jackbox announcements UNMUTED
+```
+
+## What Gets Muted?
+
+### Muted Messages ❌
+- 🎮 Game Night is starting!
+- 🎮 Coming up next: [Game] - Room Code [CODE]
+- 🗳️ Final votes for [Game]: X👍 Y👎
+- 🌙 Game Night has ended! Thanks for playing!
+
+### Still Works ✅
+- Vote detection (`thisgame++` / `thisgame--`)
+- Votes sent to Jackbox API
+- IRC ↔ Kosmi message relay
+- All other bot functionality
+
+## Log Messages
+
+**When starting muted:**
+```
+INFO Jackbox announcements started MUTED (use SIGUSR1 to toggle)
+INFO Signal handler ready: Send SIGUSR1 to toggle mute (kill -SIGUSR1 <pid> or docker kill -s SIGUSR1 <container>)
+```
+
+**When toggling to muted:**
+```
+WARN 🔇 Jackbox announcements MUTED
+```
+
+**When toggling to unmuted:**
+```
+INFO 🔊 Jackbox announcements UNMUTED
+```
+
+**When a message is suppressed:**
+```
+DEBUG Jackbox message suppressed (muted): 🎮 Coming up next: Drawful 2 - Room Code C0D3
+```
+
+## Use Cases
+
+### Testing Jackbox API
+```bash
+# Start muted
+docker-compose up -d
+
+# Test vote detection without spamming chat
+# (votes are still sent to API)
+# In chat: "thisgame++"
+
+# Check logs to see votes are being processed
+docker logs kosmi-irc-relay -f
+
+# Unmute when ready
+docker kill -s SIGUSR1 kosmi-irc-relay
+```
+
+### Running Private Games
+```bash
+# Mute during game setup
+docker kill -s SIGUSR1 kosmi-irc-relay
+
+# Play games without announcements
+# (useful if you're testing or running a private session)
+
+# Unmute for public game night
+docker kill -s SIGUSR1 kosmi-irc-relay
+```
+
+### Quick Mute Script
+Create a helper script `mute-toggle.sh`:
+```bash
+#!/bin/bash
+docker kill -s SIGUSR1 kosmi-irc-relay
+docker logs kosmi-irc-relay --tail 1
+```
+
+Make it executable:
+```bash
+chmod +x mute-toggle.sh
+```
+
+Use it:
+```bash
+./mute-toggle.sh
+# 🔇 Jackbox announcements MUTED
+
+./mute-toggle.sh
+# 🔊 Jackbox announcements UNMUTED
+```
+
+## Troubleshooting
+
+### Signal not working in Docker
+Make sure your Docker container is running:
+```bash
+docker ps | grep kosmi-irc-relay
+```
+
+If the container is restarting, check logs:
+```bash
+docker logs kosmi-irc-relay
+```
+
+### Signal not working locally
+Make sure the process is running:
+```bash
+ps aux | grep matterbridge
+```
+
+Check you're using the correct PID:
+```bash
+pgrep -f matterbridge
+```
+
+### Mute state not persisting after restart
+Mute state is **not persisted** across restarts. If you restart the bot:
+- Without `-muted` flag: Bot starts unmuted
+- With `-muted` flag: Bot starts muted
+
+This is intentional - you probably want announcements by default.
+
+## Advanced: Systemd Service
+
+If running as a systemd service, you can use `systemctl`:
+
+**Create a mute toggle script:**
+```bash
+#!/bin/bash
+# /usr/local/bin/matterbridge-mute-toggle
+PID=$(systemctl show -p MainPID --value matterbridge.service)
+kill -SIGUSR1 $PID
+journalctl -u matterbridge.service -n 1 --no-pager
+```
+
+**Use it:**
+```bash
+sudo /usr/local/bin/matterbridge-mute-toggle
+```
+