music-agregator/docs/research/lidarr/research_summary.md

Lidarr Database Research Summary

Overview

Lidarr is a music collection manager that uses a Release-based system. Key design principles:

1. Metadata Separation - Artist metadata separated from configuration
2. Release-Centric - Works with releases, not loose tracks
3. Monitoring Hierarchy - Artist → Album → Release (only one release monitored per album)
4. Quality Profiles - Separate profiles for quality and metadata preferences
5. Download Lifecycle - Pending → Queue → Imported → History/Blocklist

Core Entity Hierarchy

ArtistMetadata (1) ←→ (1) Artist (1) ←→ (N) Albums
                                              ↓
                                        (N) AlbumReleases (only 1 monitored)
                                              ↓
                                        (N) Tracks (N) ←→ (1) TrackFile

Key Entities

Music Entities

• Artists - Configuration (path, monitoring, profiles)
• ArtistMetadata - Metadata (name, images, genres, members)
• Albums - Album info with monitoring and search tracking
• AlbumReleases - Physical releases (CD, Vinyl, Digital) - only ONE monitored per album
• Tracks - Individual tracks linked to releases
• TrackFiles - Actual files on disk with quality info

Configuration

• QualityProfiles - Acceptable formats and upgrade cutoff
• MetadataProfiles - Which album types to include (Studio, EP, Live, etc.)
• RootFolders - Storage locations with defaults

Download Tracking

• PendingReleases - Delayed downloads (waiting for better quality)
• DownloadHistory - Download lifecycle events
• Blocklist - Failed/rejected releases (prevent re-download)
• History - Complete audit trail of all events

System

• Indexers - Search sources (Newznab/Torznab)
• DownloadClients - Torrent/Usenet clients
• ImportLists - Auto-import from Spotify, Last.fm, etc.
• Tags - Categorization

Monitoring States

Artist Level

• monitored - Is artist being tracked
• monitor_new_items - Policy for new releases (All/Future/Missing/Existing/None)

Album Level

• monitored - Should we look for this album
• any_release_ok - Auto-switch releases during import

Release Level

• monitored - Is this the release we want (exactly ONE per album)

Download States

TrackedDownloadState:
  Downloading → ImportPending → Importing → Imported
                                         → Ignored
            → DownloadFailed → DownloadFailedPending

History Event Types

• Grabbed - Download started
• TrackFileImported - File imported to library
• DownloadFailed - Download failed
• TrackFileDeleted - File removed
• TrackFileRenamed - File renamed
• TrackFileRetagged - Metadata updated
• AlbumImportIncomplete - Partial import
• DownloadIgnored - Download skipped

Sources

• GitHub: Lidarr/Lidarr
• Key files:
  • src/NzbDrone.Core/Music/Model/Artist.cs
  • src/NzbDrone.Core/Music/Model/Album.cs
  • src/NzbDrone.Core/Music/Model/Release.cs (AlbumRelease)
  • src/NzbDrone.Core/Music/Model/Track.cs
  • src/NzbDrone.Core/MediaFiles/TrackFile.cs
  • src/NzbDrone.Core/Datastore/Migration/001_initial_setup.cs
  • src/NzbDrone.Core/Datastore/Migration/023_add_release_groups_etc.cs