Ferelix

Ferelix is a self-hosted media server, similar to Plex or Jellyfin. It allows you to organize, manage, and stream your personal media collection from your own server.

Architecture

Ferelix is organized as a server plus client applications:

• Server - The backend API and media management engine built with Python
• Web - The Vue dashboard and media player, with playback orchestration split from reusable player controls and UI helpers

Quick Start

Prerequisites

• Python 3.14+ and uv - For the backend server
• pnpm - For the web frontend
• ffmpeg - For video metadata extraction and generated HLS playback
• just - Command runner (optional but recommended)

Install Just (Command Runner)

Just is a handy command runner that makes working with this monorepo easier:

# Debian/Ubuntu
sudo apt install just

Verify installation:

just --version

Install Dependencies

# Using just (recommended)
just install

# Or manually
cd server && uv sync
cd clients/web && pnpm install

Run Development Servers

# Start both backend and frontend together
just dev

# Or start them separately in different terminals
just dev-server   # Backend only
just dev-web      # Frontend only

The server will be available at http://localhost:8005 and the web client at http://localhost:5187.

Transcoding Configuration

Ferelix defaults to the ffmpeg binary on PATH. To run a packaged build such as jellyfin-ffmpeg, point the server at it without changing code:

export FERELIX_FFMPEG_PATH=/usr/lib/jellyfin-ffmpeg/ffmpeg
export FERELIX_TRANSCODE_DIR=/tmp/ferelix-transcode
export FERELIX_THUMBNAIL_DIR=/tmp/ferelix-thumbnails

The player uses DirectPlay when possible, HLS remux for compatible streams in unsupported containers, audio-only transcode when only audio is incompatible, and full HLS transcode as the fallback. Library scans also use ffmpeg to extract a representative thumbnail screenshot for each media card.

Hardware transcoding is detected automatically from the devices visible to the Ferelix process. The Docker image includes vainfo and Mesa VAAPI drivers so AMD/Intel devices can report their codec capabilities from inside the container. Expose the host GPU first:

# AMD/Intel VAAPI
--device /dev/dri:/dev/dri

# NVIDIA NVENC/NVDEC
--runtime=nvidia
-e NVIDIA_VISIBLE_DEVICES=all
-e NVIDIA_DRIVER_CAPABILITIES=all

Ferelix tests the visible FFmpeg encoders at runtime and uses auto by default. Admins can pin a specific detected device, or force software encoding, from Dashboard > Settings > Hardware Transcoding. The optional FERELIX_HW_ACCEL_DEVICE environment variable accepts the same values (auto, software, or a detected device id such as vaapi:/dev/dri/renderD128).

Discover Available Commands

just --list

or simply:

just

This will show all available commands you can run.

Detailed Setup

For detailed setup instructions, configuration, and development guidelines, refer to the individual README files:

• Server setup: server/README.md
• Web setup: clients/web/README.md

License

See LICENSE for details.