Playlists CLI commands

Playlists

A playlist is a JSON document of pages. playlist init prepares a full-screen document from ordered inputs. playlist create and playlist update read that document from a file; playlist patch, playlist rename and playlist page add|replace|remove change part of it. The shape is summarised under the commands.

playlist init <inputs...> --name NAME --output FILE [--overwrite] [--screen-id ID]
              [--target-width PX --target-height PX] [--duration-ms MS] [--fit contain|cover|fill] [--sound]
              [--no-transcode] [--no-progress] [--poll-ms MS]

screenrig playlist init med_01EXAMPLEIMAGE0000000000 med_01EXAMPLEVIDEO0000000000 --name "Lobby loop" --screen-id scr_01EXAMPLESCREEN00000000 --output lobby.json

playlist validate <file>

screenrig playlist validate ./lobby-loop.json

playlist create [file] [--from-template ID --name NAME [--set NAME=VALUE...] [--dry-run]] [--starter KEY [--name NAME]] [--format-region REGION --format-orientation ORIENTATION] [--note TEXT]

screenrig playlist create ./lobby-loop.json

screenrig playlist create --from-template pl_01EXAMPLETEMPLATE00000 --name "Monday notice" --set headline="Open late"

playlist update <id> <file> [--format-region REGION --format-orientation ORIENTATION] [--expect-rev REVISION] [--note TEXT]

screenrig playlist update pl_01EXAMPLEPLAYLIST000000 ./lobby-loop.json

playlist patch <id> [file] [--name NAME] [--clear-audio] [--expect-rev REVISION] [--note TEXT]

screenrig playlist patch pl_01EXAMPLEPLAYLIST000000 --name "Lobby loop" --expect-rev 7
screenrig playlist patch pl_01EXAMPLEPLAYLIST000000 changes.json --expect-rev 7

playlist rename <id> --name NAME [--expect-rev REVISION] [--note TEXT]

screenrig playlist rename pl_01EXAMPLEPLAYLIST000000 --name "Lobby loop" --expect-rev 7

playlist page add <playlist-id> (--file PAGE.json | --media MED_ID) [--seconds N] [--fit contain|cover] [--sound]
                  [--from WHEN] [--until WHEN] [--before PAGE_ID] [--page-id ID]
                  [--expect-rev REVISION] [--note TEXT]

screenrig playlist page add pl_01EXAMPLEPLAYLIST000000 --media med_01EXAMPLEIMAGE0000000000 --from 2026-12-01 --until 2026-12-24
screenrig playlist page add pl_01EXAMPLEPLAYLIST000000 --media med_01EXAMPLEVIDEO0000000000 --before up-ab12cd34 --note "Winter menu"
screenrig playlist page add pl_01EXAMPLEPLAYLIST000000 --file page.json --page-id welcome

playlist page replace <playlist-id> <page-id> [--file PAGE.json | --media MED_ID] [--seconds N] [--fit contain|cover]
                      [--sound] [--from WHEN] [--until WHEN | --always] [--expect-rev REVISION] [--note TEXT]

screenrig playlist page replace pl_01EXAMPLEPLAYLIST000000 up-ab12cd34 --media med_01EXAMPLEIMAGE0000000000
screenrig playlist page replace pl_01EXAMPLEPLAYLIST000000 up-ab12cd34 --until 2026-12-31
screenrig playlist page replace pl_01EXAMPLEPLAYLIST000000 up-ab12cd34 --always

playlist page remove <playlist-id> <page-id> [--expect-rev REVISION] [--note TEXT]

screenrig playlist page remove pl_01EXAMPLEPLAYLIST000000 up-ab12cd34

playlist show <id> [--output FILE [--overwrite]] [--editable]

screenrig playlist show pl_01EXAMPLEPLAYLIST000000
screenrig playlist show pl_01EXAMPLEPLAYLIST000000 --output playlist.json
screenrig playlist show pl_01EXAMPLEPLAYLIST000000 --editable

playlist list [--templates] [--library]

screenrig playlist list --templates
screenrig playlist list --library

playlist fields <id> [--set NAME=VALUE...] [--clear NAME...] [--refresh] [--expect-rev REVISION] [--note TEXT]

screenrig playlist fields pl_01EXAMPLECOPY00000000 --set headline="Closed today"

playlist instances <id>

screenrig playlist instances pl_01EXAMPLETEMPLATE00000

playlist revisions <id> [--after CURSOR]

screenrig playlist revisions pl_01EXAMPLEPLAYLIST000000

playlist revision show <id> --revision N

screenrig playlist revision show pl_01EXAMPLEPLAYLIST000000 --revision 3

playlist promote <id> --revision N --expect-rev CURRENT

screenrig playlist promote pl_01EXAMPLEPLAYLIST000000 --revision 3 --expect-rev 9

playlist delete <id> [--expect-rev REVISION]

screenrig playlist delete pl_01EXAMPLEPLAYLIST000000

playlist export <id> --output DIRECTORY [--skip-applications]

screenrig playlist export pl_01EXAMPLEPLAYLIST000000 --output ./lobby-bundle

playlist import <directory> [--name NAME] [--update ID [--expect-rev REVISION]] [--poll-ms MS] [--note TEXT]

screenrig playlist import ./lobby-bundle
screenrig playlist import ./lobby-bundle --name "Lobby loop (copy)"
screenrig playlist import ./lobby-bundle --update pl_01EXAMPLEPLAYLIST000000

playlist replace-release <id> --page PAGE_ID --primitive PRIMITIVE_ID --release-id REL_ID
                         [--apply [--expect-rev REVISION] [--expect-impact TOKEN] [--note TEXT]]

screenrig playlist replace-release pl_01EXAMPLEPLAYLIST000000 --page board-page --primitive board --release-id rel_NEW
screenrig playlist replace-release pl_01EXAMPLEPLAYLIST000000 --page board-page --primitive board --release-id rel_NEW --apply

The playlist document

A playlist is name (1 to 120 characters) plus pages (1 to 100), with an optional audio soundtrack and an optional format. Each page carries id, canvas, transition, advance, optional visibility, optional audio_cue, and primitives (1 to 24). Page, primitive and track ids are a letter followed by up to 63 letters, digits, _ or -; page ids are unique in the playlist and primitive ids on their page. A canvas takes width and height from 1 to 1,000,000, a background and an optional viewport_fit: see Page background and motion.

A format makes a playlist a video wall, {displays, arrangement, orientation} with columns for a grid, or a strip, {region, orientation}. A wall has 2 to 12 displays of 1920 x 1080 (1080 x 1920 in portrait), every ordinary page has the wall's canvas, and a primitive's displays names the tiles it covers in place of rect. See Video walls and Strips. An ad slot page, {id, type: "adslot", adslot_id} with optional visibility, holds no canvas or primitives; a playlist holds at most 16 of them and keeps one ordinary page with no visibility.

A template adds fields to the document, [{name, label, type, required, max_length?}] with type of text, media or url, and may mark any primitive locked: true. A page reads a field as {field.NAME} in a card's params (text and url fields), as an image or video selector.media_id (a media field) or as the whole src of an iframe (a url field). Every token must name a declared field of the right type, every field must be read, and a locked primitive reads none; playlist validate checks this offline. Only the owner or a member who can approve changes a locked primitive (primitive_locked). A template declares at most 16 fields: name is 1 to 32 lower case letters, digits or underscores, label up to 60 characters, and a text field's max_length (default 200) up to 2000. An optional media or url field left without a value leaves out the primitive that reads it. Declaring fields and locking a primitive are playlist templates, a Premium feature. A video wall format of 2 or 3 displays needs Plus and one of 4 to 12 displays Enterprise. A plan without the feature answers feature_not_in_plan with required_plan, while a write that keeps what the playlist already holds stays open. Making a copy from a template is in every plan.

The six primitives are image, uploaded video, live stream, web iframe and application, and card. Copy and chrome are not wire types: place a card for live text, or upload a finished still your agent made and place it as an image.

A stream takes one or two ordered sources with unique protocols and a ready image from the same project as fallback_media_id. Use at most one stream per page and duration-based advance. HLS uses a public HTTPS URL; Android and Qt Players connect directly to RTSP camera feeds, login included. See camera transport details for the URL forms each Player opens; optional direct UDP/MPEG-TS multicast on Android and Qt uses an IPv4 group in 239/8 and a port. A source can give only its url and let the scheme name the protocol. Other Players select the HLS alternative or display the fallback. Stream bytes are not cached for replay. Audio defaults to muted; muted set to false plays it, with the rules for a video's sound below. Playlist bundle import and export do not support streams.

{
  "id": "live",
  "primitive": "stream",
  "sources": [
    {
      "protocol": "udp-mpegts",
      "group": "239.10.0.1",
      "port": 5000
    },
    {
      "protocol": "hls",
      "url": "https://example.com/live.m3u8"
    }
  ],
  "fallback_media_id": "med_fallback",
  "muted": true,
  "rect": {
    "x": 0,
    "y": 0,
    "width": 1920,
    "height": 1080
  },
  "layer": 0,
  "content_fit": "contain"
}

Use this primitive on a page with advance: {"mode":"duration","after_ms":30000}. Replace the example feed and fallback ID. Player requirements and transport setup.

Every primitive is flat: id, primitive, that primitive's own fields, then rect, layer, content_fit, and optional enter and motion. There is no nested content object. rect is x, y, width and height in canvas units and layer a whole number from 0 to 1024. A rect may extend past the canvas for bleed: Players fit content to the whole rect and then clip to the canvas, so use content_fit cover or fill to fill the visible canvas. A card is placed by layout and needs a rect only for free; on a wall playlist displays replaces rect.

Image and video primitives require a selector. selector.by is id with one ready media_id and one_at_a_time false, ids with 1 to 1,024 unique ready media_ids, all for every ready object of that primitive, tag matching ^[A-Za-z0-9]{1,32}$, or folder with the folder_id of an existing mfd_ media folder, which plays the ready files directly inside it and none of its subfolders. Do not put media_id on the primitive itself or send server-resolved items. An application primitive pins one release_id and an iframe primitive takes a src and a title of 1 to 200 characters, so neither of those takes a selector. src is any http or https page the screen can reach, a LAN page or a page behind a login included; a YouTube link is stored as its autoplaying embed. src, and an iframe's optional fallback_src, may carry screen tokens such as {screen.field.kiosk_id}, and an application primitive may carry params with the same tokens, so one playlist gives every screen its own page. Android, Amazon Signage Stick, Linux, Raspberry Pi and Windows Players open the page itself. The Player web app and the macOS, Samsung Tizen, LG webOS and BrightSign Players frame it, so a page that sends X-Frame-Options (DENY, SAMEORIGIN or the obsolete ALLOW-FROM), or a Content-Security-Policy frame-ancestors list without the Player's origin, shows a blocked frame on them, and the Player web app shows only https pages without a login in the address. When publishing detects a public HTTPS page that refuses framing, the write still succeeds and the CLI prints the server's warnings entry: code iframe_framing_refused, the page_id, primitive_id and src, the header that refused, and the next step (use a page that allows framing from the Player origin, or ask its owner to allow that origin). The server also appends a playlist.iframe_framing_refused warning to the event log, one per refusing page, which events list prints with primitive_id. A LAN page, an http page and a page the server cannot reach within a few seconds are not checked. A Player reports a playlist as playing once its manifest is on glass, so a verified publish does not prove that an iframe page rendered: act on the warning, or look at the screen. Both web primitives require content_fit of fill, because neither has an intrinsic size.

An iframe also takes reload_s (0, the default, never reloads; 60 to 86400 loads src again every reload_s seconds while the page is on glass), fallback_src (the page shown when src does not load, with the forms and rules of src; a recovered src replaces it at the next reload) and navigation_allowlist (1 to 64 host-sources of the form [scheme://]host[:port][path], such as example.com, *.example.com or https://example.com/docs/; with a list, the page's links, scripted navigations and redirects reach only src, fallback_src and matching addresses; omit it for no restriction, an empty list is refused). A pasted <iframe> embed code is read for its src. A Google Slides, Docs or Sheets share, Publish to web or embed link, or a Microsoft 365 Embed link, is stored rebuilt for the screen: Slides and PowerPoint decks loop, a Slides deck advances on the link's own delay held to the page duration (give the page the time of the whole deck), and Docs, Sheets, Word and Excel reload every 5 minutes. A file that asks viewers to sign in is refused with document_not_shared, whose detail names the sharing setting to change. See Show a web page, a video or a document.

advance.mode is duration with after_ms, which on a page holding exactly one YouTube video (not a playlist or live stream) may also carry until set to video_end so the page lasts until the video ends and after_ms is how long it shows when the screen cannot read the video's length, media_end on a page with exactly one image or video primitive, audio_end on a page whose audio_cue names a soundtrack track, or application with max_ms when the app ends its own turn by calling window.screenrig.nextPage(). An application page needs exactly one primitive marked controller; every other mode forbids it. after_ms, max_ms and dwell_ms are whole milliseconds from 1,000 to 86,400,000, and an image on a media_end page needs dwell_ms. A page holds at most one stream and at most two application or iframe primitives, and media_end forbids both of those.

transition.type is one of crossfade, swipe-left, swipe-right, swipe-up, swipe-down, dip, wipe-left, wipe-right, wipe-up, wipe-down, slide-left, slide-right, slide-up, slide-down, or stinger. duration_ms is required, 0 through 60000. playlist init writes a 200 ms crossfade. Swipe moves both pages together like a carousel. Slide moves the incoming page over the outgoing one, which drifts a quarter as far. Wipe uncovers the incoming page behind a moving hard edge. Dip fades the outgoing page to a solid colour and then in to the incoming page; color is an optional #RRGGBB, default #000000, and is valid only on dip. Direction names are the direction of motion: wipe-left is an edge moving left. ease is optional: linear, in, out or in-out; the default is linear for crossfade and swipe-* and in-out for dip, wipe-* and slide-*; it is not allowed on stinger. The incoming page owns its transition. The first page of a playlist plays no transition.

A stinger is a themed full-frame graphic that covers the outgoing page, swaps in the incoming page while the screen is covered, then uncovers it. Use it to name a section of a playlist: put it on the first page of the section. The stinger object is required for type: "stinger" and not allowed on other types. All its members are optional. theme is one of neomustard (the default), cyanotype, propaganda, signal, avant-garde, bloom or primetime, and matches the card themes. title is up to 40 characters and subtitle up to 60, set in the theme's display type. logo is media: plus the id of a ready image in the project, for example media:med_01EXAMPLE. accent is an optional #RRGGBB that replaces the theme accent. duration_ms for a stinger is 2000 through 6000 and covers the whole bumper; typical lengths are 2700 to 4000. The title stays fully displayed for hang_ms, 0 through 6000, default 1000 (one second), and hang_ms is at most 60 percent of duration_ms; a longer hang needs a longer duration_ms. A Player that cannot draw a stinger plays a crossfade of the same length. See the live Stinger card page to watch the transition play.

The following example shows a stinger page transition:

{ "type": "stinger", "duration_ms": 3500, "stinger": { "theme": "primetime", "title": "BREAKFAST", "subtitle": "Served until 11", "logo": "media:med_01EXAMPLE", "hang_ms": 1000 } }

An optional enter object on a primitive adds one object animation: fade-up, fade-down, fade-left, fade-right, fade-in, zoom-in, or zoom-out, and an optional stagger from 0 to 8 delays its start by 120 ms a step. An optional motion keeps a primitive moving after it enters: spin and drift turn or slide an image or video, and path moves an image, video, application or iframe along waypoints. See Page background and motion.

An optional page visibility object limits when the page plays: a required enabled boolean, optional civil from and until bounds, and up to 16 recurring windows of days and civil times. from and until are YYYY-MM-DDTHH:MM in each screen's timezone, from inclusive and until exclusive and later than from; a window is days (mon to sun) with start and end as HH:MM, given together or both left out for the whole day, and an end at or before start crosses midnight. enabled: false hides the page; enabled: true needs at least one of from, until, windows or data. Every playlist keeps at least one page with no visibility field at all. A screen reads these times in its effective time zone: its override, else the zone its Player reports, else UTC.

A page visibility.data condition, {key, path?, equals?}, shows the page only while a card data document matches: key is a card data key or card ID, path an RFC 6901 pointer into the document, and equals a string, number, boolean or null (omit it to test that the value exists). The key {screen.weather} reads the weather at each screen's own location, which screen update ID --location LAT,LON sets: {"enabled":true,"data":{"key":"{screen.weather}","path":"/condition","equals":"rain"}} shows the page only while it rains where that screen is. The weather document has condition (clear, cloud, fog, rain, snow, storm or wind), band (freezing below 0 °C, cold 0 to 9, mild 10 to 17, warm 18 to 24, hot from 25), temperatureC in whole degrees and isDay. It is the current weather for the screen's 0.25 degree cell, refreshed about hourly, not a forecast. A screen without a location never shows the page, and publishing refuses a path or an equals the document cannot hold, such as cloudy for cloud. A Player that does not declare the page.conditions host capability gets such a page disabled. Data conditions are a Plus feature: without it, a write that adds a visibility.data condition a page does not already hold answers feature_not_in_plan, while keeping or removing a stored condition and time-window visibility stay open. Keep an ordinary page without visibility as the fallback.

A video or stream primitive plays silent unless it sets muted to false. Then it plays its sound at the screen's volume while its page is current, and that page pauses the playlist soundtrack, which resumes from the same point on the next page without sound. Several primitives on one page all play their sound. A page with sound cannot carry an audio_cue: a write that adds one answers invalid_request at pages[i].audio_cue, "a page with sound cannot cue the soundtrack", while a stored older page that has both keeps playing. Ads stay muted.

An optional top-level audio object adds a soundtrack that plays continuously while pages change and pauses on a page with sound. tracks lists 1 to 128 entries in playback order, each with a unique id (the page id pattern) and the media_id of a ready audio media object. loop defaults to true and restarts at the first track after the last; volume defaults to 1 and ranges from 0 to 1, multiplied by the Player volume; cued defaults to false, and true stops the soundtrack after each track so that a track plays only when a page audio_cue starts it. An ordinary page may carry audio_cue with a track id from that list and an optional restart boolean (default false): when the page appears, the Player switches to that track from its start, restarting it only when it is already playing and restart is true. Cues are hints, adslot pages cannot carry them, and a cue without a soundtrack is rejected. A page with advance {"mode":"audio_end"} ends when the track its audio_cue names ends, so it requires that cue and a soundtrack, takes no after_ms, and follows the duration rules for image and video primitives; a stream primitive still needs a duration page, and an application on the page is never its controller; max_ms is an optional hint that the server overrides. playlist update replaces the whole document, so omitting audio removes the soundtrack; playlist patch keeps it unless audio is supplied, and --clear-audio or audio: null removes it. A strip has no soundtrack. Soundtrack authoring.