Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/calmerism/Tamed/llms.txt

Use this file to discover all available pages before exploring further.

Tamed’s library is backed by a Room database (MusicDatabase) accessed through DatabaseDao. It stores every track, album, artist, and playlist as a set of related entities, tracks listening history and play counts, and keeps local data in sync with YouTube Music when an account is connected.

​
Library Entities

The core data model is a set of Room entities and their aggregated view types:

Song / SongEntity

A single track. Song is the aggregated view, composed of a SongEntity (id, title, duration, thumbnail, liked status, inLibrary date) plus its related ArtistEntity list, AlbumEntity, and FormatEntity.

Album / AlbumEntity

An album or collection. Album includes the AlbumEntity (id, title, year, thumbnail, song count, duration) and a list of ArtistEntity objects. Listening stats (songCountListened, timeListened) are joined at query time.

Artist / ArtistEntity

A music artist. ArtistEntity stores the id, name, and optional thumbnail. Joined into Artist with song count and play-time aggregates.

Playlist / PlaylistEntity

A user or synced playlist. Playlist includes PlaylistEntity (id, name, optional thumbnail URL) along with a songCount and a preview list of song thumbnail URLs for mosaic cover generation.

​
Junction Maps & Views

Relationships between entities are maintained via junction tables and database views:
  • SongArtistMap — raw song-to-artist associations (table); SortedSongArtistMap is a @DatabaseView over this table that orders rows by position, used by the Song relation
  • SongAlbumMap — song-to-album mapping
  • AlbumArtistMap — album-to-artist mapping
  • PlaylistSongMap — playlist membership (table); PlaylistSongMapPreview is a @DatabaseView limited to the first four positions for mosaic cover generation

​
View Types & Grid Size

enum class LibraryViewType {
    LIST,
    GRID,
}

enum class GridItemSize {
    BIG,
    SMALL,
}
Each library section (songs, albums, artists, playlists) has its own view type persisted via ArtistViewTypeKey, AlbumViewTypeKey, and PlaylistViewTypeKey. Grid density is controlled by GridItemsSizeKey.

​
Filters

​
Song Filter

enum class SongFilter {
    LIBRARY,    // All songs added to library
    LIKED,      // Songs with the liked flag set
    DOWNLOADED, // Songs with a locally cached download
}

​
Artist Filter

enum class ArtistFilter {
    LIBRARY, // Artists of library songs
    LIKED,   // Explicitly followed artists
}

​
Album Filter

enum class AlbumFilter {
    LIBRARY,         // Albums saved to library
    LIKED,           // Liked albums
    DOWNLOADED,      // Albums with at least one downloaded track
    DOWNLOADED_FULL, // Albums where every track is downloaded
}

​
Sort Types

enum class SongSortType {
    CREATE_DATE, // Date added to library
    NAME,        // Alphabetical by title
    ARTIST,      // Grouped by artist, then album
    PLAY_TIME,   // Total accumulated play time
}
Every sort section has a corresponding ...SortDescendingKey boolean to reverse the order.

​
Auto-Playlists

Tamed generates four smart playlists automatically. Each can be shown or hidden:
Auto-PlaylistVisibility KeyDescription
Liked SongsShowLikedPlaylistKeyAll songs with liked = true
DownloadedShowDownloadedPlaylistKeyAll locally cached songs
TopShowTopPlaylistKeyTop played tracks in a configurable time window
CachedShowCachedPlaylistKeySongs in the ExoPlayer cache

​
Play Count & Listening Stats

Every completed (or sufficiently long) playback is recorded as an Event entity in the database. PlayCountEntity aggregates these events per song. The MyTopFilter enum defines the time window for the Top playlist and stats screen: 
enum class MyTopFilter {
    ALL_TIME,
    DAY,
    WEEK,
    MONTH,
    YEAR,
}
Listening history collection can be paused without deleting existing data via PauseListenHistoryKey.

​
Playlist Management

Playlists can be created, renamed, reordered, and their tracks rearranged. PlaylistEditLockKey adds a confirmation step before destructive edits, preventing accidental changes. Playlists support tags for filtering. PlaylistTagsFilterKey stores the active tag filter as a serialised string. Tags are shown in the library when ShowTagsInLibraryKey is enabled.

​
YouTube Music Sync

When a YouTube Music account is connected, Tamed keeps the library in sync bidirectionally:
KeyDescription
YtmSyncKeyEnable automatic sync
SelectedYtmPlaylistsKeyComma-separated list of YTM playlist IDs to sync
Sync timestamps are stored to avoid redundant full scans:
KeyTracks Last Sync Of
LastLikeSongSyncKeyLiked songs
LastLibSongSyncKeyLibrary songs
LastAlbumSyncKeySaved albums
LastArtistSyncKeyFollowed artists
LastPlaylistSyncKeyPlaylists

​
Downloads

KeyTypeDescription
AutoDownloadOnLikeKeyBooleanDownload a track automatically when it is liked
ExternalDownloaderEnabledKeyBooleanHand off downloads to a third-party app
ExternalDownloaderPackageKeyStringPackage name of the external downloader

​
Search

The search source is toggled between local library and online YouTube Music via SearchSourceKey: 
enum class SearchSource {
    LOCAL,
    ONLINE,
}
Search history recording can be paused with PauseSearchHistoryKey while leaving existing history intact.

​
Backup & Restore

BackupRestoreViewModel handles serialising the entire database state (library songs, albums, artists, playlists, liked items, and settings) to a portable backup file, and restoring from one. This allows migrating between devices or reinstalling without losing local library metadata.

Build docs developers (and LLMs) love

Get started for freeTalk to us