A simple asynchronous Python bot that monitors an Icecast stream and announces track changes to an IRC channel. Supports running multiple instances with different configurations.

Note: This is a work in progress. It has only been tested on Python 3.12.6.

Features

Monitors Icecast stream metadata and announces track changes
Configurable via YAML files and command line arguments
Supports running multiple bot instances simultaneously
Pattern-based song title filtering
Configurable logging levels and output
Smart URL resolution for metadata fetching
Automatic reconnection and error recovery with status reporting
Admin commands with permission system

Dependencies

Installation

Clone the repository
Install dependencies:

pip install -r requirements.txt

Configuration

Create a YAML config file (default: config.yaml):

irc:
  host: "irc.example.net"
  port: 6667
  nick: "MusicBot"
  user: "musicbot"
  realname: "Music Announcer Bot"
  channel: "#music"

stream:
  url: "https://stream.example.com"
  endpoint: "stream"
  health_check_interval: 300

announce:
  format: "\x02Now playing:\x02 {song}"
  ignore_patterns:
    - "Unknown"
    - "Unable to fetch metadata"
    - "Error fetching metadata"

commands:
  prefix: "!"  # Command prefix (e.g. !np, !help)
  require_nick_prefix: false  # If true, commands must be prefixed with "botname: " or "botname, "
  allow_private_commands: false  # If true, allows commands in private messages

admin:
  users:  # List of users who can use admin commands (use "*" for anyone)
    - "*"

logging:
  level: "INFO"  # Logging level: DEBUG, INFO, WARNING, ERROR, or CRITICAL

Usage

Running with Automatic Restart Support

The recommended way to run the bot is using the provided bot.sh script, which handles automatic restarts when using the !restart command:

# Make the script executable
chmod +x bot.sh

# Run a single bot
./bot.sh config.yaml

# Run multiple bots
./bot.sh config1.yaml config2.yaml config3.yaml

Manual Running

You can also run the bot directly with Python:

Single Bot Mode

Run with config file:

python main.py --config myconfig.yaml

Override config with command line arguments:

python main.py --config myconfig.yaml --irc-nick CustomNick --irc-channel "#mychannel"

Available command line arguments:

--config: Path to config file
--irc-host: IRC server hostname
--irc-port: IRC server port
--irc-nick: IRC nickname
--irc-channel: IRC channel to join
--stream-url: Icecast base URL
--stream-endpoint: Stream endpoint
--cmd-prefix: Command prefix character(s)

Multiple Bot Mode

Run multiple instances with different configs:

python main.py config1.yaml config2.yaml config3.yaml

IRC Commands

Regular commands:

!np: Shows the currently playing track
!help: Shows available commands

Admin commands:

!start: Start stream monitoring
!stop: Stop stream monitoring
!reconnect: Reconnect to stream (with status feedback)
!restart: Restart the bot (requires using bot.sh)
!quit: Shutdown the bot

Logging

The bot supports different logging levels configurable in the config.yaml:

DEBUG: Detailed information for troubleshooting
INFO: General operational messages (default)
WARNING: Warning messages and potential issues
ERROR: Error messages only
CRITICAL: Critical failures only

Logs include:

Stream health status
Command processing
Connection status
Error details

The bot also maintains an ERROR.log file for critical issues.

Error Handling

Automatically reconnects on connection drops
Retries stream monitoring on errors
Smart metadata URL resolution
Connection status verification and reporting
Health checks every 5 minutes (configurable)

License

This project is licensed under the MIT License. See the LICENSE file for details.