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 treats the visual experience as a first-class feature. The player screen can display live animated canvases sourced from Apple Music or ViviMusic, a suite of dynamic background styles drawn from album art colours, and seven player UI design styles. Every visual element from blur radius to thumbnail corner rounding is tunable through a dedicated set of preference keys.
Canvas Providers
A “canvas” is a short looping video or animated artwork that plays behind the album art during playback. Tamed queries multiple independent canvas sources and picks the first hit.
Apple Music Canvas (AppleMusicCanvasProvider)
AppleMusicCanvasProvider queries the Apple Music API (amp-api.music.apple.com) for HLS motion artwork. It supports two lookup paths:
- editorialVideo — present on albums with Apple Motion artwork, accessed via
?extend=editorialVideo.
- Music-video tracks — some albums embed a full-length music video as a track, accessed via
?include=tracks.
Entry points:
// Look up by album name + artist
AppleMusicCanvasProvider.getByAlbumArtist(album, artist, storefront)
// Look up by song name + artist, optionally with album context
AppleMusicCanvasProvider.getBySongArtist(song, artist, album, storefront)
// Direct lookup by Apple Music album ID
AppleMusicCanvasProvider.getByAlbumId(albumId, storefront)
ConcurrentHashMap with a 24-hour TTL. The provider auto-refreshes its JWT developer token from the Apple Music web player when the cached token expires or returns a 401 Unauthorized.
Monochrome API Canvas (MonochromeApiCanvas)
MonochromeApiCanvas calls the canvas.monochrome.workers.dev Cloudflare Worker endpoint. It searches by "$title $artist $album" and validates the result against both song title and artist name before returning a CanvasArtwork.
ViviMusic Canvas (ViviMusicCanvasProvider)
ViviMusicCanvasProvider fetches a community-maintained JSON manifest from jsDelivr (vivizzz007/vivimusicanvas). The manifest contains a list of ViviMusicCanvasItem objects, each with song, artist, and url fields. The manifest is cached in memory.
Canvas Go Provider (CanvasGoProvider)
CanvasGoProvider calls the embedded Go backend (when the optional AAR is present) via reflection (gobackend.Gobackend.FetchCanvasBySongArtist). It fetches Apple Music trickplay motion artwork using the device’s locale storefront and parses the returned JSON to a CanvasArtwork.
Artist Background (AppleMusicArtistBackgroundProvider)
AppleMusicArtistBackgroundProvider fetches an artist’s motion background from the Apple Music API. It searches for the artist, scores candidates by name similarity, then fetches editorialVideo and editorialArtwork fields from the artist profile. Results are cached for 24 hours.
The TamedCanvas feature toggle (TamedCanvasKey) must be enabled for canvas providers to be queried during playback. The maximum canvas cache size is configured via MaxCanvasCacheSizeKey.
Background Styles
PlayerBackgroundStyle
The PlayerBackgroundStyle enum controls what is rendered behind the player UI:
| Style | Description |
|---|
DEFAULT | Simple flat background using the system theme colour |
GRADIENT | Soft gradient derived from album art palette |
CUSTOM | A user-supplied static image with adjustable blur, contrast, and brightness |
BLUR | Blurred album art fill |
COLORING | Vivid palette colouring extracted from album art |
BLUR_GRADIENT | Blurred art combined with a gradient overlay |
GLOW | Colour glow emanating from the album art edges |
GLOW_ANIMATED | Animated version of GLOW with shifting colour transitions |
APPLE_MUSIC | Replicates the Apple Music ambient colour wash |
LIVE_MESH | Animated particle mesh with palette colours |
BACKDROP | Full-bleed canvas video used as the player background |
CUSTOM, three additional keys fine-tune the image:
val PlayerCustomImageUriKey = stringPreferencesKey("playerCustomImageUri")
val PlayerCustomBlurKey = floatPreferencesKey("playerCustomBlur")
val PlayerCustomContrastKey = floatPreferencesKey("playerCustomContrast")
val PlayerCustomBrightnessKey = floatPreferencesKey("playerCustomBrightness")
HomeBackgroundStyle
The home screen has its own background style selector:
enum class HomeBackgroundStyle {
DEFAULT, // Standard Material surface
BACKDROP, // Canvas video backdrop
LIVE_MESH, // Animated mesh using palette colours
}
Player Design Styles
PlayerDesignStyle defines seven player UI layout options:
enum class PlayerDesignStyle {
V1, V2, V3, V4, V5, V6, V7,
}
V4 and V7 are reserved but not independently implemented — both fall back to V3 at runtime via asSupportedPlayerDesignStyle(). Only V1, V2, V3, V5, and V6 render distinct layouts.
Thumbnail Settings
| Key | Type | Description |
|---|
ThumbnailCornerRadiusKey | Float | Corner rounding radius for album art thumbnails |
CropThumbnailToSquareKey | Boolean | Force-crop non-square artwork to 1:1 ratio |
HidePlayerThumbnailKey | Boolean | Hide the thumbnail entirely in the player view |
Blur Settings
| Key | Type | Description |
|---|
DisableBlurKey | Boolean | Globally disable all blur effects (useful on low-end devices) |
BlurRadiusKey | Float | Radius for background blur in blur-mode backgrounds |
Dynamic Theming
Tamed’s colour system adapts to album art using the Android Palette library:
| Key | Type | Description |
|---|
DynamicThemeKey | Boolean | Extract palette colours from current album art |
CustomThemeColorKey | String | Fixed hex seed colour when dynamic theme is off |
RandomThemeOnStartupKey | Boolean | Pick a random accent colour on each app launch |
DarkModeKey | String | Dark mode preference (SYSTEM, ON, OFF) |
PureBlackKey | Boolean | Use true #000000 black for AMOLED savings |
Fonts
AppFont defines the typeface used across the entire application UI:
enum class AppFont(val value: String) {
SYSTEM("system"),
GOOGLE_SANS("google_sans"),
SANS_FLEX("sans_flex"),
OUTFIT("outfit"),
PLUS_JAKARTA_SANS("plus_jakarta_sans"),
}
SelectedFontKey. AppFont.fromValue() deserialises the stored string back to the enum, defaulting to SYSTEM if unrecognised.
Swipe Gestures
| Key | Type | Description |
|---|
SwipeToSongKey | Boolean | Swipe left/right on the player to skip tracks |
SwipeThumbnailKey | Boolean | Swipe on the album art thumbnail specifically |
SwipeSensitivityKey | Float | Distance threshold before a swipe is registered |
Slider Styles
The seek/progress bar can be rendered in five styles:
enum class SliderStyle {
Standard,
Wavy,
Thick,
Circular,
Simple,
}
SliderStyleKey.