| Name | streamwatch JSON |
| Version |
0.4.0
JSON |
| download |
| home_page | None |
| Summary | A CLI tool to manage, check status, and play favorite live streams. |
| upload_time | 2025-08-16 23:02:39 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8.1 |
| license | MIT License
Copyright (c) 2025 Johny Snow
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE. |
| keywords |
cli
interactive
live
manager
player
stream
streamlink
twitch
youtube
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# StreamWatch: Your Lightweight CLI Live Stream Companion
[](https://pypi.org/project/streamwatch/)
[](https://pypi.org/project/streamwatch/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/snowballons/streamwatch-cli)
<p align="center">
<img src="assets/Images/logoign.png" alt="StreamWatch Logo" width="150"/>
</p>
**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.
<p align="center">
<img src="assets/Images/streamwatch-cli.gif" alt="StreamWatch CLI in action" width="700"/>
<br/>
<em>(Demo showcasing StreamWatch's interactive menu and playback)</em>
</p>
---
## Table of Contents
* [Why Use StreamWatch?](#why-use-streamwatch)
* [Key Features](#key-features)
* [Architecture & Recent Improvements](#architecture--recent-improvements)
* [Supported Platforms](#supported-platforms)
* [Prerequisites](#prerequisites)
* [Installation](#installation)
* [Getting Started](#getting-started)
* [Usage](#usage)
* [Main Menu](#main-menu)
* [Playback Controls](#playback-controls)
* [Advanced Configuration](#advanced-configuration)
* [Stream Aliases](#stream-aliases)
* [Using a `streams.d` Directory](#using-a-streamsd-directory)
* [Importing & Exporting](#importing--exporting)
* [Playback Hooks](#playback-hooks)
* [Configuration File](#configuration-file)
* [Development Setup](#development-setup)
* [Troubleshooting](#troubleshooting)
* [Contributing](#contributing)
* [License](#license)
* [Acknowledgements](#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.d` directory 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.ini` for settings and `streams.json` for 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](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:
* 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](https://mpv.io/)) - **Highly recommended**
---
## Installation
Install StreamWatch using `pip`:
```bash
pip install streamwatch
```
<details>
<summary><b>Alternative: Installation from Source</b></summary>
```bash
# 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
```
</details>
---
## Getting Started
1. **Run StreamWatch for the first time:**
```bash
streamwatch
```
This will create the configuration directory and files.
2. **Add streams:**
- Press `A` in 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.
3. **Refresh and watch:**
- Press `F` to refresh the stream list and see who's live.
- Select a stream to start watching.
---
## 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. |
| `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 `.txt` file (one URL per line).
- **Export (`E`):** Create a backup of your current stream list (including aliases) to a `.json` file.
### Playback Hooks
Automate your environment by running custom scripts before and after a stream plays.
1. Create an executable script (e.g., `start_stream.sh`, `end_stream.bat`).
2. Set the full path to your script in `config.ini` under `pre_playback_hook` or `post_playback_hook`.
StreamWatch passes the following arguments to your script: `url`, `alias`, `username`, `platform`, `quality`.
**Example `hook.sh`:**
```bash
#!/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:
### Prerequisites for Development
- **Python 3.8+**
- **uv** (recommended) or **pip**
- **Git**
### Setting Up the Development Environment
1. **Clone the repository:**
```bash
git clone https://github.com/snowballons/streamwatch-cli.git
cd streamwatch-cli
```
2. **Install dependencies using uv (recommended):**
```bash
# Install all dependencies including development tools
uv sync --dev
# Or using the dependency groups
uv sync --group dev
```
**Alternative with pip:**
```bash
# 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]"
```
3. **Set up pre-commit hooks:**
```bash
# Using uv
uv run pre-commit install
# Or with pip
pre-commit install
```
4. **Run the development version:**
```bash
# Using uv
uv run streamwatch
# Or with pip (after activating venv)
streamwatch
```
### Development Tools
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
### Running Tests
```bash
# 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
```
### Code Quality Checks
```bash
# 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/
```
---
## Troubleshooting
Log files are located in the `logs/` subdirectory of your config folder. These logs contain detailed debug information that can help diagnose problems.
---
## Contributing
Contributions, bug reports, and feature requests are welcome! Please see the [Contributing Guidelines](CONTRIBUTING.md) for more details.
---
## License
StreamWatch is open-source software licensed under the MIT License. See the `LICENSE` file for details.
---
## Acknowledgements
StreamWatch is built upon these excellent open-source projects:
- [Streamlink](https://streamlink.github.io/)
- [Rich](https://github.com/Textualize/rich)
- [Python Prompt Toolkit](https://github.com/prompt-toolkit/python-prompt-toolkit)
Happy Streaming! 📺
Raw data
{
"_id": null,
"home_page": null,
"name": "streamwatch",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8.1",
"maintainer_email": null,
"keywords": "cli, interactive, live, manager, player, stream, streamlink, twitch, youtube",
"author": null,
"author_email": "Johny Snow <snowballons@protonmail.com>",
"download_url": "https://files.pythonhosted.org/packages/81/19/9844d1f8551de95c0fb8973484af0ea57a72243dd9956a03fb4c07288ad3/streamwatch-0.4.0.tar.gz",
"platform": null,
"description": "# StreamWatch: Your Lightweight CLI Live Stream Companion\n\n[](https://pypi.org/project/streamwatch/)\n[](https://pypi.org/project/streamwatch/)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/snowballons/streamwatch-cli)\n\n<p align=\"center\">\n <img src=\"assets/Images/logoign.png\" alt=\"StreamWatch Logo\" width=\"150\"/>\n</p>\n\n**StreamWatch** is a modern, fast, and powerful command-line tool for managing and watching your favorite live streams\u2014all 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<p align=\"center\">\n <img src=\"assets/Images/streamwatch-cli.gif\" alt=\"StreamWatch CLI in action\" width=\"700\"/>\n <br/>\n <em>(Demo showcasing StreamWatch's interactive menu and playback)</em>\n</p>\n\n---\n\n## Table of Contents\n\n* [Why Use StreamWatch?](#why-use-streamwatch)\n* [Key Features](#key-features)\n* [Architecture & 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 & 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 & 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- **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 & Recent Improvements\n\nStreamWatch has undergone significant architectural improvements to enhance reliability, maintainability, and performance:\n\n### \ud83c\udfd7\ufe0f **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### \ud83d\udd04 **Resilience & 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### \ud83d\udee1\ufe0f **Security & 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### \ud83e\uddea **Testing & 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### \ud83d\udcca **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### \ud83d\udd27 **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<details>\n<summary><b>Alternative: Installation from Source</b></summary>\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</details>\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| `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 & 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'\" >> ~/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! \ud83d\udcfa\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025 Johny Snow\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.",
"summary": "A CLI tool to manage, check status, and play favorite live streams.",
"version": "0.4.0",
"project_urls": {
"Documentation": "https://github.com/snowballons/streamwatch-cli#readme",
"Homepage": "https://snowballons.github.io/streamwatch-cli",
"Repository": "https://github.com/snowballons/streamwatch-cli"
},
"split_keywords": [
"cli",
" interactive",
" live",
" manager",
" player",
" stream",
" streamlink",
" twitch",
" youtube"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f635356605776df8dd774d19a8adeab562644cf2c678f6066000ec2a5c66bdb2",
"md5": "7b5001e239b7dc203bddd62f6aa0fc76",
"sha256": "278a2507070df7522a4f28f24376bd26cb34bbc5f0c1168f1371b58495270080"
},
"downloads": -1,
"filename": "streamwatch-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7b5001e239b7dc203bddd62f6aa0fc76",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8.1",
"size": 98983,
"upload_time": "2025-08-16T23:02:33",
"upload_time_iso_8601": "2025-08-16T23:02:33.071839Z",
"url": "https://files.pythonhosted.org/packages/f6/35/356605776df8dd774d19a8adeab562644cf2c678f6066000ec2a5c66bdb2/streamwatch-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "81199844d1f8551de95c0fb8973484af0ea57a72243dd9956a03fb4c07288ad3",
"md5": "430886a81c42e40f5bbffac4174d249a",
"sha256": "6c0a0527a7f7cebcb3e4678d6deb90f190530eaa5ee732e8d007d09cf554df3d"
},
"downloads": -1,
"filename": "streamwatch-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "430886a81c42e40f5bbffac4174d249a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8.1",
"size": 3068708,
"upload_time": "2025-08-16T23:02:39",
"upload_time_iso_8601": "2025-08-16T23:02:39.798959Z",
"url": "https://files.pythonhosted.org/packages/81/19/9844d1f8551de95c0fb8973484af0ea57a72243dd9956a03fb4c07288ad3/streamwatch-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-16 23:02:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "snowballons",
"github_project": "streamwatch-cli#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "streamwatch"
}
