Gerbera

Gerbera is a fully‑self‑hosted UPnP/DLNA media server that exposes local and remote media to any compliant renderer on a home network. At its core, it implements the UPnP AV‑Transport and ContentDirectory services defined by the UPnP Media Server specification, allowing devices such as smart TVs, game consoles, and media players to browse a database of audio, video, images, and streaming URLs. The server is written in C++17 and uses the pupnp library (a fork of libupnp) for network discovery, control point communication, and eventing. The application is built with CMake and supports cross‑platform compilation on Linux, BSD, macOS, Windows (via MinGW), ARM, MIPS, and other architectures.

Architecture

• Core Engine – A single‑threaded event loop that handles UPnP SSDP announcements, SOAP requests, and asynchronous media access. The engine is modular: each protocol service (ContentDirectory, AVTransport, RenderingControl) is implemented as a separate component that plugs into the pupnp runtime.
• Metadata Layer – Uses libmagic for MIME detection and a set of dedicated parsers (TagLib, ExifTool, FFmpeg) to extract tags from audio/video files. The extracted metadata is stored in an SQLite database that the web UI and UPnP services query.
• Web Interface – A lightweight HTTP server (built on libmicrohttpd) serves a tree‑view UI written in vanilla JavaScript. The UI interacts with the server via REST endpoints that expose CRUD operations on media entries and configuration settings.
• Transcoding & Thumbnail Generation – The server delegates transcoding to external scripts or the ffmpeg binary. On‑the‑fly thumbnail creation is handled by a background worker that can generate JPEG/PNG thumbnails for images and video frames.
• Extensibility – Gerbera exposes a plugin API for custom media filters, layout generators, and metadata enrichers. Plugins are shared libraries that implement a simple C interface; they can be loaded at runtime via the --plugin command‑line flag or a configuration file.

Core Capabilities

• Full UPnP Support – Implements the full ContentDirectory schema (including Container, Item, and DIDL‑Lite serialization) and AVTransport actions (SetAVTransportURI, Play, Pause, etc.).
• Metadata Extraction – Supports over 30 audio formats (MP3, FLAC, AAC, OGG, M4A), video codecs (H.264/AVC, H.265/HEVC, MPEG‑2), and image types (JPEG, PNG). Metadata is automatically refreshed on file change via inotify or scheduled rescans.
• Dynamic Layouts – Users can write JavaScript functions that receive the metadata database and return a tree structure. This allows custom grouping (e.g., by artist, genre, or custom tags) that is then reflected on all UPnP clients.
• External URLs – The server can host arbitrary HTTP/HTTPS links as virtual media items, enabling streaming from services like YouTube or internet radio without local storage.
• Last.fm Scrobbling – Built‑in integration with the Last.fm API for tracking played tracks on compatible devices.

Deployment & Infrastructure

Gerbera is designed to run as a long‑running daemon on home servers or NAS devices. It has minimal external dependencies (pupnp, SQLite, FFmpeg) and can be bundled in a Docker image (gerbera/gerbera) that exposes ports 3480 (UPnP) and 8080 (web UI). For production use, the daemon can be managed by systemd or supervisord. Scaling is achieved by running multiple instances on separate network segments and using a shared database (SQLite with WAL mode) or an external PostgreSQL backend for larger libraries. The lightweight footprint (<50 MiB binary, <200 MiB RAM usage) makes it suitable for embedded ARM boards like Raspberry Pi or ODROID.

Integration & Extensibility

• Plugin System – Developers can write C/C++ or Python plugins that hook into media ingestion, metadata enrichment, and layout generation. The API is documented on ReadTheDocs, with examples for adding custom tags or filtering out specific file types.
• Webhooks – The REST API supports POST callbacks that can trigger external services (e.g., a media crawler, notification system) whenever the library changes.
• Custom Scripts – Transcoding and thumbnail creation can be scripted, allowing integration with cloud transcoding services or GPU‑accelerated encoders.

Developer Experience

Gerbera’s documentation is hosted on ReadTheDocs and follows a clear structure: Getting Started, Architecture, API Reference, Plugin Development, and Contributing. The community is active on libera.chat (#gerbera) and GitHub issues. Configuration is file‑based (gerbera.conf) with support for environment variables, making it easy to integrate into CI/CD pipelines. The codebase is open‑source under the GPL‑3.0 license, ensuring that any modifications remain free and shareable.

Use Cases

1. Home Media Server – Stream a local music or video library to multiple smart TVs and mobile devices without manual uploads.
2. IoT Media Gateway – Deploy on a Raspberry Pi to provide a lightweight media hub for a smart home setup.
3. Embedded Device – Integrate into an appliance (e.g., a custom media player) where UPnP support is required but resources are limited.