screenRIG
DashboardGet started

Built-in cards

Add live components to a playlist: menus, clocks, queues, scores, weather and gauges. Choose a card, set its properties and publish.

A card is a built-in component on a playlist canvas. It fills its rectangle with a clock, menu, queue or other live detail, and can sit over images or video.

Views

ViewUse it for
canvasThe full design, filling its canvas rectangle.
cornerA compact plate over other content, anchored to a corner.
chipA single line over other content, anchored to a corner.

Choose params.view and params.corner: top-left, top-right, bottom-left or bottom-right. Canvas forms follow the rectangle: strip, landscape, square, portrait or tower. Each card lists the forms and views it supports.

Themes

Choose params.theme: neomustard (NeoMustard), aurora (Aurora), folio (Folio), signal (Signal), manifesto (Manifesto), bloom (Bloom), clear-dark (Clear Dark), clear-light (Clear Light). The gallery selects the published default theme. Set background to none for a transparent canvas backdrop. Corner and chip views use their theme’s compact plate.

Common properties

These properties control the theme and position of every card. Set them in params.

NameTypeDefaultValues and limitsDescription
themestring"neomustard""neomustard", "aurora", "folio", "signal", "manifesto", "bloom", "clear-dark", "clear-light"
backgroundstring"theme""theme", "none"none paints no backdrop, for layering over video.
accentstring, nullnullpattern: "^#[0-9A-Fa-f]{6}$"Overrides the theme accent.
viewstring"canvas""canvas", "corner", "chip"canvas fills the rect with the full design; corner is a compact plate and chip a one-line pill, both overlaying content and hugging corner.
cornerstring"top-right""top-left", "top-right", "bottom-left", "bottom-right"Which corner of the rect a corner or chip view hugs.

Static and dynamic properties

Static properties live in the playlist’s params: theme, view, corner, location, titles and layout. Change them by publishing the playlist again. Dynamic properties are the values marked dynamic: true in the card contract, such as menu sections, queue entries or gauge readings.

Bind the item’s data to a key in the project’s card data store. Players apply defaults, then static params, then the document’s dynamic properties. The live document cannot change styling. With a data key, keep dynamic properties out of params; without one, put the whole configuration in params. A card bound to a missing document stays hidden until the document is written.

Feeds

Feeds are third-party data fetched and cached by the backend and passed to the card by the Player. For weather, set location with a name, latitude and longitude. The backend derives the feed key from these static properties; do not send a feed field in the canvas item. Feed documents carry source attribution and fetch timestamps. Each card reference names its feed schema and source attribution.

Publish a card canvas

Follow Start to install the official plugin, select your project and pair a Player. Use the API to publish a card canvas and set its properties. Save the following as playlist.json; its gauge reads live data from gauge-main.

{
  "name": "Live gauge",
  "pages": [
    {
      "id": "main",
      "canvas": {
        "width": 1920,
        "height": 1080,
        "background": "#000000FF",
        "viewport_fit": "contain"
      },
      "transition": {
        "type": "cut"
      },
      "advance": {
        "mode": "duration",
        "after_ms": 15000
      },
      "primitives": [
        {
          "id": "gauge",
          "primitive": "card",
          "card": "gauge",
          "major": 1,
          "params": {
            "theme": "neomustard"
          },
          "data": "gauge-main",
          "rect": {
            "x": 0,
            "y": 0,
            "width": 1920,
            "height": 1080
          },
          "layer": 0,
          "content_fit": "fill"
        }
      ]
    }
  ]
}

Use API authentication for an authorized identity or project bearer. ScreenRig-Project selects the project for an identity bearer and must match a project bearer’s bound project. The environment variables below stand for your authorization and project; keep their values outside playlist files.

curl --request POST "https://api.screenrig.ai/api/playlists" \
  --header "Authorization: Bearer $SCREENRIG_TOKEN" \
  --header "ScreenRig-Project: $SCREENRIG_PROJECT" \
  --header "Content-Type: application/json" \
  --data @playlist.json

The response identifies the playlist with a pl_ id. A pending_review response waits for the project’s review before going live. To change static properties, send the edited {name, pages} document with PUT /api/playlists/{id}. A card’s major pins its contract; omitting it selects the current major when the playlist is stored.

Write live values

Use PUT /api/card-data/{key} with a {document} body. Writes replace the whole document. The document contains only dynamic properties accepted by every card bound to that key. Keys are 1–256 characters from letters, digits, ., _, :, / and -, start with a letter or digit, and cannot start with feed:. Documents are JSON objects of at most 1 MiB.

curl --request PUT "https://api.screenrig.ai/api/card-data/gauge-main" \
  --header "Authorization: Bearer $SCREENRIG_TOKEN" \
  --header "ScreenRig-Project: $SCREENRIG_PROJECT" \
  --header "Content-Type: application/json" \
  --data '{"document":{"metrics":[{"label":"Capacity","value":72,"unit":"%"}]}}'

Screens showing the card refetch the document and update it in place. Read a document with GET /api/card-data/{key}; its revision ETag can be sent as If-Match on the next write. Add Idempotency-Key for a safely repeatable write. List keys with GET /api/card-data and its after cursor; delete a document with DELETE /api/card-data/{key} and its If-Match revision.

Images in card properties use media:<mediaId>, referencing a ready image in the same project. A live data write requires those images to be approved. Never put an image URL in a card property.

Assign and verify with the CLI

Use the official plugin’s bundled CLI with the same project. Take the playlist id from the API response and the screen id from screen list, then assign and inspect the result:

screenrig screen list
screenrig screen assign scr_EXAMPLE --playlist-id pl_EXAMPLE
screenrig screen screenshot scr_EXAMPLE

Assignment records the desired playlist. Inspect Player evidence before reporting that it plays. CLI reference · API reference.

Card reference