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 that id: c is the half column (0 to 17), r the half row (0 to 9), size its size.
  • A size is a name (small is 4x4 half cells, wide is 12x4) or any WxH in half cells at or above the kind's least size. The kinds table lists both.
  • x, y, w and h on a widget are its box in pixels. You may leave them out: they are worked out from the grid as x = 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

KeyWhat it holds
v1
objectsThe widgets, at most 40.
gridon: true, v: 2, and items: each widget's place.
backgroundOne 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.
homescenes (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.
lookColours every widget shares: ink (words), sub, panel, rim, solid, paper, accent, focus, and icons (the icon style).
elementsThe home's own parts; in a widget design each is { "hidden": true }.

A widget

KeyWhat it holds
idLetters, digits, - and _, up to 60, unique in the design.
type"widget"
kindWhat it is: one of the kinds in the table below.
sizeIts size (see the grid).
optsIts options. Each kind takes only the options listed for it.
styleHow it looks: panel, gradient, ink, font, icons, corners, shadow, show, colour, accent, opacity.
starttrue on the one widget the remote starts on.
items, turnA 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

LimitValue
File size256 KB
A design as stored64 KB
Widgets40
Apps in one widget16 (12 shown in a dock or folder)
Google Fonts families3
Nesting8 levels
Parts in the whole file4000
Items in any list200
Keys in any object120
Characters in any string2000 (words: 120 at most, each option lower)

What happens to an uploaded file

  1. 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.
  2. 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.
  3. The layout is checked on the grid: every widget a kind and size that exists, and room for each.
  4. 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.

KindWhat it isLeast sizeNamed sizesOptions
clockBig numerals, with the date under if you like2x2tile, wtile, small, medium, wide, xl, hero, fullformat ampm seconds date align
tallclockTall thin digits that fill the space, the couch-tv clock2x2tile, wtile, small, medium, wide, xl, hero, fullformat align
glassclockThe digits filled from the scene photo, couch-tv's signature4x2wtile, small, medium, wide, xl, heroformat scene
analogA face with hands and a coloured second hand2x2tile, small, largeseconds
flipclockSplit flap digits4x2wtile, medium, wideformat
wordclock"Twenty to eight, Wednesday morning"4x2wtile, small, medium, large
solarThe sun's arc today with sunrise and sunset4x2wtile, small, medium
worldclockTwo to four cities, faces or a list2x2tile, wtile, small, medium, widelabel cities
countdown"37 sleeps to Christmas"2x2tile, wtile, smalllabel month day unit icon
dateToday's date, long or short, with the weather if you like2x1line, wline, tile, smallshow dfmt align place
monthThis month's calendar, today marked2x2tile, small, large
timerA ring counting down2x2tile, wtile, smalllabel
weatherThe place, the temperature, the sky, high and low2x2tile, wtile, small, mediumplace hilo night
bigtempOne huge temperature on the colour of the day2x2tile, small, medium, largeplace
hourlyThe next hours: time, sky and temperature4x2wtile, small, medium, wideplace
weekThe next 7 days, with the range of each4x2wtile, small, tall, medium, largeplace
rainRain in the next two hours, as bars3x2wtile, small, mediumlabel
uvToday's UV, its band and the sun protection window2x2tile, wtile, smalllabel
sunTwo times and the sun's arc2x2tile, wtile, smalllabel
moonTonight's moon, its name and the next full moon2x2tile, wtile, small
airThe air quality number and band2x2tile, wtile, smalllabel
surfSwell, period, wind and the tide4x2wtile, small, mediumlabel
photoOne of the TV's photos, with a caption2x2tile, wtile, small, tall, medium, wide, large, xl, hero, fullimage fit caption sub
slideshowFlicks through your photos, dots show where it is up to2x2tile, wtile, small, tall, medium, wide, large, xl, hero, fullseconds_each caption sub
mosaicThree to five photos in a collage4x4small, medium, large, xlcount
artframeA painting in a mat with a museum label4x4small, tall, large, xl, hero, fullimage mat caption sub
memoryA photo from this date in past years2x2tile, wtile, small, mediumalign
keepOne show at a time, the next slides in2x2tile, wtile, small, medium
keeprowTwo to five shows with how far you got6x2medium, wide, herolabel shows
upnextOne show filling the space: Resume or Start over8x4medium, wide, xl, hero, fullapps sport
picks"Because you watched" posters4x3small, medium, widelabel align
appA single app as a big icon2x2tile, smallapps
folderA box of apps with a name: Streaming, Free to air2x2tile, small, tall, medium, largelabel apps cols
dockA row of your apps in a bar6x2row8, row12, row18apps more
appgridTwo to four rows of apps with their names4x4small, medium, large, xlapps cols names
gamesGame apps as tall tiles4x3small, medium, widelabel apps
nowplayingCover, song, artist, play and pause2x2tile, wtile, small, medium, large
soundscapeRain, fire, waves or brown noise2x2tile, wtilesound
queueThe next songs4x4small, tall, largelabel align
speakersEach room's speaker and its volume4x2wtile, small, talllabel players align
airconA dial with the setpoint and the other rooms2x2tile, wtile, small, tall, medium, largeentity
scenesMovie night, Goodnight, Morning as big buttons2x2tile, wtile, small, mediumlabel
controlsLights, lamps, blinds and locks as toggles2x2tile, wtile, small, medium, wide, largelabel controls cols switches align
cameraA still from a camera, refreshed while on screen4x2wtile, small, medium, largelabel cam align
doorbellThe last ring with a still2x2tile, wtile, small, mediumlabel align
energyMade today, money back, the day's curve2x2tile, wtile, small, medium, widelabel align
sensorOne reading: pool, rain gauge, humidity2x2tile, wtile, smalllabel reading align
batteryRemotes and controllers paired with the TV, and their charge2x2tile, wtile, small, medium
binsTonight's bins with their lid colours2x2tile, wtile, smalllabel weekday alt anchor lid_a lid_b bin_a bin_b
peopleWho is watching, switch with OK4x1line, wline, wtile
agendaToday's events with colours and times2x2tile, wtile, small, tall, medium, largelabel align
noteA sticky note typed at home2x2tile, wtile, smallalign
listReminders or shopping, ticked from the phone4x2wtile, small, tall, largelabel icon align
cardAny household number: solar today, the pool4x2wtile, smalllabel text icon
quoteA short line for the day4x2wtile, small, medium, widetext sub
wordA word and what it means4x2wtile, small, medium
newsOne to four headlines from a news feed4x2wtile, small, tall, mediumfeed label align
sportsScores for your teams4x2wtile, small, tall, mediumlabel league team align
stocksThe ASX, a few shares and the dollar2x2tile, wtile, small, talllabel tickers align
commuteDrive time and when to leave2x2tile, wtile, small, mediumlabel arrive_h arrive_m buffer weekdays align
welcomeA greeting in your own words4x1wline, wtile, medium, widekicker text sub align source times
quickSleep timer, picture, input2x1line, wline, tile, wtilequick align
wifiThe network and a code to join4x4small, medium, widealign
guideHouse guide, check out, around here4x2wtile, small, tallalign
screentimeMinutes left today and bedtime2x2tile, wtile, small, mediumalign
askAsk by voice or typing, answered on the TV by your own AI4x2wtile, small, medium, wide, largelabel align
agentMessages from your own AI agent, shown on the TV4x2wtile, small, medium, widelabel align
stackUp to ten widgets taking turns in one place (items, turn)as its widgets

Options

OptionValues
alignleft, center, right
alttrue or false
ampmtrue or false
anchorwhole number, 0 to 100000
appsa 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_hwhole number, 0 to 23
arrive_mwhole number, 0 to 59
bin_awords, up to 20 characters
bin_bwords, up to 20 characters
bufferwhole 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.
captionwords, up to 60 characters
citiesa list of up to 4 time zones (IANA names). Time zones by IANA name, such as Australia/Sydney.
colswhole number, 1 to 6
controlsa list of up to 8 controls, each { icon, name }
countwhole number, 1 to 8
datetrue or false
daywhole number, 1 to 31
dfmtshort, numeric, weekday, day_month, full
entity^climate\.[a-z0-9_]{1,64}$. A Home Assistant climate entity id.
feedabc, abc-justin, abc-sport, abc-business, sbs, guardian, bbc, rnz
fitcover, contain
format12h, 24h
hilotrue or false
icon^[a-z][a-z-]{1,23}$. An icon's name from the TV's icon set.
imagebackgrounds/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.
kickerwords, up to 60 characters
labelwords, up to 40 characters
leagueafl, nrl, aleague, epl, nba, bbl, cricket
lid_aa colour. A colour: #rgb, #rrggbb, #rrggbbaa, rgb() or rgba().
lid_ba colour. A colour: #rgb, #rrggbb, #rrggbbaa, rgb() or rgba().
mata colour. A colour: #rgb, #rrggbb, #rrggbbaa, rgb() or rgba().
monthwhole number, 1 to 12
moretrue or false
namestrue or false
nighttrue or false
placetrue or false
playersa 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.
quicka 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.
scenenight, fog, golden, dawn, water
secondstrue or false
seconds_eachwhole number, 5 to 600
showdate, weather, both
showswhole number, 1 to 5
soundrain, fire, waves, brown
sourcetyped, calendar. Where the guest's name comes from: typed words, or the bookings calendar kept on the TV. A design never carries the name.
sporttrue or false
subwords, up to 80 characters
switchesa 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.
teamwords, up to 24 characters
textwords, up to 120 characters
tickersa list of up to 6 ticker symbols. Ticker symbols, such as CBA.AX, ^AXJO or AUDUSD=X.
timestrue or false. false hides the check in and check out line.
unitsleeps, days, weeks
weekdaywhole number, 0 to 6
weekdaystrue or false

Style

KeyValues
panelglass, solid, colour, paper, none
gradientoff, soft
inkauto, white, ink, accent
fontinter, antonio, rounded, cormorant, jost, or any Google Fonts family by name
iconsline, solid, duotone, tile, glass, playful, classic
cornerssquare, soft, round, pill
shadownone, soft, lifted
showalways, live, night, day
coloura colour
accenta colour
opacitynumber, 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