torttube/docs/install.md

Installing torttube on the LibreELEC RPi

The addon ships as a single plugin.video.torttube-<version>.zip that contains the Python addon, a static aarch64 sidecar binary, and yt-dlp's aarch64 release binary (for Tier 2/3 fallback). Nothing else needs to be installed on the Pi.

Build the zip

bash scripts/build-addon-zip.sh
# → dist/plugin.video.torttube-<version>.zip

The script cross-compiles the sidecar in a throwaway messense/rust-musl-cross:aarch64-musl container, fetches yt-dlp's universal Python zipapp, and drops the result at dist/ under the repo root. Override DEST_DIR=... to land it elsewhere.

Install on the Pi (Kodi UI flow)

1. Copy the zip onto the Pi (SMB share, scp, USB stick — anything).
2. Settings → Add-ons → Install from zip file → pick the zip.
3. Kodi installs torttube and pulls plugin.video.youtube from the official Kodi repo (declared as a dep in addon.xml).
4. The addon appears under Video add-ons.

Unsigned addons need Settings → System → Add-ons → Unknown sources ON.

Install via SSH + JSON-RPC (no UI needed)

If SSH is enabled (Settings → Services → SSH):

# from any LAN host with ssh access to the Pi
scp plugin.video.torttube-0.0.1.zip kodi-host:/tmp/
ssh kodi-host 'cd /storage/.kodi/addons && unzip -o /tmp/plugin.video.torttube-0.0.1.zip && chmod +x plugin.video.torttube/bin/*'
ssh kodi-host 'systemctl restart kodi'

# wait ~5s for Kodi to come back, then enable the addon
curl -u kodi:<pw> -H "Content-Type: application/json" -X POST http://kodi-host:8080/jsonrpc \
  -d '{"jsonrpc":"2.0","id":1,"method":"Addons.SetAddonEnabled","params":{"addonid":"plugin.video.torttube","enabled":true}}'

Freshly-installed addons land in Kodi's database as enabled:false — the SetAddonEnabled call above flips that. Without it, Player.Open with the plugin URL fails silently with "Unable to find plugin" in kodi.log.

Verify

After install, fire the smoke from any LAN client:

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 TV should switch to playback of "Never Gonna Give You Up" within a few seconds (rustypipe resolve takes ~1s, then Kodi starts the stream).

Troubleshooting

• Black screen + "no stream URL" notification: rustypipe returned separate audio + video streams (DASH-style), and we're picking the video stream which may be video-only. This is the M3 known gap — needs the audio+video merge work in M3+. Workaround: try a video that yt-dlp's tier-2 path can resolve to a combined format; the sidecar falls back automatically.
• Sidecar crashes: cat /storage/.kodi/temp/kodi.log | grep torttube on the Pi. Sidecar logs to stderr; Kodi captures those.
• yt-dlp permission denied: addon's bin/ dir needs +x. The zip preserves perms but if you copied files manually, chmod +x bin/*.
• HTTPS errors from sidecar: it bundles rustls + webpki roots, so no system CA store needed. If you see "invalid certificate", your Pi clock is wrong (LibreELEC's NTP failed).

Updating

Bump the version in addon/plugin.video.torttube/addon.xml, re-run build-addon-zip.sh, install the new zip. Kodi treats it as an upgrade if the version is higher.