fix: make Apple TV text and posters easier to read from the couch
Problem and reproduction
I've been told the metadata and synopses on Apple TV are hard to read from the couch.
Most of that text was below Apple's own smallest tvOS caption size (23 points): poster captions were 20 and 18, the synopsis 22, cast roles 17, and Apple's body size is 29.
Making the text bigger on its own doesn't work.
Every row on the detail hero sits in a fixed, clipped box, and captions are a single line under a poster of fixed width, so larger text is cut off or truncates sooner unless the boxes and posters grow with it.
Implementation and impact
Detail pages
- Synopsis 22 > 28 (still four lines) in a text column 900 wide (was 750); heading, year and runtime 24 > 29; credit line 23 > 27; badges 18 > 22.
- The poster grows from 235 by 353 to 290 by 435, upward into the empty space under the logo. The action row and the fold have not moved.
- The hero's layout numbers are now derived from the poster height and one set of constants, where they were repeated literals, and the loading page and text shade use the same ones.
- Series page: the season poster is the same size as the hero poster (was 360 by 540), the season header is 40 points shorter so the episode row sits higher, and the season synopsis is set like the series synopsis (28 points, near-white, four lines, up to 1,300 wide).
- Episode cards are captioned like Home's Continue Watching cards: the number and name together in the 24-point card title style ("3 · The Long Way Home"), then the summary on three lines and the date in the 22-point grey second-line style. The separate "EPISODE 3" line is gone, which is where the third summary line comes from. The still stays 400 by 225.
- Cast names and roles 20 and 17 > 24 and 21, trailers 21 and 17 > 25 and 21, Media Information one step up throughout.
- The standalone season page and the fallback episode page take the same synopsis and credit sizes. Their episode rail's captions go from 24 and 18 to 28 and 22. Their hero is 49 points taller (99 for an episode with two metadata rows), and the season page's series capsule moves above the title so "Read more" is no longer clipped.
Spotlight
- Synopsis 22 > 28 and 900 wide (was 760), metadata 24 > 29, episode line 23 > 29.
- The logo has no fixed position; it sits on the text, so it rises by up to about 29 points. The zoom and logo flight when a slide opens measure the logo where it is and are unchanged.
Posters and captions
- Captions 20 and 18 > 24 and 22 on every card, including Continue Watching, Next Up and Library cards, whose card size is unchanged.
- Row posters (Home, Home Collections, More Like This, collection rail, studio rows, cast) 211 > 240 wide.
- Grids (Search and its request results, Library tab, library pages, collection pages, Collections tab, studio grids, a chosen Calendar day) go from seven across to six, so 217 > 260 wide. Person filmography goes from eight across to seven at the Standard poster size. The portrait at the top of a person's page grows with the same width, from 176 to 200 wide.
- Calendar trending posters 220 > 240 wide with the same captions.
- Grids keep eight rows of decoded artwork instead of ten, so decoded memory stays about where it was (roughly 74 MiB against 75.5 by my arithmetic, not profiled).
Two fixes on the series page
- A season's Load button now sets the shown season while it has focus.
- Just after crossing into a new season, each move along the episodes flicked the header and season poster back to the previous season and forward again. The focused card was past the edge of the row while it scrolled, so the season came from the row's leading edge, which was still in the season before. A focused episode up to two cards past either edge now still decides the season. The same code is on main, so I believe this was already possible there and the smaller poster made it obvious; I haven't confirmed it on a main build.
- The season poster no longer turns over when the next season shows the same picture.
Affects Apple TV only, on Silo, Emby and Jellyfin. The caption tokens and layout constants are tvOS-only.
Unchanged
- Settings.
- iPhone and iPad.
- Card sizes for Continue Watching, Next Up and Library cards, the episode still, the action row, section headers and the full description panel.
- Focus behaviour, the fold, and how pages load (70 items at a time).
Validation
scripts/l10n/sync-string-catalog.shbuilds the iOS and tvOS apps for the simulator and both pass; no strings changed.python3 scripts/ci/check-docs.py --base origin/mainpasses.- One test added (
TVCatalogGridIndexTests) for the artwork window following the grid's columns and rows. I did not run the test suite locally; CI runs it. - Full CI results are on this PR.
Performance
No benchmarks were run.
A grid poster is decoded at 520 by 780 pixels instead of 434 by 651, offset by keeping eight rows instead of ten.
Home warms seven posters per row instead of eight.
Testing status
- Tested? Partly.
- Environment: tvOS Simulator (Apple TV 4K 3rd generation, tvOS 27.0), against Silo and Emby profiles.
- Revision: this branch at
337591c6, in a local build that also had my other three open PRs merged in. - Checks and results: I went through the build on the simulator. The season synopsis matches the series synopsis, and I looked at the new episode cards. Scrolling episodes across a season boundary changes the season and poster once and they stay put; a log on the first build showed the three flick-backs, and I confirmed the fix on screen with the version before the last commit, which let any focused episode decide.
- Limitations: The later commits (narrowing the season fix to two cards past either edge, the Load button, the episode loading skeleton's second row) have not been rechecked on screen. An episode whose series title can't be found still loads into a hero 50 points shorter than its skeleton. Not run on a physical Apple TV, so readability from the couch itself is unconfirmed. Not checked: a movie with no logo, no poster or no synopsis; a full row of badges; long German or Japanese titles; the standalone season page and fallback episode page; opening a spotlight slide and coming back; Home with Title Only and Artwork Only captions; the part-filled last row while a grid loads its next page; Reduce Motion; memory on older Apple TVs.
Design impact and approval
- Design impact: Larger text and posters across Apple TV as listed above, six-across grids, a larger hero poster, a smaller season poster and a higher episode row.
- Approval from blurbery: I asked for this and chose the sizes: the proposed text sizes, posters growing in rows and grids, the season poster matching the hero poster, the same caption size on Continue Watching, Next Up and Library cards, and the season synopsis matching the series synopsis. Smaller choices made while building (poster-to-caption gaps up by 2 to 4 points, the wider season synopsis, seven-across filmography, six-across Calendar day, the season page's capsule position) are in the build I looked at.
Documentation impact
Updated in this PR: README.md (Search is six across), docs/apple-tv-browsing.md, docs/app-design.md and docs/apple-tv-focus.md.
The privacy policy is unchanged; nothing about what the app sends or stores changes.
- I checked the docs this change affects and updated them in this PR, or explained above why none needed changes.
AI disclosure
I implemented these changes and used Claude Fable as a tool.