ServeMedia

ServeMedia is The Self-Hosted Media-Server for Linux. It is built around a core application called MatchMedia which acts as a statistical engine responsible for directory hierarchy discovery of media libraries, title extraction and grouping, metadata search-and-fetch from providers like TVMaze, statistically scoring and ranking candidates and mapping them to the appropriate files. ServeMedia is built to be lightweight, minimal and concise, yet feature-complete for a self hosted media server. ServeMedia provides a desktop entry which starts its services then opens the browser pointed to its webpage (port 7676), which is server-side-rendered and provides a home theater experience, complete with dri accelerated hls streamed video playback.

Warning

ServeMedia is currently in Beta, users might face some breaking bugs or incomplete functionality. Work is being done to remedy any issues, please feel free to open up issues on github

Requirements

• Linux x86_64
• GPU transcode:
  1. host Mesa/libva when present for Harware Acceleration (on GPU/iGPU)
  2. otherwise software encode (on CPU)

Install

As a Desktop Application

AppImage (Download)	Flatpak (Download)	AppImage (Install with AppManager)	Flatpak (Install with Gnome Software)

Flatpak

Needs org.freedesktop.Platform.ffmpeg-full (26.08).

flatpak run eu.alyshmahell.ServeMedia

• Sandbox can already read /media, /mnt, /run/media, ~/Videos, and ~/Music.
• Extra media library directories:

  flatpak override --user --filesystem=/path/to/library eu.alyshmahell.ServeMedia

As a Server Application

curl -fL https://github.com/AlyShmahell/ServeMedia/releases/latest/download/servemedia-linux-amd64.tar.gz \
  | tar -xz -C "$HOME" --strip-components=1 servemedia/.local

Start

• Desktop entry, flatpak run eu.alyshmahell.ServeMedia, or servemedia
• Browser opens on port 7676 (SERVEMEDIA_NO_BROWSER=1 skips that)
• A second start opens the app and exits if ServeMedia is already listening
• First visit is /register and creates the admin; after that /register is gone
• Other users: Settings → Users

How to

Start ServeMedia, create the admin, add a library, open a title, and play.

Create the admin account.

Home with libraries and recently added titles.

Anime library poster grid.

Title page with plot and seasons.

Season page with episode stills.

Browser playback.

Controls

Arrow keys or a gamepad move focus on Home, libraries, titles, and Settings. The focus outline appears while using arrows or a pad, not for mouse-only use.

If the pad does nothing in Firefox from Flathub, grant host udev, then fully quit Firefox and reopen ServeMedia:

flatpak override --user --filesystem=/run/udev:ro org.mozilla.firefox

Same grant works in Flatseal. Other Flatpak browsers: use that app’s ID. Distro Firefox usually needs nothing extra.

Media

Default media library roots: /mnt, /media, $XDG_VIDEOS_DIR, $XDG_MUSIC_DIR.

	Flatpak	AppImage
Data	~/.var/app/eu.alyshmahell.ServeMedia/data/servemedia/	~/.local/share/servemedia/
MatchMedia Config Overlay	…/config/overlay.yaml	…/config/overlay.yaml
Cache	~/.var/app/eu.alyshmahell.ServeMedia/cache/servemedia/transcode	~/.cache/servemedia/transcode

Misc

• Provider keys and MatchMedia YAML: Settings → Engines → MatchMedia
• FFMPEG Hardware Acceleration Status: Settings → Engines → FFMPEG
• Scan: Home → add a library (3 Scan modes to choose from)

Developers:

docs/architecture.md.