Files

T

Jaroslav Beneš b4ff618d41 Add fork documentation and rewrite README

- README: watch-first feature overview, install + libmpv requirement,
  fork attribution.
- docs/UPSTREAM.md: upstream merge procedure, expected conflict zones,
  list of SageTube-only modules.
- docs/BUILDING.md: per-OS libmpv install, managed-binary locations,
  playback reliability notes, warning that inherited GitHub release
  workflows download appimagetool/ffmpeg without checksum verification.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

2026-07-25 02:46:59 +02:00

1.7 KiB

Raw Blame History

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

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.

1.7 KiB Raw Blame History