IRC-kosmi-relay/MUTE_CONTROL.md

# 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
```