clippiti-player 0.1.3.post0__tar.gz

clippiti_player-0.1.3.post0/.coveragerc

@@ -0,0 +1,10 @@
+[run]
+branch = True
+omit =
+  */__init__.py
+  tests/*
+
+[report]
+omit =
+  */__init__.py
+  tests/*

clippiti_player-0.1.3.post0/.editorconfig

@@ -0,0 +1,13 @@
+# Editor configuration, see https://editorconfig.org
+root = true
+
+[*]
+charset = utf-8
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.md]
+max_line_length = off
+trim_trailing_whitespace = false

clippiti_player-0.1.3.post0/.env

@@ -0,0 +1 @@
+PYTHONPATH=src

clippiti_player-0.1.3.post0/.github/workflows/publish.yml

@@ -0,0 +1,63 @@
+name: Publish Python package
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch: {}
+
+jobs:
+  publish-testpypi:
+    name: Publish to TestPyPI
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.12'
+
+      - name: Install build dependencies
+        run: |
+          python -m pip install --upgrade pip build
+
+      - name: Build distributions
+        run: |
+          rm -rf build dist *.egg-info || true
+          python -m build
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: publish-testpypi
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.12'
+
+      - name: Install build dependencies
+        run: |
+          python -m pip install --upgrade pip build
+
+      - name: Build distributions
+        run: |
+          rm -rf build dist *.egg-info || true
+          python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

clippiti_player-0.1.3.post0/.gitignore

@@ -0,0 +1,46 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Distribution / packaging
+*.whl
+*.tar.gz
+MANIFEST
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Type checkers / linters
+.mypy_cache/
+.ruff_cache/
+
+# Editors
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Runtime / generated
+/tmp/clippiti/
+*.stderr.log
+
+# OS
+.DS_Store
+Thumbs.db

clippiti_player-0.1.3.post0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tarzasai
+
+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.

clippiti_player-0.1.3.post0/MANIFEST.in

@@ -0,0 +1,12 @@
+# Include icons and resources in the package distribution
+recursive-include src/clippiti/resources *.png *.svg *.ico *.jpg *.jpeg
+
+# Include documentation
+include README.md
+include LICENSE
+include requirements.txt
+
+# Exclude unnecessary files
+global-exclude __pycache__
+global-exclude *.py[cod]
+global-exclude .DS_Store

clippiti_player-0.1.3.post0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: clippiti-player
+Version: 0.1.3.post0
+Summary: Single-stream live player with rolling buffer, clipping, and recording
+License-Expression: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: python-mpv>=1.0.7
+Requires-Dist: PyQt6>=6.6.0
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: streamlink>=6.0
+Dynamic: license-file
+
+# Clippiti
+*Single-stream live player with rolling buffer, clipping, and recording.*
+
+Clippiti is a PyQt6 desktop app that opens a live stream through Streamlink, keeps a rolling local buffer, and lets you export clips or recordings without leaving the player.
+
+## Features
+
+- Live stream playback via Streamlink + mpv
+- Rolling HLS buffer pipeline (Streamlink -> ffmpeg)
+- Clip export from buffered timeline
+- Recording with optional auto-remux to MP4
+- Floating controls, keyboard shortcuts, and OSD feedback
+- YAML config with runtime-editable settings dialog
+- CLI overrides for Streamlink and mpv options
+
+Supported OS: Linux, Windows, macOS
+
+## Requirements
+
+- Python 3.12+
+- `streamlink` installed and available in `PATH`
+- `ffmpeg` installed and available in `PATH` (or configured path)
+- Desktop environment that supports PyQt6 apps
+
+## Install
+
+From source (recommended for now):
+
+```bash
+git clone <your-repo-url>
+cd clippiti
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+pip install -e .
+```
+
+Run:
+
+```bash
+clippiti <url> <quality>
+```
+
+Alternative without editable install:
+
+```bash
+PYTHONPATH=src ./.venv/bin/python -m clippiti <url> <quality>
+```
+
+## Command-line options
+
+```text
+positional:
+  url                      Stream URL to open
+  quality                  Desired stream quality
+
+optional:
+  --sl TEXT                Pass-through Streamlink arguments string
+  --mpv TEXT               Additional mpv options (YAML or key=value)
+  --config PATH            Path to config YAML file
+  --workdir PATH           Path to runtime working directory
+  --verbose                Enable verbose startup logs
+```
+
+Example:
+
+```bash
+clippiti https://www.twitch.tv/example_channel best --sl "--retry-max 5" --mpv "vf=hflip"
+```
+
+## Configuration
+
+Clippiti stores configuration in YAML.
+
+Resolution order:
+
+1. `--config <path>` if provided
+2. User config location (`clippiti.yaml`) if it exists
+3. `<workdir>/config.yaml` if it exists
+4. Fallback to `<workdir>/config.yaml` (or `./clippiti.yaml` if no workdir)
+
+User config location (`clippiti.yaml`) is typically:
+
+- Linux: `~/.config/clippiti.yaml`
+- Windows: `%APPDATA%\clippiti.yaml`
+- macOS: `~/Library/Application Support/clippiti.yaml`
+
+Default workdir is:
+
+- `/tmp/clippiti`
+
+## Development
+
+Install dev/test deps (already included in `requirements.txt`):
+
+```bash
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+Run tests:
+
+```bash
+PYTHONPATH=src ./.venv/bin/python -m pytest -q
+```
+
+## Documentation
+
+- [Technical documentation index](doc/README.md)
+
+## Troubleshooting
+
+- Stream metadata probe fails:
+  - Verify URL is online/public
+  - Verify `streamlink` is installed and runnable
+- Playback pipeline does not start:
+  - Verify `ffmpeg` is installed and reachable
+  - Use `--verbose` to inspect startup logs
+- mpv/video issues:
+  - Verify `python-mpv` is installed
+  - Try with simpler `--mpv` options first
+
+## License
+
+MIT License - see `LICENSE` if present in this repository.
+
+## Acknowledgments
+
+- Streamlink
+- ffmpeg
+- PyQt6
+- python-mpv
+
+## Screenshots
+
+![Main Window](https://raw.githubusercontent.com/tarzasai/Clippiti/main/doc/media/main-window.png)
+![Clip Dialog](https://raw.githubusercontent.com/tarzasai/Clippiti/main/doc/media/clip-dialog.png)
+![Settings Dialog](https://raw.githubusercontent.com/tarzasai/Clippiti/main/doc/media/settings-dialog.png)

clippiti_player-0.1.3.post0/README.md

@@ -0,0 +1,138 @@
+# Clippiti
+*Single-stream live player with rolling buffer, clipping, and recording.*
+
+Clippiti is a PyQt6 desktop app that opens a live stream through Streamlink, keeps a rolling local buffer, and lets you export clips or recordings without leaving the player.
+
+## Features
+
+- Live stream playback via Streamlink + mpv
+- Rolling HLS buffer pipeline (Streamlink -> ffmpeg)
+- Clip export from buffered timeline
+- Recording with optional auto-remux to MP4
+- Floating controls, keyboard shortcuts, and OSD feedback
+- YAML config with runtime-editable settings dialog
+- CLI overrides for Streamlink and mpv options
+
+Supported OS: Linux, Windows, macOS
+
+## Requirements
+
+- Python 3.12+
+- `streamlink` installed and available in `PATH`
+- `ffmpeg` installed and available in `PATH` (or configured path)
+- Desktop environment that supports PyQt6 apps
+
+## Install
+
+From source (recommended for now):
+
+```bash
+git clone <your-repo-url>
+cd clippiti
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+pip install -e .
+```
+
+Run:
+
+```bash
+clippiti <url> <quality>
+```
+
+Alternative without editable install:
+
+```bash
+PYTHONPATH=src ./.venv/bin/python -m clippiti <url> <quality>
+```
+
+## Command-line options
+
+```text
+positional:
+  url                      Stream URL to open
+  quality                  Desired stream quality
+
+optional:
+  --sl TEXT                Pass-through Streamlink arguments string
+  --mpv TEXT               Additional mpv options (YAML or key=value)
+  --config PATH            Path to config YAML file
+  --workdir PATH           Path to runtime working directory
+  --verbose                Enable verbose startup logs
+```
+
+Example:
+
+```bash
+clippiti https://www.twitch.tv/example_channel best --sl "--retry-max 5" --mpv "vf=hflip"
+```
+
+## Configuration
+
+Clippiti stores configuration in YAML.
+
+Resolution order:
+
+1. `--config <path>` if provided
+2. User config location (`clippiti.yaml`) if it exists
+3. `<workdir>/config.yaml` if it exists
+4. Fallback to `<workdir>/config.yaml` (or `./clippiti.yaml` if no workdir)
+
+User config location (`clippiti.yaml`) is typically:
+
+- Linux: `~/.config/clippiti.yaml`
+- Windows: `%APPDATA%\clippiti.yaml`
+- macOS: `~/Library/Application Support/clippiti.yaml`
+
+Default workdir is:
+
+- `/tmp/clippiti`
+
+## Development
+
+Install dev/test deps (already included in `requirements.txt`):
+
+```bash
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+Run tests:
+
+```bash
+PYTHONPATH=src ./.venv/bin/python -m pytest -q
+```
+
+## Documentation
+
+- [Technical documentation index](doc/README.md)
+
+## Troubleshooting
+
+- Stream metadata probe fails:
+  - Verify URL is online/public
+  - Verify `streamlink` is installed and runnable
+- Playback pipeline does not start:
+  - Verify `ffmpeg` is installed and reachable
+  - Use `--verbose` to inspect startup logs
+- mpv/video issues:
+  - Verify `python-mpv` is installed
+  - Try with simpler `--mpv` options first
+
+## License
+
+MIT License - see `LICENSE` if present in this repository.
+
+## Acknowledgments
+
+- Streamlink
+- ffmpeg
+- PyQt6
+- python-mpv
+
+## Screenshots
+
+![Main Window](https://raw.githubusercontent.com/tarzasai/Clippiti/main/doc/media/main-window.png)
+![Clip Dialog](https://raw.githubusercontent.com/tarzasai/Clippiti/main/doc/media/clip-dialog.png)
+![Settings Dialog](https://raw.githubusercontent.com/tarzasai/Clippiti/main/doc/media/settings-dialog.png)

clippiti_player-0.1.3.post0/bump_version.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+set -e
+
+# Get the latest tag
+LATEST_TAG=$(git tag --list 'v*' --sort=-version:refname | head -1)
+
+if [ -z "$LATEST_TAG" ]; then
+  echo "No existing version tags found. Starting with v1.0.0"
+  LATEST_TAG="v0.0.0"
+fi
+
+echo "Current version: $LATEST_TAG"
+
+# Parse version components (remove 'v' prefix)
+VERSION="${LATEST_TAG#v}"
+IFS='.' read -r MAJOR MINOR PATCH <<< "$VERSION"
+
+# Default bump type
+BUMP_TYPE="${1:-patch}"
+
+case "$BUMP_TYPE" in
+  major)
+    MAJOR=$((MAJOR + 1))
+    MINOR=0
+    PATCH=0
+    ;;
+  minor)
+    MINOR=$((MINOR + 1))
+    PATCH=0
+    ;;
+  patch)
+    PATCH=$((PATCH + 1))
+    ;;
+  *)
+    echo "Usage: $0 [major|minor|patch]"
+    echo "  major: bump major version (X.0.0)"
+    echo "  minor: bump minor version (x.Y.0)"
+    echo "  patch: bump patch version (x.y.Z) [default]"
+    exit 1
+    ;;
+esac
+
+NEW_VERSION="v${MAJOR}.${MINOR}.${PATCH}"
+
+echo "New version: $NEW_VERSION"
+echo ""
+read -p "Create tag $NEW_VERSION? [y/N] " -n 1 -r
+echo
+
+if [[ $REPLY =~ ^[Yy]$ ]]; then
+  # Check if there are uncommitted changes
+  if ! git diff-index --quiet HEAD --; then
+    echo "Warning: You have uncommitted changes. Please commit them first."
+    exit 1
+  fi
+
+  # Create annotated tag
+  git tag -a "$NEW_VERSION" -m "Release $NEW_VERSION"
+  echo "✓ Created tag $NEW_VERSION"
+
+  # Push the tag to remote
+  echo "Pushing tag to remote..."
+  git push origin "$NEW_VERSION"
+  echo "✓ Pushed tag $NEW_VERSION to remote"
+else
+  echo "Cancelled."
+  exit 1
+fi

clippiti_player-0.1.3.post0/doc/README.md

@@ -0,0 +1,17 @@
+# Clippiti Documentation
+
+This folder contains the technical documentation for the current Clippiti architecture and runtime behavior.
+
+## Documents
+
+- [Architecture Overview](architecture-overview.md)
+- [Runtime Workflows](runtime-workflows.md)
+- [Module Reference](module-reference.md)
+- [Configuration and CLI](configuration-and-cli.md)
+- [Operations and Troubleshooting](operations-and-troubleshooting.md)
+
+## Scope
+
+These documents describe the current app behavior and code layout under `src/clippiti`.
+
+Examples use neutral stream URLs or Twitch/YouTube only.

clippiti_player-0.1.3.post0/doc/architecture-overview.md

@@ -0,0 +1,60 @@
+# Architecture Overview
+
+Clippiti is a desktop application built with PyQt6 and python-mpv.
+It uses Streamlink and ffmpeg to build a local rolling HLS buffer, then plays the local playlist through mpv.
+
+## High-Level Structure
+
+```mermaid
+flowchart TD
+    U[User] --> UI[PyQt UI]
+    UI --> APP[App Controller]
+    APP --> BE[Buffer Engine]
+    APP --> CLIP[Clip Service]
+    APP --> REC[Recording Service]
+    APP --> RQ[Remux Queue]
+
+    BE --> SL[Streamlink]
+    SL --> FF[ffmpeg]
+    FF --> HLS[/local live.m3u8 + segments/]
+    HLS --> MPV[mpv via python-mpv]
+
+    CLIP --> HLS
+    CLIP --> FF
+    REC --> HLS
+    REC --> FF
+    RQ --> FF
+```
+
+## C4-Style Container View
+
+```mermaid
+C4Context
+    title Clippiti Container Diagram
+    Person(user, "User", "Watches, clips, records live streams")
+    System(clippiti, "Clippiti Desktop App", "PyQt6 application")
+    System_Ext(streamlink, "Streamlink", "Resolves and fetches stream data")
+    System_Ext(ffmpeg, "ffmpeg", "Builds HLS buffer and handles remux/export")
+    System_Ext(mpv, "mpv", "Playback engine via python-mpv")
+
+    Rel(user, clippiti, "Uses")
+    Rel(clippiti, streamlink, "Requests metadata + stream bytes")
+    Rel(clippiti, ffmpeg, "Runs for buffering/recording/clipping")
+    Rel(clippiti, mpv, "Controls playback")
+
+    UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")
+```
+
+## Key Design Choices
+
+- Startup is asynchronous so the window can open while pipeline initialization is in progress.
+- The stream processing path is explicit: Streamlink stdout -> ffmpeg HLS output -> local playlist.
+- Clipping and recording are service-driven and isolated from UI widgets.
+- Post-processing (remux/export) uses a queue service to avoid overlapping ffmpeg process control.
+
+## Core Runtime Artifacts
+
+- Session directory: `<workdir>/sessions/<session_id>/`
+- Live playlist: `<session_dir>/live.m3u8`
+- HLS segments: `<session_dir>/seg_*.ts`
+- Optional stderr logs per process when debug logging is enabled.

clippiti_player-0.1.3.post0/doc/configuration-and-cli.md

@@ -0,0 +1,55 @@
+# Configuration and CLI
+
+## CLI Interface
+
+`clippiti <url> <quality> [options]`
+
+Options:
+
+- `--sl`: additional Streamlink arguments
+- `--mpv`: additional mpv options (YAML mapping or key=value pairs)
+- `--config`: explicit config file path
+- `--workdir`: explicit runtime workdir path
+- `--verbose`: debug logging
+
+Example (Twitch):
+
+```bash
+clippiti https://www.twitch.tv/example_channel best --sl "--retry-max 5" --mpv "vf=hflip"
+```
+
+Example (YouTube):
+
+```bash
+clippiti https://www.youtube.com/watch?v=dQw4w9WgXcQ best
+```
+
+## Config Resolution Order
+
+1. `--config <path>`
+2. user config location (`clippiti.yaml`) if it already exists
+3. `<workdir>/config.yaml` if it already exists
+4. fallback to `<workdir>/config.yaml` (or `./clippiti.yaml` when no workdir)
+
+Typical user config locations:
+
+- Linux: `~/.config/clippiti.yaml`
+- Windows: `%APPDATA%\clippiti.yaml`
+- macOS: `~/Library/Application Support/clippiti.yaml`
+
+Default workdir:
+
+- `/tmp/clippiti`
+
+## Main Config Sections
+
+- `general`
+  - `ffmpeg_path`, `segment_seconds`, `window_segments`, `controls_area`, `controls_resize_debounce_ms`, `mpv_options`
+- `streamlink`
+  - `default_args`
+- `clip`
+  - `dir`, `default_duration`
+- `recording`
+  - `dir`, `filename_format`, `auto_remux_to_mp4`
+- `snapshot`
+  - `dir`, `filename_format`