getcoral/aurora repository overview

⁠Aurora UI

Aurora UI is a premium Jellyfin frontend built with TanStack Start and React. It keeps Jellyfin as the source of truth while layering on a more cinematic home experience, richer detail views, embedded playback, favorites, genre browsing, and translation-ready UI foundations.

⁠Highlights

• Jellyfin-powered home screen with featured, continue watching, favorites, and recommendation rails
• Embedded playback with progress sync back to Jellyfin
• Rich title detail views with cast, related titles, and series episode context
• Movie and series library pages with genre browsing, sorting, and pagination
• My List / favorites workflow backed by Jellyfin favorites
• Multi-user profiles with a Netflix-style profile picker for shared households
• Optional required sign-in with per-user Jellyfin sessions, so playback and watch progress are attributed to the right account
• Admin dashboard for managing users, parental controls, libraries, and active sessions
• Translation-ready UI with locale files contributors can extend
• Local-first onboarding backed by SQLite so self-hosting does not require an external database

⁠Stack

• TanStack Start⁠
• React 19
• TanStack Router + TanStack Query
• Tailwind CSS v4
• Jellyfin API

⁠Getting Started

Install dependencies:

pnpm install

Create your local env file if you want to skip the in-app setup flow during development:

cp .env.example .env

Fill in the Jellyfin settings in .env:

JELLYFIN_URL=http://localhost:8096
JELLYFIN_API_KEY=your_api_key_here
JELLYFIN_USER_ID=your_user_id_here
JELLYFIN_USERNAME=your_username_here
JELLYFIN_PASSWORD=your_password_here

Start the app:

pnpm dev

Open http://localhost:3000⁠.

If you do not provide Jellyfin env vars, Aurora will open a local onboarding screen at /setup and store the connection details in a local SQLite file under ./data/aurora.sqlite.

⁠Scripts

pnpm dev
pnpm build
pnpm start
pnpm preview
pnpm test

⁠CI

GitHub Actions workflows are included for:

• CI on pushes and pull requests: install, test, web build, Android Capacitor sync, Android debug assemble, and Docker build validation
• Docker publish to Docker Hub and GHCR on main, version tags, or manual dispatch

Workflow files:

• .github/workflows/ci.yml⁠
• .github/workflows/docker-publish.yml⁠

⁠Local Storage

Aurora stores local app configuration in SQLite.

• Default database path: ./data/aurora.sqlite
• Override with: AURORA_DATA_DIR=/path/to/data
• Main use today: persisted Jellyfin connection details for onboarding and self-hosted installs

This keeps Aurora simple to deploy on a VM or home server because there is no external database requirement.

⁠Jellyfin Notes

Aurora uses Jellyfin as the system of record.

• API key access is enough for browsing, favorites, and most library features
• Username/password are used to create a real Jellyfin playback session so Aurora can sync progress and watched state more reliably; with required sign-in enabled, each signed-in user's own session is used instead and the configured credentials are only the fallback
• JELLYFIN_USER_ID must be the actual Jellyfin user UUID, not the app name
• If you use the onboarding flow, Aurora stores these values in local SQLite instead of requiring env vars

⁠User Profiles

Aurora supports multiple profiles for shared households: everyone picks their own Jellyfin user on a profile screen when opening Aurora.

• Enable it in Settings → User profiles, or force it on with AURORA_MULTI_USER=true in the environment
• Administrators manage users (create, disable, delete, parental controls) from the dashboard at /admin
• When required sign-in is enabled, switching to another profile asks for that profile's password

⁠Requiring Sign-In

By default anyone who can reach your Aurora instance can browse and stream the connected library. If your instance is reachable from the internet (or any network you do not fully trust), enable Require sign-in in Settings → Security. Everyone then has to sign in with their own Jellyfin username and password before Aurora serves anything.

• Sessions are stored server-side in the local SQLite database and last 30 days
• Sign-in is validated directly against your Jellyfin server, so Jellyfin account lockout policies apply
• Each sign-in gets its own Jellyfin access token, so playback and watch progress are attributed to the signed-in user (not the configured account), and signing out revokes the token on the Jellyfin side
• To force it on (so it cannot be disabled from the UI), set AURORA_REQUIRE_LOGIN=true in the environment

Administration is gated separately and always requires signing in. Even on an open instance, the admin dashboard and the settings that change your Jellyfin connection, users, or security options are only available to a signed-in Jellyfin administrator — "Require sign-in" controls who can browse and stream, not who can administer. The one exception is a brand-new install that is not connected to Jellyfin yet, since there is no account to sign in with until setup completes.

⁠Playing on a TV (AirPlay & Cast)

The player has a "Play on TV" button that opens the browser's own device picker — AirPlay in Safari and on iOS, Cast in Chrome. It only appears once a receiver has been discovered, so give it a second or two on first load.

A TV doesn't play the video through your browser: it's handed the stream URL and fetches it itself. That has a few consequences worth knowing:

• Aurora has to be reachable from the TV. http://localhost:3000 cannot work — serve Aurora on a hostname or IP the receiver can also reach.
• Cast needs HTTPS. Chrome only exposes the picker on a secure origin. AirPlay has no such requirement and works over plain HTTP on a LAN.
• Subtitles stay on your device. The receiver plays the stream as its own player, so neither Aurora's subtitle tracks nor the OpenSubtitles overlay reach the TV.
• Quality is fixed for the duration of the cast, and seeking is limited to what's already buffered — changing either would restart the stream and drop the connection to the TV.

With Require sign-in on, stream URLs are signed with a token so the TV can fetch them without your session cookie. Each token covers a single title, expires within six hours, and stops working the moment you sign out. Aurora generates the signing secret on first use; set AURORA_STREAM_TOKEN_SECRET only if you run several replicas behind a load balancer.

⁠Translations

Translations live in dedicated locale files so contributors can add languages without touching the runtime logic.

Files:

• src/lib/i18n/messages/en.ts⁠
• src/lib/i18n/messages/nl.ts⁠
• src/lib/i18n/messages/index.ts⁠

To add a new language:

1. Copy src/lib/i18n/messages/en.ts to a new file such as fr.ts
2. Translate the strings
3. Export and register the file in src/lib/i18n/messages/index.ts
4. Add the locale to the language picker if you want it selectable in the UI

⁠Docker

Aurora ships with a production Dockerfile and can be deployed to a VM with Docker or Docker Compose.

Build locally:

docker build -t aurora .

Run locally with the onboarding flow:

docker run --rm -p 3000:3000 \
  -v aurora-data:/data \
  getcoral/aurora:latest

Then open http://localhost:3000⁠ and complete the Jellyfin onboarding form once. Aurora will persist the connection in /data/aurora.sqlite.

If you prefer skipping onboarding, you can still pass the Jellyfin env vars directly:

docker run --rm -p 3000:3000 \
  -v aurora-data:/data \
  -e JELLYFIN_URL=http://your-jellyfin:8096 \
  -e JELLYFIN_API_KEY=your_api_key \
  -e JELLYFIN_USER_ID=your_user_id \
  -e JELLYFIN_USERNAME=your_username \
  -e JELLYFIN_PASSWORD=your_password \
  getcoral/aurora:latest

The container listens on port 3000 and stores local config in /data.

⁠Capacitor Wrappers

Aurora now supports a real local Capacitor build for Android and iOS.

How it works:

• Capacitor uses the built local web bundle from dist/client.
• TanStack Start SPA mode now emits a real dist/client/index.html, which Capacitor requires.
• pnpm cap:sync, pnpm cap:copy, and pnpm cap:run:* build Aurora first and then sync the native projects.
• In native-shell mode, Aurora stores Jellyfin and OpenSubtitles settings in device-local storage instead of relying on the Node server.
• Android hardware back now exits fullscreen first, then closes Aurora overlays, then navigates back before exiting the app at the true root.

The Capacitor config lives in capacitor.config.ts⁠.

⁠Native Setup

Sync the latest web assets into Android and iOS:

pnpm cap:sync

Open the native projects:

pnpm cap:open:android
pnpm cap:open:ios

Run directly to a connected device or emulator:

pnpm cap:run:android
pnpm cap:run:ios

Build the Android debug app without launching a device target:

pnpm android:assemble:debug

⁠First Launch

On first launch in the native app:

1. Open the /setup flow.
2. Enter the Jellyfin server URL, API key, user ID, username, and password.
3. Optionally add your OpenSubtitles API key in settings.

Aurora stores that configuration on the device.

⁠What Works Locally

• Setup and settings
• Home feeds
• Movie and series library browsing
• Search
• My List and favorites toggles
• History
• Media details and episode browsing
• Basic local playback bootstrapping
• OpenSubtitles search and download using the stored API key

⁠Current Limits

• The admin screen is still server-oriented.
• Native playback works locally, but full Jellyfin playback-session and progress sync is still less complete than the hosted server build.
• If you want the native shell to target a hosted Aurora deployment instead, you can still set AURORA_APP_URL before syncing.

Example hosted override:

AURORA_APP_URL=https://your-aurora-domain.example pnpm cap:sync

⁠Packaging Notes

• Android packaging happens from Android Studio after opening the generated project.
• iOS packaging happens from Xcode after opening the generated project.
• Google TV should be treated as an Android TV target using the same Capacitor Android project once the TV UX is finalized.
• Capacitor Android 8 requires JDK 21 for local and CI builds.
• pnpm cap:run:android resolves JAVA_HOME automatically on macOS and prefers the Homebrew JDK 21 path when present, then falls back to system JDK 21 or 17.
• CI validates the native Android path with pnpm cap:sync and pnpm android:assemble:debug.

Published images go to:

• getcoral/aurora⁠ on Docker Hub
• ghcr.io/get-coral/aurora⁠ on GHCR

⁠Contributing

Issues and pull requests are welcome.

If you want to contribute:

1. Fork the repo
2. Create a branch
3. Make your changes
4. Run pnpm build
5. Open a pull request

⁠Sponsoring

If Aurora helps you or you want to support ongoing work, you can sponsor the project here:

• GitHub Sponsors: ElianCodes⁠

⁠License

Aurora UI is released under the MIT License⁠.