clippiti-player 0.1.9

Single-stream live player with rolling buffer, clipping, and recording

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+
• Desktop environment that supports PyQt6 apps

Non-Python dependencies

Clippiti requires these external tools at runtime:

• mpv / libmpv (used by python-mpv for playback)
• ffmpeg

streamlink is installed from Python packaging (clippiti-player dependency), so you do not need to install a system streamlink package.

Install them with your OS package manager.

Linux:

# Ubuntu / Debian
sudo apt install mpv libmpv2 ffmpeg

# Fedora
sudo dnf install mpv mpv-libs ffmpeg

# Arch Linux
sudo pacman -S mpv ffmpeg

macOS:

brew install mpv ffmpeg

Windows (PowerShell, using Scoop):

scoop install mpv ffmpeg

Verify they are available in PATH:

mpv --version
ffmpeg -version

Verify Python-installed Streamlink version from the same environment used to run Clippiti:

python -m streamlink --version

Install

From PyPI (recommended):

pip install clippiti-player

or with pipx:

pipx install clippiti-player

Run:

clippiti <url> <quality>

Install from source (development)

git clone <your-repo-url>
cd clippiti
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -e .

Alternative without editable install:

PYTHONPATH=src ./.venv/bin/python -m clippiti <url> <quality>

Command-line options

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:

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):

source .venv/bin/activate
pip install -r requirements.txt

Run tests:

PYTHONPATH=src ./.venv/bin/python -m pytest -q

Documentation

• Technical documentation index

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