metadata-agregator/docs/research/meelo/analysis/EVALUATION.md

# Meelo Evaluation

## Strengths

### Data Model Sophistication

Meelo's data model is the most mature among self-hosted music servers. The Album/Release and Song/Track distinctions accurately represent real-world music organization.

**Album vs Release**:
- Albums are abstract concepts (e.g., "Abbey Road")
- Releases are physical/digital manifestations (original, 2019 remaster, deluxe edition)
- One album can have multiple releases with different track listings, mastering, labels

This mirrors how music collectors think. A remaster is not a different album, it's a different release of the same album.

**Song vs Track**:
- Songs are compositions (e.g., "Come Together")
- Tracks are recordings (studio version, live version, acoustic version)
- One song can have multiple tracks across different releases

This enables tracking different performances of the same composition without creating duplicate songs.

**Song Groups**:
- Group versions of the same composition (original, covers, remixes)
- Example: "Hallelujah" by Leonard Cohen, Jeff Buckley, Pentatonix
- Enables discovering different interpretations

No other self-hosted music server implements this level of versioning.

### Multi-Provider Metadata

Meelo queries 8 external providers:
1. **MusicBrainz**: Primary database, most accurate
2. **Genius**: Lyrics and song descriptions
3. **Wikipedia**: Artist/album context
4. **Wikidata**: Structured data
5. **Discogs**: Release details
6. **AllMusic**: Editorial reviews
7. **Metacritic**: Critic scores
8. **LrcLib**: Synced lyrics

**Aggregation Strategy**:
- Priority-based merging (MusicBrainz > Genius > Wikipedia)
- Concatenate descriptions from multiple sources
- Average ratings across providers
- Prefer synced lyrics over plain

**Result**: Richer metadata than single-provider systems. Descriptions combine MusicBrainz facts, Wikipedia context, and Genius annotations.

### Music Video Support

Videos are first-class citizens, not afterthoughts.

**Video Types**:
- Official music videos
- Live performances
- Lyric videos
- Behind the scenes
- Interviews
- Documentaries

**Integration**:
- Videos link to songs (same as audio tracks)
- Kyoo transcoder handles adaptive streaming
- UI treats videos equally with audio

**Comparison**:
- **Navidrome**: No video support
- **Jellyfin**: Videos are separate media type, not linked to songs
- **Plex**: Similar to Jellyfin

Meelo is the only self-hosted music server with proper music video integration.

### Event-Driven Architecture

RabbitMQ decouples scanning from enrichment.

**Flow**:
1. Scanner registers file with Server
2. Scanner publishes event to RabbitMQ
3. Matcher consumes event asynchronously
4. Matcher queries providers in parallel
5. Matcher pushes enriched metadata to Server

**Benefits**:
- Scanning doesn't block on provider queries
- Matcher can retry failed providers without re-scanning
- Multiple matchers can process events in parallel
- Provider failures don't stop scanning

**Comparison**:
- **Navidrome**: Synchronous metadata fetching blocks scanning
- **Airsonic**: No external metadata providers

### Scrobbling Built-In

Last.fm and ListenBrainz integration is native, not a plugin.

**Features**:
- OAuth flow for Last.fm
- Token-based auth for ListenBrainz
- Automatic scrobbling on track play
- "Now playing" updates

**Comparison**:
- **Navidrome**: Last.fm only, requires external scrobbler
- **Airsonic**: No built-in scrobbling

### Mobile App

Expo/React Native app shares code with web frontend.

**Shared**:
- Components (ArtistCard, AlbumCard, TrackList)
- Hooks (useArtists, useAlbums, usePlayback)
- State management (Jotai atoms)

**Mobile-Specific**:
- React Navigation instead of Next.js router
- AsyncStorage instead of localStorage
- expo-av for media playback
- expo-notifications for background playback

**Result**: Feature parity between web and mobile without duplicating code.

**Comparison**:
- **Navidrome**: Third-party mobile apps (Substreamer, Subtracks)
- **Jellyfin**: Official mobile app, but music is secondary

### Search Performance

MeiliSearch provides sub-100ms search across large libraries.

**Features**:
- Typo tolerance (handles misspellings)
- Faceted search (filter by genre, year, type)
- Instant results (as-you-type)
- Relevance ranking

**Indexed Entities**:
- Artists (name, sort name)
- Albums (name, artist name, type, release date)
- Songs (name, artist name, type)
- Videos (name, artist name, type)

**Comparison**:
- **Navidrome**: Database full-text search (slower, no typo tolerance)
- **Airsonic**: Basic SQL LIKE queries

### Active Development

**Indicators**:
- 40 releases (consistent iteration)
- 1,095 stars (healthy community)
- GitHub Actions CI/CD per service
- SonarCloud quality gates
- Regular commits (weekly)

**Comparison**:
- **Navidrome**: Active (single maintainer)
- **Airsonic**: Stagnant (last release 2020)
- **Funkwhale**: Active but slower

### Geographic Context

Areas (countries, cities, regions) are first-class entities.

**Features**:
- ISO 3166 codes
- Parent/child hierarchy (city → state → country)
- Artist associations (birthplace, formation location)

**Use Case**:
- Browse artists by location
- Discover local music scenes
- Understand artist context

**Comparison**: No other self-hosted music server has area support.

### Code Quality

**Measures**:
- SonarCloud enforces 80% coverage, no critical bugs
- Biome linting for TypeScript
- Pyright type checking for Python
- golangci-lint for Go
- Jest, pytest, Go testing

**Result**: High code quality, low bug rate.

## Weaknesses

### Complex Deployment

8+ containers required:
1. Server (NestJS)
2. Scanner (Go)
3. Matcher (Python)
4. Front (Next.js)
5. PostgreSQL
6. MeiliSearch
7. RabbitMQ
8. Kyoo Transcoder
9. Nginx

**Challenges**:
- Docker Compose orchestration
- Health check dependencies
- Volume management
- Network configuration
- Resource allocation

**Comparison**:
- **Navidrome**: Single binary, no dependencies
- **Airsonic**: Single JAR, embedded database option

**Impact**: High barrier to entry for non-technical users.

### Multi-Language Stack

4 languages across services:
- TypeScript (Server, Front)
- Go (Scanner)
- Python (Matcher)
- TypeScript again (Front mobile)

**Challenges**:
- Different toolchains (npm, go, pip)
- Different testing frameworks (Jest, Go testing, pytest)
- Different linting tools (Biome, golangci-lint, Ruff)
- Harder to contribute (need expertise in multiple languages)

**Comparison**:
- **Navidrome**: Single language (Go)
- **Airsonic**: Single language (Java)

**Impact**: Steeper learning curve for contributors.

### Heavy Infrastructure

Required services:
- **PostgreSQL**: Relational database
- **MeiliSearch**: Search engine
- **RabbitMQ**: Message queue
- **Kyoo Transcoder**: Video transcoding

**Resource Requirements**:
- Minimum: 4GB RAM, 2 CPU cores
- Recommended: 8GB RAM, 4 CPU cores
- Storage: 10GB + library size

**Comparison**:
- **Navidrome**: 512MB RAM, 1 CPU core, SQLite
- **Airsonic**: 1GB RAM, 1 CPU core, embedded database

**Impact**: Not suitable for low-power devices (Raspberry Pi 3, old NAS).

### Requires Clean Collection

Meelo works best with well-organized music:
- Embedded metadata (ID3 tags, Vorbis comments)
- Standard folder structure (Artist/Album/Track)
- Consistent naming

**Challenges**:
- Messy collections require manual cleanup
- Missing tags need filename regex
- Inconsistent naming breaks matching

**Comparison**:
- **Navidrome**: More forgiving, uses folder structure
- **Jellyfin**: Handles messy collections better

**Impact**: Not suitable for users with poorly organized libraries.

### GPL-3.0 License

**Restrictions**:
- Derivative works must be GPL-3.0
- Source code must be disclosed
- No proprietary forks

**Impact**:
- Prevents commercial SaaS offerings
- Limits corporate adoption
- Acceptable for self-hosters, restrictive for businesses

**Comparison**:
- **Navidrome**: GPL-3.0 (same restrictions)
- **Jellyfin**: GPL-2.0 (similar restrictions)
- **Airsonic**: GPL-3.0 (same restrictions)

### Kyoo Transcoder Dependency

Video transcoding relies on external project (Kyoo).

**Risks**:
- Kyoo development stalls
- Breaking changes in Kyoo API
- Meelo must maintain compatibility

**Comparison**:
- **Jellyfin**: Built-in transcoder (FFmpeg wrapper)
- **Plex**: Built-in transcoder

**Impact**: Video support is fragile.

### No Prometheus Metrics

No built-in metrics for monitoring.

**Missing**:
- Request rates
- Error rates
- Latency percentiles
- Queue depths
- Provider response times

**Workaround**: Parse logs or use external monitoring.

**Comparison**:
- **Navidrome**: Prometheus metrics endpoint
- **Jellyfin**: No metrics

**Impact**: Harder to monitor in production.

## Integration Potential

### Data Model

**Applicability**: Excellent reference for metadata aggregator.

**Lessons**:
- Separate abstract entities (Album, Song) from concrete instances (Release, Track)
- Use song groups for versioning
- Store external metadata separately from core entities
- Use local identifiers for cross-referencing

**Adoption**:
- Implement Album/Release distinction
- Implement Song/Track distinction
- Implement song groups for covers/remixes
- Separate ExternalMetadata table

### Provider Pattern

**Applicability**: Directly applicable to metadata aggregator.

**Architecture**:
- Base provider interface (search, fetch)
- Per-provider modules (musicbrainz.py, genius.py)
- Factory pattern for provider instantiation
- Parallel queries with asyncio
- Rate limiting per provider
- Priority-based aggregation

**Adoption**:
- Copy provider interface design
- Implement factory pattern
- Use asyncio for parallel queries
- Implement per-provider rate limiters
- Use priority-based merging

### Event-Driven Enrichment

**Applicability**: Scalable approach for metadata aggregator.

**Architecture**:
- Scanner publishes events to queue
- Matcher consumes events asynchronously
- Server receives enriched metadata via API
- Decouples scanning from enrichment

**Adoption**:
- Use message queue (RabbitMQ, Redis Streams)
- Separate scanner and matcher services
- Enable retries without re-scanning

### Search Integration

**Applicability**: Fast search is critical for metadata aggregator.

**Architecture**:
- MeiliSearch for full-text search
- Index on entity creation/update
- Typo tolerance and faceted search
- Sub-100ms response times

**Adoption**:
- Integrate MeiliSearch or Typesense
- Index artists, albums, songs
- Implement as-you-type search

## Relevance to Metadata Aggregator

### High Relevance

**Data Model**:
- Album/Release and Song/Track distinctions are essential for accurate metadata
- Song groups enable tracking versions and covers
- External metadata separation keeps provider data clean

**Provider Architecture**:
- Factory pattern simplifies adding new providers
- Parallel queries optimize performance
- Rate limiting prevents API bans
- Priority-based aggregation ensures quality

**Event-Driven Design**:
- Decouples metadata fetching from file scanning
- Enables retries without re-processing
- Scales horizontally (multiple matchers)

### Medium Relevance

**Search Integration**:
- Fast search improves user experience
- Typo tolerance handles misspellings
- Faceted search enables filtering

**Scrobbling**:
- OAuth flows are reusable patterns
- Token management is standard practice

**Mobile App**:
- Code sharing between web and mobile reduces duplication
- Monorepo structure simplifies version coordination

### Low Relevance

**Video Support**:
- Metadata aggregator may not handle videos
- Transcoding is out of scope

**Geographic Context**:
- Areas are nice-to-have, not essential
- ISO 3166 codes are useful for standardization

**Deployment Complexity**:
- Metadata aggregator may use simpler deployment (single service)
- Docker Compose is overkill for smaller projects

## Comparison with Alternatives

### vs Navidrome

**Meelo Advantages**:
- Richer data model (Album/Release, Song/Track)
- Multi-provider metadata (8 vs 1)
- Music video support
- Built-in scrobbling
- Search performance (MeiliSearch vs SQL)

**Navidrome Advantages**:
- Simpler deployment (single binary)
- Lower resource requirements (512MB vs 4GB)
- Faster startup (no dependencies)
- More mature (older project)

**Verdict**: Meelo for metadata richness, Navidrome for simplicity.

### vs Jellyfin

**Meelo Advantages**:
- Music-focused (not general media server)
- Better music metadata (Album/Release, Song/Track)
- Multi-provider enrichment
- Faster search (MeiliSearch)

**Jellyfin Advantages**:
- Handles all media types (movies, TV, music)
- Larger community
- More mature
- Better transcoding (built-in)

**Verdict**: Meelo for music collectors, Jellyfin for general media.

### vs Airsonic

**Meelo Advantages**:
- Modern stack (NestJS, Next.js vs Java)
- Active development (40 releases vs stagnant)
- Better metadata (multi-provider)
- Search performance

**Airsonic Advantages**:
- Simpler deployment (single JAR)
- Subsonic API compatibility
- Larger ecosystem (mobile apps)

**Verdict**: Meelo for modern features, Airsonic for stability.

### vs Funkwhale

**Meelo Advantages**:
- Better metadata model
- Multi-provider enrichment
- Faster search

**Funkwhale Advantages**:
- Federated (share music across instances)
- Social features (follows, favorites)
- Podcast support

**Verdict**: Meelo for personal use, Funkwhale for communities.

## Recommendations for Metadata Aggregator

### Adopt

1. **Data Model**:
   - Implement Album/Release distinction
   - Implement Song/Track distinction
   - Implement song groups for versions
   - Separate ExternalMetadata table

2. **Provider Pattern**:
   - Base provider interface
   - Per-provider modules
   - Factory pattern
   - Parallel queries with asyncio
   - Rate limiting per provider
   - Priority-based aggregation

3. **Event-Driven Architecture**:
   - Message queue for decoupling
   - Separate scanner and matcher services
   - Retry logic without re-scanning

### Adapt

1. **Search Integration**:
   - Use MeiliSearch or Typesense
   - Index on entity creation/update
   - Implement typo tolerance

2. **Scrobbling**:
   - OAuth flows for Last.fm
   - Token-based auth for ListenBrainz

3. **Code Quality**:
   - Linting (Biome, Ruff)
   - Type checking (TypeScript, Pyright)
   - Testing (Jest, pytest)
   - SonarCloud quality gates

### Avoid

1. **Complex Deployment**:
   - Prefer single service or fewer containers
   - Avoid heavy infrastructure (PostgreSQL, RabbitMQ) if possible
   - Use SQLite for smaller deployments

2. **Multi-Language Stack**:
   - Stick to one or two languages
   - Avoid mixing TypeScript, Go, Python unless necessary

3. **Kyoo Dependency**:
   - If video support needed, use built-in transcoder (FFmpeg)
   - Avoid external dependencies for core features

## Summary

Meelo excels at data modeling, multi-provider metadata enrichment, and music video support. The Album/Release and Song/Track distinctions are the most accurate representation of real-world music organization among self-hosted servers. The provider pattern with parallel queries and priority-based aggregation is directly applicable to metadata aggregators. The event-driven architecture scales well and decouples concerns. However, deployment complexity (8+ containers), multi-language stack (TypeScript, Go, Python), and heavy infrastructure (PostgreSQL, MeiliSearch, RabbitMQ) limit accessibility. The GPL-3.0 license restricts commercial use. For a metadata aggregator, adopt the data model and provider architecture, adapt the search integration and scrobbling patterns, but avoid the deployment complexity and multi-language stack. Meelo is an excellent reference for sophisticated metadata handling in a self-hosted context.