getcoral/aurora repository overview

⁠Aurora

A cinematic, TV-friendly way to browse and watch your Jellyfin library.

⁠

Aurora UI is an open-source Jellyfin frontend. It keeps Jellyfin as the source of truth and adds a living-room-ready way to browse and watch: a featured home, richer detail views, embedded playback, favorites, genre browsing, and a translation-ready UI. Self-host it, or install Aurora for Jellyfin on Google Play⁠.

Aurora is an independent project and is not affiliated with or endorsed by the Jellyfin project.

⁠Why Aurora

Jellyfin's web client is the server console: libraries, metadata, users, and playback in one place. Aurora is a separate frontend built for the people watching.

• A home screen for discovery. Featured titles, Continue Watching, favorites, and recommendation rails.
• Detail pages for the couch. Cast, related titles, and series episode lists, with resume-next-up.
• Shared households. A Netflix-style profile picker. With required sign-in, each person gets their own Jellyfin session, so playback and watch progress stay on the right account.
• The living room. TV mode uses larger text and simpler navigation for a remote. The player can hand the stream to a TV over AirPlay or Cast.
• Your server, your data. Aurora has no accounts of its own, no ads, and no tracking. It talks only to the Jellyfin server you connect, and stores that connection in a local SQLite file, so self-hosting does not need another database.

Keep Jellyfin's web client for administering the server. Open Aurora when you want to watch.

⁠Screenshots

These are the English Google Play phone screenshots shipped in fastlane/metadata/android/en-US/images/phoneScreenshots⁠. Dutch listings are in fastlane/metadata/android/nl-NL/images/phoneScreenshots⁠.

⁠Quick start

Docker Compose, with the in-app Jellyfin setup:

services:
  aurora:
    image: getcoral/aurora:latest
    ports:
      - "3000:3000"
    volumes:
      - aurora-data:/data
    restart: unless-stopped

volumes:
  aurora-data:

docker compose up -d

Open http://localhost:3000⁠ and complete the Jellyfin onboarding form once. Aurora persists the connection in /data/aurora.sqlite.

The Jellyfin URL is requested by the Aurora container, so localhost in that form is the container itself. Use a hostname the container can reach: another Compose service name, a LAN address, or host.docker.internal on Docker Desktop.

The same stack with onboarding skipped (the container image is also published as ghcr.io/get-coral/aurora⁠):

services:
  aurora:
    image: getcoral/aurora:latest
    ports:
      - "3000:3000"
    volumes:
      - aurora-data:/data
    environment:
      JELLYFIN_URL: http://your-jellyfin:8096
      JELLYFIN_API_KEY: your_api_key
      JELLYFIN_USER_ID: your_user_id
      JELLYFIN_USERNAME: your_username
      JELLYFIN_PASSWORD: your_password
    restart: unless-stopped

volumes:
  aurora-data:

JELLYFIN_USER_ID is the Jellyfin user UUID. More on images, the local build, and docker run is in Docker⁠.

⁠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. The copy-paste Compose files are in Quick start⁠.

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.
3. Either leave the API key empty and sign in with your Jellyfin username and password (the password may be empty for accounts without one), or enter an API key together with your user ID, username, and password.
4. 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

⁠Android Release Builds

The Play Store bundle is signed with an upload key that never goes in the repo. Copy android/keystore.properties.example⁠ to android/keystore.properties and point it at your keystore, or set the AURORA_UPLOAD_STORE_FILE, AURORA_UPLOAD_STORE_PASSWORD, AURORA_UPLOAD_KEY_ALIAS and AURORA_UPLOAD_KEY_PASSWORD environment variables. Then build the bundle:

pnpm android:bundle:release

The signed bundle is written to android/app/build/outputs/bundle/release/app-release.aab. Without a keystore the release build is left unsigned.

The version comes from package.json. The versionCode is major * 1000000 + minor * 10000 + patch * 100 + build, so 1.14.1 becomes 1140100. To upload the same version again, raise the build number with AURORA_BUILD_NUMBER (0–99), for example AURORA_BUILD_NUMBER=1 pnpm android:bundle:release.

Store listing texts, release notes, the icon, the feature graphic and phone screenshots live in fastlane/metadata/android⁠. The privacy policy is in docs/privacy-policy.md⁠ and is published at https://getcoral.dev/apps/aurora/privacy⁠.

The public Android app is Aurora for Jellyfin⁠ (dev.getcoral.aurora).

⁠Packaging Notes

• Android release bundles are built with pnpm android:bundle:release (see above). Android Studio is still useful for running and debugging.
• 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⁠.