Jaroslav Beneš
b4ff618d41
- 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>
49 lines
1.7 KiB
Markdown
49 lines
1.7 KiB
Markdown
# 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.
|