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
Responds to !np commands in IRC channels
Automatic reconnection and error recovery

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"
    # Add more patterns to ignore

Usage

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

Multiple Bot Mode

Run multiple instances with different configs:

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

Or use the launcher script:

python launch.py

IRC Commands

!np: Shows the currently playing track

Logging

The bot logs important events to stdout with timestamps. Log level is set to INFO by default.

Error Handling

Automatically reconnects on connection drops
Retries stream monitoring on errors
Logs errors for debugging
Health checks every 5 minutes (configurable)

License

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