Start here

Setup

Tater Tube is intended to run as an appliance image. Flash first, then configure modules from Settings inside the app.

1. Download

Open the latest GitHub release and choose the NTSC, PAL, or Pi 5 HDMI image for your display.

2. Flash

Use Raspberry Pi Imager, Balena Etcher, or dd to write the `.img.xz` to an SD card.

3. Boot

Connect the display, audio, remote receiver, and network, then boot directly into Tater Tube.

The Tube backend

Use Tater Tube Server for Tube TV, Stream, and Local libraries.

Install the server on a NAS, PC, or small Linux host. It handles the shared Tube TV schedule, Newznab Stream, local media folders, music, player pairing, activity history, and optional transcoding.

Server setup Server downloads

Normal update path

Existing images update from inside Tater Tube.

Use Settings, System, Check For Updates. The updater refreshes the app, helpers, runtime packages, RetroArch cores, Moonlight, Bluetooth support, boot splash, IR, fan control, and display setup. The update splash keeps the logo visible and uses one compact bottom status line.

SSH update fallback

bash <(curl -fsSL https://github.com/TaterTotterson/Tater-Tube/releases/latest/download/install.sh)

Tater Tube boot screen — The image boots into Tater Tube and keeps SSH available for recovery.

Player Web Setup

Configure Pi-side modules from another device.

Open http://tatertube.local:24024/setup from a phone or computer on the same network. Pair The Tube to its server first, then configure VoD, Public Access, Tape Deck, Game Center, PC Link, local commercials, and custom VoD channels.

The Tube

Enter the server address and short-lived pairing PIN. Tube TV, Stream, Local, server music, guide data, and TaterText then arrive from the server.

Server URLPairing PINFirst Module

Player Commercials

Create local commercial categories for Public Access and VoD TV Mode. Tube TV commercials are managed separately by Tater Tube Server.

VoDPublic AccessNo Repeat

Custom VoD Channels

Build named TV Mode channels from Plex, Emby, or Jellyfin movies and series. Custom channels appear first and can use a specific commercial category.

MoviesSeriesCategories

Server Web UI

Build The Tube from `http://SERVER-IP:8080`.

Use the server UI to pair and name players, add Newznab and NNTP providers, scan local movies, series, and music, configure transcoding, upload Tube TV commercials, create channels, choose logos, and inspect the TV Guide and Activity history.

1. Add Libraries

Map folders into Docker, add their container paths under Local Media, and scan metadata.

MoviesSeriesMusic

2. Build Tube TV

Enable automatic channels or create your own from genres, movies, series, seasons, and episodes.

Custom ChannelsCommercialsLogos

3. Pair Players

Create a setup PIN, enter the server URL and PIN on each Pi, and give every box a room name.

Short-Lived PINNamed Players