{"id":37067440,"url":"https://github.com/snowballons/streamwatch-cli","last_synced_at":"2026-01-14T07:55:14.813Z","repository":{"id":292839353,"uuid":"982088869","full_name":"snowballons/streamwatch-cli","owner":"snowballons","description":"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.","archived":false,"fork":false,"pushed_at":"2025-08-16T23:30:35.000Z","size":14253,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-19T19:50:51.942Z","etag":null,"topics":["cli","entertainment","lightweight","livestreaming","mpv-player","opensource","python","stream-manager","streaming","streamlink","terminal"],"latest_commit_sha":null,"homepage":"https://snowballons.github.io/streamwatch-cli/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/snowballons.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"patreon":null,"open_collective":null,"ko_fi":"snowballons","tidelift":null,"community_bridge":null,"liberapay":"snowballons","issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":"snowballons","thanks_dev":"snowballons","custom":null}},"created_at":"2025-05-12T11:04:55.000Z","updated_at":"2025-08-17T10:23:44.000Z","dependencies_parsed_at":null,"dependency_job_id":"4976d16d-6d8f-4484-812a-99fce1c04591","html_url":"https://github.com/snowballons/streamwatch-cli","commit_stats":null,"previous_names":["snowballons/stream-manager-cli","snowballons/streamwatch-cli"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/snowballons/streamwatch-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snowballons%2Fstreamwatch-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snowballons%2Fstreamwatch-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snowballons%2Fstreamwatch-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snowballons%2Fstreamwatch-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/snowballons","download_url":"https://codeload.github.com/snowballons/streamwatch-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snowballons%2Fstreamwatch-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28413527,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T05:26:33.345Z","status":"ssl_error","status_checked_at":"2026-01-14T05:21:57.251Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","entertainment","lightweight","livestreaming","mpv-player","opensource","python","stream-manager","streaming","streamlink","terminal"],"created_at":"2026-01-14T07:55:14.096Z","updated_at":"2026-01-14T07:55:14.801Z","avatar_url":"https://github.com/snowballons.png","language":"Python","funding_links":["https://ko-fi.com/snowballons","https://liberapay.com/snowballons","https://buymeacoffee.com/snowballons","https://thanks.dev/snowballons"],"categories":[],"sub_categories":[],"readme":"# StreamWatch: Your Lightweight CLI Live Stream Companion\n\n[![PyPI version](https://img.shields.io/pypi/v/streamwatch.svg)](https://pypi.org/project/streamwatch/)\n[![Python Versions](https://img.shields.io/pypi/pyversions/streamwatch.svg)](https://pypi.org/project/streamwatch/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![GitHub stars](https://img.shields.io/github/stars/snowballons/streamwatch-cli.svg?style=social)](https://github.com/snowballons/streamwatch-cli)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/Images/logoign.png\" alt=\"StreamWatch Logo\" width=\"150\"/\u003e\n\u003c/p\u003e\n\n**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.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/Images/streamwatch-cli.gif\" alt=\"StreamWatch CLI in action\" width=\"700\"/\u003e\n  \u003cbr/\u003e\n  \u003cem\u003e(Demo showcasing StreamWatch's interactive menu and playback)\u003c/em\u003e\n\u003c/p\u003e\n\n---\n\n## Table of Contents\n\n*   [Why Use StreamWatch?](#why-use-streamwatch)\n*   [Key Features](#key-features)\n*   [Architecture \u0026 Recent Improvements](#architecture--recent-improvements)\n*   [Supported Platforms](#supported-platforms)\n*   [Prerequisites](#prerequisites)\n*   [Installation](#installation)\n*   [Getting Started](#getting-started)\n*   [Usage](#usage)\n    *   [Main Menu](#main-menu)\n    *   [Playback Controls](#playback-controls)\n*   [Advanced Configuration](#advanced-configuration)\n    *   [Stream Aliases](#stream-aliases)\n    *   [Using a `streams.d` Directory](#using-a-streamsd-directory)\n    *   [Importing \u0026 Exporting](#importing--exporting)\n    *   [Playback Hooks](#playback-hooks)\n*   [Configuration File](#configuration-file)\n*   [Development Setup](#development-setup)\n*   [Troubleshooting](#troubleshooting)\n*   [Contributing](#contributing)\n*   [License](#license)\n*   [Acknowledgements](#acknowledgements)\n\n---\n\n## Why Use StreamWatch?\n\n*   **Lightweight \u0026 Fast:** Consumes a fraction of the CPU and RAM compared to a browser.\n*   **Focus-Friendly:** A clean, distraction-free interface.\n*   **Efficient Workflow:** Manage and launch streams from a single, keyboard-driven interface.\n*   **Highly Customizable:** Tailor StreamWatch to your needs with custom settings and automation hooks.\n*   **Broad Platform Support:** Works with hundreds of sites out of the box, powered by Streamlink.\n*   **Cross-Platform:** A consistent experience on Windows, macOS, and Linux.\n\n---\n\n## Key Features\n\n- **Live Status Display:** See who's live with their Alias/Username, Platform, Category, and Viewer Count.\n- **Interactive Navigation:** Use arrow keys, number input, or first-letter search to quickly select streams.\n- **Playback Controls:** Replay, play next/previous, change quality, and more, all from the terminal.\n- **Stream Aliases:** Assign custom nicknames to your streams for a personalized list.\n- **Stream Management:** Add, remove, list, import, and export your stream list with ease.\n- **File-Based Management:** Use a `streams.d` directory to manage your streams with simple text files.\n- **Background Recording:** Record live streams to a file while you continue to browse or watch other streams.\n- **Automatic Reconnection:** Automatically attempts to reconnect if a stream drops.\n- **Playback Hooks:** Trigger custom scripts before and after a stream plays.\n- **Persistent Configuration:** User-editable `config.ini` for settings and `streams.json` for your interactive list.\n- **Quick Access:** Instantly replay the last stream you watched.\n- **Polished UI:** A colorful and modern terminal interface with enhanced pagination and input handling.\n- **Detailed Logging:** Comprehensive log files for easy troubleshooting.\n- **Enhanced Resilience:** Built-in retry mechanisms, circuit breaker patterns, and intelligent caching for improved reliability.\n- **Modular Architecture:** Clean separation of concerns with dedicated modules for UI, stream management, and playback control.\n\n---\n\n## Architecture \u0026 Recent Improvements\n\nStreamWatch has undergone significant architectural improvements to enhance reliability, maintainability, and performance:\n\n### 🏗️ **Modular Architecture**\n- **Separation of Concerns:** Clean division between UI components, stream management, and playback control\n- **Command Pattern:** Structured command system for better code organization and testing\n- **Dependency Injection:** Improved modularity and testability through proper dependency management\n- **Enhanced Models:** Comprehensive data models with validation using Pydantic for type safety\n\n### 🔄 **Resilience \u0026 Performance**\n- **Intelligent Caching:** Stream status caching with TTL to reduce API calls and improve response times\n- **Retry Mechanisms:** Exponential backoff retry logic for handling temporary failures\n- **Circuit Breaker Pattern:** Prevents cascading failures by temporarily disabling failing streams\n- **Rate Limiting:** Token bucket algorithm to respect platform rate limits and prevent abuse\n\n### 🛡️ **Security \u0026 Validation**\n- **Enhanced Input Validation:** Comprehensive URL and user input sanitization\n- **Security Scanning:** Integrated Bandit security vulnerability scanning in CI/CD\n- **XSS Protection:** Safe rendering of user content and stream metadata\n- **Input Sanitization:** Proper validation and cleaning of all user inputs\n\n### 🧪 **Testing \u0026 Quality Assurance**\n- **Comprehensive Test Suite:** Unit and integration tests with high coverage requirements\n- **Type Safety:** Full type hints throughout the codebase with MyPy static type checking\n- **Code Quality Tools:** Black, isort, Flake8, and MyPy integrated via pre-commit hooks\n- **Automated Testing:** CI/CD pipeline with automated quality checks and security scanning\n\n### 📊 **Enhanced User Experience**\n- **Improved Pagination:** Better handling of large stream lists with efficient navigation\n- **Enhanced Error Handling:** More informative error messages and graceful failure recovery\n- **Better Logging:** Comprehensive logging system for easier troubleshooting and debugging\n- **UI Responsiveness:** Optimized UI components for smoother interaction and better performance\n\n### 🔧 **Developer Experience**\n- **Modern Development Tools:** Integration with uv for faster dependency management\n- **Pre-commit Hooks:** Automated code quality checks before commits\n- **Development Documentation:** Comprehensive setup and contribution guidelines\n- **Consistent Coding Standards:** Enforced code formatting and style guidelines\n\nThese improvements ensure StreamWatch remains maintainable, secure, and performant while providing an excellent user experience.\n\n---\n\n## Supported Platforms\n\nStreamWatch uses **[Streamlink](https://streamlink.github.io/)**, 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:\n\n*   YouTube, Twitch, Kick, TikTok\n*   BiliBili, Douyin, Huya, Vimeo, Dailymotion\n*   PlutoTV, BBC iPlayer, ARD/ZDF Mediathek, RaiPlay, RTVE Play, Atresplayer, Mitele\n*   AbemaTV, Adult Swim, Bloomberg, Bigo Live, and more.\n\nA generic fallback is used for other platforms.\n\n---\n\n## Prerequisites\n\n- **Python 3.7+**\n- **Streamlink** (installed automatically with StreamWatch)\n- **MPV Media Player** ([Download](https://mpv.io/)) - **Highly recommended**\n\n---\n\n## Installation\n\nInstall StreamWatch using `pip`:\n\n```bash\npip install streamwatch\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eAlternative: Installation from Source\u003c/b\u003e\u003c/summary\u003e\n\n```bash\n# 1. Clone the repository\ngit clone https://github.com/snowballons/streamwatch-cli.git\ncd streamwatch-cli\n\n# 2. Create and activate a virtual environment\npython -m venv .venv\nsource .venv/bin/activate  # On Windows: .venv\\Scripts\\activate\n\n# 3. Install in editable mode\npip install -e \".[dev]\"\n\n# 4. Run StreamWatch\nstreamwatch\n```\n\u003c/details\u003e\n\n---\n\n## Getting Started\n\n1.  **Run StreamWatch for the first time:**\n    ```bash\n    streamwatch\n    ```\n    This will create the configuration directory and files.\n\n2.  **Add streams:**\n    - Press `A` in the main menu to add a stream.\n    - Enter a stream URL. To add a custom alias, type it after the URL (e.g., `https://twitch.tv/shroud The FPS King`).\n    - To add multiple streams, separate them with commas.\n\n3.  **Refresh and watch:**\n    - Press `F` to refresh the stream list and see who's live.\n    - Select a stream to start watching.\n\n---\n\n## Usage\n\n### Main Menu\n\n| Key(s) | Action                                       |\n|--------|----------------------------------------------|\n| `Enter`  | Open interactive selection for live streams. |\n| `[Number]` | Play a live stream directly by its number.   |\n| `L`      | List all configured streams.                 |\n| `A`      | Add new streams (with optional aliases).     |\n| `R`      | Remove streams from your list.               |\n| `I`      | Import streams from a `.txt` file.           |\n| `E`      | Export your stream list to a `.json` file.   |\n    | `V`      | Open Recording Controls menu.                |\n| `P`      | Play the last stream you watched.            |\n| `F`      | Force a refresh of the live stream list.     |\n| `Q`      | Quit StreamWatch.                            |\n\n### Playback Controls\n\n| Key(s) | Action                                         |\n|--------|------------------------------------------------|\n| `S`      | Replay the current stream.                     |\n| `N`      | Play the next live stream in the list.         |\n| `P`      | Play the previous live stream in the list.     |\n| `C`      | Change quality on the fly.                     |\n| `M`      | Stop stream and return to the main menu.       |\n| `D`      | Open the developer donation link in your browser.|\n| `Q`      | Stop stream and quit StreamWatch.              |\n\n---\n\n## Advanced Configuration\n\n### Stream Aliases\n\nAssign custom names to your streams for easier identification. When adding a stream, type the alias after the URL:\n\n```\nURL(s) [and optional alias(es)]: https://www.youtube.com/channel/UC-lHJZR3Gqxm24_Vd_AJ5Yw Linus Tech Tips\n```\n\n### Using a `streams.d` Directory\n\nFor 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.\n\nStreamWatch will load all streams from `streams.json` and any files in `streams.d` at startup.\n\n**Note:** The `A` (Add) and `R` (Remove) commands only affect `streams.json`. To manage streams in `streams.d`, you must edit the files directly.\n\n### Importing \u0026 Exporting\n\n- **Import (`I`):** Bulk-add streams from any `.txt` file (one URL per line).\n- **Export (`E`):** Create a backup of your current stream list (including aliases) to a `.json` file.\n\n### Playback Hooks\n\nAutomate your environment by running custom scripts before and after a stream plays.\n\n1.  Create an executable script (e.g., `start_stream.sh`, `end_stream.bat`).\n2.  Set the full path to your script in `config.ini` under `pre_playback_hook` or `post_playback_hook`.\n\nStreamWatch passes the following arguments to your script: `url`, `alias`, `username`, `platform`, `quality`.\n\n**Example `hook.sh`:**\n\n```bash\n#!/bin/bash\nTIMESTAMP=$(date \"+%Y-%m-%d %H:%M:%S\")\necho \"[$TIMESTAMP] Event for alias '$2' on platform '$4' with quality '$5'\" \u003e\u003e ~/stream_events.log\n```\n\n---\n\n## Configuration File\n\nYour settings and stream lists are stored in your user configuration directory:\n\n- **Linux/macOS:** `~/.config/streamwatch/`\n- **Windows:** `%APPDATA%\\\\StreamWatch\\\\`\n\nThe `config.ini` file is created on the first run and can be edited to customize StreamWatch's behavior.\n\n---\n\n## Development Setup\n\nIf you want to contribute to StreamWatch or run it from source, follow these steps:\n\n### Prerequisites for Development\n\n- **Python 3.8+**\n- **uv** (recommended) or **pip**\n- **Git**\n\n### Setting Up the Development Environment\n\n1. **Clone the repository:**\n   ```bash\n   git clone https://github.com/snowballons/streamwatch-cli.git\n   cd streamwatch-cli\n   ```\n\n2. **Install dependencies using uv (recommended):**\n   ```bash\n   # Install all dependencies including development tools\n   uv sync --dev\n\n   # Or using the dependency groups\n   uv sync --group dev\n   ```\n\n   **Alternative with pip:**\n   ```bash\n   # Create and activate virtual environment\n   python -m venv .venv\n   source .venv/bin/activate  # On Windows: .venv\\Scripts\\activate\n\n   # Install in editable mode with dev dependencies\n   pip install -e \".[dev]\"\n   ```\n\n3. **Set up pre-commit hooks:**\n   ```bash\n   # Using uv\n   uv run pre-commit install\n\n   # Or with pip\n   pre-commit install\n   ```\n\n4. **Run the development version:**\n   ```bash\n   # Using uv\n   uv run streamwatch\n\n   # Or with pip (after activating venv)\n   streamwatch\n   ```\n\n### Development Tools\n\nThe project includes several development tools configured via pre-commit hooks:\n\n- **Black**: Code formatting\n- **isort**: Import sorting\n- **Flake8**: Linting and style checking\n- **MyPy**: Static type checking\n- **Bandit**: Security vulnerability scanning\n\n### Running Tests\n\n```bash\n# Run all tests\nuv run pytest\n\n# Run tests with coverage\nuv run pytest --cov=src/streamwatch --cov-report=html\n\n# Run specific test file\nuv run pytest tests/test_stream_utils.py\n```\n\n### Code Quality Checks\n\n```bash\n# Run all pre-commit hooks manually\nuv run pre-commit run --all-files\n\n# Run specific tools\nuv run black src/ tests/\nuv run isort src/ tests/\nuv run flake8 src/ tests/\nuv run mypy src/\nuv run bandit -r src/\n```\n\n---\n\n## Troubleshooting\n\nLog files are located in the `logs/` subdirectory of your config folder. These logs contain detailed debug information that can help diagnose problems.\n\n---\n\n## Contributing\n\nContributions, bug reports, and feature requests are welcome! Please see the [Contributing Guidelines](CONTRIBUTING.md) for more details.\n\n---\n\n## License\n\nStreamWatch is open-source software licensed under the MIT License. See the `LICENSE` file for details.\n\n---\n\n## Acknowledgements\n\nStreamWatch is built upon these excellent open-source projects:\n\n- [Streamlink](https://streamlink.github.io/)\n- [Rich](https://github.com/Textualize/rich)\n- [Python Prompt Toolkit](https://github.com/prompt-toolkit/python-prompt-toolkit)\n\nHappy Streaming! 📺\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsnowballons%2Fstreamwatch-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsnowballons%2Fstreamwatch-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsnowballons%2Fstreamwatch-cli/lists"}