Skip to content

API reference

Screen groups

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.

Create a screen group

PermissionScreens · Write

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.

Body parameters

  • namestringRequired
  • rowsintegerRequired
  • colsintegerRequired
  • bezelMmnumberOptionalNullable
  • diagInnumberOptionalNullable
  • timezonestringOptional
  • membersarray of stringsRequired

Returns

The group.

Returns the Screen object.

Errors

StatusCodeMeaning
401invalid_token

The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.

403wrong_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>.”

404unknown_screennot_connected

unknown_screen (no such group, or one this key can’t see), or not_connected.

409group_changednot_placingnot_groupapi_offintegration_off

group_changed (the version is old: reload and retry), not_placing, not_group (400: the screen isn’t a group), api_off or integration_off.

501

The player is not available on this server.

Start the numbers on a group's screens

PermissionScreens · Write

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.

Path parameters

  • idstring (uuid)Required

Body parameters

  • versionintegerRequired

Returns

The group.

Returns the Screen object.

Errors

StatusCodeMeaning
401invalid_token

The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.

403wrong_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>.”

404unknown_screennot_connected

unknown_screen (no such group, or one this key can’t see), or not_connected.

409group_changednot_placingnot_groupapi_offintegration_off

group_changed (the version is old: reload and retry), not_placing, not_group (400: the screen isn’t a group), api_off or integration_off.

501

The player is not available on this server.

Update where a group's screens are

PermissionScreens · Write

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.

Path parameters

  • idstring (uuid)Required

Body parameters

  • versionintegerRequired
  • positionsobjectRequired

Returns

The group.

Returns the Screen object.

Errors

StatusCodeMeaning
401invalid_token

The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.

403wrong_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>.”

404unknown_screennot_connected

unknown_screen (no such group, or one this key can’t see), or not_connected.

409group_changednot_placingbad_positionsnot_groupapi_offintegration_off

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.

501

The player is not available on this server.

Cancel the numbers on a group's screens

PermissionScreens · Write

Needs an editor’s or an owner’s key or session. Ends the numbers without placing: the group keeps the places it had. ?version= is optional.

Path parameters

  • idstring (uuid)Required

Query parameters

  • versionintegerOptional

Returns

The group.

Returns the Screen object.

Errors

StatusCodeMeaning
401invalid_token

The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.

403wrong_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>.”

404unknown_screennot_connected

unknown_screen (no such group, or one this key can’t see), or not_connected.

409group_changednot_placingnot_groupapi_offintegration_off

group_changed (the version is old: reload and retry), not_placing, not_group (400: the screen isn’t a group), api_off or integration_off.

501

The player is not available on this server.

Create the screen files of a group

PermissionScreens · Write

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 source split 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

StatusCodeMeaning
400

files doesn’t name each position once (a check may name fewer), or source isn’t upload.

401invalid_token

The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.

403wrong_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>.”

404unknown_screennot_connected

unknown_screen (no such group, or one this key can’t see), or not_connected.

409group_changedgroup_not_placednot_groupapi_offintegration_off

group_changed (the version is old: reload and retry), group_not_placed, not_group (400: the screen isn’t a group), api_off or integration_off.

422screen_files_checkswrong_sizeother_fpsother_lengthno_framesno_filenot_videono_screengroup_max_fpsdecode_load

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.

501

The player is not available on this server.

List all videos a group's screens can be given

PermissionScreens · Read

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

StatusCodeMeaning
401invalid_token

The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.

403wrong_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>.”

409api_offintegration_off

api_off (an owner hasn’t turned the API on), or integration_off (Mestra screens are off).

501

The player is not available on this server.