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

./matterbridge -conf matterbridge.toml -muted

Docker

Update docker-compose.yml:

services:
  kosmi-irc-relay:
    command: ["/app/matterbridge", "-conf", "/app/matterbridge.toml", "-muted"]

Or run with override:

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:

ps aux | grep matterbridge
# or
pgrep matterbridge

Toggle mute:

kill -SIGUSR1 <pid>

Example:

$ pgrep matterbridge
12345

$ kill -SIGUSR1 12345
# Bot logs: 🔇 Jackbox announcements MUTED

$ kill -SIGUSR1 12345
# Bot logs: 🔊 Jackbox announcements UNMUTED

Docker

Find the container name:

docker ps

Toggle mute:

docker kill -s SIGUSR1 <container_name>

Example:

$ 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

# 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

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

#!/bin/bash
docker kill -s SIGUSR1 kosmi-irc-relay
docker logs kosmi-irc-relay --tail 1

Make it executable:

chmod +x mute-toggle.sh

Use it:

./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:

docker ps | grep kosmi-irc-relay

If the container is restarting, check logs:

docker logs kosmi-irc-relay

Signal not working locally

Make sure the process is running:

ps aux | grep matterbridge

Check you're using the correct PID:

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:

#!/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:

sudo /usr/local/bin/matterbridge-mute-toggle