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 streams for metadata changes
Announces new tracks in IRC channels
Supports multiple IRC networks and channels
Customizable announcement formats
Command system with admin privileges
Automatic reconnection on network issues
Multiple bot instances can be managed together
Systemd service integration

Dependencies

Installation

Clone the repository
Install dependencies:

pip install -r requirements.txt

Configuration

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

irc:
  host: "irc.libera.chat"
  port: 6667
  nick: "IcecastBot"
  user: "icecastbot"
  realname: "Icecast IRC Bot"
  channel: "#yourchannel"

stream:
  url: "https://your.stream.url"  # Base URL without /stream or .mp3
  endpoint: "/stream"  # The endpoint part (e.g. /stream, /radio.mp3)
  health_check_interval: 300  # How often to check health status (in seconds)

announce:
  format: "\x02Now playing:\x02 {song}"  # Format for song announcements
  ignore_patterns:  # Don't announce songs matching these 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

help:  # Help message templates
  specific_format: "\x02{prefix}{cmd}\x02: {desc}"  # Format for specific command help
  list_format: "(\x02{cmd}\x02, {desc})"  # Format for commands in list
  list_separator: " | "  # Separator between commands in list

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

Usage

Manager Commands

The bot manager supports the following commands:

icecast-irc-bot-manager list                     # List running bots
icecast-irc-bot-manager start --config FILE      # Start a bot
icecast-irc-bot-manager stop BOT_ID              # Stop a bot
icecast-irc-bot-manager restart BOT_ID           # Restart a bot
icecast-irc-bot-manager quiet BOT_ID             # Disable song announcements
icecast-irc-bot-manager unquiet BOT_ID           # Enable song announcements

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

Commands

The bot supports the following commands:

!np - Show the currently playing song
!help - Show available commands or help for a specific command

Admin commands (only available to users listed in the admin.users config):

!start - Start stream monitoring
!stop - Stop stream monitoring
!quiet - Disable song announcements but continue monitoring
!unquiet - Enable song announcements
!reconnect - Reconnect to the stream
!restart - Restart the bot
!quit - Shutdown the bot

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.