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

- [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.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:

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

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

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