Menu

Tree [e421fe] main 0.3.0 /
 History

HTTPS access


File Date Author Commit
 .github 2025-05-13 Johny Snow Johny Snow [89f7d4] Create FUNDING.yml
 assets 2025-06-25 snowballons snowballons [616877] assets and readme update
 docs 2025-06-24 snowballons snowballons [fb9faf] Fixes: README.md update
 streamwatch 2025-06-24 snowballons snowballons [0ae706] streamwatch v.0.3.0
 .gitignore 2025-05-12 Johny Snow Johny Snow [aed35c] Initial commit
 LICENSE 2025-05-12 Johny Snow Johny Snow [aed35c] Initial commit
 README.md 2025-06-25 snowballons snowballons [616877] assets and readme update
 activate_dev.sh 2025-06-24 snowballons snowballons [0ae706] streamwatch v.0.3.0
 requirements-frozen.txt 2025-06-24 snowballons snowballons [0ae706] streamwatch v.0.3.0
 requirements.txt 2025-06-24 snowballons snowballons [0ae706] streamwatch v.0.3.0
 setup.py 2025-06-25 snowballons snowballons [e421fe] Release StreamWatch v0.3.0

Read Me

StreamWatch: Your Lightweight CLI Live Stream Companion

PyPI version
Python Versions
License: MIT
GitHub stars

StreamWatch Logo

StreamWatch is a fast, efficient, and distraction-free command-line tool for managing and watching your favorite live streams—no browser required!

StreamWatch CLI in action


Table of Contents


Why StreamWatch?

  • 🚀 Lightweight & Fast: No more resource-hungry browsers.
  • 🎯 Focus-Friendly: No ads, popups, or web clutter.
  • 💡 Efficient Workflow: Check all your favorites and launch streams from a single interface.
  • ⚙️ Customizable: Tweak quality, performance, and more.
  • 📺 Broad Platform Support: Works with any site supported by Streamlink.
  • 🖥️ Cross-Platform: Windows, macOS, and Linux.

Key Features

  • Live Status Display: See who's live, with username, platform, and category/game.
  • Interactive Navigation: Use arrow keys, numbers, or search to select streams.
  • Direct Playback: Launches streams in your media player (MPV recommended) via Streamlink.
  • Playback Controls: Stop, next/previous, change quality, return to menu, or donate—all from the terminal.
  • Stream Management: Add, remove, and list your favorite streams.
  • Persistent Configuration: User-editable streams.json and config.ini.
  • Automatic Reconnection: Tries to reconnect if a stream drops.
  • Quick Access: Instantly replay the last stream you watched.
  • Colorful Interface: Uses rich for a beautiful terminal experience.
  • Detailed Logging: For troubleshooting and support.

Supported Platforms

StreamWatch uses Streamlink under the hood, so it supports any platform Streamlink does. Enhanced display features are available for:

  • YouTube, Twitch, Kick, TikTok, BiliBili, Douyin, Huya, Vimeo, Dailymotion, PlutoTV
  • Major European broadcasters (BBC iPlayer, ARD/ZDF Mediathek, RaiPlay, RTVE Play, Atresplayer, Mitele)
  • AbemaTV, Adult Swim, Bloomberg, Bigo Live, and more!

If your platform isn't listed, StreamWatch will still try to display what it can, and playback will work if Streamlink supports the URL.


Prerequisites

  • Python 3.7+ (Download)
  • Streamlink (installed automatically with pip)
  • MPV Media Player (Download) — recommended for best results

Installation

pip install streamwatch

This will install StreamWatch and all dependencies, including Streamlink.

From Source (for Development)

git clone https://github.com/snowballons/streamwatch-cli.git
cd streamwatch-cli
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

Run StreamWatch from source:

streamwatch

Getting Started

First Run

  • On first launch, StreamWatch creates a config directory, a default config.ini, and an empty streams.json.
  • You'll see a welcome message with instructions.

StreamWatch First Run Experience

Adding Streams

  • From the main menu, press A (Add).
  • Enter one or more stream URLs (comma-separated for multiple).
  • Example:
    https://twitch.tv/streamer1, https://youtube.com/@channel2, https://kick.com/user3
  • Your streams are saved to streams.json.

Usage Guide

  • [Enter]: Select a live stream interactively.
  • [Number]: Play a stream by its number.
  • [L]: List all configured streams.
  • [A]: Add new streams.
  • [R]: Remove streams.
  • [P]: Play last watched stream (if available).
  • [F]: Refresh live stream list.
  • [Q]: Quit StreamWatch.

Playing a Stream

  • Select a stream and StreamWatch launches it in your media player via Streamlink.

Playback Controls

  • [S]: Stop stream
  • [N]: Next live stream
  • [P]: Previous live stream
  • [C]: Change quality
  • [M]: Main menu
  • [D]: Donate to developer
  • [Q]: Quit StreamWatch

If the stream ends or you close the player, StreamWatch returns you to the menu. If a stream drops, it will try to reconnect for about 30 seconds.


Configuration

StreamWatch uses two main files:

Stream List (streams.json)

  • Stores your stream URLs.
  • Location:
  • Linux/macOS: ~/.config/streamwatch/streams.json
  • Windows: %APPDATA%\\StreamWatch\\streams.json
  • Manage via the [A] (Add) and [R] (Remove) options.

Settings (config.ini)

  • Created on first run, editable with any text editor.
  • Location: Same as streams.json.

Example:

[Streamlink]
quality = best
timeout_liveness = 10
timeout_metadata = 15
max_workers_liveness = 4
max_workers_metadata = 2
twitch_disable_ads = true

[Misc]
donation_link = https://buymeacoffee.com/snowballons
first_run_completed = true
last_played_url =

Logging

  • Log file for troubleshooting:
  • Linux/macOS: ~/.config/streamwatch/logs/streamwatch.log
  • Windows: %APPDATA%\\StreamWatch\\logs\\streamwatch.log
  • Includes INFO, WARNING, ERROR, and DEBUG messages.
  • Log files are rotated automatically.

Contributing

Contributions, bug reports, and feature requests are welcome!

  • Check Issues: Search existing issues before submitting.
  • Open an Issue: For bugs or ideas, include steps to reproduce, version, OS, and logs if possible.
  • Pull Requests: Fork, branch, commit, and submit with a clear description.

License

StreamWatch is open-source software licensed under the MIT License. See the LICENSE file for details.


Acknowledgements


Happy Streaming! 📺

Want the latest updates on software, tech news, and AI?
Get latest updates about software, tech news, and AI from SourceForge directly in your inbox once a month.