The couch-tv design format
For people and AI tools that write a design file. Already made a layout somewhere else? Upload the file and we will check it.
A couch-tv design is one JSON file that describes a TV home screen: which widgets it has, where each sits on a grid, how they look, which apps they hold and what is behind them. Couch-tv Studio writes it, the couch-tv marketplace sells it, and every couch-tv TV draws it.
The format is open. Any tool, script or AI may write it, and anyone may build a tool that reads it. A file in this format can be uploaded to the marketplace as it is, and goes through the same checks as a design made in Studio.
- The JSON Schema:
couch-tv-design.schema.json(JSON Schema 2020-12). Check a file against it before you upload. - The tables under "Reference" and the schema are built from the TV's own code, so they say exactly what a TV accepts.
The file
{
"design": {
"v": 1,
"background": { "image": "backgrounds/scene-night.jpg", "darken": 0.25 },
"elements": { "clock": { "hidden": true }, "date": { "hidden": true }, "weather": { "hidden": true }, "people": { "hidden": true }, "quick": { "hidden": true }, "keep_watching": { "hidden": true }, "dock": { "hidden": true } },
"objects": [
{ "id": "clock", "type": "widget", "kind": "tallclock", "style": { "font": "Playfair Display" } },
{ "id": "weather", "type": "widget", "kind": "weather", "style": { "panel": "glass" } },
{ "id": "apps", "type": "widget", "kind": "folder", "opts": { "label": "Streaming", "apps": ["netflix", "youtube", "iview", "stan"], "cols": 2 } }
],
"grid": {
"on": true,
"v": 2,
"items": {
"obj:clock": { "c": 0, "r": 0, "size": "12x5" },
"obj:weather": { "c": 13, "r": 0, "size": "small" },
"obj:apps": { "c": 13, "r": 5, "size": "small" }
}
}
}
}
- UTF-8 JSON, at most 256 KB. The whole file is
{ "design": { ... } }, or the design object on its own. - Plain data only: no code, no HTML, no CSS, no links of any kind.
- Your own background photo never goes inside the file. Upload it beside the file (JPEG, PNG or WebP, up to 2 MB), or zip the file and the photo together. The marketplace makes its own copy of the photo.
The screen and the grid
The screen is 1920 by 1080. Widgets sit on a grid of 18 half columns by 10 half rows (9 by 5 tiles), and no two widgets share a cell.
grid.items["obj:<id>"]places the widget with thatid:cis the half column (0 to 17),rthe half row (0 to 9),sizeits size.- A size is a name (
smallis 4x4 half cells,wideis 12x4) or anyWxHin half cells at or above the kind's least size. The kinds table lists both. x,y,wandhon a widget are its box in pixels. You may leave them out: they are worked out from the grid asx = 80 + c * 100,y = 60 + r * 100,w = cols * 100 - 40,h = rows * 100 - 40.- A widget design hides the home's own parts (
elements, as in the example): the widgets draw everything.
The design
| Key | What it holds |
|---|---|
v | 1 |
objects | The widgets, at most 40. |
grid | on: true, v: 2, and items: each widget's place. |
background | One of the TV's own photos (image), one colour or two as a gradient (colour, colour2, angle, radial), or the settings for your own photo (darken, zoom, x, y, blur, scrim). With none, the TV's five scenes take turns. |
home | scenes (which scenes take turns: night, fog, golden, dawn, water), scene_seconds, ambient_weather (rain and snow over the scene when the weather has them) and a few look settings. |
look | Colours every widget shares: ink (words), sub, panel, rim, solid, paper, accent, focus, and icons (the icon style). |
elements | The home's own parts; in a widget design each is { "hidden": true }. |
A widget
| Key | What it holds |
|---|---|
id | Letters, digits, - and _, up to 60, unique in the design. |
type | "widget" |
kind | What it is: one of the kinds in the table below. |
size | Its size (see the grid). |
opts | Its options. Each kind takes only the options listed for it. |
style | How it looks: panel, gradient, ink, font, icons, corners, shadow, show, colour, accent, opacity. |
start | true on the one widget the remote starts on. |
items, turn | A stack only: up to ten widgets taking turns in one place. |
A design never carries a widget's data. The clock reads the TV's time, the weather the TV's own place, Keep watching the TV's own shows. A design says what to show, the TV fills it in.
Apps
Apps are named by their couch-tv id, never by a package name: "apps": ["netflix", "iview", "stan"]. Each TV opens the app it has under that id, on Google TV, Fire TV, Samsung, LG and the rest. An app the TV does not have shows as "Not on this TV". Leave apps out of a dock, folder or app grid and the TV fills it with the apps it has. A dock or folder shows up to 12 apps, an app grid 16. The ids are listed under "Reference".
Fonts
A widget's style.font is one of the TV's own fonts (inter, antonio, rounded, cormorant, jost) or any Google Fonts family by its name, such as "Playfair Display". At most three Google Fonts families in a design. The TV loads them from couch-tv, never from Google. A font file or a link to one is never accepted.
Words
Labels, captions and welcome words are drawn only if every character is a Latin letter (accents are fine), a space, or . , ' ! ? & ( ) : ; " -. A line with a digit, an @, an emoji or another script is not shown: write numbers as words ("Room four"). The time, the date and the temperature come from their own widgets.
Words that read as a phone number or a web address are never shown, however they are written ("oh four one two", "example dot com"). A design must not tell anyone to ring or visit anywhere.
Limits
| Limit | Value |
|---|---|
| File size | 256 KB |
| A design as stored | 64 KB |
| Widgets | 40 |
| Apps in one widget | 16 (12 shown in a dock or folder) |
| Google Fonts families | 3 |
| Nesting | 8 levels |
| Parts in the whole file | 4000 |
| Items in any list | 200 |
| Keys in any object | 120 |
| Characters in any string | 2000 (words: 120 at most, each option lower) |
What happens to an uploaded file
- The shape is checked: size, nesting, no links, no markup, no keys such as
__proto__. A file that breaks one of these is refused whole. - The TV's own gate rebuilds it from its allow list: unknown keys are dropped, numbers are brought into range, words are kept only as a TV draws them.
- The layout is checked on the grid: every widget a kind and size that exists, and room for each.
- A person looks at every design before it reaches the marketplace.
The upload page says what was changed or could not be kept, and why. Open the design in Studio to fix anything before it goes to review.
Reference
These tables are built from the TV's own code, so they say exactly what a TV accepts.
Widget kinds
Sizes are in half cells (columns x rows). A kind takes its named sizes, or any WxH at or above its least size, except a dock, which takes only its rows.
| Kind | What it is | Least size | Named sizes | Options |
|---|---|---|---|---|
clock | Big numerals, with the date under if you like | 2x2 | tile, wtile, small, medium, wide, xl, hero, full | format ampm seconds date align |
tallclock | Tall thin digits that fill the space, the couch-tv clock | 2x2 | tile, wtile, small, medium, wide, xl, hero, full | format align |
glassclock | The digits filled from the scene photo, couch-tv's signature | 4x2 | wtile, small, medium, wide, xl, hero | format scene |
analog | A face with hands and a coloured second hand | 2x2 | tile, small, large | seconds |
flipclock | Split flap digits | 4x2 | wtile, medium, wide | format |
wordclock | "Twenty to eight, Wednesday morning" | 4x2 | wtile, small, medium, large | |
solar | The sun's arc today with sunrise and sunset | 4x2 | wtile, small, medium | |
worldclock | Two to four cities, faces or a list | 2x2 | tile, wtile, small, medium, wide | label cities |
countdown | "37 sleeps to Christmas" | 2x2 | tile, wtile, small | label month day unit icon |
date | Today's date, long or short, with the weather if you like | 2x1 | line, wline, tile, small | show dfmt align place |
month | This month's calendar, today marked | 2x2 | tile, small, large | |
timer | A ring counting down | 2x2 | tile, wtile, small | label |
weather | The place, the temperature, the sky, high and low | 2x2 | tile, wtile, small, medium | place hilo night |
bigtemp | One huge temperature on the colour of the day | 2x2 | tile, small, medium, large | place |
hourly | The next hours: time, sky and temperature | 4x2 | wtile, small, medium, wide | place |
week | The next 7 days, with the range of each | 4x2 | wtile, small, tall, medium, large | place |
rain | Rain in the next two hours, as bars | 3x2 | wtile, small, medium | label |
uv | Today's UV, its band and the sun protection window | 2x2 | tile, wtile, small | label |
sun | Two times and the sun's arc | 2x2 | tile, wtile, small | label |
moon | Tonight's moon, its name and the next full moon | 2x2 | tile, wtile, small | |
air | The air quality number and band | 2x2 | tile, wtile, small | label |
surf | Swell, period, wind and the tide | 4x2 | wtile, small, medium | label |
photo | One of the TV's photos, with a caption | 2x2 | tile, wtile, small, tall, medium, wide, large, xl, hero, full | image fit caption sub |
slideshow | Flicks through your photos, dots show where it is up to | 2x2 | tile, wtile, small, tall, medium, wide, large, xl, hero, full | seconds_each caption sub |
mosaic | Three to five photos in a collage | 4x4 | small, medium, large, xl | count |
artframe | A painting in a mat with a museum label | 4x4 | small, tall, large, xl, hero, full | image mat caption sub |
memory | A photo from this date in past years | 2x2 | tile, wtile, small, medium | align |
keep | One show at a time, the next slides in | 2x2 | tile, wtile, small, medium | |
keeprow | Two to five shows with how far you got | 6x2 | medium, wide, hero | label shows |
upnext | One show filling the space: Resume or Start over | 8x4 | medium, wide, xl, hero, full | apps sport |
picks | "Because you watched" posters | 4x3 | small, medium, wide | label align |
app | A single app as a big icon | 2x2 | tile, small | apps |
folder | A box of apps with a name: Streaming, Free to air | 2x2 | tile, small, tall, medium, large | label apps cols |
dock | A row of your apps in a bar | 6x2 | row8, row12, row18 | apps more |
appgrid | Two to four rows of apps with their names | 4x4 | small, medium, large, xl | apps cols names |
games | Game apps as tall tiles | 4x3 | small, medium, wide | label apps |
nowplaying | Cover, song, artist, play and pause | 2x2 | tile, wtile, small, medium, large | |
soundscape | Rain, fire, waves or brown noise | 2x2 | tile, wtile | sound |
queue | The next songs | 4x4 | small, tall, large | label align |
speakers | Each room's speaker and its volume | 4x2 | wtile, small, tall | label players align |
aircon | A dial with the setpoint and the other rooms | 2x2 | tile, wtile, small, tall, medium, large | entity |
scenes | Movie night, Goodnight, Morning as big buttons | 2x2 | tile, wtile, small, medium | label |
controls | Lights, lamps, blinds and locks as toggles | 2x2 | tile, wtile, small, medium, wide, large | label controls cols switches align |
camera | A still from a camera, refreshed while on screen | 4x2 | wtile, small, medium, large | label cam align |
doorbell | The last ring with a still | 2x2 | tile, wtile, small, medium | label align |
energy | Made today, money back, the day's curve | 2x2 | tile, wtile, small, medium, wide | label align |
sensor | One reading: pool, rain gauge, humidity | 2x2 | tile, wtile, small | label reading align |
battery | Remotes and controllers paired with the TV, and their charge | 2x2 | tile, wtile, small, medium | |
bins | Tonight's bins with their lid colours | 2x2 | tile, wtile, small | label weekday alt anchor lid_a lid_b bin_a bin_b |
people | Who is watching, switch with OK | 4x1 | line, wline, wtile | |
agenda | Today's events with colours and times | 2x2 | tile, wtile, small, tall, medium, large | label align |
note | A sticky note typed at home | 2x2 | tile, wtile, small | align |
list | Reminders or shopping, ticked from the phone | 4x2 | wtile, small, tall, large | label icon align |
card | Any household number: solar today, the pool | 4x2 | wtile, small | label text icon |
quote | A short line for the day | 4x2 | wtile, small, medium, wide | text sub |
word | A word and what it means | 4x2 | wtile, small, medium | |
news | One to four headlines from a news feed | 4x2 | wtile, small, tall, medium | feed label align |
sports | Scores for your teams | 4x2 | wtile, small, tall, medium | label league team align |
stocks | The ASX, a few shares and the dollar | 2x2 | tile, wtile, small, tall | label tickers align |
commute | Drive time and when to leave | 2x2 | tile, wtile, small, medium | label arrive_h arrive_m buffer weekdays align |
welcome | A greeting in your own words | 4x1 | wline, wtile, medium, wide | kicker text sub align source times |
quick | Sleep timer, picture, input | 2x1 | line, wline, tile, wtile | quick align |
wifi | The network and a code to join | 4x4 | small, medium, wide | align |
guide | House guide, check out, around here | 4x2 | wtile, small, tall | align |
screentime | Minutes left today and bedtime | 2x2 | tile, wtile, small, medium | align |
ask | Ask by voice or typing, answered on the TV by your own AI | 4x2 | wtile, small, medium, wide, large | label align |
agent | Messages from your own AI agent, shown on the TV | 4x2 | wtile, small, medium, wide | label align |
stack | Up to ten widgets taking turns in one place (items, turn) | as its widgets |
Options
| Option | Values |
|---|---|
align | left, center, right |
alt | true or false |
ampm | true or false |
anchor | whole number, 0 to 100000 |
apps | a list of up to 16 app ids (below). Apps by couch-tv catalogue id (never a package name): each TV opens the app it has under that id. A dock or folder shows up to 12, an app grid 16. Leave it out to show every app the TV has. |
arrive_h | whole number, 0 to 23 |
arrive_m | whole number, 0 to 59 |
bin_a | words, up to 20 characters |
bin_b | words, up to 20 characters |
buffer | whole number, 0 to 60 |
cam | ^camera\.[a-z0-9_]{1,64}$. A Home Assistant camera entity id. A TV shows it only when its own config.json names it too. |
caption | words, up to 60 characters |
cities | a list of up to 4 time zones (IANA names). Time zones by IANA name, such as Australia/Sydney. |
cols | whole number, 1 to 6 |
controls | a list of up to 8 controls, each { icon, name } |
count | whole number, 1 to 8 |
date | true or false |
day | whole number, 1 to 31 |
dfmt | short, numeric, weekday, day_month, full |
entity | ^climate\.[a-z0-9_]{1,64}$. A Home Assistant climate entity id. |
feed | abc, abc-justin, abc-sport, abc-business, sbs, guardian, bbc, rnz |
fit | cover, contain |
format | 12h, 24h |
hilo | true or false |
icon | ^[a-z][a-z-]{1,23}$. An icon's name from the TV's icon set. |
image | backgrounds/albury-storm.jpg, backgrounds/aresquiers-beach.jpg, backgrounds/grose-valley.jpg, backgrounds/loop-clouds.jpg, backgrounds/loop-fire.jpg, backgrounds/loop-ocean.jpg, backgrounds/loop-rain.jpg, backgrounds/tessellated-pavement.jpg, backgrounds/vang-vieng-sunset.jpg. One of the TV's own photos. |
kicker | words, up to 60 characters |
label | words, up to 40 characters |
league | afl, nrl, aleague, epl, nba, bbl, cricket |
lid_a | a colour. A colour: #rgb, #rrggbb, #rrggbbaa, rgb() or rgba(). |
lid_b | a colour. A colour: #rgb, #rrggbb, #rrggbbaa, rgb() or rgba(). |
mat | a colour. A colour: #rgb, #rrggbb, #rrggbbaa, rgb() or rgba(). |
month | whole number, 1 to 12 |
more | true or false |
names | true or false |
night | true or false |
place | true or false |
players | a list of up to 6 entity ids. Home Assistant media player entity ids. A TV shows one only when its own config.json names it too. |
quick | a list of up to 6: sleep, picture, look, soundscape, screen_off, headphones, input, bluetooth, network, tvsettings, screensaver |
reading | ^sensor\.[a-z0-9_]{1,64}$. A Home Assistant sensor entity id. A TV shows it only when its own config.json names it too. |
scene | night, fog, golden, dawn, water |
seconds | true or false |
seconds_each | whole number, 5 to 600 |
show | date, weather, both |
shows | whole number, 1 to 5 |
sound | rain, fire, waves, brown |
source | typed, calendar. Where the guest's name comes from: typed words, or the bookings calendar kept on the TV. A design never carries the name. |
sport | true or false |
sub | words, up to 80 characters |
switches | a list of up to 16 entity ids. Home Assistant light, switch, fan or cover entity ids. A TV shows one only when its own config.json names it too. |
team | words, up to 24 characters |
text | words, up to 120 characters |
tickers | a list of up to 6 ticker symbols. Ticker symbols, such as CBA.AX, ^AXJO or AUDUSD=X. |
times | true or false. false hides the check in and check out line. |
unit | sleeps, days, weeks |
weekday | whole number, 0 to 6 |
weekdays | true or false |
Style
| Key | Values |
|---|---|
panel | glass, solid, colour, paper, none |
gradient | off, soft |
ink | auto, white, ink, accent |
font | inter, antonio, rounded, cormorant, jost, or any Google Fonts family by name |
icons | line, solid, duotone, tile, glass, playful, classic |
corners | square, soft, round, pill |
shadow | none, soft, lifted |
show | always, live, night, day |
colour | a colour |
accent | a colour |
opacity | number, 0.2 to 1 |
App ids
netflix youtube prime disney stan binge kayo iview sbs 7plus 9now 10play foxtel paramount appletv max spotify youtubemusic googletv twitch plex audible moonlight optussport britbox docplay hayu kanopy beamafilm abclisten abcnews skynewsau fetch stansport abckids hotstar jiocinema sonyliv zee5 mxplayer hoichoi aha sunnxt erosnow altt airtelxstream tataplaybinge lionsgateplay shemaroome etvwin chaupal discoveryplusin waves fancode jiosaavn gaana wynk aajtak ndtv hungama tubi plutotv crunchyroll mubi shudder curiosity dailymotion hulu peacock youtubetv sling fubo philo starz mgmplus amcplus fandango rokuchannel espn nba f1tv cnn bloomberg pbskids pandora iheart iplayer itvx channel4 my5 nowuk bbcnews dazn raiplay now vtmgo vrtmax youtubekids applemusic amazonmusic tidal deezer tunein soundcloud xbox geforcenow steamlink retroarch kodi vlc jellyfin stremio nuvio