No description
  • Rust 41.2%
  • TypeScript 38.7%
  • CSS 12.9%
  • JavaScript 7.1%
  • HTML 0.1%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
axoisaxo a8c36639fe Initial commit: Kolora Cinema
A native Jellyfin client for macOS and Linux built on the Kolora shell:
Tauri 2 + React 19 + Rust, with the Kolora Files design system and the
gray default theme.

- Jellyfin auth, libraries, home rows, grids, search and detail pages
- Loopback media server with token auth, image proxy and range pass-through
- Direct playback with local remux/transcode planning and a bundled ffmpeg
- Network, secret-storage and redirect hardening

Co-authored-by: CommandCodeBot <noreply@commandcode.ai>
2026-11-18 11:04:28 +01:00
.commandcode/taste Initial commit: Kolora Cinema 2026-11-18 11:04:28 +01:00
devtools/mock-jellyfin Initial commit: Kolora Cinema 2026-11-18 11:04:28 +01:00
docs Initial commit: Kolora Cinema 2026-11-18 11:04:28 +01:00
scripts Initial commit: Kolora Cinema 2026-11-18 11:04:28 +01:00
src Initial commit: Kolora Cinema 2026-11-18 11:04:28 +01:00
src-tauri Initial commit: Kolora Cinema 2026-11-18 11:04:28 +01:00
.gitignore Initial commit: Kolora Cinema 2026-11-18 11:04:28 +01:00
package-lock.json Initial commit: Kolora Cinema 2026-11-18 11:04:28 +01:00
package.json Initial commit: Kolora Cinema 2026-11-18 11:04:28 +01:00
README.md Initial commit: Kolora Cinema 2026-11-18 11:04:28 +01:00
tsconfig.json Initial commit: Kolora Cinema 2026-11-18 11:04:28 +01:00
tsconfig.web.json Initial commit: Kolora Cinema 2026-11-18 11:04:28 +01:00
vite.config.ts Initial commit: Kolora Cinema 2026-11-18 11:04:28 +01:00
vitest.config.ts Initial commit: Kolora Cinema 2026-11-18 11:04:28 +01:00

Kolora Cinema

A fast, native Jellyfin client for macOS and Linux. It uses the Kolora shell architecture (Tauri 2 + React 19 + Rust) and the Kolora Files design system verbatim, with Kolora's gray accent as the default theme.

The client streams the original file from your Jellyfin server and, when the built-in player cannot decode it, remuxes or transcodes on this machine. Jellyfin is never asked to transcode. The security model is written down in docs/security.md.


What works in this build

  • Servers — add, test, sign in with username/password, activate, sign out, remove. Tokens live in a 0600 JSON file, never in the webview or SQLite.
  • Browsing — libraries come from GET /UserViews; the sidebar, home rows, grids and lists are driven by the server's CollectionType and item Type, not by hard-coded names.
  • Detail pages — movies, series, seasons, episodes, albums, tracks, people. Season tabs, episode rows with progress, cast, media facts.
  • Search — server-side searchTerm across the active server.
  • Images — a loopback proxy with token auth, disk-friendly cache headers and a width cap; the Jellyfin token never appears in an <img src>.
  • Playback (direct) — MP4/WebM with H.264/HEVC/VP9/AV1 as the webview allows. Custom player chrome, keyboard shortcuts, volume, fullscreen, resume from UserData.PlaybackPositionTicks. Video bytes are proxied with full Range pass-through from GET /Videos/{id}/stream?static=true.
  • Planner — a tested decision table in Rust that classifies every title as Direct Play / Remux / Transcode from the server's MediaStreams.

Not in this build yet

These are the next phases; the design is written down in docs/playback.md.

  • Local remux (MKV → fMP4 HLS) and transcode (VideoToolbox / NVENC / libx264) with hls.js.
  • Subtitle tracks (WebVTT) and image-subtitle burn-in.
  • Playback progress reporting to Jellyfin, favourites / played toggles.
  • Music queue and Now Playing bar.
  • Signed updater.

Titles that need local work fail with an explicit transcode_required error and the reason ("MKV container — needs a local remux"). They never fall back to a server-side transcode.


Requirements

  • Node 20.19+
  • Rust (stable) and the Tauri 2 toolchain
  • macOS 11+ or Linux with libwebkit2gtk-4.1

End users install nothing else. npm run dev and every build/dist command first run scripts/fetch-ffmpeg.mjs, which downloads a standalone ffmpeg 6.1.1 (79 MB) into src-tauri/binaries/ and bundles it as a Tauri sidecar. The app resolves, in order: an explicit ffmpegPath preference, the bundled sidecar next to its own binary, the development binaries/ path, Homebrew, /usr/bin, then PATH — so a system ffmpeg still overrides the bundled one if you prefer. The sidecar's license is downloaded and shipped alongside it.

The first npm run dev needs network access once; afterwards the fetch is a no-op.

Run

npm install
npm run dev

The window opens with an empty state until a server is added.

Try it without a Jellyfin server

npm run mock:jellyfin

Then add http://127.0.0.1:8096 in the app and sign in with any username and password. The fixture has three libraries, twelve films, two seasons of episodes and two albums.

Playback needs a sample file. Generate one with the bundled ffmpeg:

npm run mock:sample

mock:sample writes a 20-second H.264/AAC clip to devtools/mock-jellyfin/media/sample.mp4, which the fixture server streams with range support.

Tests

npm test              # typecheck + vitest + cargo test
npm run check:rust    # clippy -D warnings
npm run build:ui      # production renderer bundle

55 Rust tests cover the Jellyfin mapping, query building, URL joins with reverse-proxy sub-paths, scheme and path-traversal rejection, the playback decision table, ffmpeg resolution, range parsing, token lifecycle and constant-time comparison, redirect pinning, cache-table bounds, SQLite migrations, the prefs merge/validation, and the HTTP client against a mocked Jellyfin.

Layout

src/renderer            React shell, views, player, styles.css (the design system)
src/shared              types shared by the renderer
src-tauri/src
  jellyfin/             typed HTTP client, models, library queries
  playback/             decision table, ffmpeg detection, playback tickets
  server/               loopback axum server: /v1/image, /v1/raw
  store/                SQLite (servers, prefs, positions) + migrations
  security/             0600 secrets file
  commands/             typed Tauri commands
devtools/mock-jellyfin  fixture server for local QA
docs/                   design system, decisions, playback design, QA checklist