Loading repository data…
snowballons / repository
streamwatch-cli
A simple, lightweight command-line tool to manage your favorite live streams, check their status efficiently, and launch them directly in your media player without needing a heavy web browser.
#cli#entertainment#lightweight#livestreaming#mpv-player#opensource
Live repository statistics
★ 8Stars
⑂ 0Forks
◯ 0Open issues
◉ 8Watchers
README preview
StreamWatch: Your Lightweight CLI Live Stream Companion
StreamWatch is a modern, fast, and powerful command-line tool for managing and watching your favorite live streams—all without the resource drain of a web browser. It provides a rich terminal interface to see who's online, what they're streaming, and lets you jump right into the action.
Table of Contents
- Why Use StreamWatch?
- Key Features
- Architecture & Recent Improvements
- Supported Platforms
- Prerequisites
- Installation
- Getting Started
- Usage
- Advanced Configuration
- Configuration File
- Development Setup
- Troubleshooting
- Contributing
- License
- Acknowledgements
Why Use StreamWatch?
- Lightweight & Fast: Consumes a fraction of the CPU and RAM compared to a browser.
- Focus-Friendly: A clean, distraction-free interface.
- Efficient Workflow: Manage and launch streams from a single, keyboard-driven interface.
- Highly Customizable: Tailor StreamWatch to your needs with custom settings and automation hooks.
- Broad Platform Support: Works with hundreds of sites out of the box, powered by Streamlink.
- Cross-Platform: A consistent experience on Windows, macOS, and Linux.
Key Features
- Live Status Display: See who's live with their Alias/Username, Platform, Category, and Viewer Count.
- Interactive Navigation: Use arrow keys, number input, or first-letter search to quickly select streams.
- Playback Controls: Replay, play next/previous, change quality, and more, all from the terminal.
- Stream Aliases: Assign custom nicknames to your streams for a personalized list.
- Stream Management: Add, remove, list, import, and export your stream list with ease.
- File-Based Management: Use a
streams.ddirectory to manage your streams with simple text files. - Background Recording: Record live streams to a file while you continue to browse or watch other streams.
- Automatic Reconnection: Automatically attempts to reconnect if a stream drops.
- Playback Hooks: Trigger custom scripts before and after a stream plays.
- Persistent Configuration: User-editable
config.inifor settings andstreams.jsonfor your interactive list. - Quick Access: Instantly replay the last stream you watched.
- Polished UI: A colorful and modern terminal interface with enhanced pagination and input handling.
- Detailed Logging: Comprehensive log files for easy troubleshooting.
- Enhanced Resilience: Built-in retry mechanisms, circuit breaker patterns, and intelligent caching for improved reliability.
- Modular Architecture: Clean separation of concerns with dedicated modules for UI, stream management, and playback control.
Architecture & Recent Improvements
StreamWatch has undergone significant architectural improvements to enhance reliability, maintainability, and performance:
🏗️ Modular Architecture
- Separation of Concerns: Clean division between UI components, stream management, and playback control
- Command Pattern: Structured command system for better code organization and testing
- Dependency Injection: Improved modularity and testability through proper dependency management
- Enhanced Models: Comprehensive data models with validation using Pydantic for type safety
🔄 Resilience & Performance
- Intelligent Caching: Stream status caching with TTL to reduce API calls and improve response times
- Retry Mechanisms: Exponential backoff retry logic for handling temporary failures
- Circuit Breaker Pattern: Prevents cascading failures by temporarily disabling failing streams
- Rate Limiting: Token bucket algorithm to respect platform rate limits and prevent abuse
🛡️ Security & Validation
- Enhanced Input Validation: Comprehensive URL and user input sanitization
- Security Scanning: Integrated Bandit security vulnerability scanning in CI/CD
- XSS Protection: Safe rendering of user content and stream metadata
- Input Sanitization: Proper validation and cleaning of all user inputs
🧪 Testing & Quality Assurance
- Comprehensive Test Suite: Unit and integration tests with high coverage requirements
- Type Safety: Full type hints throughout the codebase with MyPy static type checking
- Code Quality Tools: Black, isort, Flake8, and MyPy integrated via pre-commit hooks
- Automated Testing: CI/CD pipeline with automated quality checks and security scanning
📊 Enhanced User Experience
- Improved Pagination: Better handling of large stream lists with efficient navigation
- Enhanced Error Handling: More informative error messages and graceful failure recovery
- Better Logging: Comprehensive logging system for easier troubleshooting and debugging
- UI Responsiveness: Optimized UI components for smoother interaction and better performance
🔧 Developer Experience
- Modern Development Tools: Integration with uv for faster dependency management
- Pre-commit Hooks: Automated code quality checks before commits
- Development Documentation: Comprehensive setup and contribution guidelines
- Consistent Coding Standards: Enforced code formatting and style guidelines
These improvements ensure StreamWatch remains maintainable, secure, and performant while providing an excellent user experience.
Supported Platforms
StreamWatch uses Streamlink, so it can play streams from any platform Streamlink supports. Enhanced display features (Username, Platform, Category, Viewer Count) are available for over 20 popular platforms, including:
- YouTube, Twitch, Kick, TikTok
- BiliBili, Douyin, Huya, Vimeo, Dailymotion
- PlutoTV, BBC iPlayer, ARD/ZDF Mediathek, RaiPlay, RTVE Play, Atresplayer, Mitele
- AbemaTV, Adult Swim, Bloomberg, Bigo Live, and more.
A generic fallback is used for other platforms.
Prerequisites
- Python 3.7+
- Streamlink (installed automatically with StreamWatch)
- MPV Media Player (Download) - Highly recommended
Installation
Install StreamWatch using pip:
pip install streamwatch
# 1. Clone the repository
git clone https://github.com/snowballons/streamwatch-cli.git
cd streamwatch-cli
# 2. Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# 3. Install in editable mode
pip install -e ".[dev]"
# 4. Run StreamWatch
streamwatch
Getting Started
-
Run StreamWatch for the first time:
streamwatchThis will create the configuration directory and files.
-
Add streams:
- Press
Ain the main menu to add a stream. - Enter a stream URL. To add a custom alias, type it after the URL (e.g.,
https://twitch.tv/shroud The FPS King). - To add multiple streams, separate them with commas.
- Press
-
Refresh and watch:
- Press
Fto refresh the stream list and see who's live. - Select a stream to start watching.
- Press
Usage
Main Menu
| Key(s) | Action |
|---|---|
Enter | Open interactive selection for live streams. |
[Number] | Play a live stream directly by its number. |
L | List all configured streams. |
A | Add new streams (with optional aliases). |
R | Remove streams from your list. |
I | Import streams from a .txt file. |
E | Export your stream list to a .json file. |
| `V` | Open Recording Controls menu. |
| P | Play the last stream you watched. |
| F | Force a refresh of the live stream list. |
| Q | Quit StreamWatch. |
Playback Controls
| Key(s) | Action |
|---|---|
S | Replay the current stream. |
N | Play the next live stream in the list. |
P | Play the previous live stream in the list. |
C | Change quality on the fly. |
M | Stop stream and return to the main menu. |
D | Open the developer donation link in your browser. |
Q | Stop stream and quit StreamWatch. |
Advanced Configuration
Stream Aliases
Assign custom names to your streams for easier identification. When adding a stream, type the alias after the URL:
URL(s) [and optional alias(es)]: https://www.youtube.com/channel/UC-lHJZR3Gqxm24_Vd_AJ5Yw Linus Tech Tips
Using a streams.d Directory
For advanced stream management, create a streams.d directory in your StreamWatch config folder. Inside this directory, create any number of text files (e.g., gaming.list, news.txt) and add one stream URL per line.
StreamWatch will load all streams from streams.json and any files in streams.d at startup.
Note: The A (Add) and R (Remove) commands only affect streams.json. To manage streams in streams.d, you must edit the files directly.
Importing & Exporting
- Import (
I): Bulk-add streams from any.txtfile (one URL per line). - Export (
E): Create a backup of your current stream list (including aliases) to a.jsonfile.
Playback Hooks
Automate your environment by running custom scripts before and after a stream plays.
- Create an executable script (e.g.,
start_stream.sh,end_stream.bat). - Set the full path to your script in
config.iniunderpre_playback_hookorpost_playback_hook.
StreamWatch passes the following arguments to your script: url, alias, username, platform, quality.
Example hook.sh:
#!/bin/bash
TIMESTAMP=$(date "+%Y-%m-%d %H:%M:%S")
echo "[$TIMESTAMP] Event for alias '$2' on platform '$4' with quality '$5'" >> ~/stream_events.log
Configuration File
Your settings and stream lists are stored in your user configuration directory:
- Linux/macOS:
~/.config/streamwatch/ - Windows:
%APPDATA%\\StreamWatch\\
The config.ini file is created on the first run and can be edited to customize StreamWatch's behavior.
Development Setup
If you want to contribute to StreamWatch or run it from source, follow these steps: