Meelo

Meelo is a self‑hosted media server focused on music collections, offering a rich browsing and playback experience comparable to Plex or Jellyfin but with advanced cataloging semantics. From a technical standpoint, it ingests raw media files, extracts metadata via embedded tags or filename heuristics, and normalizes the data into a relational schema that supports complex relationships such as releases, versions, B‑sides, and exclusive tracks. The server exposes a RESTful API for programmatic access, enabling developers to build custom clients or integrate with existing workflows.

Architecture

• Backend: Written in Go, leveraging the Echo web framework for routing and middleware. The choice of Go ensures low runtime memory footprint and high concurrency, essential for serving audio streams to multiple clients simultaneously.
• Database: PostgreSQL is the primary persistence layer. The schema is heavily normalized, with tables for artists, albums, releases, tracks, and media files. Indexes on foreign keys and full‑text search fields allow efficient querying of large libraries.
• Media Handling: FFmpeg is invoked for transcoding on demand, ensuring browser‑compatible formats. Meelo parses container metadata using the go-mp3 and go-mkv libraries, falling back to custom regex parsing when tags are missing.
• API: A JSON‑based REST API provides endpoints for library browsing, playback URLs (signed with JWT), and webhook hooks. The API is documented in OpenAPI format, available at /docs.

Core Capabilities

• Advanced Cataloging: Support for multiple releases per album, track versions, and automatic detection of featuring artists or duets. These features are exposed via dedicated endpoints (/albums/{id}/releases, /tracks/{id}/versions).
• Metadata Enrichment: Pulls genres, descriptions, and ratings from external services (MusicBrainz, Genius, Wikipedia) through configurable adapters. Developers can add new providers by implementing a simple interface.
• Scrobbling & Lyrics: Pushes playback events to ListenBrainz and LastFM via webhooks, and serves lyrics from embedded metadata or external APIs.
• Plugin System: Meelo allows dynamic loading of Go plugins compiled as shared objects (.so). Plugins can hook into the media ingestion pipeline or extend the API with new endpoints.

Deployment & Infrastructure

Meelo ships as a Docker image, making it trivial to deploy on any container‑oriented platform (Docker Compose, Kubernetes, or Docker Swarm). A typical deployment requires:

1. Persistent storage for media files mounted to /media.
2. PostgreSQL container with a dedicated database user.
3. Optional Redis cache for session tokens and API rate limiting.

The application scales horizontally by running multiple stateless instances behind a load balancer. Since the media files are served via signed URLs, cache‑control headers can be tuned to leverage CDN edge caching if desired.

Integration & Extensibility

• Webhooks: External services can subscribe to events such as track_played or album_scanned. The payloads are JSON and follow a stable schema.
• Custom Clients: The Android app demonstrates how to consume the API. Developers can build iOS, web, or desktop clients using standard HTTP libraries.
• CLI Tools: A lightweight Go CLI (meelo-cli) can trigger library scans, generate reports, or invoke API endpoints from scripts.

Developer Experience

The project follows semantic versioning and provides comprehensive OpenAPI docs. The source code is well‑structured with clear package boundaries, making it approachable for contributors. Community support is active on GitHub Discussions and the project's Wiki contains detailed guides for advanced configuration (regex rules, provider setup). Licensing is MIT, allowing unrestricted use in commercial or private deployments.

Use Cases

• Personal Music Server: Hobbyists with large vinyl‑digitized libraries can enjoy a clean UI and advanced filtering without paying for commercial services.
• Enterprise Audio Libraries: Media companies can host internal catalogs, expose APIs to their own players, and integrate scrobbling for analytics.
• Educational Projects: The Go codebase serves as a learning resource for building media servers, demonstrating best practices in API design, database normalization, and plugin architecture.

Advantages

Meelo’s focus on metadata fidelity and cataloging granularity gives developers precise control over how music is organized. The use of Go provides performance and concurrency benefits, while the plugin system offers extensibility beyond what typical commercial servers allow. Licensing under MIT removes barriers to modification and redistribution, making Meelo an attractive choice for developers seeking a fully controllable, self‑hosted music platform.