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
• Optional timecode sync with TorrServer

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 10-second seek
• YouTube trailers in the same player
• Skip intro, recap, credits, and preview, 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

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. If "Track timecode on server" is on, the same time is sent to TorrServer. On open, local position is preferred; otherwise the server's timecode is used.
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:

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.

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.