163 lines
4.3 KiB
Markdown
163 lines
4.3 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 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.
|