screenRIG
Sign inGet started

Documentation

Fleet links CLI commands

Create fleet links for device managers and move another signage platform's media, playlists, schedules and screens into screenRIG.

Every command here runs as described in the CLI reference: global flags, JSON output, exit codes, revisions and retries.

Migrate

migrate moves your previous signage platform's media, playlists, layouts, schedules and screens into the project. It runs in the CLI on your machine: the platform's key is read from a --credentials FILE of NAME=VALUE lines, goes only to that platform, and is never stored, printed, logged or sent to screenRIG, which sees ordinary media, playlist, fleet link, campaign and screen writes. migrate vendors lists the platforms it reads, and the files fallback reads a folder or .zip of media from any other platform.

Run the steps in order: migrate vendors (what a platform takes), migrate scan (read the account and report what can and cannot come over; it needs no screenRIG sign-in), migrate apply --dry-run (the plan), migrate apply (needs Manage access), then migrate pair for each display.

--dir DIR is the migration directory, ./screenrig-migration-VENDOR by default, created with mode 0700. It holds scan.json (the scan and its report), map.json (which object each old item became, bound to this API URL, project, vendor and source account) and staging/ (downloads in progress). apply and pair use the one screenrig-migration-* directory in the working directory, or take --dir; one of them runs in a directory at a time.

Problem codeExitMeaning
migration_dir_mismatch2The directory was made for another project, API URL, vendor or source account. Use another --dir.
vendor_refused3The platform refused the key. Make a read-only key (migrate vendors VENDOR shows how), fix the --credentials file and run the same command again.
vendor_not_found4The platform answered 404. --url is usually wrong.
vendor_rate_limited7The platform is rate limiting the key. Run the command again later.
vendor_file_gone8A media file address expired or is protected. migrate scan again refreshes it, and --files supplies a file that still fails.
vendor_file_stalled8A media download went silent. Run apply again.
vendor_bad_response9The platform sent an answer the CLI cannot use.
vendor_unavailable9 or 10The platform could not be reached or kept failing.

migrate vendors#

List the platforms migrate reads, what each takes and how to make its read-only key.

migrate vendors [VENDOR]
ParameterTypeRequiredDefaultNotes
VENDORstringnoevery platformOne platform's id. An id it does not list is usage_error (exit 2) naming the ids that exist.
screenrig migrate vendors
screenrig migrate vendors files

It works offline and needs no sign-in. data.vendors holds, for each platform, its id and name; inputs, with the flags it takes (each with flag and required, and values for a region) and the credentials lines its key file holds (name, secret, required and help); connect, the steps that make a read-only key; maps, what comes over; skips, what does not; docs; and example, a working migrate scan command. Platforms are sorted by id with files last. files takes a folder or .zip and an optional time zone, and needs no key.

migrate scan#

Read a signage account and report what can and cannot come over. It writes scan.json and sends nothing to screenRIG.

migrate scan --from VENDOR [--url ADDRESS] [--region REGION] [--timezone ZONE] [--files PATH]
    [--credentials FILE] [--dir DIR]
ParameterTypeRequiredDefaultNotes
--from VENDORstringyesnoneThe platform to read: an id from migrate vendors, or files.
--url ADDRESSstringper platformnoneThe address of a self-hosted platform.
--region REGIONstringper platformnoneThe region of a hosted account, for a platform that has regions.
--timezone ZONEstringnononeAn IANA time zone name such as America/Toronto, set on each screen whose old platform names none. Without it a screen follows the zone its Player reports.
--files PATHpathper platformnoneA folder or .zip. With --from files it holds the media; with another platform it holds the originals that platform's API cannot hand out, matched to its media by file name.
--credentials FILEpathper platformnoneThe key file: NAME=VALUE lines with the names migrate vendors VENDOR lists. Blank lines and # comments are skipped, and a value may sit in one pair of quotes. A required name missing from the file is usage_error (exit 2) naming it.
--dir DIRpathno./screenrig-migration-VENDORThe migration directory.
screenrig migrate scan --from files --files ./signage-media
screenrig migrate scan --from files --files ./signage-media.zip --dir ./old-signage --timezone America/Toronto

A flag the platform does not take, or one it needs and lacks, is usage_error (exit 2) naming what the platform takes. No flag takes the key itself. A new scan replaces scan.json and keeps map.json, and it exits 0 when it completes, even when some items cannot come over.

data is the report: vendor, label, scanned_at, found and importable (counts of media, playlists, layouts, schedules, groups and screens), not_imported (each with kind, source_id, name, a reason and usually a next step), lossy (each with kind, source_id, name and the change that happens on the way), notes, dir and scan_file. A file the platform hands out downloads at apply. A file it does not, or hands out only as a re-encoded copy, is matched by name in --files; with no match, or several, it is in not_imported or lossy with the step that fixes it.

--from files needs no key. It reads each image, video and audio file by its contents, not its extension. An optional playlists.csv at the root has the columns playlist, file (a path or a unique file name), duration (seconds) and order; without it each folder that holds media becomes a playlist in natural file-name order, and the files at the root form one named after the folder or zip. An optional screens.csv has name, group (several separated by ;), playlist and timezone, and each row becomes a waiting screen with its groups as tags. Other files and encrypted zip entries are in not_imported. A files scan has no schedules: create them with campaign create once the playlists exist.

migrate apply#

Import what the scan found: media, playlists and layouts, waiting screens and campaigns. It is safe to rerun.

migrate apply [--dir DIR] [--dry-run] [--only KINDS] [--folder ID] [--canvas WIDTHxHEIGHT]
    [--credentials FILE] [--concurrency N] [--no-transcode]
ParameterTypeRequiredDefaultNotes
--dir DIRpathnothe one ./screenrig-migration-* directoryThe migration directory that holds scan.json.
--dry-runbooleannooffRead the project and print the plan. It writes nothing and needs no key.
--only KINDSstringnoall fourComma-separated, each at most once: media, playlists, screens, schedules.
--folder IDstringnoa new folder named Imported from and the platform's nameAn existing media folder (mfd_…) for the imported media.
--canvas WIDTHxHEIGHTstringno1920x1080The canvas of plain playlists, each side at least 16 pixels. A layout keeps its own size.
--credentials FILEpathnononeThe key file, read only when a media file is downloaded from the platform.
--concurrency Nintegerno4Media imported at once, 1 to 8.
--no-transcodebooleannooffUpload the source bytes unchanged, as media upload does.
screenrig migrate apply --dry-run
screenrig migrate apply --dir ./screenrig-migration-files
screenrig migrate apply --only media,playlists --concurrency 2

apply imports in order: media into one folder, playlists and layouts, one waiting screen per old screen, and a campaign per schedule that campaigns can express. It reads the platform again only to download media files. A playlist has one page per item: images and videos fill the canvas, a web address becomes an iframe page, audio becomes the soundtrack and a nested playlist is inlined. A layout becomes a playlist on its own canvas with one page per item of its main zone. A schedule that repeats by the month, year, hour or minute, or on a numbered weekday of the month, cannot become a campaign: scan lists it in not_imported.

--dry-run reads only the project and answers data.plan (for media, playlists, layouts, screens and schedules: create, reuse, recreate, waiting and fail counts), data.items, data.bytes to download, data.placeholders counts and data.project, the fleet links and campaigns in use against their maximums of 50 and 100. Progress goes to stderr as JSON lines (migrate_progress with phase, done and total), or as text with --human. A rerun reuses what still exists, makes again anything you deleted and never changes what it made. A real run answers data.applied (the same counts), data.waiting (items that wait on media or a playlist that is not imported, each with a reason), data.failed, data.placeholders (one entry per old screen with its source_id, name and state: linked, unlinked, paired, finished or waiting), data.tags and data.folder_id.

A group becomes a tag made of letters and digits, numbered when it collides with a tag another screen carries. A campaign targets the tags of the groups and screens its schedule names, with its dates, days, hours and priority. A campaign reads its dates and hours in each screen's own timezone and needs a default playlist (no_default_playlist): scan notes the screens that lack one, and screen assign sets it after pairing.

A waiting screen is a fleet link of one screen that carries the old name, the groups as tags and the playlist. An organization holds at most 50 fleet links across its projects; the rest are unlinked in data.placeholders and wait for a Player code (migrate pair). A Player that opens a link becomes a screen, and running apply again gives it the old name and time zone and deletes the link. apply never prints a fleet link URL: fleet-links show does.

A failing item keeps ok true with data.failed (each with key, name, code, status and detail) and the warning migration_items_failed; the items that depend on it wait, and the exit code follows the status of the last failure. A media file that fails alone (an expired address, an answer that is not a file, a download that goes silent) fails that media only; for an expired address run migrate scan again. A refusal that would repeat for every item (quota_exceeded, campaign_limit_reached, insufficient_access, pending_review, the platform refusing the key, a lost connection) ends the run with data.stopped (code, detail and next) and that problem's exit code. Fix the cause and run the same command again: it continues where it stopped.

migrate pair#

Pair a Player code to one waiting screen, under its old name, playlist, time zone and tags.

migrate pair <CODE...> --screen ID_OR_NAME [--dir DIR]
ParameterTypeRequiredDefaultNotes
<CODE...>stringyesnoneThe code the Player shows, such as ABC 234: six characters from 23456789ABCDEFGHJKMNPQRSTUVWXYZ, in either case. Spaces and dashes between them are ignored, so it needs no quotes.
--screen ID_OR_NAMEstringyesnoneThe waiting screen: its source id or its exact old name. A name that two screens share lists their ids.
--dir DIRpathnothe one ./screenrig-migration-* directoryThe migration directory.
screenrig migrate pair ABC 234 --screen "Front desk"
screenrig migrate pair ABC234 --screen 3 --dir ./old-signage

Run migrate apply first: pairing needs the map and the playlist it made. pair claims the code for the screen under its old name, sets its playlist, time zone and migrated_from field, sets its tags, deletes the waiting screen's link and records the result. data holds source_id, name, screen_id, steps (paired, updated, tagged, link deleted, recorded), next and, when this run claimed the code, public_url. Each step is recorded as it lands, so a rerun finishes what an interrupted pair left. A screen that is already paired is resource_conflict (exit 5) naming it. The Player finishes pairing the next time it contacts the service; screen show then reports state active.

Other command groups