docs: rewrite README for public release + tidy CI/milestones
- README rewritten as a general-purpose, external-user-facing guide (what it is, build, install, usage, configuration, contributing, license). - gitleaks workflow header reduced to a generic description. - MILESTONES M0 scaffold line genericized.
This commit is contained in:
Sulkta
parent
b93246ee74
commit
44267a37f6
3 changed files with 128 additions and 38 deletions
|
|
@ -1,16 +1,6 @@
|
|||
# .forgejo/workflows/gitleaks.yml
|
||||
#
|
||||
# Sulkta canonical gitleaks workflow. Drop a copy into every public repo at
|
||||
# `.forgejo/workflows/gitleaks.yml` after the Forgejo act_runner is registered
|
||||
#.
|
||||
#
|
||||
# Pairs with the pre-receive hook installed on every bare repo — that one is
|
||||
# the strict enforcement layer (rejects the push); this one provides the
|
||||
# per-PR red ✗ that branch-protection rules can require before merge.
|
||||
#
|
||||
# Layer 1 (this workflow): visible per-PR status, can be a required check.
|
||||
# Layer 2 (pre-receive hook): strict enforcement at the server.
|
||||
# Layer 3 (scheduled cron sweep): nightly full-history secret sweep.
|
||||
# Scan the repository for accidentally-committed secrets with gitleaks on
|
||||
# every push and pull request. Runs over full history so it catches secrets
|
||||
# introduced in any commit in the pushed range.
|
||||
|
||||
name: gitleaks
|
||||
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
## M0 — Scaffold [current]
|
||||
|
||||
- [x] `Sulkta/torttube`
|
||||
- [x] repository scaffolded
|
||||
- [x] Layout: `addon/` (Python) + `sidecar/` (Rust workspace)
|
||||
- [x] GPL-3.0 license headers
|
||||
- [ ] the build container produces a static aarch64 sidecar binary
|
||||
|
|
|
|||
148
README.md
148
README.md
|
|
@ -1,35 +1,135 @@
|
|||
# torttube — RETIRED 2026-05-23
|
||||
# torttube
|
||||
|
||||
This addon has been retired. We reinvented an existing wheel.
|
||||
A [Kodi](https://kodi.tv/) add-on that browses, searches, and plays YouTube
|
||||
videos **without a YouTube account**, with automatic
|
||||
[SponsorBlock](https://sponsor.ajay.app/) skipping. It pairs a small Python
|
||||
plugin UI with a native Rust sidecar that does the heavy lifting (metadata,
|
||||
stream resolution, SponsorBlock lookups).
|
||||
|
||||
**Use these instead, both via official sources:**
|
||||
> **Project status:** torttube is feature-complete but no longer under active
|
||||
> development. For everyday use on a stock Kodi box you are probably better
|
||||
> served by the mature upstream add-ons it ended up leaning on:
|
||||
> [`plugin.video.youtube`](https://github.com/anxdpanic/plugin.video.youtube)
|
||||
> for playback and
|
||||
> [`script.service.sponsorblock`](https://github.com/siku2/script.service.sponsorblock)
|
||||
> for SponsorBlock skipping across *all* YouTube playback. torttube remains a
|
||||
> compact, hackable reference for a Rust-sidecar + Python-plugin Kodi add-on.
|
||||
|
||||
- [`plugin.video.youtube`](https://github.com/anxdpanic/plugin.video.youtube) — playback. Has years of work on multi-Innertube-client fallback and proper DASH MPD construction.
|
||||
- [`script.service.sponsorblock`](https://github.com/siku2/script.service.sponsorblock) — SponsorBlock skips for ALL YouTube playback in Kodi, including phone-cast. Polished settings UI, multi-backend support (pv.youtube, Invidious, Piped, sendtokodi), works silently in the background.
|
||||
## What it does
|
||||
|
||||
## What torttube was
|
||||
- **Browse & search** YouTube from the Kodi UI — search, channels, playlists,
|
||||
per-user subscriptions and a "Watch Later" list, all account-free and curated
|
||||
by you (no recommendation algorithm).
|
||||
- **Play any video** by ID or URL, including over Kodi's JSON-RPC API so a
|
||||
phone, Home Assistant, or a `curl` one-liner can "send to TV".
|
||||
- **Skip SponsorBlock segments** automatically during playback (sponsor,
|
||||
self-promo and interaction reminders by default).
|
||||
- **Account-free extraction** via a native Rust sidecar (RustyPipe) with a
|
||||
`yt-dlp` fallback, and optional delegation to `plugin.video.youtube` for
|
||||
high-definition DASH playback.
|
||||
|
||||
A LibreELEC Kodi addon for the home TVs — Rust sidecar (`rustypipe` + `yt-dlp` + SponsorBlock client) + Python plugin UI for browse/search/channels/subscriptions/watch-later. Built across 2026-05-23 in response to YouTube blocking anonymous playback on Kodi via `plugin.video.youtube`.
|
||||
## Architecture
|
||||
|
||||
The architecture peaked at v1.0.4:
|
||||
- Bundled `plugin.video.youtube` 7.4.3 zip + auto-install on first run
|
||||
- Service-level SponsorBlock for all YouTube playback (including phone cast)
|
||||
- Rustypipe-backed browse UI (search / channels / subs / WL)
|
||||
- Native DASH MPD path (parked — audio-sync drift on long videos)
|
||||
- yt-dlp progressive 360p fallback
|
||||
```
|
||||
addon/plugin.video.torttube/ Python Kodi plugin (UI, routing, SponsorBlock service)
|
||||
sidecar/ Rust workspace — the torttube-sidecar binary
|
||||
```
|
||||
|
||||
By the time v1.0.4 shipped, every job we did had an existing addon doing it better:
|
||||
- Playback: pv.youtube (we were already delegating to it 100% of the time)
|
||||
- SponsorBlock-for-all-YT-playback: `script.service.sponsorblock` (we wrote essentially the same code as their `Monitor` + `PlayerCheckpointListener`)
|
||||
- The only piece we built that wasn't a duplicate was the rustypipe browse UI — which we only used when navigating torttube on the TV remote, not when casting from the phone
|
||||
The plugin talks to the sidecar over a simple JSON-over-stdio protocol. Stream
|
||||
resolution is three-tier:
|
||||
|
||||
Lessons in the [v1.0.0 → v1.0.4 commits](/Sulkta/torttube/commits/branch/main) and [closed PRs](/Sulkta/torttube/pulls?state=closed).
|
||||
1. **RustyPipe** (native Rust InnerTube client) — fast metadata + stream URLs.
|
||||
2. **`yt-dlp`** subprocess fallback when tier 1 can't resolve a video.
|
||||
3. **`rip`** — last-resort download-to-temp for streams that die mid-play.
|
||||
|
||||
## Repo state
|
||||
For HD playback the add-on can delegate to `plugin.video.youtube`, which has a
|
||||
mature DASH manifest builder; torttube layers its account-free browse UI and
|
||||
SponsorBlock skipping on top. A SponsorBlock service component (`service.py`)
|
||||
also watches *all* YouTube playback in Kodi — including videos cast from a
|
||||
phone — and skips segments globally.
|
||||
|
||||
- Latest tag: `v1.0.4`
|
||||
- Build artifact: `dist/plugin.video.torttube-<version>.zip` from `scripts/build-addon-zip.sh`
|
||||
- Sidecar Rust source: `sidecar/crates/torttube-sidecar/` (aarch64-musl cross-compile)
|
||||
- Vendored: `plugin.video.youtube-7.4.3.zip`
|
||||
## Requirements
|
||||
|
||||
Repo archived 2026-05-23.
|
||||
- Kodi 20 (Nexus) or newer (`xbmc.python` 3.0.0).
|
||||
- `inputstream.adaptive` (optional, for DASH playback).
|
||||
- A target device that can run the sidecar binary (the build targets
|
||||
`aarch64`; see below).
|
||||
|
||||
## Build
|
||||
|
||||
The add-on ships as a single installable zip containing the Python plugin, a
|
||||
statically-linked sidecar binary, and `yt-dlp`'s universal Python zipapp:
|
||||
|
||||
```bash
|
||||
bash scripts/build-addon-zip.sh
|
||||
# → dist/plugin.video.torttube-<version>.zip
|
||||
```
|
||||
|
||||
The script cross-compiles the sidecar for `aarch64-musl` in a throwaway
|
||||
`messense/rust-musl-cross` container (so no host Rust toolchain is required,
|
||||
only Docker), fetches the `yt-dlp` zipapp, and packages everything into the
|
||||
Kodi "install from zip" layout. Override `DEST_DIR=...` to land the zip
|
||||
elsewhere. Requirements: `docker`, `zip`, `curl`.
|
||||
|
||||
## Install
|
||||
|
||||
In Kodi: **Settings → Add-ons → Install from zip file**, then pick the built
|
||||
zip. Unsigned add-ons require **Settings → System → Add-ons → Unknown sources**
|
||||
to be enabled. If you opt into delegated playback, Kodi will pull
|
||||
`plugin.video.youtube` from the official repository.
|
||||
|
||||
A headless install over SSH + JSON-RPC is documented in
|
||||
[`docs/install.md`](docs/install.md).
|
||||
|
||||
## Usage
|
||||
|
||||
Open the add-on under **Video add-ons** and use Search / Channels /
|
||||
Subscriptions / Watch Later from the root menu.
|
||||
|
||||
To start playback from another device on the network, POST to Kodi's JSON-RPC
|
||||
endpoint (enable the HTTP control server + a password under
|
||||
**Settings → Services → Control** first):
|
||||
|
||||
```bash
|
||||
curl -u kodi:<pw> -H "Content-Type: application/json" \
|
||||
-X POST http://<kodi-host>:8080/jsonrpc -d '{
|
||||
"jsonrpc": "2.0", "id": 1, "method": "Player.Open",
|
||||
"params": {"item": {"file":
|
||||
"plugin://plugin.video.torttube/?action=play&id=dQw4w9WgXcQ"}}}'
|
||||
```
|
||||
|
||||
The add-on accepts a bare 11-character ID or any `youtube.com` / `youtu.be` /
|
||||
`shorts` / `embed` / `live` URL. See
|
||||
[`docs/remote-control.md`](docs/remote-control.md) for the full JSON-RPC recipe.
|
||||
|
||||
## Configuration
|
||||
|
||||
Add-on settings (**Settings → Add-on settings → torttube**):
|
||||
|
||||
- **Use plugin.video.youtube for playback (HD)** — delegate playback to
|
||||
`plugin.video.youtube` for proper DASH/HD (default on).
|
||||
- **Native DASH (WIP)** — experimental in-add-on DASH manifest path, used when
|
||||
`plugin.video.youtube` is absent (default off).
|
||||
|
||||
## Contributing
|
||||
|
||||
Contributions are welcome. The add-on intentionally leans on the wider FOSS
|
||||
ecosystem — when a bug traces back to an upstream project (RustyPipe,
|
||||
NewPipeExtractor, `yt-dlp`), the fix should land there first. Please keep the
|
||||
Python plugin dependency-free (Kodi modules + stdlib only) and the sidecar's
|
||||
JSON-over-stdio protocol stable. See [`docs/upstream.md`](docs/upstream.md) for
|
||||
the upstream-contribution log and [`MILESTONES.md`](MILESTONES.md) for the
|
||||
development history.
|
||||
|
||||
## License
|
||||
|
||||
GPL-3.0-or-later. See [`LICENSE`](LICENSE).
|
||||
|
||||
### Acknowledgements
|
||||
|
||||
torttube stands on the shoulders of
|
||||
[RustyPipe](https://codeberg.org/ThetaDev/rustypipe),
|
||||
[NewPipeExtractor](https://github.com/TeamNewPipe/NewPipeExtractor),
|
||||
[`yt-dlp`](https://github.com/yt-dlp/yt-dlp),
|
||||
[SponsorBlock](https://sponsor.ajay.app/), and
|
||||
[`plugin.video.youtube`](https://github.com/anxdpanic/plugin.video.youtube).
|
||||
|
|
|
|||
Reference in a new issue