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
- Supported Platforms
- Prerequisites
- Installation
- Getting Started
- Usage
- Advanced Configuration
- Configuration File
- 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: Stop, 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. - 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.
- Detailed Logging: Comprehensive log files for easy troubleshooting.
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. |
P |
Play the last stream you watched. |
F |
Force a refresh of the live stream list. |
Q |
Quit StreamWatch. |
| Key(s) | Action |
|---|---|
S |
Stop 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.
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. (TODO: Create CONTRIBUTING.md)
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! 📺
