Getting started

Alumira is a self-hosted media server for a personal collection of films and series. Each file is encoded once, ahead of time, into CMAF stems (one per video quality, audio language and subtitle); playback serves them as they are, with no transcoding, as multi-track / multi-bitrate HLS to a media-first web interface that also works with a TV remote (D-pad).

Specification: what Alumira does and why. The code is the reference; the specification follows it.

Requirements

Go ≥ 1.25 and Node ≥ 20 (to build).
FFmpeg + ffprobe ≥ 7, with libx264 and libx265; libsvtav1, libopus, libvmaf (quality control) and zimg (zscale) are recommended, and for the video chips NVENC, Quick Sync, AMF, VideoToolbox or VA-API with their drivers.

Alumira and its workers run the FFmpeg installed on the machine, as separate programs: neither distribution includes it. It is looked up in this order: the -ffmpeg option (or ALUMIRA_FFMPEG), an ffmpeg/ directory next to the executable, then the PATH.

System	Command	Other builds
macOS	`brew install ffmpeg`	static builds: https://ffmpeg.martin-riedl.de
Windows	`winget install Gyan.FFmpeg`	"gpl" builds: https://github.com/BtbN/FFmpeg-Builds
Linux	the distribution's package (`apt install ffmpeg`…)	static "gpl" builds: https://github.com/BtbN/FFmpeg-Builds

Homebrew's build has VideoToolbox but no zimg; distribution packages (Debian, Alpine…) often lack libvmaf; the static builds above have both.

Build and run

cd web && npm install && npm run build && cd ..
go build -o alumira ./cmd/alumira
./alumira serve -listen :7575

Open http://localhost:7575: the onboarding guides the first install (admin account, network, stores, sources, encoding, ladder, metadata, bandwidth, languages, backups, invitations).

Useful options:

Option	Effect
`-data DIR`	server data (default: the OS application data directory)
`-listen ADDR`	HTTP listen address (default `:7575`, or `ALUMIRA_LISTEN`)
`-ffmpeg DIR`	directory containing ffmpeg and ffprobe (or `ALUMIRA_FFMPEG`)
`-no-worker`	disable the built-in encoding worker
`-web DIR`	serve the web UI from disk during development (e.g. `web/dist`)
`-reset`	start over from the onboarding (see below)
`-reset-stores`	with `-reset`: also delete the stems of the previous setup (`-yes` skips the confirmation)

Desktop app

cmd/alumira-desktop (macOS, Windows): the app in a window of its own, with an icon in the menu bar or the notification area; it hosts the server or shows one of the network. Built with scripts/build-desktop.sh on a Mac (cgo for macOS; Docker for the Windows installer, NSIS); go run ./scripts/icons makes its icons again from the logo.

Docker (NAS)

The Dockerfile at the root builds an image of Alumira beside an FFmpeg with the video chips' drivers (VA-API and Quick Sync with Intel's, NVENC), for amd64 or arm64: what a NAS needs (Asustor, Synology, QNAP, Unraid…), whose system has no such FFmpeg.

docker buildx build --platform linux/amd64 -t alumira .

services:
  alumira:
    image: alumira
    restart: unless-stopped
    ports: ["7575:7575"]
    devices: ["/dev/dri:/dev/dri"]   # Intel chip: Quick Sync, VA-API
    volumes:
      - /volume1/Docker/Alumira:/data   # its data
      - /volume1:/volume1   # the whole volume, at the same path: stores and sources are chosen in the onboarding

The volume is mounted at the same path inside as on the NAS: the paths Alumira shows are the NAS's, and its onboarding picks the stores and sources there. With network_mode: host in place of ports, the desktop apps of the network find it by themselves; otherwise its address is typed in them. Without /dev/dri (or on a NAS without a video chip), it encodes with the processor and converts nothing on the fly.

For Alumira Connect (an address on the Internet in one click), network_mode: host: Alumira asks the router to open its port and knows the machine's IPv6 address only from there.

Where the data lives

What	Where
Setup, users, catalogue, queues (SQLite `alumira.db`), images, backups	the data directory: `~/Library/Application Support/Alumira` (macOS), `%APPDATA%\Alumira` (Windows), `$XDG_DATA_HOME/alumira` or `~/.local/share/alumira` (Linux); `-data` or `ALUMIRA_DATA` to change it
Normalized stems	the stores chosen during onboarding, under `media/` (plus a `.alumira-store` marker)
Originals	the sources: never modified, except `inbox` files moved to `.alumira-trash` once normalized

Starting over

./alumira serve -reset sets the current setup aside (the data directory is renamed to <dir>.reset-<date>, nothing is deleted) and starts again from the onboarding. Rename the directory back to undo it.

The stems written by the previous setup stay in its stores. -reset -reset-stores deletes them too, after confirmation: they are the only copy of inbox files already moved to the trash.

Console output

Alumira prints one line per meaningful event: encoder detection, storage, new files, identifications, finished passes, failures, workers. Bulk activity is grouped into a single summary line.

Variable	Effect
`ALUMIRA_COLOR=always\|never`	force colours on or off (automatic on a terminal; `NO_COLOR` is honoured)
`ALUMIRA_DEBUG_HTTP=1`	print failed or slow HTTP requests
`ALUMIRA_DEBUG_FF=1`	debug events on whatever the setting (the ffmpeg command lines among them)
`ALUMIRA_STABLE_SECONDS`	delay before a new file is considered complete (default 60)

Encoding workers

In Administration → Workers → Add, copy the displayed command, for example:

./alumira-worker -server http://alumira.lan:7575 -token <token>

Run it from the worker's folder; the server and token are then remembered (user configuration folder), so ./alumira-worker alone starts it next time.

The administration names the machine and sets how many chunks it encodes at once; the name the machine gives itself is shown as a hint. SIGTERM (or "Pause" in the administration) finishes the current chunks, then stops the worker: handy for updates. A paused machine stays paused until "Resume", even when started again.

Encoders are tested at startup. On a busy machine, a test that fails slowly, or that contradicts the previous detection of the same FFmpeg build, is tried again; what stays inconclusive keeps its previous answer and is tested again 10 minutes later.

The worker is a distribution of its own (scripts/build-worker.sh, see Packages): for macOS, Windows and Linux, a command-line program with a README and, to start it with the machine, a launchd agent or a systemd unit. It remembers the server and the token once accepted: ./alumira-worker alone is enough afterwards. Like Alumira, it runs the FFmpeg installed on the machine (see Requirements).

A worker takes the chunks of a job whose encoder it can run for each rendition (§7.3), whatever its FFmpeg build. Each job picks the encoder most machines online share: with a Windows PC, a Mac server in speed mode moves from VideoToolbox to libx264 to share the work.

Development

scripts/make-corpus.sh               # test media corpus (testdata/corpus)
go test ./...                        # tests (use the corpus and FFmpeg)
./alumira dev fake-tmdb              # fake TMDB and OpenSubtitles, to develop without keys
ALUMIRA_TMDB_BASE=http://127.0.0.1:7599/3 ALUMIRA_OPENSUBTITLES_BASE=http://127.0.0.1:7599/os/api/v1 ./alumira serve -web web/dist

Packages

scripts/build.sh          # Alumira: web app + server, archives in dist/
scripts/build-worker.sh   # encoding workers (macOS, Windows, Linux), archives in dist-worker/
scripts/build-desktop.sh  # the desktop app: macOS disk image, Windows installer, in dist-desktop/
scripts/release.sh        # a release: the desktop app, macOS, Windows, Docker images for amd64 and arm64, workers, README and SHA256SUMS, in release/<version>/

The version (the date by default, VERSION=2026.10.06) is the one the server and the workers show.

Licence

Alumira is free software under the GNU Affero General Public License, version 3 or later (LICENSE file at the root of the repository): it may be used, studied, modified and shared; whoever runs a modified version for others, over a network included, must offer them its source code. A commercial licence is available for uses that cannot meet these terms (an appliance, a closed product). Contributions are accepted under the contributor agreement (CLA.md). "Alumira" and its logo are trademarks: a fork takes another name.

Each distribution carries LICENSE and THIRD_PARTY_LICENSES.md, the licences of the components it includes.

Documentation

The documentation is written in Markdown in docs/en and docs/fr (same files in both languages). The HTML site is generated with:

go run ./scripts/docs            # writes docs/site

The generator reports pages or sections present in one language only.