# 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](https://withmestra.com/docs/player/video-walls/) for the guide.

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](https://withmestra.com/docs/player/video-walls/) for the guide.

## Create a screen group

`POST /api/v1/player/groups`

Permission: Screens · 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`.

### Parameters

- `name` (string, required):
- `rows` (integer, required):
- `cols` (integer, required):
- `bezelMm` (number, optional, nullable):
- `diagIn` (number, optional, nullable):
- `timezone` (string, optional):
- `members` (array of strings, required):

### Returns

The group.

Returns the Screen object (/docs/api/screens/#object).

### Errors

- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`, `screens_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_screen`, `not_connected`): `unknown_screen` (no such group, or one this key can't see), or `not_connected`.
- 409 (`group_changed`, `not_placing`, `not_group`, `api_off`, `integration_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.

### Example request

```sh
curl --request POST \
  --url https://app.withmestra.com/api/v1/player/groups \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"name":"Menu board","rows":2,"cols":2,"members":["7c1e5f2a-3b4d-4e6f-8a9b-0c1d2e3f4a5b","7c1e5f2a-3b4d-4e6f-8a9b-0c1d2e3f4a5c","7c1e5f2a-3b4d-4e6f-8a9b-0c1d2e3f4a5d","7c1e5f2a-3b4d-4e6f-8a9b-0c1d2e3f4a5e"]}'
```

## Start the numbers on a group's screens

`POST /api/v1/player/devices/{id}/placing`

Permission: Screens · 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`.

### Parameters

- `id` (string (uuid), required):
- `version` (integer, required):

### Returns

The group.

Returns the Screen object (/docs/api/screens/#object).

### Errors

- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`, `screens_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_screen`, `not_connected`): `unknown_screen` (no such group, or one this key can't see), or `not_connected`.
- 409 (`group_changed`, `not_placing`, `not_group`, `api_off`, `integration_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.

### Example request

```sh
curl --request POST \
  --url https://app.withmestra.com/api/v1/player/devices/string/placing \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"version":3}'
```

## Update where a group's screens are

`PUT /api/v1/player/devices/{id}/placing`

Permission: Screens · 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.

### Parameters

- `id` (string (uuid), required):
- `version` (integer, required):
- `positions` (object, required):

### Returns

The group.

Returns the Screen object (/docs/api/screens/#object).

### Errors

- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`, `screens_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_screen`, `not_connected`): `unknown_screen` (no such group, or one this key can't see), or `not_connected`.
- 409 (`group_changed`, `not_placing`, `bad_positions`, `not_group`, `api_off`, `integration_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.

### Example request

```sh
curl --request PUT \
  --url https://app.withmestra.com/api/v1/player/devices/string/placing \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"version":3,"positions":{"7c1e5f2a-3b4d-4e6f-8a9b-0c1d2e3f4a5b":1,"7c1e5f2a-3b4d-4e6f-8a9b-0c1d2e3f4a5c":2}}'
```

## Cancel the numbers on a group's screens

`DELETE /api/v1/player/devices/{id}/placing`

Permission: Screens · 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.

### Parameters

- `id` (string (uuid), required):
- `version` (integer, optional):

### Returns

The group.

Returns the Screen object (/docs/api/screens/#object).

### Errors

- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`, `screens_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_screen`, `not_connected`): `unknown_screen` (no such group, or one this key can't see), or `not_connected`.
- 409 (`group_changed`, `not_placing`, `not_group`, `api_off`, `integration_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.

### Example request

```sh
curl --request DELETE \
  --url https://app.withmestra.com/api/v1/player/devices/string/placing \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```

## Create the screen files of a group

`POST /api/v1/player/devices/{id}/screen-files`

Permission: Screens · 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.

### Parameters

- `id` (string (uuid), required):
- `source` (string, required):  One of: `upload`, `split`.
- `version` (integer, required):
- `files` (object, optional): Position (as text) to the library file's sha-256. For source upload.
- `check` (boolean, optional):
- `upload` (string, optional): The library MP4's sha-256. For source split.
- `reencode` (boolean, optional): 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:

- `ok` (boolean, optional): With `check`: true when every position passes.
- `set` (string, optional):
- `fileId` (string, optional):
- `name` (string, optional):
- `positions` (integer, optional):
- `fpsMilli` (integer, optional): The files' frame rate, in frames per 1000 seconds.
- `frameCount` (integer, optional):

### Errors

- 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_key`, `screens_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_screen`, `not_connected`): `unknown_screen` (no such group, or one this key can't see), or `not_connected`.
- 409 (`group_changed`, `group_not_placed`, `not_group`, `api_off`, `integration_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`.
- 422 (`screen_files_checks`, `wrong_size`, `other_fps`, `other_length`, `no_frames`, `no_file`, `not_video`, `no_screen`, `group_max_fps`, `decode_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.

### Example request

```sh
curl --request POST \
  --url https://app.withmestra.com/api/v1/player/devices/string/screen-files \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"source":"upload","version":3,"files":{"1":"3b1f0a9c5e7d2b4a6c8e0f1a3b5d7c9e1f2a4b6c8d0e2f4a6b8c0d2e4f6a8b0c","2":"9c8b7a6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b"}}'
```

## List all videos a group's screens can be given

`GET /api/v1/player/screen-files/library`

Permission: Screens · 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:

- `files` (array of objects, optional):
  - `sha` (string, optional):
  - `name` (string, optional):
  - `runId` (string, optional):
  - `size` (integer, optional):

### Errors

- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`, `screens_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_off`, `integration_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.

### Example request

```sh
curl --request GET \
  --url https://app.withmestra.com/api/v1/player/screen-files/library \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```
