# 210 — Cinematic Vinyl

Requested 2026-10-06 from three visual references. Built in the addon source;
GUI testing was not authorized in this session. The touched XML and music
textures were synced to the installed skin copy, then Kodi was restarted while
no player was active to load the service changes and apply the requested defaults.
No release or commit.

## Experience

- Vinyl joins the existing cinematic Home renderer: a dark fading backdrop,
  the selected music item's title, genre/type, description, artist/count/time,
  original artwork, Play, Tracks, Shuffle when applicable and More options.
- Existing transparent playlist title images replace text titles in the hero
  and banner cards. A missing title-image version uses the ordinary title.
- Seven layouts: square covers, circular vinyl records with subtle grooves,
  circular artist portraits, landscape cards, cinematic banners with title
  images, compact track cards and photographic genre tiles.
- An explicit detail opens a WindowXML music card with cover/title artwork,
  a track list, Play, Shuffle, Favorite, More options, Back and page controls.
  Album/artist/genre lists request one 20-song page at a time; playlist detail
  is read once and preserves track order. Selecting a track plays from it in
  the displayed order. Play/Shuffle of a paged collection uses the full collection.
- Detail track context menus reuse the current context manager, including
  originating widget UID, action order and hidden actions. Deliberate mutations
  use the existing ownership checks and refresh the dialog's data/selection.
  A canceled deletion retains the dialog. Other skins retain collection folders.

## Default layout and preservation

`MilionarVinylCinemaV1` applies the presentation once after Home's existing
full defaults have been initialized. Only Vinyl changes. Existing sources,
counts, sorting, clicks, widget UIDs and serialized context menus are retained;
free slots are filled from the shipped Vinyl defaults. Widgets are reordered
by music source, carrying their own menus with them, then assigned the styles:

1. AI curator — cinematic banners.
2. Genres — photographic tiles.
3. Discover — square covers.
4. My playlists — square covers.
5. Favorite tracks — circular records.
6. Artists — circular portraits.

Customized alternative sources and duplicate widgets are preserved too.
Later layout edits are respected because the migration flag prevents repeated
application. Both the fallback slot catalog and `resources/defaults/skin.json`
ship this mixed layout. The separate new Popular tracks source reads the actual
`featured.topTracks`; it is available in the widget editor, not substituted for
the user's favorite tracks.

## API audit and implementation

Read the local Vinyl app's `BrowseCard`, `PlaylistCover`, playlist hero components,
`shared/media.ts`, REST client and server routes. Read-only public API confirmed
`featured.curatorPlaylists`, `featured.topTracks` and title-image/cover availability
for Daylong House Journey (playlist 1063, both HTTP 200).

- `title_image_version` identifies the transparent title asset;
  `/playlists/:id/title-image?v=:version&w=1200` is the normal hero variant,
  `w=720` the low-power variant. These are supported aspect-preserving widths.
- Artwork retains `cover_version`; hero artwork omits square `size` to preserve
  the original custom cover. Thumbnails use the existing widget size profile.
- Genre images use their returned `cover_songs`; artists use the existing portrait
  route. No generated editorial artwork or new AI/TTS calls.
- Cache whitelist includes presentation metadata but excludes private share tokens,
  server paths and session credentials. Existing caches request a background
  presentation upgrade and remain usable. Title-image version changes invalidate
  the visible row. Home builders remain cache-only.
- Public media URLs continue to use anonymous authorization. Account/session
  changes prevent subsequent detail actions and close the old dialog.

Generators: `gen_cinema.py` composes `gen_music.py`; existing shape generator
adds music masks/grooves. `gen_vinyl_detail.py` owns the detail XML.
Runtime: `wcs/vinyl/presentation.py`, `detail.py`, `defaults.py` and existing
client/widgets/actions/context. New addon strings 32685–32690 in cs/sk/en.

## Verification

Targeted offline tests cover the cache-only builder and output context decorator,
real Popular tracks source, versioned artwork and supported widths, preservation
of context menus/UIDs/clicks through reordered defaults, detail paging, playback
order, account changes, failed page retention and canceled deletion. Existing
cinema, media detail, Vinyl cache/performance, slot, context and defaults tests
were checked. 115 targeted checks passed. Python compilation and XML parsing passed.
The saved settings were read back after activation: curator/banner, genres/categories,
discover/square, playlists/square, favorite tracks/record and artists/artist,
all with their custom menus still present. This verifies configuration, not rendering.

Rendering, remote-control navigation and audio playback in live Kodi remain
unverified, per the user's standing prohibition on unsolicited GUI testing.

## Hero layout (2026-10-06, from the user's reference of the Vinyl app)

One text block that ends right above the buttons (`gen_music.HERO_BODY`: a bottom-aligned vertical group list, so a
short description or a missing line leaves no hole), top to bottom:

1. the playlist's title image (760x150 box, kept aspect) or the text title in the films' three font steps;
2. genres, upper case and letter-spaced, at most three, joined with ` • ` (no genres known: the kind, `PLAYLIST`);
3. the description, up to three lines (auto height);
4. facts in the small dim font: artist, track count, length, creation date and time (API UTC -> local time);
5. the buttons, texts as before, a horizontal group list (31905): Play 31901, Shuffle 31902, Favorite 31903,
   More options 31904. A hidden button (no shuffle of a track or radio; no favorite of a genre or without an
   account) leaves no gap and the navigation skips it.

The separate cover picture and the Tracks button are gone; the item's own click still opens the detail.

- **Playlist genres.** The playlist lists of the API carry no genres. The service refresh (`widgets._playlist_genres`)
  reads the detail of each shown playlist once, keeps the three most frequent genres of its tracks in
  `skin_cache/vinyl_playlist_genres.json` (keyed by id and `updated_at`, at most 60 details per refresh) and stores
  them as `_genres`. The widget path stays cache-only.
- Favorite runs the existing `vinyl_context` `op=favorite`; its label comes from the cached `is_favorite` only
  (`presentation.favorite`).
- Item properties `milionar.hero.meta / favorite / favorite_label`; `size` is empty when a title image stands for
  the title; `left` is no longer used by Vinyl.
- The click option `hero` (Focus hero buttons, 32684) works for the Vinyl rows like for films and series (focuses 31901).

Verified: 18 Vinyl cinema tests, 30 Vinyl performance tests (the refresh test now expects the one-time genre
details), cinema and detail suites; live Kodi 21.3 after a restart: playlist with a title image and genres, a
favorite track (text title, no shuffle), focus across the buttons and back to the rows, `hero` click focused 31901
without playback (setting restored). Play, Shuffle and Favorite were not pressed.

## Card shapes and focus frames (2026-10-06)

- Kodi lays a diffuse mask over the whole picture, also over the part `aspectratio` scale crops away, so a mask of
  the card's own size lost its corners on every cropped cover (banner, genre, wide card). Every music card now
  draws the square cover (`ListItem.Art(thumb)`) uncropped and a window mask (`gen_cinema_textures.band`) opens the
  card's rounded shape.
- The panel `card.png` is drawn with its border (round corners at any size); masks and shades are twice the card's
  size like the film cards; the genre tile has its own shade.
- Round cards (record, artist) have a ring focus frame (`focus_circle.png`, `gen_music.FRAMES`), centred texts and a
  "more" panel as tall as the circle.

Verified natively (2560x1440) for all seven styles with a focused and an unfocused card; the three rows switched
to record / landscape / track for the check were restored.