Icecast-metadata-IRC-announcer/README.md

Icecast-metadata-IRC-announcer

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

• asif
• aiohttp
• pyyaml

Installation

1. Clone the repository
2. 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.