Icecast-metadata-IRC-announcer/README.md

# Icecast-metadata-IRC-announcer

[![Version](https://img.shields.io/badge/dynamic/raw?color=blue&label=version&query=.&url=https%3A%2F%2Fcode.cottongin.xyz%2Fcottongin%2FIcecast-metadata-IRC-announcer%2Fraw%2Fbranch%2Fmaster%2FVERSION)](https://code.cottongin.xyz/cottongin/Icecast-metadata-IRC-announcer/releases)

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](https://github.com/minus7/asif)
- [aiohttp](https://github.com/aio-libs/aiohttp)
- [pyyaml](https://github.com/yaml/pyyaml)

## Installation

1. Clone the repository
2. Install dependencies:
```bash
pip install -r requirements.txt
```

## Configuration

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

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

```bash
# 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:
```bash
python main.py --config myconfig.yaml
```

Override config with command line arguments:
```bash
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:
```bash
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.