# Building & running SageTube

## Requirements

- Python >= 3.10
- **libmpv** (system library; `python-mpv` binds to it at runtime)
  - Arch: `sudo pacman -S mpv`
  - Debian/Ubuntu: `sudo apt install libmpv2`
  - Fedora: `sudo dnf install mpv-libs`
  - macOS: `brew install mpv`
  - Windows: place `libmpv-2.dll` next to the executable (builds from
    https://github.com/shinchiro/mpv-winbuild-cmake/releases), or install mpv
    and add it to PATH
- ffmpeg (for download merging; the app can auto-install it)

Without libmpv the app still runs — the Watch tab shows an install hint and
search/browse/download work normally.

## Run from source

```bash
python -m venv .venv && source .venv/bin/activate
pip install -e .
sagetube
```

On first start the app downloads its own SHA256-verified `yt-dlp` binary and
the Deno runtime (yt-dlp's JS challenge solver) into the SageTube data dir:

- Linux: `~/.local/share/SageTube/bin/`
- macOS: `~/Library/Application Support/SageTube/bin/`
- Windows: `%LOCALAPPDATA%\SageTube\bin\`

## Notes on YouTube playback reliability

Playback resolves streams through mpv's `ytdl_hook` using the managed yt-dlp.
YouTube's CDN intermittently serves stalled streams to non-browser clients;
the player retries automatically (twice, after 25 s of no playback). Keeping
yt-dlp updated (built-in updater, stable or nightly channel) is the long-term
fix channel for extractor breakage.

## Release workflows

The `.github/workflows/` files are inherited from upstream YTSage and target
GitHub runners; they do not run on Gitea. If you set up Gitea Actions, note
that the upstream Linux/Windows workflows download appimagetool and a bundled
ffmpeg **without checksum verification** — add hash checks before reusing
them for release artifacts.