150 lines
4.2 KiB
Markdown
150 lines
4.2 KiB
Markdown
# Icecast-metadata-IRC-announcer
|
|
|
|
[](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
|
|
|
|
### 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
|
|
- `!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.
|