Catalog¶

The Catalog context manages the core media catalog: artists, albums, songs, movies, videos, and genres. It provides CRUD operations, full-text search via PGroonga, and cover art extraction. This is the largest context by entity count.

Domain Models¶

Aggregate Roots¶

Value Objects¶

Commands & Handlers¶

The API controllers and the console commands dispatch the same commands and queries, so each edit, delete and cover change has one use case. A malformed public ID or UUID, an invalid value, or a rejected file raises InvalidInputException (HTTP 422, console exit INVALID). A missing item or credit raises NotFoundException (HTTP 404).

FilesDiscoveredHandler handles Library's FilesDiscovered message and imports the files a scan found. It reads the metadata of up to 50 audio files, then writes their songs, artist links and genres in one transaction; a delete with files cannot claim the library while that transaction runs (see Library). When a delete holds the library, the handler puts the files it has not imported back on the queue.

Queries¶

The previews change nothing. They read playlists through Playlist's PlaylistDeletionPreviewPortInterface and check files through Library's LibraryMediaFilesInterface::inspect(), which returns a verdict for each path in a FileDeletionPreview.

Field Locks¶

Album, Song and Artist each have a list of lockable fields, and they share the lock rules in LockedFields. A locked field keeps its value: updateMetadata() rejects the whole edit when it gives any locked field a value. Every lockable field is enforced, not only the title or name. Locking or unlocking a field that is not lockable is rejected too.

An update command takes the edit, a complete lockedFields list that replaces the current one, and fields to lock and unlock. CatalogInput::lockChanges() turns these into fields to unlock and fields to lock. The handler applies the unlocks, then the edit, then the locks, and saves only when all three are accepted. One request can therefore unlock a field and change it, or change a field and lock it. A field in both lists ends locked. On the console, --lock and --unlock can be repeated and accept comma-separated field names.

Automatic updates skip locked fields rather than fail. Metadata's AlbumMetadataEnricher and ArtistMetadataEnricher leave locked fields out of the values they apply. AlbumMergeService keeps the target album's value for a locked field, even when that value is empty. After the merge, the target also locks every field that was locked on the source album.

Deletes¶

Every delete returns a CatalogDeletionResult: the rows deleted by kind and, when the delete included audio files, the files removed, already missing, and left on disk.

AlbumPortInterface::delete() and SongPortInterface::delete() delete rows only; they never touch audio files. A delete with files goes through Library's LibraryMediaFilesInterface (see Library). Before anything changes, DeleteAlbumHandler and DeleteSongHandler call prepareDeletion() for the song paths. It refuses the whole request with a 409 while a scan holds the library, when the library root is not available, or when the server cannot write a song's directory, and with a 422 when a path lies outside the library root. The handlers then delete the catalog rows and the file index rows in one transaction through TransactionPortInterface, and unlink the files after the commit. The next scan imports any file left on disk again. When a file is left, the console command exits with FAILURE.

DeleteAlbumHandler deletes the album's cover image after the commit unless deleteCover is false, so a rollback leaves the album with its cover. DeleteArtistHandler deletes the artist, then its cover image. DeleteMovieHandler deletes the movie and, in the same transaction, the videos that no other movie links (VideoRepositoryInterface::deleteUnlinked()).

The public delete routes pass only the public ID, so they keep the audio files and delete the album cover. DELETE /api/admin/albums/{publicId} takes deleteFiles and deleteCover, and DELETE /api/admin/songs/{publicId} takes deleteFile. On the console, --delete-files requires --force even on a terminal, app:album:delete --keep-cover keeps the cover, and --dry-run prints the preview without changing anything.

Covers¶

SetCoverHandler accepts a JPEG, PNG or WebP file of at most 10 MB, detected with Filesystem's MimeDetectorPortInterface. The upload route passes the uploaded temporary file; the console passes a path in the container. The handler copies the file into Media storage under a new path for each cover (images/<owner>/<owner UUID>/<UUID>.<ext>), so a replacement never overwrites the file it replaces. It saves the image record and the owner in one transaction. If that fails before both saves complete, the handler removes the new file and the old cover stays. It deletes the old cover only after the commit.

RemoveCoverHandler clears the owner's cover, saves the owner, then deletes the image. Removing the cover of an owner that has none returns a 404. CoverImageDiscarder deletes a cover image that its owner no longer uses: first the image record through ImagePortInterface, then the file and its derived files through StoragePortInterface. It runs only after the owner's change has committed, and it logs a failure instead of throwing.

Artist Credits¶

A credit links an artist to a song or an album (CreditTarget) with an ArtistRole; the song or album is named by its UUID. The ArtistPortInterface credit methods return false instead of throwing, and the handlers turn that into a 404 for an unknown artist, song or album, or an artist without the named credit. ChangeArtistCreditRoleCommand names the credit to change by its current role. The current role may be omitted when the artist has a single credit on the target; with several credits, omitting it is a 422. When the new role is one the artist already holds on the target, the changed credit is removed.

Ports¶

Domain Events¶

API Endpoints¶

All endpoints are prefixed with /api. Every route that writes requires ROLE_ADMIN. The list routes search with PGroonga when given a q parameter.

Artists¶

Albums¶

Songs¶

Movies¶

Genres¶

Admin — Duplicate Albums¶

Routes under /api/admin/albums (controller AlbumDuplicateController, gated ROLE_ADMIN).

Admin — Deletes With Files¶

Routes under /api/admin/albums and /api/admin/songs (controllers AdminAlbumController and AdminSongController, gated ROLE_ADMIN).

Cross-Context Relationships¶

Infrastructure¶

Console Commands¶

See the Search page for details on PGroonga full-text search.