LB-1651: Add granular caption options and color customization to Art Creator grid stats

[Gopal7387]

Summary

This update adds a feature to customize captions on the Album Grid stats template. Users can now turn on or off each caption field. Choose their own colors.

Changes

Backend

• The listen_count info from user release stats is now sent to the cover art image pipeline in cover_art_generator.py.

• The /1/art/grid-stats/ endpoint in art_api.py now accepts two query parameters: caption-text-color and caption-bg-color.

• These color values are passed on to the SVG template.

SVG Templates

• Each caption element now has its own CSS class: .caption-rank .caption-release .caption-artist .caption-listen-count in macros.j2.

• The loop.index is sent as the rank to the render_image_link macro in simple-grid.svg.

• The inline fill color from query parameters is applied to each tspan and background rect.

Frontend

• The single "Show caption" toggle is replaced with four toggles: Show Rank, Show Release Title, Show Artist, Show Listen Count.

• Users can now pick their own caption text color and background color.

• The showCaption option is now based on the options: showRank || showRelease || showArtist || showListenCount.

• The color options are sent to the grid-stats API URL as query parameters.

• The ToggleOption component is refactored into a controlled component with checked and onChange props.

• Preview.tsx now accepts visibility for each field via CSS class targeting.

Defaults

• Show Rank: off

• Show Release on

• Show Artist: on

• Show Listen Count: off

• Caption text color: #ffffff

• Caption background color: #0000007a

Not included

• A font selection dropdown is not added yet. This needs to confirm which fonts are available in the SVG renderer.

Testing

• Each field can be toggled on or off independently. Shows or hides the correct caption element.

• The color pickers update the preview in time.

• The color values are passed as query parameters to the API and rendered inline in the SVG.

AI Usage

I got some help from AI during this implementation. It helped with understanding the data flow across Python, Jinja2 and React and, with debugging some SVG rendering issues. I understood every change before committing it. The architecture decisions are entirely based on my thinking, and also file choices and PR structure are my own.

[Gopal7387]

I made some changes to the caption layout so it looks like the original plan. Now the strip is set up like a 2×2 grid(small 4 squares):

• Top left square is for the Rank

• Bottom left square is for the number of people who have Listened

• Top right square is for the Release * Bottom right square is, for the Artist

Each of these squares can be turned on or off by itself. The layout still looks neat. Tidy no matter which ones are turned on.

[Aerozol]

Looks good (just looking at the screenshot, I haven't tested any behaviour). Some notes:

• I would change "Caption Options" to the same heading style as 'Advanced' and just call it "Captions"
• The spacing above the captions options section looks very big
• You can use the same toggles as in fresh releases, here: https://listenbrainz.org/explore/fresh-releases/ (the spacing and everything should match, and reuse as much CSS/styles as possible)
• I would change the checkbox next to 'skip missing covers' to a toggle as well, to keep it consistent.

[Gopal7387]

Hey @Aerozol
I really appreciate you taking the time to give me feedback. I have made some changes to the commits.

Here is what I did:

• I changed the name of "Caption Options" to "Captions". I used h4 styling so it looks like "Advanced".

• I took out the line that separated the captions section from the rest.

• I changed the "Skip missing covers" checkbox to a toggle button so it looks the same as the buttons.

• I replaced the ToggleOption component that we used in this part of the website with the Switch component that we use in the rest of the website like the fresh-releases toggles so they look exactly the same with the same classes and spacing.

Let me know if I need to make any changes, to the captions or anything else.

[Aerozol]

Nice work, the UI looks good to me :)

[Gopal7387]

@anshg1214
Just wanted to circle back on this, as its been visually approved.
So, if you have some time, do check this out.
Thanks 🙂

[anshg1214]

I've deployed your PR on test.listenbrainz.org.

Can we find a way to align the test for Release name and artist name better? Most of the titles are being cut off.

[Gopal7387]

Hi @anshg1214 🙂
I made a change to stop the text from getting cut off. I used a filter called truncate, from Jinja on the title and artist name of the image in the caption. Now when the names are really long they will show with three dots at the end of going over the edge. The title and artist name of the image will be shorter now. I used truncate with 18 characters so the title and artist name of the image will have 18 characters before the three dots appear. Let me know if the title and artist name of the image are too short or just right.

[Aerozol]

Thanks for deploying to test ansh!

A few notes from me:

• I think the background looks better slightly transparent (so you can see some of the cover art) (regression)
• When 'show rank' and 'show listen count' are disabled then the artist and release title should be left-aligned (regression)
• When rank and count are enabled, there is a huge gap between them and the titles

In general I think it needs to be smarter and move elements around based on what's been enabled, not just hide and show parts. If I've only selected 'release title' then it should be at the bottom left, with a smaller background. Currently there's no point in a user disabling anything, since it looks the same just with less info. Does that make sense?

No notes on the colour UI, nice one! But when I download the file the background is always black (text colours download fine).

[Gopal7387]

Hi @anshg1214 can you redeploy on test.listenbrainz.org when you have a moment? I made changes based on Aerozol's feedback.
I cannot check rank. Listen count locally because our dev database has no stats.
So it would be great if you could redeploy the changes to see them visually.

[anshg1214]

I've deployed the latest version to test.LB.

You can always use mock data in your backend to test things like these.

[Gopal7387]

Hi @Aerozol
Please have a look at the updated changes.
https://test.listenbrainz.org/explore/art-creator/?range=this_year&style=grid-stats
if there are any further issues or suggestions, just ping me 🙂

[Aerozol]

Thanks! Looking better! A few things still:

1. There is still a massive gap between the numbers on the left and the title/artist.
2. When only title/artist are selected, the text gets truncated too early (e.g. we don't need to end the text with '...' as early)
3. Great that title/artist now move to the left if they are the only ones displayed, but there's more combos that should be taken into account and displayed in a tidy manner. For instance, if only one element is displayed (or two that are side by side), the caption bar should be half height.

Example of large gap + placement that should be tidier/half height:

[Gopal7387]

Hi @Aerozol , pushed a new commit addressing latest feedback:

Half-height bar (15px) when only a single row of caption info is visible
Wider truncation (~32 chars) when only title/artist are shown and left column is absent
Fixed the gap between left and right columns
show_release and show_artist now properly passed through art_api.py → simple-grid.svg → macro so layout responds correctly to all toggle combos
Please take a look ,when you get a chance. Thanks 🙂