torttube

A Kodi add-on that browses, searches, and plays YouTube videos without a YouTube account, with automatic SponsorBlock skipping. It pairs a small Python plugin UI with a native Rust sidecar that does the heavy lifting (metadata, stream resolution, SponsorBlock lookups).

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 for playback and 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.

What it does

• 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.

Architecture

addon/plugin.video.torttube/   Python Kodi plugin (UI, routing, SponsorBlock service)
sidecar/                       Rust workspace — the torttube-sidecar binary

The plugin talks to the sidecar over a simple JSON-over-stdio protocol. Stream resolution is three-tier:

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.

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.

Requirements

• 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 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.

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

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 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 for the upstream-contribution log and MILESTONES.md for the development history.

License

AGPL-3.0-or-later. See LICENSE.

Acknowledgements

torttube stands on the shoulders of RustyPipe, NewPipeExtractor, yt-dlp, SponsorBlock, and plugin.video.youtube.