Lidify

Lidify is a lightweight, self‑hosted music discovery service that surfaces new releases and related tracks for artists already tracked in Lidarr. Built to run inside Docker, it consumes Lidarr’s API to fetch artist metadata and then queries a music‑information provider (currently Last.fm) to generate curated recommendations. The application exposes a small REST interface and a web UI, enabling developers to embed it into larger media‑management stacks or expose its endpoints to external tooling.

Technical Stack & Architecture

• Runtime: The core is a Python 3 application that leverages the FastAPI framework for its web layer, providing both synchronous and asynchronous request handling.
• Data Layer: Lidarr acts as the sole persistent store; Lidify does not maintain its own database. All state is derived from Lidarr’s API responses and the Last.fm cache (if enabled).
• External APIs:
  • Lidarr API – authentication via API key, endpoints for artists, albums, and queue operations.
  • Last.fm API – uses the public web service to fetch artist tags, similar artists, and track recommendations. The integration is fully stateless; the app forwards requests directly to Last.fm without caching, though developers can add a local cache layer if needed.
• Configuration: All tunables are environment variables, making it trivial to adjust IDs, timeouts, and feature flags without code changes. The Docker image ships with sensible defaults for a typical home‑media server.

Core Capabilities & Developer APIs

• Artist Recommendation Engine: Given a Lidarr artist ID, the service retrieves the artist’s Last.fm tag set and queries the “getSimilar” endpoint to surface related artists. It then cross‑references those artists against Lidarr’s catalog, returning only those not yet tracked.
• Album Search & Queue: When enabled, Lidify can automatically enqueue missing albums for download in Lidarr. The search_for_missing_albums flag triggers a background task that performs an album search via Lidarr’s /search endpoint and pushes results to the queue.
• Webhook‑Friendly: The application can be wired into Lidarr’s webhook system; on artist addition, a POST to Lidify triggers the recommendation flow.
• Extensible Discovery Modes: Though currently limited to Last.fm, the codebase is structured around a DiscoveryProvider interface, making it straightforward for contributors to add support for Spotify (historically) or other services.

Deployment & Infrastructure

• Containerization: A single‑layer Docker image (thewicklowwolf/lidify) is available on Docker Hub. It expects a bind mount for /lidify/config to persist environment variables or an external secrets manager.
• Scalability: As a stateless service, multiple instances can run behind a load balancer to handle high query volumes. The only shared resource is Lidarr, so scaling should be coordinated with Lidarr’s own performance limits.
• Resource Footprint: The app requires minimal RAM (≈50 MiB) and CPU (<0.1 GHz idle), making it ideal for a Raspberry Pi or NAS host.

Integration & Extensibility

• Plugin System: While no formal plugin API exists, the modular design around providers means developers can fork the repository and add new discovery engines.
• Configuration Options: The rich set of environment variables covers user IDs, API keys, timeouts, quality profiles, and more. These can be injected via Docker Compose or Kubernetes ConfigMaps/Secrets.
• Community & Documentation: The project’s GitHub repo hosts a concise README, issue tracker, and community discussions. Although the documentation is lightweight, it covers all necessary environment variables and explains the workflow clearly.

Use Cases

1. Home Media Server Automation – A dev can deploy Lidify alongside Sonarr/Lidarr on a NAS, enabling automatic discovery of related artists whenever a new artist is added.
2. Custom Recommendation API – Expose the /recommendations endpoint to a front‑end app or voice assistant, letting users query for new music based on their existing library.
3. Testing & CI Pipelines – Use Lidify in a Docker‑Compose test environment to validate Lidarr integration before pushing changes upstream.

Advantages for Developers

• Zero‑Configuration Self‑Hosting – No database setup, no external services beyond Lidarr and Last.fm.
• Lightweight & Fast – Python + FastAPI delivers sub‑second responses, keeping latency low for UI interactions.
• Open Source & MIT Licensed – Free to modify and redistribute, with no licensing constraints that could impede commercial deployments.
• Extensible Architecture – The provider interface and environment‑driven configuration make it straightforward to swap APIs or add new features without touching the core.

In summary, Lidify offers developers a focused, container‑ready tool that bridges Lidarr’s catalog with Last.fm’s recommendation engine. Its minimal footprint, clear API surface, and flexible configuration make it a pragmatic choice for automating music discovery in self‑hosted media environments.