English | Русский

What and why | Features | How it works | Install | Architecture | Roadmap | Contributing | Disclaimer

What and why

Cinebox is a native app for Windows, Linux, and Android TV. Movie and series catalog, torrent search, and playback in one window: no browser, no extra player.

The stack is the same one people already use in LAMPA MX: TMDB, Jackett or Prowlarr, TorrServer. LAMPA is a website. It runs in a browser or a WebView, the built-in player handles few codecs and often stutters, so the stream almost always ends up in VLC or MPC-HC. The browser also eats RAM on its own.

TMDB is a separate story. In regions where api.themoviedb.org is DNS-blocked (including Russia), LAMPA goes through someone else's TMDB proxy. Cinebox talks to TMDB itself. If regular DNS cannot resolve the host, built-in DNS-over-HTTPS kicks in: you can set your own server, otherwise Quad9 / DNS.SB / AliDNS. No extra plugin and no third-party proxy.

Features

Catalog

• Sections: Movies, Cartoons, Series, Anime, each with its own themed shelves
• Discover: filter by genre, decade, rating, and sort order
• Lists: Watching, Plan to watch, Completed, Dropped, and Liked
• Home: recently watched, your lists, trending, popular, top rated
• Search for movies, series, and people with query history
• Title pages with cast, collections, recommendations, and similar titles
• Actor and director pages
• Resume from the last position per movie or episode
• Continue on another device through your TorrServer, LAMPA included

Playback

• Built-in libmpv: MKV, HEVC, and HDR play without an external player
• Hardware video decoding on the GPU
• On Android TV, ExoPlayer: 4K, HDR10, and Dolby Vision on the hardware decoder
• Torrent search via Jackett or Prowlarr with quality, HDR, voice, and language filters
• Streaming through TorrServer with preload and auto-play of the next file
• Audio and subtitle tracks, subtitle delay, speed, scale, loudness normalization
• Track, speed, and scale choices remembered per torrent
• Fullscreen with auto-hiding controls and cursor, 10-second seek
• YouTube trailers in the same player
• Skip intro, recap, credits, and preview from TheIntroDB or the file's chapters, with optional auto-skip

App

• English, Russian, and Ukrainian UI; TMDB content follows the UI language
• System proxy for TMDB and the parser; TorrServer always connects directly
• Built-in DNS-over-HTTPS to get around DNS blocks
• Connection checks for TMDB, the parser, and TorrServer, plus a speed test

Android TV

• Remote control: D-pad, media keys, and Back the way Android TV apps work
• Voice search and typing from the phone remote
• Edge margin for TVs that crop the picture, set in the first-run wizard

How it works

flowchart LR
  UI[Cinebox] --> TMDB[TMDB]
  UI --> Parser[Jackett / Prowlarr]
  Parser --> TS[TorrServer]
  TS --> Player[libmpv / ExoPlayer]
  UI --> YT[YouTube trailers]
  YT --> Player
  TMDB -.-> DoH[DoH if DNS is blocked]
  Parser -.-> DoH

Loading

1. Catalog. Cinebox calls TMDB with your key: home, sections, discover, search, title pages, seasons, images. Responses and posters go into SQLite so a bad network does not force a full reload.
2. Releases. The Watch button sends the title to Jackett or Prowlarr. Quality, HDR, voice, and episodes are parsed out of release names, then the list is filtered on that.
3. Stream. The magnet goes to TorrServer. You can wait for preload, then the stream opens in the player. No browser in this path.
4. Watch history. Progress is written to local SQLite as you watch, keyed by title or episode, not by torrent. With "Remember position on the server" on, the same time goes to TorrServer, and on open the local position wins. With "Continue on other devices" on, torrents on the server join Recently watched, matched to TMDB by the card in the torrent or by name, and a position another device moved wins. Cards are written in the format LAMPA reads, so each app sees the other's torrents.
5. Player settings. Open the same torrent again and the last audio track, subtitles, speed, and video scale come back. Subtitle size and delay last for the current playback only. Volume is app-wide.
6. Trailers. TMDB gives a video id. Cinebox talks to YouTube InnerTube, deciphers the player JS signature, and feeds the media URLs into the same player.
7. Network. TMDB and the parser can use the system proxy. If that path fails and DNS bypass is on, the host is resolved over DoH and the request goes out direct. TorrServer is never proxied.

Install

Get a build from GitHub Releases:

• Windows x64: unpack the zip and run cinebox.exe. Settings and the database stay in that folder.

• Linux x86_64, pick one:

  • Flatpak (any distribution): flatpak install --user cinebox-*.flatpak. Shows up in the app menu and in GNOME Software or Discover; the runtime and codecs come from Flathub. To update, install the newer file over it. Settings and the database live in ~/.var/app/io.github.dexsper.cinebox/.
  • .deb (Debian 12+, Ubuntu 24.04+, Mint 22+): sudo apt install ./cinebox_*.deb. Uses the system libmpv.
  • AppImage (Debian 12, Ubuntu 24.04, Fedora 37 or newer): chmod +x and run. libmpv is inside. For a menu entry and updates, open it with Gear Lever or AppImageLauncher, like any other AppImage.

  Outside Flatpak, settings go to ~/.config/cinebox and the database to ~/.local/share/cinebox.

• Android TV (Android 8.0+, ARM): install cinebox-*-android.apk.

Cinebox does not ship TMDB, a parser, or TorrServer. You run those yourself:

What	Settings	Typical URL
TMDB API key	TMDB	-
Jackett or Prowlarr	Parser	http://127.0.0.1:9117
TorrServer	TorrServer	http://127.0.0.1:8090

On Android TV, 127.0.0.1 works only for what runs on the TV itself; for a server on another machine, use its LAN address.

Important

TMDB wants the short API key (32 hex characters). A JWT access token will not work here.

On first launch, open Settings (gear) and fill in the key and URLs. Same screen can check the TMDB key, the parser, and ping TorrServer. If the catalog is empty because TMDB is blocked, leave DNS bypass on: it is on by default.

Build from source

For hacking on the code, or if there is no release yet.

1. Rust 1.95+ and the platform toolchain:
   • Windows 10/11 x64: MSVC C++ Build Tools (lib.exe on PATH). The first build downloads libmpv (about 30 MB) into crates/cinebox-player/mpv-src/.
   • Linux: a C compiler, pkg-config, and the system libmpv 0.35+ with headers.
     • Debian/Ubuntu: sudo apt install build-essential pkg-config libmpv-dev
     • Arch: sudo pacman -S --needed base-devel mpv
2. Clone and run:

git clone https://github.com/dexsper/cinebox.git
cd cinebox
cargo run -p cinebox --release

3. Tests: cargo test --workspace.

Linux packages: cargo install cargo-deb && cargo deb -p cinebox builds the .deb. The Flatpak builds offline from packaging/flatpak/ (needs org.flatpak.Builder); after changing Cargo.lock, run ./scripts/flatpak-cargo-sources.sh and commit the refreshed cargo-sources.json.

flatpak run org.flatpak.Builder --user --install --install-deps-from=flathub --force-clean \
  .flatpak-builder/build-dir packaging/flatpak/io.github.dexsper.cinebox.yml

Android TV APK: JDK 17+, the Android SDK with NDK r28 (ANDROID_HOME), the Rust targets aarch64-linux-android and armv7-linux-androideabi, and cargo install cargo-ndk --locked.

./scripts/android-build.sh debug

Without debug it builds the release APK, signed when ANDROID_KEYSTORE_PATH, ANDROID_KEYSTORE_PASSWORD, ANDROID_KEY_ALIAS, and ANDROID_KEY_PASSWORD are set.

Architecture

The repo is split into crates. The window and screens live in cinebox, the rest are libraries.

Crate	What it does
cinebox	Window (egui/eframe), screens, translations
cinebox-core	Models, settings.json, SQLite (cache, history, lists)
cinebox-tmdb	TMDB requests, section shelves, discover queries
cinebox-net	HTTP: proxy, DoH, retries
cinebox-indexer	Jackett and Prowlarr, release-name parse, voices, filters
cinebox-torrserver	TorrServer client, file/episode parse
cinebox-player	libmpv over OpenGL; ExoPlayer on Android TV
cinebox-youtube	YouTube InnerTube and signature decipher for the player
cinebox-skip	Skip-segment data (TheIntroDB; extensible for other sources)
cinebox-typograf	Title typography (ru / en-US)
cinebox-android	Android TV entry point; the Java side (ExoPlayer, MediaSession, voice input, keyboard) is in android/

Roadmap

• Skip intro and credits
  • Third-party API (TheIntroDB)
  • Custom Chromaprint-based analyzer
• Categories on the home screen, plus custom lists (Favorites, Watched)
• First-run wizard
• Linux build
• Android TV app
• Playback sync between clients

Contributing

Bugs and ideas go in Issues. Code changes go through a pull request.

1. Fork, branch off master.
2. Run cargo test --workspace before you push.
3. One PR per topic is better. If the change is large, open an issue first.
4. Do not commit keys, settings.json, or sqlite files.

If you touched SQLx query! or migrations, refresh offline data with scripts/sqlx-prepare

Disclaimer

Cinebox is a media player and a catalog. It does not host, upload, or distribute copyrighted content. Users are responsible for what they open and for following the law. This product uses the TMDB API but is not endorsed or certified by TMDB.