Frequently asked questions

Getting started

Do I need an existing media server?

Lumastra is a standalone media server for movies, TV shows and music. You supply your own media.

Audiobooks require an Audiobookshelf server. Jellyfin is optional and can sync watch progress. The Kavita integration lets you search for books in Lumastra, then opens them in Kavita.

What do I need to run it?

You need a machine that can run Docker Compose, with 8 GB of RAM and 20 GB of disk space for the application and its data, plus storage for your media.

Background scans and library analysis need that memory. A small library can run with less in low-RAM mode, but memory may be tight. The setup includes a web service, a background worker, PostgreSQL and two Valkey instances.

How does playback work?

Lumastra sends the original file when the player can use it directly. Many files, such as MKV files with several audio tracks, go through HLS instead: the video is copied into short segments without re-encoding, while audio or subtitles are converted when the player needs it.

Segmenting supports seeking, audio-track switching and subtitle synchronisation, but costs some CPU per stream. Re-encoding video costs much more and is needed when a device cannot play the codec or a connection needs lower quality. A supported GPU can handle that work.

Does it run on ARM, a Raspberry Pi or a NAS?

Lumastra supports arm64 and x86-64 Docker hosts, including compatible Synology, Unraid and other NAS systems. x86-64 hosts need an x86-64-v2-capable CPU. Plan for 8 GB of RAM; a Raspberry Pi with less memory is likely too small for a full library.

Use a stable release image on arm64; the edge image is amd64-only. Music BPM and mood analysis, the sound-similarity sidecar and Intel Quick Sync or VA-API transcoding are not available on arm64. Check the hardware limitations before choosing a device.

How do my files need to be organized?

For movies, use the title and year in the filename; a folder per movie is recommended. For TV shows, use a layout such as Show/Season 01/Show - S01E01.mkv. Lumastra uses the series folder name to identify the show.

The organizing guide covers supported layouts, naming examples and ways to resolve mismatches.

Are mixed libraries supported?

No. Movies and TV shows must be kept in separate folders and added as separate libraries.

Can my family use it from outside my home?

Yes. Give everyone their own account, using built-in login or single sign-on, and put Lumastra behind a reverse proxy with HTTPS.

The iPhone, iPad and Apple TV apps require HTTPS with a trusted certificate. The reverse proxy guide includes setups for Caddy, nginx, Traefik and Nginx Proxy Manager.

How do updates and backups work?

To update a Docker Compose install, pull the new image with docker compose pull, then restart with docker compose up -d. Lumastra updates its database automatically on startup. Read the release notes before upgrading.

Back up the database, the /config volume and your .env file or secrets-manager configuration. Keep a separate backup of LUMASTRA_MASTER_KEY: it protects stored secrets and may live in your environment or in /config/master.key.

Coming from Jellyfin or Plex

Can I run Jellyfin at the same time?

Yes. Both servers can read the same media folders. Lumastra stores generated files such as trickplay images, custom artwork and lyrics in /config by default. It only writes into your media folders if you change the metadata storage setting.

Optional Jellyfin sync keeps watch progress in step, with users matched by username. Jellyfin-compatible apps can also connect directly to Lumastra through its Jellyfin bridge.

Both servers can share a GPU, but simultaneous transcodes share its capacity.

How does Lumastra compare to Jellyfin?

Lumastra adds single sign-on that works on the TV, music discovery with a smart queue and DJ crossfades, audiobooks and Live TV in the same server, recommendations across your library, most subtitle formats without burn-in, and Watch Together. It runs several web pods and a separate worker, so large libraries stay fast.

Jellyfin is lighter and has more apps, so it suits small systems such as a Raspberry Pi. Lumastra runs PostgreSQL and Valkey alongside the app.

You can run both on the same media and try Lumastra first. Jellyfin sync works in both directions, keeping watch progress in step.

Does Lumastra use more resources than Jellyfin?

Its baseline is higher, mostly RAM: Lumastra runs a web service, a background worker, PostgreSQL and two Valkey instances. Plan for 8 GB.

In return, scans and analysis run separately from playback, and you can add web nodes as the library and the number of users grow, with one worker and no duplicated background jobs.

Can I move over from Jellyfin or Plex?

From Jellyfin, yes. Point Lumastra at the same media folders and turn on Jellyfin sync to bring over watch progress, with users matched by username. Both servers can keep running side by side.

Watch progress cannot be imported from Plex.

Deployment and architecture

Is Kubernetes supported?

Yes. The Helm chart runs several web pods, a router that keeps each video stream on one pod, a background worker and two Valkey instances. You bring PostgreSQL, or let the chart create a CloudNativePG cluster.

Docker Compose works on a single host. The guide covers storage, single sign-on, GPU transcoding, GitOps upgrades and moving from Docker Compose.

What are the web service, worker and stream proxy?

The web service serves the app and handles playback and transcoding. The worker runs background jobs such as scans, trickplay, intro detection and embeddings, with their own resource limits; it can run on another node with shared storage. The stream proxy is only needed for Live TV.

PostgreSQL 17+ with pgvector and two Valkey instances hold the data. The Compose file includes all of them; the Helm chart bundles Valkey and uses your PostgreSQL or a CloudNativePG cluster.

Why PostgreSQL? Could it run on SQLite or another database?

Lumastra requires PostgreSQL. It uses pgvector for recommendations, semantic search and music similarity, plus fuzzy search, full-text search, JSON columns, and locks and triggers for background tasks. Multiple web containers and the worker can write concurrently.

Supporting another database would require alternatives for those features and testing every query on each database. The supplied Docker Compose setup already runs PostgreSQL in its own container; the backup guide explains how to protect its data.

Why does Lumastra need two Valkey instances?

They have different jobs and memory policies. The cache instance holds data that Lumastra can fetch or calculate again, so it can discard older entries when its memory budget is full.

The task instance holds job queues, locks, and shared session and playback coordination. It uses persistent storage and a policy that prevents keys from being discarded to make room.

Memory policies apply to a whole Valkey instance. Separate database numbers or key prefixes would not isolate them. Docker Compose configures both instances for you, and they can run on the same machine.

Apps and features

Which apps can I use with Lumastra?

Use the web app or the native iPhone, iPad and Apple TV apps, available through public TestFlight. The iPhone and iPad app supports offline playback and smart automatic downloads.

Jellyfin apps connect without a Jellyfin server. Tested with Streamyfin, Moonfin and the Jellyfin Android TV app.

Subsonic music clients and the native API for third-party players are included.

Is there an Android or Android TV app?

There is no native Android or Android TV app. On Android, you can install the web app from your browser.

Jellyfin-compatible clients such as Streamyfin can connect through the Jellyfin bridge, and Subsonic or OpenSubsonic clients can connect for music.

What role does Audiobookshelf play?

Audiobookshelf provides the audiobook metadata and audio. Lumastra streams the books through its own server, so they sit in the same apps and interface as your movies and music. Apps connect through the Lumastra API, which translates requests for Audiobookshelf.

You can keep using the Audiobookshelf apps too. Listening progress syncs both ways, so you can start a book in one app and continue in the other.

Can developers build their own players?

Yes. Lumastra provides a documented, versioned API for third-party players, including playback, smart downloads and notifications.

The native API is part of the AGPL-3.0 code.

How do AI and privacy work?

You host the library and choose which integrations to enable. AI features use your own provider credentials. Relevant prompts or text may be sent to that provider, and provider usage may cost extra. Lumastra does not include an AI key.

The data-flow guide explains what each integration sends.

Does Lumastra need the internet, and what does it send?

Core scanning, browsing and playback can work without an internet connection once the required binaries are available locally. Fetching new metadata, artwork and updates, using cloud AI providers, and delivering push notifications need access to their services.

By default, the server can contact external services for FFmpeg downloads, update checks and metadata or artwork. Push uses a relay after a user enables notifications in the iOS app.

The data-flow guide lists every destination, what it receives, when it is contacted and how to turn it off.

What does Lumastra not do?

It does not record Live TV (no DVR), and the web app has no offline downloads. The native iPhone and iPad app supports offline playback and smart automatic downloads.

Licence and the project

What does it cost?

Nothing. The server is open source under AGPL-3.0, with no paid parts. AI features use your own provider credentials, and provider usage may cost extra.

The Apple apps are closed source and free.

Why are the Apple apps closed source?

The iPhone, iPad and Apple TV apps are separate from the server and are not open source. They are free.

They use the same open, documented API available to other apps. The developer docs explain how the players work so anyone can build their own. The server stays open source.

How is Lumastra maintained?

I run it for my own household every day, and bugs and security issues get fixed. Feature ideas go to Discussions.

← Back to the start page