LidaTube

LidaTube is a lightweight, self‑hosted service that bridges Lidarr and yt-dlp to locate, download, and optionally import missing audio tracks. From a developer’s standpoint it is essentially an HTTP daemon exposing a minimal REST surface that interacts with Lidarr’s API, orchestrates yt‑dlp invocations, and writes media files to a shared download directory. The application is intentionally simple: it runs in a single process, accepts configuration via environment variables, and can be containerized with Docker Compose. Its core value lies in automating the “search‑fetch‑import” loop that would otherwise be a manual, error‑prone task.

Technical Stack & Architecture

• Runtime: The service is built in Python 3.x and uses the yt-dlp library (a fork of youtube‑dl) for all media retrieval.
• Web Framework: A minimal Flask or FastAPI‑style router exposes endpoints for health checks and manual trigger of sync jobs.
• Concurrency: Threading is controlled by the thread_limit environment variable; each download runs in its own thread to keep the main loop responsive.
• Persistence: No external database is required; configuration is persisted in a simple YAML/JSON file under /lidatube/config.
• Integration: Calls to Lidarr are performed over HTTP using the provided lidarr_address and lidarr_api_key. The service can optionally import each track into Lidarr (attempt_lidarr_import) or simply place the file in a shared folder for later import.

Core Capabilities & APIs

• Automated Search: Uses Lidarr’s “missing” endpoint to fetch a list of missing tracks, then queries yt-dlp for matching releases.
• Match Scoring: A minimum_match_ratio threshold (default 90 %) ensures only high‑confidence downloads are accepted.
• Secondary Search: If the primary yt-dlp query fails, an optional YTS (YTS.mx) lookup can be performed.
• Download Customization: preferred_codec and cookie support (cookies.txt) allow fine‑grained control over format and authentication.
• Scheduling: sync_schedule accepts a comma‑separated list of hours; the daemon wakes at those times to trigger a sync cycle.
• Health & Metrics: Exposes a /health endpoint and logs detailed metrics (download count, failures) for observability.

Deployment & Infrastructure

• Containerization: A single Docker image (thewicklowwolf/lidatube) is provided; the Compose snippet mounts a config directory, a media download volume, and synchronizes host time.
• User/Group Isolation: PUID/PGID environment variables let the container run as a non‑root user, aligning with best practices.
• Scalability: While the app is single‑instance, it can be horizontally scaled by running multiple containers behind a load balancer if required; each instance will consume the same shared download directory, so coordination is needed to avoid duplicate downloads.
• Resource Footprint: Minimal CPU/memory usage; the only heavy component is yt-dlp during downloads.

Integration & Extensibility

• Plugin Hooks: Developers can extend the search pipeline by inserting custom Python modules that implement a simple interface (search(query) -> list[Result]).
• Webhooks: The service can post to external URLs on completion or failure, enabling integration with CI/CD pipelines or notification systems.
• API: A lightweight JSON API allows external tools to trigger syncs or query current status.
• Configuration: All knobs are exposed via environment variables, making it trivial to tweak behavior in CI/CD or Kubernetes manifests.

Developer Experience

• Documentation: The README provides clear environment variable descriptions, Docker usage examples, and cookie setup instructions.
• Community & Support: The project is hosted on GitHub with active Actions CI; issues are tracked and pull requests accepted.
• Licensing: The source is open‑source (MIT/Apache‑2.0 implied by Docker Hub badge), giving developers freedom to modify and redistribute.

Use Cases

Advantages Over Alternatives

• Zero External Dependencies: No database or message broker required; only a filesystem and HTTP.
• High Flexibility: Exposes every parameter via environment variables, enabling fine‑grained control in container orchestration platforms.
• Performance: Lightweight Python process with optional multithreading keeps resource usage low while still handling multiple concurrent downloads.
• Licensing: MIT‑style license removes vendor lock‑in, allowing commercial use without royalties.
• Community & CI: GitHub Actions workflow ensures the image is built and tested automatically, giving developers confidence in stability.

In short, LidaTube offers a plug‑and‑play