multi-scrobbler

multi‑scrobbler is a self‑hosted, JavaScript‑powered service that aggregates scrobble data from a wide array of media sources and forwards it to popular scrobbling backends such as Last.fm, ListenBrainz, Maloja, and Koito. Built on Node.js with an Express‑like API layer, it runs as a single process that exposes a RESTful endpoint for status and health checks. The application’s core responsibility is to translate source‑specific playback events into the canonical scrobble payload expected by each client, handling authentication, rate limits, and retry logic internally. This design allows developers to embed scrobbling into heterogeneous environments—Docker‑based media stacks, home automation hubs, or custom web dashboards—without requiring platform‑specific extensions.

Architecture & Technical Stack

• Runtime – Node.js (v18+) with a lightweight event‑driven architecture; all source adapters run as asynchronous workers that emit trackStart, trackEnd, and nowPlaying events.
• Adapters – The codebase ships with over 30 source adapters (e.g., Azuracast, Jellyfin, Mopidy, VLC, Spotify Web API, Subsonic‑compatible APIs). Each adapter implements a minimal interface: subscribe() to listen for playback changes and formatTrack() to produce the scrobble payload.
• Clients – Adapter clients are modular: Last.fm, ListenBrainz, Maloja, Koito. They expose a unified scrobble(track) method that handles OAuth, API version negotiation, and error handling. The client layer is pluggable; new clients can be added by implementing the same interface.
• Persistence – Optional SQLite or JSON file storage for queued scrobbles and credential caches; the core logic is stateless otherwise, enabling easy scaling behind a reverse proxy or in a Docker swarm.
• Configuration – Environment variables or a JSON file drive all settings. Sensitive data (API keys, OAuth secrets) can be injected via Docker secrets or Kubernetes Secret objects. Regex filters and search patterns allow fine‑grained metadata transformation before scrobbling.

Core Capabilities

• Source‑to‑Client Mapping – One or many sources can be mapped to one or more clients; the mapping is expressed in a declarative config section, supporting per‑user overrides for family or team setups.
• Now‑Playing & Scrobble Queue – Clients that support the “now playing” endpoint receive immediate updates; scrobbles are queued locally and retried on transient failures, ensuring data integrity even behind flaky networks.
• Webhook & Health Monitoring – The service exposes a /health endpoint and can push status updates to Gotify, Ntfy, or Apprise. This is useful for integration into monitoring stacks (Prometheus, Grafana) or home‑automation alerts.
• Metadata Transformation – Regular expressions and search patterns can strip suffixes, normalize artist names, or map tracks to custom genres before sending them downstream.

Deployment & Infrastructure

• Containerization – Official Docker images are available for both x86_64 and ARM architectures, making it trivial to deploy on Raspberry Pi, NAS devices, or cloud VMs. The image is built from a slim Node base and exposes only the necessary ports.
• Scalability – Because the service is stateless (aside from optional local persistence), it can be replicated behind a load balancer. The adapter workers are lightweight and can be scaled independently if a particular source generates high event rates.
• Self‑Hosting Requirements – Minimal: Node.js runtime or a container runtime, network access to the source APIs and scrobble clients, and optional storage for persistence. No external databases are required unless you enable the SQLite queue.

Integration & Extensibility

• Plugin System – New source adapters or client backends can be added by implementing the defined interfaces; the core library automatically discovers modules in a plugins/ directory.
• Webhooks & Events – External services can subscribe to internal events via a simple HTTP callback mechanism, allowing real‑time dashboards or custom analytics pipelines.
• Configuration API – A REST endpoint (/config) can be enabled to modify source/client mappings on the fly, facilitating dynamic re‑configuration without restarting the service.

Developer Experience

• Documentation – The project hosts comprehensive docs on ReadTheDocs, covering configuration examples for every supported source and client. Code comments are plentiful, and the public API is stable.
• Community & Licensing – MIT‑licensed, encouraging commercial use. The repo has an active issue tracker and a Slack channel for quick support.
• Testing – Unit tests cover adapter logic, and integration tests simulate source events, making it safe to fork and extend.

Use Cases

1. Home Media Server – A Raspberry Pi running Jellyfin, Mopidy, and Spotify Connect can feed all playback events to a single multi‑scrobbler instance, ensuring consistent scrobbling across devices.
2. Family Music Analytics – By configuring per‑user credentials, parents can aggregate listening stats for children while still using a shared scrobbling account.
3. Automation Pipelines – Home‑automation systems (Home Assistant, OpenHAB) can trigger scrobble events via the webhooks API, enabling smart lighting or notifications tied to music playback.
4. Enterprise Music Discovery – Organizations can deploy