Show a cover picture for every soundtrack (game, anime, film...). The server finds and stores the covers, so the clients only download a small picture and the API key stays on the server.
Plan
Source. Search an external API by the soundtrack's name and save the best match:
SteamGridDB (free API key, game covers in many sizes) or IGDB (free, Twitch client ID and secret) for games.
Media that are not games, such as anime or films, may need AniList (no key) or TMDB (free key) as a fallback.
Storage. Save covers in a folder like the characters folder, e.g. COVERS_PATH, named by the soundtrack's UUID. Keep in the database where each cover came from and when it was fetched (a cover table, or columns on soundtrack).
Fetching. Run a background job after a sync and at startup that fetches covers for soundtracks without one, slowly (rate limits), never as part of a client request. Also search with the soundtrack's alternative names (see #32), since folder names often don't match the API's title.
API.
GET /api/v1/soundtracks/{uuid}/cover returns the image, or 404 when there is none.
The statistics and soundtrack responses get a cover_modified time (or has_cover), so the client can cache like it does with /character/details.
Fixing bad matches. Allow a manual override: PUT /api/v1/soundtracks/{uuid}/cover with an uploaded image, or a chosen external ID. Mark manual covers so the job never replaces them.
Config. API keys come from environment variables. Without a key the job is off and everything else works as before.
Which API? Many soundtracks are probably games, so SteamGridDB or IGDB first, with AniList for anime?
Is a manual override (upload your own cover) needed from the start, or is "search again with an alternative name" enough?
Show a cover picture for every soundtrack (game, anime, film...). The server finds and stores the covers, so the clients only download a small picture and the API key stays on the server.
## Plan
- **Source.** Search an external API by the soundtrack's name and save the best match:
- **SteamGridDB** (free API key, game covers in many sizes) or **IGDB** (free, Twitch client ID and secret) for games.
- Media that are not games, such as anime or films, may need **AniList** (no key) or **TMDB** (free key) as a fallback.
- **Storage.** Save covers in a folder like the characters folder, e.g. `COVERS_PATH`, named by the soundtrack's UUID. Keep in the database where each cover came from and when it was fetched (a `cover` table, or columns on `soundtrack`).
- **Fetching.** Run a background job after a sync and at startup that fetches covers for soundtracks without one, slowly (rate limits), never as part of a client request. Also search with the soundtrack's alternative names (see #32), since folder names often don't match the API's title.
- **API.**
- `GET /api/v1/soundtracks/{uuid}/cover` returns the image, or 404 when there is none.
- The statistics and soundtrack responses get a `cover_modified` time (or `has_cover`), so the client can cache like it does with `/character/details`.
- **Fixing bad matches.** Allow a manual override: `PUT /api/v1/soundtracks/{uuid}/cover` with an uploaded image, or a chosen external ID. Mark manual covers so the job never replaces them.
- **Config.** API keys come from environment variables. Without a key the job is off and everything else works as before.
## Used by
- MusicPlayer: covers on the statistics cards, Sansan/MusicPlayer#49.
- MusicFrontend could show them too later.
## Questions
- Which API? Many soundtracks are probably games, so SteamGridDB or IGDB first, with AniList for anime?
- Is a manual override (upload your own cover) needed from the start, or is "search again with an alternative name" enough?
Sansan
added the feature label 2025-09-19 22:31:19 +02:00
Sansan
changed title from Add functionallity to have cover art to Cover art for soundtracks, fetched and stored by the server2026-10-09 16:04:06 +02:00
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Show a cover picture for every soundtrack (game, anime, film...). The server finds and stores the covers, so the clients only download a small picture and the API key stays on the server.
Plan
COVERS_PATH, named by the soundtrack's UUID. Keep in the database where each cover came from and when it was fetched (acovertable, or columns onsoundtrack).GET /api/v1/soundtracks/{uuid}/coverreturns the image, or 404 when there is none.cover_modifiedtime (orhas_cover), so the client can cache like it does with/character/details.PUT /api/v1/soundtracks/{uuid}/coverwith an uploaded image, or a chosen external ID. Mark manual covers so the job never replaces them.Used by
Questions
Add functionallity to have cover artto Cover art for soundtracks, fetched and stored by the server