Internals
Thumbnail cache
Disk cache and ytmd-thumb protocol for album art
YTMDesktop2 caches YouTube Music album art on disk and serves it to app chrome over ytmd-thumb://.
Who uses it
| Surface | Role |
|---|---|
| Tray view | Cover art in the tray popup (toAppThumbUrl) |
| Mini player (removed in 1.4.0) | Cover art in the compact window (toAppThumbUrl) |
| Track accent | Palette / accent color from the cached image buffer |
| macOS Touch Bar | Artwork bytes via getBuffer |
The embedded YouTube Music webview does not use this cache — it loads CDN thumbs itself.
Why it exists
Tray view is a separate window from the YouTube Music webview. Loading CDN URLs directly often fails without the logged-in session cookies and browser-like headers. The cache:
- Fetches thumbs through the YouTube Music session (cookies, user agent, referer).
- Stores image bytes under the app user-data folder.
- Serves them back to tray view and other app UI over
ytmd-thumb://.
How tray view loads art
Remote URLs are mapped with toAppThumbUrl():
- HTTPS thumbs on
googleusercontent.com,ggpht.com, orytimg.com→ytmd-thumb://i/<base64url> - Anything else stays as the original URL
The main process handles ytmd-thumb on the default session (shared by tray view) and returns cached bytes, or fetches once then caches.
Storage
| Item | Location / limit |
|---|---|
| Cache directory | <userData>/thumb-cache/ |
| Entry key | SHA-256 of the remote URL |
| Files per entry | Binary blob + encrypted .json meta |
| Max entries | 200 (oldest pruned) |
| Meta encryption | AES-256-CBC via thumb-cache.key |
Meta stores URL, MIME type, size, and save time. Invalid or decrypt-failed meta triggers a refetch.
Fetch behavior
- Prefer
youtubeViewsessionfetchso Google sees the logged-in client. - Spoof image
Sec-Fetch-*/Sec-CH-UAheaders similar to a real Music page request. - Fall back to
net.fetchif session fetch fails. - In-flight requests are deduped per URL key.
- Successful responses are served with long-lived
Cache-Controlto the renderer.