Watch it built
Film / Build a kiosk app with the SDK
2:17

Some screens are apps, not stills. Claude Code writes a kiosk app, uploads it as an immutable release with app upload, and pins it in one playlist for a kiosk and a welcome wall. Chapters and transcript →
Use screenrig after the session setup on
Quickstart.
Choose the content path
| Page | Tool |
|---|---|
| Finished image or video | media upload |
| Finished poster, menu or announcement the agent made | media upload the finished image |
| Supplied art with text over it | media upload the art, then a built-in card on the same page |
| Text, a table, a menu or a board that stays editable | A built-in card: card create, placed in a playlist |
| Live video, stream, iframe or application | Playlist primitives |
| A dashboard behind a sign-in | A BI web connection and view, placed in an iframe primitive |
| Media that changes as files are added or tagged | A dynamic selector (tag, folder or all), checked with media selector-preview |
| Background music across the whole playlist | media upload an MP3, then the playlist audio soundtrack |
The agent makes or finds its own images and uploads them. Cards draw their text in the Player, so a changed word or number needs no new image. Animation alone does not require either.
Add a soundtrack
A playlist can carry one soundtrack: an ordered list of MP3 tracks that plays continuously while pages change. Page transitions never stop, restart or fade the music. The soundtrack is a playlist setting, not a seventh primitive, so it has no rectangle or layer on the canvas.
Upload each track with media upload. MP3 files go up as they are; WAV, AAC,
M4A, OGG and FLAC files are transcoded to MP3 first. Every track becomes an
audio media object with a med_… id and a duration.
screenrig media upload ./intro.mp3 --tag LobbyMusic
screenrig media upload ./bed.wav --tag LobbyMusic
Name the tracks in the playlist audio member; it holds 1 to 128 tracks.
Tracks play in order, back to back. loop (default true) starts again at the first track after the last;
volume (default 1, from 0 to 1) scales the Player's own volume.
{
"name": "Lobby",
"audio": {
"tracks": [
{ "id": "intro", "media_id": "med_01EXAMPLEINTRO000000000" },
{ "id": "bed", "media_id": "med_01EXAMPLEBED00000000000" }
],
"loop": true,
"volume": 0.8
},
"pages": [
{ "id": "welcome", "audio_cue": { "track": "intro", "restart": true } },
{ "id": "menu" }
]
}
A page may carry an optional audio_cue. When that page appears, the Player
switches to the named track from its start; if that track is already playing,
it restarts only when restart is true. The sequence then continues from the
cued track. Cues are hints: a Player applies them with a short fade or skips
them when the track is not ready. Pages without a cue leave the music alone.
Page fields other than id and audio_cue are omitted from the example above.
Replacing a playlist replaces its soundtrack too; leave audio out to remove
it. Video and stream primitives play silent unless one sets muted to false.
A page with a primitive that plays its sound pauses the soundtrack, which
resumes from the same point on the next page without sound, and that page
cannot carry an audio_cue.
Bind a page to a track
For an album or a book with one page per track, or any page that lasts exactly as long as a track, bind the page to its track.
Set the page advance to { "mode": "audio_end" }. The page applies its
audio_cue when it appears, as any cue does, and ends when that track ends,
the way a media_end page ends with its video. The page must carry an
audio_cue and the playlist an audio soundtrack. Image and video primitives
follow the duration rules: no dwell_ms, and one_at_a_time: true on every
dynamic selector (all, tag, folder, or ids with more than one id), even
when it matches one object today. A stream primitive still needs a
duration page, and an application on the page is never its controller.
max_ms is an optional safety hint; the server sets the deadline from the track's length, so leave it out. If
the Player cannot play the track, the page still lasts the track's length.
Set cued to true in the audio member to stop the soundtrack after each
track. A cued track plays only when a page audio_cue starts it. It keeps
playing under any ordinary pages that follow its page until it ends, and then
the soundtrack is silent until the next cue, so a page and its track stay
bound, with any number of ordinary pages between bound pages. loop has no
effect on a cued soundtrack, and cued defaults to false.
{
"name": "Album",
"audio": {
"tracks": [
{ "id": "song1", "media_id": "med_01EXAMPLESONG1000000000" },
{ "id": "song2", "media_id": "med_01EXAMPLESONG2000000000" }
],
"cued": true
},
"pages": [
{ "id": "song1-cover", "advance": { "mode": "audio_end" }, "audio_cue": { "track": "song1", "restart": true } },
{ "id": "interlude", "advance": { "mode": "duration", "after_ms": 8000 } },
{ "id": "song2-cover", "advance": { "mode": "audio_end" }, "audio_cue": { "track": "song2", "restart": true } }
]
}
Page fields other than id, advance and audio_cue are omitted from the
example above.
Place a card for live text
A built-in card draws text, a menu, a table, a clock or a gauge in the Player
itself, so the text stays editable and a new value reaches every screen without
a new still. cards list shows the types, card create makes an instance, and
the playlist places it as a card primitive. card data put writes its live
values. Cards lists every type and layout.
screenrig cards list
screenrig card create --type gauge --file gauge-params.json
screenrig card data put crd_EXAMPLE --file gauge-data.json
Show a web page, a video or a document
An iframe primitive shows a web page. Its src is any http or https
address the screen can reach, a page on the local network included, and its
content_fit is fill. What the page can call on the screen's own network is in
Pages on the screen's network.
A YouTube link is stored as an autoplaying, looping embed
whose page can last as long as the video: see
Players. fallback_src takes any form src takes and shows when src does not load,
and each reload tries src first again. reload_s is 0 (never, the default) or
60 to 86,400 seconds: the screen loads the page again that often while it shows.
navigation_allowlist limits where the page itself may go. Beyond src and
fallback_src, it lists 1 to 64 addresses, each [scheme://]host[:port][path].
*.example.com is any subdomain (list example.com too for the
bare name), * is any host, a port of * is any port, a path that ends in /
covers everything under it, another path matches only itself, and no scheme
means http or https. A link, script or redirect to any other address is
refused and the page stays; a src that redirects off the list counts as not
loading. Leave it out for no restriction.
{
"id": "board",
"primitive": "iframe",
"title": "Queue board",
"src": "https://queue.example.com/board",
"fallback_src": "https://queue.example.com/static/board.html",
"reload_s": 300,
"navigation_allowlist": ["auth.example.com", "cdn.example.com/assets/"],
"rect": { "x": 0, "y": 0, "width": 1920, "height": 1080 },
"layer": 0,
"content_fit": "fill"
}
A Google Slides, Docs or Sheets file, or a PowerPoint, Word or Excel file on
OneDrive or SharePoint, goes in src as its share link, Publish to web link or
Embed code, and screenRIG stores the embed address. Slides loop and advance on
the link's delayms (10 seconds by default, held to the page's after_ms, so
give the page the time of the whole deck); Docs, Sheets, Word and Excel reload
every 5 minutes. Google needs Share, Anyone with the link, or File, Share,
Publish to web. Microsoft needs File, Share, Embed on a file its administrator
lets share with Anyone links; 1drv.ms addresses and SharePoint sharing links
are refused. A file that asks viewers to sign in is refused with
document_not_shared, which names the
setting to change. The screen reaches Google or Microsoft over the internet, so
a document does not play offline.
Show a dashboard behind a sign-in
A web connection signs in to a site the way a person does, with a service account, and a web view shows one page of it. It suits dashboards in Salesforce, Looker Studio, Datadog, HubSpot and any other site that has no public link. A browser on screenRIG's edge opens the page signed in and the Player shows a picture of it, drawn again every refresh_s seconds (60 to 86,400, default 300). Every screen of the same size shares one picture, so more screens add no sign-ins, and a picture is drawn only while a screen's playlist shows the view. Grafana, Power BI and Tableau connections and views work the same way and are in the API reference.
- Make a service account at the site that can read only the dashboards your screens show. Every capture signs in as it.
- Create the connection with
kindweband the settings below. The password issecret. - Create a view of one page: its
httpsaddress asurland, aswait_for, a CSS selector of an element that appears only when the page is signed in and ready, so a sign-in page times out instead of being drawn.clipdraws only the part of the page a selector names, andwait_ms(up to 10,000) waits for late charts. - Place the view's
embed_urlin aniframeprimitive withcontent_fitfill.
{
"kind": "web",
"name": "Sales dashboard",
"config": {
"login_mode": "auto",
"login_url": "https://login.example.com/sign-in",
"username": "screens@example.com"
},
"secret": "ACCOUNT_PASSWORD",
"totp_secret": "AUTHENTICATOR_KEY"
}
{
"connection_id": "bic_01EXAMPLECONNECTION0000",
"name": "Sales this week",
"url": "https://app.example.com/dashboards/sales",
"refresh_s": 300,
"wait_for": "#sales-total"
}
From the CLI, screenrig bi connection create web takes the same settings as
flags (--login-mode, --login-url, --username, --password-file,
--totp-file, --steps and --cookies-file), and screenrig bi view create --connection-id ID --url PAGE_URL takes --refresh, --wait-for, --wait-ms
and --clip.
| Setting | Meaning |
|---|---|
login_mode | auto fills the form at login_url with username and the password. steps runs your own script. none signs in nowhere: the connection shows pages with its cookies, or none |
login_url | The https address of the site's sign-in page, on a public host. Required for auto and steps |
username | The service account's username, for auto and steps |
steps | Up to 30 steps: goto (url), fill (selector, value), click and wait_for (selector), press (value is a key such as Enter, with an optional selector to focus first) and wait_ms (ms). A value may hold {{username}}, {{password}} and {{otp}}: write the placeholder, never the password or a code |
secret | The password. Required by auto |
totp_secret | For an account that uses an authenticator app: the base32 key the site shows (16 to 128 characters, spaces allowed) or its otpauth://totp/... address, which may set SHA256 or SHA512, 6 to 8 digits and a 10 to 120 second period. screenRIG works out the code on its server and sends only the code |
cookies | A cookie jar exported from a signed-in browser, up to 100 cookies: name, value, domain (.example.com for every subdomain), path, expires (Unix seconds, 0 for a session cookie), httpOnly, secure and sameSite |
The password, the TOTP key and the cookies sit beside config, are stored sealed and are never shown again: a read says whether each is set. An empty secret or totp_secret, or cookies: [], removes it.
- Cookies come first. The connection keeps one sealed cookie jar: the one you pasted, then the cookies each capture returns. A capture sends the jar and no credential, and signs in only when there is no jar or the last capture reached a sign-in page. A site that keeps its session outside cookies signs in on every capture, so give its view a long
refresh_s. - The password goes to the sign-in page only. It is typed at
login_urland in thegotosteps, never into a view's address. Adding an address to either needs the password in the same request, so a member who cannot read the password cannot point it at a page of their own. - The account is protected. A refused sign-in (
bi_web_login_failedorbi_web_otp_required) waits 5 minutes, then 15, 60 and 120, and the fifth in a row stops the connection until you change its credentials or sign-in settings, so at most 3 attempts run in the first hour. A sign-in that ends otherwise (a timeout, a block, a page that would not open) waits 15 minutes. Use a read-only service account. - Some sites cannot be scripted. A site that approves sign-ins on a phone, checks devices or shows a CAPTCHA needs a cookie jar (
login_modenone) or a service account the site exempts.
The Player keeps the last good picture while a capture fails, and the view's status carries one of these codes:
| Code | Meaning |
|---|---|
bi_web_login_failed | The site refused the sign-in: fix the username, password, TOTP key, login_url or steps |
bi_web_otp_required | The site wanted a code the connection could not give |
bi_web_session_expired | A sign-in page showed. With auto or steps the next capture signs in; with cookies alone, paste a new jar |
bi_web_login_paused | A sign-in is waiting out the rate limit, the connection is stopped, or another capture is signing in |
bi_web_timeout | The page did not load: set wait_for or wait_ms |
bi_web_navigation_failed | The page would not open |
bi_web_blocked | The site blocked the renderer with a bot check or a CAPTCHA |
bi_upstream_unavailable | The renderer did not answer |
screenrig bi connection test ID signs in and reports the result. A connection's session says where its cookies and sign-in stand: idle, active, login_needed, paused, stopped or expired.
Page background and motion
A page canvas takes width, height, viewport_fit (contain, cover or
fill; contain by default) and background, a solid #RRGGBBAA colour or a
top-to-bottom gradient. A gradient has 2 to 8 stops, each with a color and
an at from 0 at the top edge to 1 at the bottom; at rises from stop to stop,
the first is 0 and the last is 1.
{
"width": 1920,
"height": 1080,
"viewport_fit": "contain",
"background": {
"type": "linear",
"stops": [
{ "at": 0, "color": "#0B1F3AFF" },
{ "at": 1, "color": "#1F6FEBFF" }
]
}
}
A primitive's enter animates it in once its page fills the screen: fade-up,
fade-down, fade-left, fade-right, fade-in, zoom-in or zoom-out. Its
optional stagger, 0 to 8, delays the start by 120 milliseconds a step, so
layered elements arrive in reading order. motion keeps a primitive moving
after it has entered. spin turns an image or video (direction cw or
ccw, speed slow, medium or fast). drift slowly scales and slides an
image or video and back (zoom in or out, direction left, right,
up, down or none, and speed). path moves any primitive from its rect
through 1 to 64 points, each the top-left corner of the rect at that
waypoint, at rate canvas units a second (above 0, up to 10,000) and with
loop set to loop (the default), ping-pong or once.
{
"id": "logo",
"primitive": "image",
"selector": { "by": "id", "media_id": "med_01EXAMPLELOGO0000000000" },
"rect": { "x": 0, "y": 0, "width": 320, "height": 180 },
"layer": 1,
"content_fit": "contain",
"enter": { "type": "fade-up", "stagger": 1 },
"motion": {
"type": "path",
"points": [{ "x": 1600, "y": 0 }, { "x": 1600, "y": 900 }],
"rate": 120,
"loop": "ping-pong"
}
}
Motion suits one moving element per page, and playlist validate reports
motion_overuse for a second.
Tag filters and playback batches
Media carries up to 32 unique tags, each 1–32 letters or digits. Replace the whole set with screenrig media update med_ID --tags Summer,Drinks. --tag Summer replaces it with one tag; --clear-tag clears every tag. media list --tag Summer matches membership anywhere in the set. Tags are case-sensitive and are never authorization.
A folder selector, { "by": "folder", "folder_id": "mfd_…" }, plays the ready
files directly inside one media folder and none of its subfolders; media folder list shows the ids. It takes the same order, one_at_a_time and
batch_size as all and tag, and deleting a folder moves its files up a level
and leaves the selector empty.
A dynamic selector can use one tag or a tags filter object:
{
"by": "tag",
"tags": { "all": ["Summer", "Drinks"], "any": ["Lobby", "Patio"], "none": ["Expired"] },
"order": "random",
"one_at_a_time": false,
"batch_size": 3
}
all requires every listed tag, any requires at least one, and none excludes any listed tag. Present groups combine with AND; omitted groups impose no condition. Supply at least one nonempty group. Each group accepts up to 32 unique tags. tag and tags are mutually exclusive. A none-only filter selects all ready media of that primitive except the excluded tags. Image selectors select images and video selectors select videos.
The candidate pool contains up to 1,024 ready media per selector, with 1,024 media references across the complete loop snapshot. A larger match returns an error; narrow the filters. batch_size is a separate limit of 1–1,024 items per page visit. On a media_end page, one_at_a_time: false plays the next batch in sequence; omitting batch_size plays the remaining pass. one_at_a_time: true plays one item per appearance and allows only an omitted batch size or batch_size: 1. On duration, application and audio_end pages this selector, or ids with more than one id, requires one_at_a_time: true and refuses dwell_ms. Images on media_end also require dwell_ms; videos cannot loop on that page.
The Player resolves every dynamic media primitive in one request at playlist startup and at each loop boundary. Membership is frozen during the loop. Uploads, removals, tagging changes, and availability edges do not regenerate the manifest. At the next refresh, removed or newly excluded items leave the pending queue; new matches join when the current pass finishes. A final batch may contain fewer than the requested number; it does not refill from the next pass. Filename order sorts by filename, then media ID. Random order shuffles once per complete pass, preserving the remaining order across loop refreshes. Weighted order follows its weights, below. The cursor is local to the screen, playlist, page, and primitive, persists across restart, and resets when the filter, order, or batch policy changes. Offline playback uses the last successful snapshot. Empty matches skip the primitive and any resulting empty page.
Save the selector object above as selector.json, then inspect its current candidate catalog before publishing:
screenrig media selector-preview selector.json --primitive video
Preview returns matched_count, filename-ordered candidates with media IDs and tags, and the normalized selector policy. With random order it shows the pool and shuffle policy; it does not choose the Player's shuffle, advance a cursor, create a playback grant, or change a manifest. With weighted order it returns each candidate's weight and share_percent and the cycle. --rect WxH (API rect: {width, height}) is the slot's size and is required with fit: "aspect"; the matches it leaves out are listed in excluded with reason aspect_mismatch. Image selectors pass --primitive image. The API is POST /api/selectors/preview with { "primitive": "video", "selector": ... }. It uses the authenticated project and the same matching rules as playback. Catalog changes after preview are resolved at playback's next loop boundary.
Static bundle export freezes dynamic matches as exact IDs. It preserves one-at-a-time or complete-pass playback; a bounded runtime sequence using batch_size with one_at_a_time: false requires removing that field or choosing explicit IDs before export. This prevents silently losing a runtime batch cursor in a static bundle.
Weighted rotation and aspect fit
order: "weighted" rotates one slot's creatives by weight, so each sponsor keeps its share of plays. weights maps a media ID (med_...) or tag:NAME to an integer from 1 to 1,000, with at most 64 keys. It works with by of all, tag or folder:
{
"by": "all",
"order": "weighted",
"one_at_a_time": true,
"weights": { "tag:Acme": 50, "tag:Globex": 30, "tag:Initech": 20 },
"fit": "aspect"
}
Weights of 50, 30 and 20 deliver exactly 5, 3 and 2 of every 10 plays, every cycle, and a restart resumes mid-cycle. An item's weight is its media ID key when present; otherwise the first tag:NAME key, alphabetically, among the tags it carries, split equally among the items of the selection that carry it, so a sponsor's share holds however many creatives it has; otherwise the item counts as its own group with weight 1. A cycle is at most 4,096 plays; shares are rounded to it only when the exact ratio needs a longer one.
Weighted order plays one item per visit, so set one_at_a_time: true or batch_size: 1. weights is required with weighted order and allowed only with it; otherwise the write returns invalid_request. Weighted rotation is a Plus feature: without it, a write that sets a weight an item does not already hold answers feature_not_in_plan, while equal rotation, keeping stored weights and clearing them stay open. Every Player plays weighted order. A Player that does not declare the selector.weighted host capability is sent random, and the manifest diagnostics carry selector_order_downgraded.
fit: "aspect" on a dynamic selector keeps only files whose width over height is within 5% of the slot's rectangle, a video wall or display frame included, read when the selector resolves. A portrait slot never plays a landscape file. No Player change is involved.
screenrig media selector-preview prints the expected share of every weighted or aspect-fitted selector, and the dashboard page editor shows the same table in the inspector. Static bundle export freezes a weighted selector as exact IDs in filename order; weights are not kept.
Screen tokens in tag selectors
A tag selector's tag, and each entry of its tags filter, may be {screen.field.NAME} or {screen.id}, the screen's identifier without its scr_ prefix, which is a tag. The server fills the token for each screen when it builds that screen's manifest and selector snapshot, so one playlist plays each screen's own media. Tag the media Lobby or Garage, set each screen's field with screenrig screen update scr_ID --field zone=Lobby, and give the slot this selector:
{ "by": "tag", "tag": "{screen.field.zone}", "one_at_a_time": true }
The filled value follows the tag rules: 1 to 32 letters or digits. A screen without the field, or whose value is not a tag, selects nothing: it plays no file from that slot, and the manifest diagnostics carry screen_fact_missing or screen_fact_invalid. Changing a field re-mints that screen's manifest. A selector with a token cannot be previewed (media selector-preview takes a concrete tag) or frozen by playlist export.
Screen tokens in iframe addresses and application params
An iframe's src and fallback_src may carry screen tokens in the path, query or fragment of an http or https address, and so may the optional params of an application primitive: up to 16 names of 1 to 32 lower case letters, digits or underscores (ticket and policy are reserved) with values of up to 512 characters. The server fills them for each screen:
| Token | Value |
|---|---|
{screen.id} | The screen's identifier without its scr_ prefix. |
{screen.name} | The screen's name. |
{screen.timezone} | The screen's effective IANA timezone: its override, else the zone its Player reports, else UTC. |
{screen.field.NAME} | The screen's field NAME, 1 to 32 lower case letters, digits or underscores. |
{screen.location.lat}, {screen.location.lon} | Its location in decimal degrees. |
{screen.location.name}, {screen.location.address} | Its place name and street address. |
{
"primitive": "iframe",
"src": "https://maps.example.com/directory?kiosk={screen.field.kiosk_id}&level={screen.field.level}",
"title": "Directory"
}
The write stores the template as written, braces included. Each screen's manifest carries its own address, every value percent-encoded for its place in the URL: a kiosk_id of B 2&3 becomes B%202%263. A token in the scheme, credentials, host or port, or in a YouTube link, a Google or Microsoft document link or a BI view address, is invalid_request at src (or fallback_src). Publishing skips the framing check for a templated src, and previews show the template as written.
A screen that lacks a value (an unset field, no location), or whose values fill into an address over 2048 characters or one with a path segment of . or .., gets no such iframe or application, and its manifest diagnostics carry screen_fact_missing or screen_fact_invalid; a page left empty is dropped. Every write that reaches such a screen (a playlist write, screen assign, screen update, a fleet assign, an approved review) answers with a screen_fact_missing warning that names the tokens, the first 20 screen ids and how many there are. Changing a field or location re-mints the manifest of the screens it affects.
For an application, the filled params, at most 4096 characters together once percent-encoded, reach it in context.params on every Player (SDK). The Player web app and the Players that run it (Samsung Tizen, BrightSign, LG webOS and Vega) also append each one to the launch address after ticket, percent-encoded, so the application can read location.search. A template's url field may be a whole iframe src, and its value may itself carry screen tokens, filled when the manifest is built. A tag selector uses {screen.id} and {screen.field.NAME} the same way (above). Cards keep their own {screen.…} tokens.
Application primitives in one playlist that pin the same release carry the same params.
Media availability
screenrig media availability med_ID --file rule.json sets when the dynamic selectors (all, tag and folder) may pick a file. --clear removes the rule and --expect-rev N guards the media revision. The API is PATCH /api/media/{id}/availability with If-Match and { "availability": {...} | null }. Setting a rule needs Manage access; a Propose credential gets insufficient_access.
The rule is the schedule's clock grammar, read in each screen's time zone, and holds at least one member: from and until (civil YYYY-MM-DDTHH:MM, until exclusive), windows (weekly {days, start, end}), monthly ({day} or {nth, weekday}, each with optional start and end), dates ({date, start, end}) and except (dates that remove an occurrence, overnight tails included). It has no data or interaction. A sponsor's creative for the long weekend, available only on weekday evenings inside the span:
{
"from": "2026-11-27T00:00",
"until": "2026-11-30T23:59",
"windows": [{ "days": ["mon", "tue", "wed", "thu", "fri"], "start": "17:00", "end": "22:00" }]
}
Only selectors read the rule: an explicit id or ids selector ignores it, as do cards' media references, soundtrack audio and ad creatives. A file leaves the selection and returns at each screen's next playlist loop, within about a minute of the edge. No playlist or manifest revision changes, and an offline Player keeps its last selection until it reconnects. screenrig media selector-preview --timezone ZONE (default UTC) lists the files outside their rule now in excluded with reason outside_window.
Return to the screenRIG CLI reference.