Icecast Stream Monitor

A beautiful command-line tool to stream and monitor Icecast radio servers with real-time metadata display and audio playback.

Features

• Live Audio Playback - Streams audio directly to your system's default audio device
• Real-time Metadata - Displays current track information with ICY metadata support
• Track History - Shows recently played tracks with duration tracking
• Connection Statistics - Monitor data transfer, uptime, and metadata updates
• Beautiful TUI - Rich terminal UI with color-coded panels and live updates
• Web Interface - Modern web dashboard with real-time updates via WebSocket
• Audio Device Info - Displays which audio output device is being used
• Low Latency - Efficient streaming with minimal buffer overhead

Screenshots

The monitor displays:

• Connection information (station name, genre, bitrate, etc.)
• Audio player widget with playback status and volume
• Current track metadata
• Track history with durations
• Real-time statistics

Requirements

• Python 3.8 or higher
• FFmpeg (includes ffplay for audio playback)
• macOS, Linux, or Windows

Installation

1. Install FFmpeg

macOS (using Homebrew):

brew install ffmpeg

Linux (Ubuntu/Debian):

sudo apt-get update
sudo apt-get install ffmpeg

Linux (Fedora):

sudo dnf install ffmpeg

Windows: Download from ffmpeg.org and add to PATH.

2. Clone or Download This Repository

git clone <repository-url>
cd icecast

3. Set Up Python Virtual Environment (Recommended)

python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

4. Install Python Dependencies

pip install -r requirements.txt

Usage

Basic Usage

Stream from the default URL (configured in the script):

python3 icecast_stream_monitor.py

Specify a Custom Stream URL

Using positional argument:

python3 icecast_stream_monitor.py http://example.com:8000/stream

Using the -u flag:

python3 icecast_stream_monitor.py -u http://example.com:8000/stream

Enable Web Interface

Run with web interface on default port (5000):

python3 icecast_stream_monitor.py --web http://example.com:8000/stream

Run web interface on custom port:

python3 icecast_stream_monitor.py --web --port 8080 http://example.com:8000/stream

Run in headless mode (web only, no terminal UI):

python3 icecast_stream_monitor.py --web --no-tui http://example.com:8000/stream

Then open your browser to http://localhost:5000 (or your custom port)

Examples

# Stream from a local Icecast server
python3 icecast_stream_monitor.py http://192.168.60.5:8000/stream

# Stream from an internet radio station
python3 icecast_stream_monitor.py http://stream.example.com:8000/radio

# Run with web interface
python3 icecast_stream_monitor.py --web http://192.168.60.5:8000/stream

# Run headless with web interface on custom port
python3 icecast_stream_monitor.py --web --no-tui --port 8080 http://example.com:8000/stream

# View help
python3 icecast_stream_monitor.py --help

Controls

Terminal UI

• Ctrl+C - Stop streaming and exit the monitor

Web Interface

• Open browser to http://localhost:5000 (or your configured host:port)
• Real-time updates via WebSocket
• Works on mobile devices
• Can run alongside terminal UI or in headless mode

Display Panels

Connection Information

• URL, Status Code
• Station Name, Genre, Station URL
• Bitrate, Sample Rate
• Content Type, Server
• Metadata Interval

Audio Player

• Playback Status (Playing / Paused / Stopped)
• Volume Bar (visual indicator)
• Output Device (current audio device name)
• Audio Format
• Stream Bitrate

Current Track

• Real-time metadata from the stream
• Stream title and other ICY metadata fields

Track History

• Shows previously played tracks
• Displays timestamp and duration for each track
• Most recent tracks shown first

Statistics

• Connection uptime
• Total data received
• Number of metadata updates
• Last update timestamp

Configuration

The default stream URL can be modified in the script:

default='http://192.168.60.5:8000/stream'

Troubleshooting

No Audio Output

1. Check FFmpeg installation:

   which ffplay  # macOS/Linux
   where ffplay  # Windows
   

2. Verify audio device: Make sure your system's default audio output is configured correctly.

3. Test FFmpeg directly:

   ffplay http://your-stream-url
   

Connection Issues

• Verify the stream URL is correct and accessible
• Check firewall settings
• Ensure the Icecast server is running and accepting connections

Module Not Found Errors

Make sure all dependencies are installed:

pip install -r requirements.txt

Dependencies

• requests - HTTP library for streaming data
• rich - Beautiful terminal formatting and TUI components
• flask - Web framework for web interface (optional)
• flask-socketio - WebSocket support for real-time updates (optional)
• flask-cors - CORS support for web interface (optional)

Technical Details

Audio Playback

• Uses ffplay (part of FFmpeg) for audio decoding and playback
• Supports various audio formats (MP3, AAC, OGG, etc.)
• Threaded audio queue for smooth playback

Metadata Parsing

• Supports ICY metadata protocol
• Parses inline metadata at configured intervals
• Tracks metadata changes for history

Display Updates

• Live updating TUI using Rich library
• Refreshes 2 times per second
• Responsive layout adapts to terminal size

Development

Code Quality Tools

The project includes linting and formatting tools for code quality:

# Install development dependencies
make install-dev

# Run linters (flake8, pylint, mypy)
make lint

# Format code (black, isort)
make format

# Run all checks
make check

Linting Configuration

• flake8 - Style guide enforcement (configured in .flake8)
• pylint - Code analysis (configured in pyproject.toml)
• black - Code formatter with 100 char line length
• isort - Import statement formatter
• mypy - Static type checker

License

MIT License - Feel free to use and modify as needed.

Contributing

Contributions are welcome! Feel free to:

• Report bugs
• Suggest features
• Submit pull requests

Author

Created for monitoring Icecast streaming servers with style.

Acknowledgments

• Built with Rich for beautiful terminal output
• Uses FFmpeg for audio playback
• Supports the Icecast streaming protocol