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.
(Demo showcasing StreamWatch's interactive menu and playback)
- 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
- 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.
- 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.
StreamWatch has undergone significant architectural improvements to enhance reliability, maintainability, and performance:
- 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
- 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
- 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
- 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
- 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
- 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.
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.
- Python 3.7+
- Streamlink (installed automatically with StreamWatch)
- MPV Media Player (Download) - Highly recommended
Install StreamWatch using pip:
pip install streamwatchAlternative: Installation from Source
# 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-
Run StreamWatch for the first time:
streamwatch
This 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
| 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. |
| 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. |
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
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.
- 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.
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.logYour 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.
If you want to contribute to StreamWatch or run it from source, follow these steps:
- Python 3.8+
- uv (recommended) or pip
- Git
-
Clone the repository:
git clone https://github.com/snowballons/streamwatch-cli.git cd streamwatch-cli -
Install dependencies using uv (recommended):
# Install all dependencies including development tools uv sync --dev # Or using the dependency groups uv sync --group dev
Alternative with pip:
# Create and activate virtual environment python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate # Install in editable mode with dev dependencies pip install -e ".[dev]"
-
Set up pre-commit hooks:
# Using uv uv run pre-commit install # Or with pip pre-commit install
-
Run the development version:
# Using uv uv run streamwatch # Or with pip (after activating venv) streamwatch
The project includes several development tools configured via pre-commit hooks:
- Black: Code formatting
- isort: Import sorting
- Flake8: Linting and style checking
- MyPy: Static type checking
- Bandit: Security vulnerability scanning
# Run all tests
uv run pytest
# Run tests with coverage
uv run pytest --cov=src/streamwatch --cov-report=html
# Run specific test file
uv run pytest tests/test_stream_utils.py# Run all pre-commit hooks manually
uv run pre-commit run --all-files
# Run specific tools
uv run black src/ tests/
uv run isort src/ tests/
uv run flake8 src/ tests/
uv run mypy src/
uv run bandit -r src/Log files are located in the logs/ subdirectory of your config folder. These logs contain detailed debug information that can help diagnose problems.
Contributions, bug reports, and feature requests are welcome! Please see the Contributing Guidelines for more details.
StreamWatch is open-source software licensed under the MIT License. See the LICENSE file for details.
StreamWatch is built upon these excellent open-source projects:
Happy Streaming! 📺
