Canvas is VIVI Music’s animated video backdrop system. While a song plays, a looping video or animated artwork fills the background of the player screen — the same visual style popularised by Apple Music. VIVI fetches canvas content from several independent sources and renders it as a live backdrop behind the album art thumbnail, creating an immersive, always-moving player UI. Canvas is fully optional and can be enabled, disabled, or reconfigured at any time from Settings → Appearance → VIVI Music Canvas.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/vivizzz007/vivi-music/llms.txt
Use this file to discover all available pages before exploring further.
Canvas requires an active network connection to fetch backdrop videos the first time a track plays. Resolved canvas results are stored in an in-memory
CanvasArtworkPlaybackCache keyed by track ID and source, so repeated plays within the same session do not trigger additional network requests.How Canvas Works
When a track begins playing, VIVI’s canvas pipeline queries the configured source for an animated artwork URL matching the song title and artist. TheCanvasArtwork data class represents a resolved result and exposes several URL fields:
animated— the primary animated artwork URLvideoUrl— a fallback video URLanimatedTall— a tall-format variant for portrait layoutsstatic— a static fallback image if no animation is available
preferredAnimationUrl property selects animated first, then falls back to videoUrl. Once resolved, the video is rendered in a looping player that underlays the main player UI.
The CanvasThumbnailAnimationKey preference is the master enable/disable switch for the entire feature. When it is false, no canvas content is fetched and the player background falls back to the active PlayerBackgroundStyle.
Enabling Canvas
Tap VIVI Music Canvas
In the Player section, tap the VIVI Music Canvas row to open the
CanvasSelection screen.Toggle Use Canvas
Flip the Use Canvas capsule switch at the top of the screen. This writes to
CanvasThumbnailAnimationKey.Canvas Sources
TheCanvasSourceKey preference (default: CanvasSource.AUTO) selects which backend provides animated artwork. All sources are part of the CanvasSource enum and are shown as radio buttons on the CanvasSelection screen.
AUTO
VIVI queries Apple Music first, then Tidal, then the VIVI Music CDN, and uses the first successful match. Recommended for the widest catalog coverage.Key value:
CanvasSource.AUTOApple Music
Queries Apple Music’s animated artwork catalogue. Provides high-quality animated covers for mainstream releases.Key value:
CanvasSource.APPLE_MUSICVIVI Music
Uses the VIVI Music canvas CDN (
vivimusicanvas.mkmdevilmi.workers.dev), powered by the vivimusiccanvas module. This is VIVI’s own curated canvas catalogue.Key value: CanvasSource.VIVIMUSICTidal
Fetches canvas artwork from the Tidal catalogue via the
TidalCanvasProvider. Strong for electronic, pop, and international releases.Key value: CanvasSource.TIDALThe vivimusiccanvas Module
Thevivimusiccanvas module is VIVI Music’s own canvas rendering engine. It hosts a manifest at https://vivimusicanvas.mkmdevilmi.workers.dev/canvas.json that maps tracks (by song title, artist, and album) to animated video URLs. The manifest is parsed into ViviMusicCanvasManifest → ViviMusicCanvasItem structures, and lookups are performed using a normalised string comparison to handle minor title variations.
Alongside vivimusiccanvas, the canvas module provides the shared CanvasArtwork model and the TidalCanvasProvider implementation. Apple Music song canvas is handled by AppleMusicCanvasProvider in the separate applecanvas module, while the canvas module also contains AppleMusicArtistBackgroundProvider for fetching artist motion artwork on artist screens. All providers share the same CanvasArtwork result shape, ensuring a consistent output across all sources.
Player Background Styles
Canvas is one layer of a broader player background system. When canvas content is unavailable or canvas is disabled, VIVI falls back to the style set byPlayerBackgroundStyleKey. The PlayerBackgroundStyle enum provides:
| Value | Description |
|---|---|
DEFAULT | Follows the current Material You theme with no extra effect |
GRADIENT | Extracts dominant colors from the album art and applies a gradient (default) |
BLUR | Blurs the album art as the player background (Android 12+ only) |
GLOW_ANIMATED | Animated glow that pulses with the album’s dominant color |
APPLE_MUSIC | Mimics the Apple Music fluid gradient background style |
LIVE_MESH | Animated mesh gradient using the album’s color palette |
MiniPlayerBackgroundStyleKey controls the mini-player bar background independently, with the same options except APPLE_MUSIC.
Change the background style in Settings → Appearance → Player Background Style.
Dynamic Material You Colors
DynamicThemeKey (default: true) enables Material You dynamic theming, extracting a full color scheme from the current track’s album art. When active, the entire app UI — including the player, navigation bar, and settings screens — adapts its color palette to match the playing track. This works alongside canvas: the canvas video plays in the background while the UI chrome adopts the album’s colors.
Rotating Thumbnail
RotatingThumbnailKey makes the album art thumbnail in the player slowly rotate like a vinyl record while the song plays. This is purely cosmetic and is disabled by default.
Enable it in Settings → Appearance — the toggle appears in the Player section alongside the canvas controls.
Canvas and Data Saver
When Data Saver mode is active (DataSaverKey), canvas is automatically disabled to prevent background video fetches. VIVI stores the previous canvas state in DataSaverBackupCanvasKey and restores it when Data Saver is turned off, so your canvas preference is preserved.