Maloja

Maloja is a lightweight, self‑hosted music scrobbling service that turns raw listening data into structured statistics. Unlike full‑blown social platforms, it focuses on a single responsibility: ingesting scrobbles via an OpenAPI‑compliant endpoint and exposing a clean REST API for querying artists, tracks, albums, and custom associations. The application is built in Python 3 using the FastAPI framework, which provides automatic OpenAPI generation and asynchronous request handling. A minimal SQLite database (or any SQL‑compatible engine via SQLAlchemy) stores user, scrobble, and metadata tables, making the data portable and easy to back up.

• Web Layer: FastAPI + Uvicorn (ASGI) delivers HTTP endpoints, WebSocket support for live updates, and a templated front‑end powered by Jinja2. The server is containerised in Docker with a multi‑stage Containerfile that installs only runtime dependencies.
• Persistence: SQLite is the default, but the SQLAlchemy ORM allows swapping for PostgreSQL or MySQL without code changes. All tables are versioned via Alembic migrations, ensuring schema evolution is safe in production.
• Background Workers: Scrobble ingestion can be throttled or batched by a lightweight Celery worker (optional). The core logic is synchronous, but the async FastAPI runtime can handle thousands of concurrent scrobbles thanks to Uvicorn’s event loop.
• Proxy Scrobbling: A configurable middleware forwards incoming scrobbles to external services (e.g., Last.fm, Libre.fm) via HTTP hooks, enabling a single source of truth while still feeding other platforms.

• Artist & Album Normalisation: Each artist or track can be associated with multiple sub‑units or collaborations; the API exposes endpoints to create, read, update, and delete these associations.
• Custom Media: Users upload images that replace the default placeholders; the image service is served via FastAPI’s static file handler.
• Manual Scrobbling UI: A lightweight web form lets users submit scrobbles for vinyl or non‑digitised sources, which are then persisted with the same API payload as automated clients.
• Scrobble Statistics: Endpoints return top artists, tracks, and albums over arbitrary time windows (day, week, month, year), with optional filtering by user or artist group.
• Webhooks & Extensions: Developers can hook into events (scrobble_received, artist_updated) using the built‑in webhook system or by extending FastAPI routers.

Maloja is designed for containerised environments. The Docker image exposes a single port (8000) and expects environment variables such as MALOJA_SKIP_SETUP, MALOJA_FORCE_PASSWORD, and MALOJA_DATA_DIRECTORY. Persisting the data directory via a Docker volume guarantees that configuration, media assets, and the database survive container restarts. For scaling, a reverse proxy (NGINX or Traefik) can route traffic to multiple instances behind a load balancer; the stateless API combined with a shared database makes horizontal scaling straightforward.

• Plugin System: While not a full‑blown plugin architecture, developers can subclass FastAPI routers or inject middleware to add new endpoints or modify request/response flows.
• Standard API: Because Maloja implements the scrobbling protocol used by many music players, existing libraries (e.g., lastfm-python) can target it without modification.
• Custom Tagging: The API allows arbitrary metadata fields on tracks and artists, enabling integration with local tagging tools or external databases.
• Webhooks: External services can subscribe to events, making Maloja a hub in a larger media ecosystem (e.g., syncing with Plex or Emby).

The codebase is intentionally small (~2 kLOC), with clear separation of concerns. Documentation resides in the repository’s README and inline docstrings, and an OpenAPI spec is auto‑generated. Community support is modest but active on GitHub issues; contributors can fork, extend, or submit PRs. The licensing is permissive (MIT), allowing commercial deployment without royalties.

• Personal Analytics: Developers building a personal dashboard can pull data via the API and render custom visualisations in React or Vue.
• Music Library Management: Integrate Maloja with a local media server (e.g., Jellyfin) to track what’s played on the network.
• Research Projects: Researchers can collect anonymised listening statistics for studies on music consumption patterns, leveraging the lightweight database.
• Enterprise Use: Companies can host Maloja internally to monitor employee listening habits for wellness programmes, benefiting from the self‑hosted nature and data sovereignty.

Maloja offers a focused, high‑performance alternative to feature‑heavy platforms. Its minimal footprint, Docker readiness, and strict separation of data from UI make it ideal for developers who need reliable scrobble ingestion without the overhead of social networking or recommendation engines. The open API, flexible storage backend, and ability to proxy scrobbles give developers full control over data flow while keeping the codebase approachable and maintainable.