A screen group is several screens that show one picture across them, such as a video wall, and is itself listed and changed as one screen. Make a group from screens that are already paired, then place it so that each screen knows its position; for a wall too big to play one video, give each position its own file. See Screen groups and video walls for the guide.
Needs an owner’s key or session, not limited to some screens. Makes a screen group: one screen made of rows x cols screens that show one picture across them. members is the screens’ ids, in the order they are first numbered; there must be exactly rows x cols, all named, in no group, at one site, with one pixel size and no bookings of their own, on a player that can crop. bezelMm (the gap between pictures) and diagIn (the screens’ size) are optional and only yours to give; with neither, there is no gap. timezone is needed only when the screens are in different zones. The group starts placing: each screen shows its number. The answer is the group as a screen, with its members and layout.
The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.
403
wrong_keyscreens_limited
wrong_key: the key lacks the Screens permission this call needs; or screens_limited: the key is limited to some screens and this call acts on all of them. A session below an owner’s gets “Your role (<role>) can’t <action>.”
404
unknown_screennot_connected
unknown_screen (no such group, or one this key can’t see), or not_connected.
Needs an editor’s or an owner’s key or session. Makes every screen of the group show its number, so you can tell which is which. The numbers end by themselves after 30 minutes. version is the group’s version from its layout.
The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.
403
wrong_keyscreens_limited
wrong_key: the key lacks the Screens permission this call needs; or screens_limited: the key is limited to some screens and this call acts on all of them. A session below an editor’s gets “Your role (<role>) can’t <action>.”
404
unknown_screennot_connected
unknown_screen (no such group, or one this key can’t see), or not_connected.
Needs an editor’s or an owner’s key or session. positions gives each screen’s place, 1 to the number of screens, row by row from the top left; every screen of the group exactly once. This ends the numbers and fixes the screens’ size.
The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.
403
wrong_keyscreens_limited
wrong_key: the key lacks the Screens permission this call needs; or screens_limited: the key is limited to some screens and this call acts on all of them. A session below an editor’s gets “Your role (<role>) can’t <action>.”
404
unknown_screennot_connected
unknown_screen (no such group, or one this key can’t see), or not_connected.
group_changed (the version is old: reload and retry), not_placing, bad_positions (400: not one place for each screen), not_group (400: the screen isn’t a group), api_off or integration_off.
The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.
403
wrong_keyscreens_limited
wrong_key: the key lacks the Screens permission this call needs; or screens_limited: the key is limited to some screens and this call acts on all of them. A session below an editor’s gets “Your role (<role>) can’t <action>.”
404
unknown_screennot_connected
unknown_screen (no such group, or one this key can’t see), or not_connected.
Needs an owner’s key or session, not limited to some screens. For a group whose screens a canvas video is too big for to play whole: names one of your library MP4s for each position (files maps each position, 1 to the number of screens, to the file’s sha-256) and saves them as one set, a library item of its own, named after the first file and the group. Publish the set to the group like any file of the run it was saved in. Each file must be exactly its position’s size, all must have the same frame rate and the same number of frames, and each must play on its screen; codec and bitrate may differ. version is the group’s version from its layout; source is upload. With check true nothing is saved: the answer says whether the files pass, and may name only the files picked so far (it then says ok false, with the frame rate and length the others need). A failed check is 422 screen_files_checks, with a problems list that names each position and what is wrong. No sizes are counted.
With sourcesplit Mestra re-encodes one of your library MP4s (upload, its sha-256) into one H.264 file for each screen, but only when you ask in as many words: reencode must be the JSON value true (missing, false or text is 400). Your video stays exactly as it is. It is offered only when the video is too big or too fast for the screens to play whole and each screen’s part would fit it as H.264, and only on a plan that includes it; otherwise 422 split_wont_help, with the screen and the reason in the message. The split runs on Mestra’s render queue: the answer is 202 with the queue row’s render, and the set is saved to your library when it finishes, tagged “re-encoded by Mestra” in its name, with one mestra.screen_files_split event in the activity log. No sizes are counted.
Path parameters
idstring (uuid)Required
Body parameters
sourcestringRequired
Possible valuesuploadsplit
versionintegerRequired
filesobjectOptional
Position (as text) to the library file’s sha-256. For source upload.
checkbooleanOptional
uploadstringOptional
The library MP4’s sha-256. For source split.
reencodebooleanOptional
Must be true for source split: you are asking Mestra to re-encode this video.
Returns
Saved (or, with check, passed). set is the set’s sha-256.
An object with:
okbooleanOptional
With check: true when every position passes.
setstringOptional
fileIdstringOptional
namestringOptional
positionsintegerOptional
fpsMilliintegerOptional
The files’ frame rate, in frames per 1000 seconds.
frameCountintegerOptional
Errors
Status
Code
Meaning
400
files doesn’t name each position once (a check may name fewer), or source isn’t upload.
401
invalid_token
The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.
403
wrong_keyscreens_limited
wrong_key: the key lacks the Screens permission this call needs; or screens_limited: the key is limited to some screens and this call acts on all of them. A session below an owner’s gets “Your role (<role>) can’t <action>.”
404
unknown_screennot_connected
unknown_screen (no such group, or one this key can’t see), or not_connected.
screen_files_checks: at least one position failed. problems lists each with its position, a code (wrong_size, other_fps, other_length, no_frames, no_file, not_video, no_screen, group_max_fps (the video’s rate is above what groups play, or couldn’t be read), decode_load (a screen in the group can’t decode its file: it needs more pictures a second than that screen has measured), or the reason its screen can’t play it) and a message.
429
Other files are being read for this organisation. Try again shortly.
Needs an owner’s key or session, not limited to some screens. Your library’s MP4 files, newest first, one for each distinct file: what files of Create the screen files of a group may name. Each has its sha (sha-256), its name, the run it is in and its size in bytes.
Returns
The videos.
An object with:
filesarray of objectsOptional
Show child attributesHide child attributes
shastringOptional
namestringOptional
runIdstringOptional
sizeintegerOptional
Errors
Status
Code
Meaning
401
invalid_token
The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.
403
wrong_keyscreens_limited
wrong_key: the key lacks the Screens permission this call needs; or screens_limited: the key is limited to some screens and this call acts on all of them. A session below an owner’s gets “Your role (<role>) can’t <action>.”
409
api_offintegration_off
api_off (an owner hasn’t turned the API on), or integration_off (Mestra screens are off).