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

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

## Usage

### 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

### Multiple Bot Mode

Run multiple instances with different configs:
```bash
python main.py config1.yaml config2.yaml config3.yaml
```

Or use the launcher script:
```bash
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.

-------

## TODO

- Add a help command
- Add commands to control the stream connection from IRC
    - Also to start/stop the service entirely
- Add a version command
- Add a list of commands to the README
- Enable joining multiple channels with a single bot instance
- Add a command to force the bot to reconnect to the stream
- Add a command to check the status of the bot
- Add a command to check the status of the stream
- Add a command to check the status of the IRC connection
- Add a command to check the status of the bot
- Add a command to check the status of the stream
- Move this to a TODO.md file :)