Démarrer

Alumira est un serveur multimédia auto-hébergé pour les films et séries d'un foyer, présentés comme un service de streaming à soi : les visuels d'abord, un profil pour chacun, toutes les versions et toutes les langues d'un titre. Il se regarde dans une interface web utilisable aussi à la télécommande (D-pad), en HLS multi-piste / multi-bitrate.

Chaque fichier est soit pré-encodé (encodé une seule fois, à l'avance, en stems CMAF : un par qualité vidéo, langue audio et sous-titre, puis servis tels quels), soit en lecture directe (servi tel qu'il est, converti à la volée par la puce vidéo seulement pour un appareil qui en a besoin).

Spécification : ce que fait Alumira, et pourquoi. Le code fait foi ; la spécification le suit.

Prérequis

Go ≥ 1.25 et Node ≥ 20 (pour compiler).
FFmpeg + ffprobe ≥ 7, avec libx264 et libx265 ; libsvtav1, libopus, libvmaf (contrôle qualité) et zimg (zscale) sont recommandés, et pour les puces vidéo NVENC, Quick Sync, AMF, VideoToolbox ou VA-API avec leurs pilotes.

Alumira et ses workers utilisent le FFmpeg installé sur la machine, comme programmes séparés : aucune des deux distributions ne l'inclut. Il est cherché dans cet ordre : l'option -ffmpeg (ou ALUMIRA_FFMPEG), un dossier ffmpeg/ à côté de l'exécutable, puis le PATH.

Système	Commande	Autres builds
macOS	`brew install ffmpeg`	builds statiques : https://ffmpeg.martin-riedl.de
Windows	`winget install Gyan.FFmpeg`	builds « gpl » : https://github.com/BtbN/FFmpeg-Builds
Linux	le paquet de la distribution (`apt install ffmpeg`…)	builds statiques « gpl » : https://github.com/BtbN/FFmpeg-Builds

Le build Homebrew a VideoToolbox mais pas zimg ; les paquets des distributions (Debian, Alpine…) n'ont souvent pas libvmaf ; les builds statiques ci-dessus ont les deux.

Compiler et lancer

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

Ouvrez http://localhost:7575 : l'onboarding guide la première installation (compte admin, réseau, stores, sources, encodage, ladder, métadonnées, bande passante, langues, sauvegardes, invitations).

Options utiles :

Option	Effet
`-data DIR`	données du serveur (défaut : dossier applicatif de l'OS)
`-listen ADDR`	adresse d'écoute HTTP (défaut `:7575`, ou `ALUMIRA_LISTEN`)
`-ffmpeg DIR`	dossier contenant ffmpeg et ffprobe (ou `ALUMIRA_FFMPEG`)
`-no-worker`	désactive le worker d'encodage intégré
`-web DIR`	sert l'interface depuis le disque pendant le développement (ex. `web/dist`)
`-reset`	repart de l'onboarding (voir plus bas)
`-reset-stores`	avec `-reset` : supprime aussi les stems de l'installation précédente (`-yes` saute la confirmation)

Application de bureau

cmd/alumira-desktop (macOS, Windows) : l'application dans une fenêtre à elle, avec une icône dans la barre des menus ou la zone de notification ; elle héberge le serveur ou affiche un serveur du réseau. Construite avec scripts/build-desktop.sh sur un Mac (cgo pour macOS ; Docker pour l'installeur Windows, NSIS) ; go run ./scripts/icons refait ses icônes depuis le logo.

Docker (NAS)

Le Dockerfile à la racine construit une image d'Alumira avec un FFmpeg doté des pilotes des puces vidéo (VA-API et Quick Sync avec ceux d'Intel, NVENC), pour amd64 ou arm64 : ce qu'il faut à un NAS (Asustor, Synology, QNAP, Unraid…), dont le système n'a pas un tel FFmpeg.

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

services:
  alumira:
    image: alumira
    restart: unless-stopped
    ports: ["7575:7575"]
    devices: ["/dev/dri:/dev/dri"]   # puce Intel : Quick Sync, VA-API
    volumes:
      - /volume1/Docker/Alumira:/data   # ses données
      - /volume1:/volume1   # tout le volume, au même chemin : stores et sources se choisissent dans l'accueil

Le volume est monté au même chemin dedans que sur le NAS : les chemins qu'affiche Alumira sont ceux du NAS, et son onboarding y choisit stores et sources.

Préférez network_mode: host à ports :

les applications de bureau du réseau le trouvent d'elles-mêmes (sinon on y tape son adresse) ;
Alumira Connect (une adresse sur Internet en un clic) en a besoin : Alumira ne peut demander à la box d'ouvrir son port, et ne connaît l'adresse IPv6 de la machine, que de là.

Sans /dev/dri (ou sur un NAS sans puce vidéo), il encode avec le processeur et ne convertit rien à la volée.

Où sont les données

Quoi	Où
Setup, utilisateurs, catalogue, files d'attente (SQLite `alumira.db`), images, sauvegardes	le dossier de données : `~/Library/Application Support/Alumira` (macOS), `%APPDATA%\Alumira` (Windows), `$XDG_DATA_HOME/alumira` ou `~/.local/share/alumira` (Linux) ; `-data` ou `ALUMIRA_DATA` pour le changer
Stems normalisés	les stores choisies à l'onboarding, dans `media/` (plus un marqueur `.alumira-store`)
Originaux	les sources : jamais modifiées, sauf les fichiers `inbox`, supprimés une fois encodés

Repartir de zéro

./alumira serve -reset met l'installation actuelle de côté (le dossier de données est renommé en <dossier>.reset-<date>, rien n'est supprimé) et repart de l'onboarding. Renommer le dossier annule l'opération.

Les stems écrits par l'installation précédente restent dans ses stores. -reset -reset-stores les supprime aussi, après confirmation : ce sont les seules copies des fichiers inbox déjà passés en corbeille.

Sortie console

Alumira affiche une ligne par événement utile : détection des encodeurs, stockage, nouveaux fichiers, identifications, passes terminées, échecs, workers. L'activité de masse est regroupée en une ligne de résumé.

Variable	Effet
`ALUMIRA_COLOR=always\|never`	force ou coupe les couleurs (automatiques sur un terminal ; `NO_COLOR` est respecté)
`ALUMIRA_DEBUG_HTTP=1`	affiche les requêtes HTTP en erreur ou lentes
`ALUMIRA_DEBUG_FF=1`	événements de débogage activés quel que soit le réglage (dont les commandes ffmpeg)
`ALUMIRA_STABLE_SECONDS`	délai avant qu'un nouveau fichier soit considéré complet (défaut 60)

Workers d'encodage

Dans Administration → Workers → Ajouter, copiez la commande affichée, par exemple :

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

À lancer depuis le dossier du worker. Une fois acceptés, le serveur et le jeton sont retenus (dossier de configuration de l'utilisateur) : ./alumira-worker suffit la fois suivante.

Le worker est une distribution à part (scripts/build-worker.sh, voir Paquets) : pour macOS, Windows et Linux, un programme en ligne de commande avec un README et, pour le démarrer avec la machine, un agent launchd ou une unité systemd. Comme Alumira, il utilise le FFmpeg installé sur la machine (voir Prérequis).

L'administration nomme la machine et règle combien de chunks elle encode à la fois ; le nom que la machine se donne est affiché comme indication. SIGTERM (ou « Pause » dans l'administration) termine les chunks en cours puis arrête le worker : pratique pour les mises à jour. Une machine en pause le reste jusqu'à « Reprendre », même relancée.

Les encodeurs sont testés au démarrage. Sur une machine chargée, un test qui échoue lentement, ou qui contredit la détection précédente du même build FFmpeg, est refait ; ce qui reste incertain garde sa réponse précédente et est retesté 10 minutes plus tard.

Un worker prend les chunks d'un job dont il sait faire tourner l'encodeur de chaque rendu (spécification, §7.3), quel que soit son build FFmpeg. Chaque job choisit l'encodeur que le plus de machines en ligne partagent : avec un PC Windows, un serveur Mac en mode speed passe de VideoToolbox à libx264 pour se répartir le travail.

Développement

scripts/make-corpus.sh               # corpus de médias de test (testdata/corpus)
go test ./...                        # tests (utilisent le corpus et FFmpeg)
./alumira dev fake-tmdb              # faux TMDB et OpenSubtitles, pour développer sans clés
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

Paquets

scripts/build.sh          # Alumira : app web + serveur, archives dans dist/
scripts/build-worker.sh   # workers d'encodage (macOS, Windows, Linux), archives dans dist-worker/
scripts/build-desktop.sh  # l'application de bureau : image disque macOS, installeur Windows, dans dist-desktop/
scripts/release.sh        # une release : l'application de bureau, macOS, Windows, images Docker amd64 et arm64, workers, README et SHA256SUMS, dans release/<version>/

La version (par défaut la date, VERSION=2026.10.06) est celle qu'affichent le serveur et les workers.

Licence

Alumira est un logiciel libre sous GNU Affero General Public License, version 3 ou ultérieure (fichier LICENSE à la racine du dépôt). On peut l'utiliser, l'étudier, le modifier et le partager ; qui fait tourner une version modifiée pour d'autres, y compris via le réseau, doit leur en proposer le code source.

Les contributions sont acceptées sous l'accord de contribution (CLA.md). « Alumira » et son logo sont des marques : un fork prend un autre nom.

Chaque distribution contient LICENSE et THIRD_PARTY_LICENSES.md, les licences des composants qu'elle inclut.

Documentation

La documentation est écrite en Markdown dans docs/en et docs/fr (mêmes fichiers dans les deux langues). Le site HTML est généré par :

go run ./scripts/docs            # écrit docs/site

Le générateur signale les pages ou sections présentes dans une seule langue.