---
sidebar_position: 0
---

# screen

The `sos.management.screen` API groups together methods for controlling the screen of the device. It allows for manipulating the screen
resolution or orientation, set brightness, retrieve the current brightness of the display, and manipulate the power mode.

:::warning
This method only turns on/off the display/backlight. It will **not** set any power-saving mode. We also strongly recommend rebooting any
device once a day.
:::

:::info
There is a specific behavior based on the device type you operate:
**On SoC displays** (e.g., Samsung Tizen, LG webOS, Android-based SoC displays from Sony, Vestel Philips,...)
- `powerOn()` and `powerOff()` are turning the display backlight and the panel off
**On external media players** (e.g., BrightSign, Windows PC, Android players, Raspberry Pi)
- `powerOn()` and `powerOff()` are turning off the video output (typically HDMI-out); this functionality does not manage the connected display backlight and needs to be controlled via RS232 or another way.
:::

<details>
    <summary>Screen Management Capabilities</summary>
		| Capability | Description |
		|:------------|:-------------|
		| `SET_BRIGHTNESS` | If device can brightness. |
		| `GET_BRIGHTNESS` | If device can return current brightness. |
		| `SCREEN_RESIZE` | If the device can change screen resolution and orientation. |
		| `ORIENTATION_LANDSCAPE` | If device supports landscape orientation. |
		| `ORIENTATION_PORTRAIT` | If device supports portrait orientation. |
		| `ORIENTATION_LANDSCAPE_FLIPPED` | If device supports flipped landscape orientation. |
		| `ORIENTATION_PORTRAIT_FLIPPED` | If device supports flipped portrait orientation. |
		| `ORIENTATION_AUTO` | If device supports auto orientation. |

		If you want to check if the device supports those capabilities, use [`sos.management.supports()`](https://developers.signageos.io/sdk/sos_management/#supports).
</details>

## Methods

### getBrightness()

The `getBrightness()` method returns information about the currently set brightness values.

```ts expandable
getBrightness(): Promise<IBrightness>;
// show-more
interface IBrightness {
    timeFrom1: string;
    brightness1: number;
    timeFrom2: string;
    brightness2: number;
}

```

#### Return value

A promise that resolves to the current brightness settings.

#### Possible errors

If the brightness cannot be retrieved.

<Separator />

### getOrientation()

The `getOrientation()` method returns the current orientation of the screen.

```ts expandable
getOrientation(): Promise<IOrientation>;
// show-more
interface IOrientation {
    screenOrientation: Orientation;
}

type Orientation = 'LANDSCAPE' | 'PORTRAIT' | 'LANDSCAPE_FLIPPED' | 'PORTRAIT_FLIPPED' | 'AUTO';

```

#### Return value

A promise that resolves to the current screen orientation.

#### Possible errors

If the orientation cannot be retrieved.

#### Example

```ts
const orientation = (await sos.management.screen.getOrientation()).screenOrientation;
console.log(`Current screen orientation is: ${orientation}`);
```

<Separator />

### isPoweredOn()

The `isPoweredOn()` method returns whether the screen is on.

```ts expandable
isPoweredOn(): Promise<boolean>;
```

#### Return value

A promise that resolves to a boolean indicating whether the screen is powered on.

#### Possible errors

If the power state cannot be retrieved.

<Separator />

### powerOff()

The `powerOff()` method turns the screen off. It will turn off the display backlight and the panel, and it will also disable the applet.

:::warning
On Android devices, `powerOff()` also shuts down the webview and the Applet. It's the default Android behavior that cannot be changed. Once
the Applet is off, you cannot call `powerOn()` to resume the playback.

To manage the display On/Off state, use [REST API Power Actions](https://developers.signageos.io/api/#tag/DevicePower-Actions) instead.
:::

```ts expandable
powerOff(): Promise<void>;
```

#### Return value

A promise that resolves when the screen is successfully turned off.

#### Possible errors

If the screen cannot be turned off.

<Separator />

### powerOn()

The `powerOn()` method turns the screen on.

```ts expandable
powerOn(): Promise<void>;
```

#### Return value

A promise that resolves when the screen is successfully turned on.

#### Possible errors

If the screen cannot be turned on.

<Separator />

### resize()

The `resize()` method changes the resolution and orientation of the display.

:::info
For Tizen, you have to provide `baseUrl` which points to the Core App for Tizen, which will be downloaded to the device [Read more on how to upload your Core Apps here.](https://docs.signageos.io/hc/en-us/articles/4405245195666).
:::

```ts expandable
resize(baseUrl: string, orientation: string, resolution: string, currentVersion: string, videoOrientation?: string): Promise<void>;
```

#### Params

| Name               | Type     | Required         | Description                                                                                                                          |
|--------------------|----------|------------------|--------------------------------------------------------------------------------------------------------------------------------------|
| `baseUrl`          | `string` |  <div>Yes</div>  | SSSP & Tizen devices require installing an orientation-specific Core App if you want to switch orientation to portrait or landscape. |
| `orientation`      | `string` |  <div>Yes</div>  | Screen orientation                                                                                                                   |
| `resolution`       | `string` |  <div>Yes</div>  | Where it applies (mainly SSSP 2/3)                                                                                                   |
| `currentVersion`   | `string` |  <div>Yes</div>  | Core App version                                                                                                                     |
| `videoOrientation` | `string` |  <div>No</div>   | If the video has a different orientation than the HTML5 content                                                                      |

#### Return value

A promise that resolves when the screen is successfully resized.

#### Possible errors


- If `baseUrl` is not a valid URL
- If `orientation` is not a valid orientation
- If `resolution` is not a valid resolution
- If `currentVersion` is not a valid string
- If `videoOrientation` is not a valid video orientation

#### Example

```ts
// for Tizen
await sos.management.screen.resize(
    "https://cdn.your-cms.com/tizen/1.0.4",
    "PORTRAIT",
    "FULL_READY",
    "1.0.4"
);

// for all other supported devices
await sos.management.screen.resize(
    "",
    "PORTRAIT",
    "HD_READY",
    ""
);
```

:::note[GitHub Example]

- [How to resize screen on device](https://github.com/signageos/applet-examples/blob/master/examples/management-js-api/resize/)

:::

<Separator />

### setBrightness()

The `setBrightness()` method sets the brightness of the screen. It supports two different brightness values for 2 time points in the day.

```ts expandable
setBrightness(timeFrom1: string, brightness1: number, timeFrom2: string, brightness2: number): Promise<void>;
```

#### Params

| Name          | Type     | Required         | Description                        |
|---------------|----------|------------------|------------------------------------|
| `timeFrom1`   | `string` |  <div>Yes</div>  | Time in the XX:XX format           |
| `brightness1` | `number` |  <div>Yes</div>  | Brightness value between 0 and 100 |
| `timeFrom2`   | `string` |  <div>Yes</div>  | Time in the XX:XX format           |
| `brightness2` | `number` |  <div>Yes</div>  | Brightness value between 0 and 100 |

#### Return value

A promise that resolves when the brightness is successfully set.

#### Possible errors


- If `timeFrom1` is not a valid time in the XX:XX format
- If `brightness1` is not a number between 0 and 100
- If `timeFrom2` is not a valid time in the XX:XX format
- If `brightness2` is not a number between 0 and 100

#### Example

```ts
// Set brightness to 10% between 00:00 and 17:00, and to 30% between 17:00 and 23:59
await sos.management.screen.setBrightness(
    '00:00',
    '10',
    '17:00',
    '30'
);

// Set brightness to 50% all day
await sos.management.screen.setBrightness(
   00:00,
   50,
   23:59,
   50
);
```

:::note[GitHub Example]

- [ Applet Example with Brightness setup](https://github.com/signageos/applet-examples/blob/master/examples/management-js-api/brightness/)

:::

<Separator />

### takeAndUploadScreenshot(uploadBaseUrl, options)

The `takeAndUploadScreenshot()` method takes a screenshot and uploads it to a specified URL. This can be either a signageOS upload URL
(`https://upload.signageos.io`) or a dedicated server URL for uploading screenshots. The format in which the screenshot is uploaded may be
different for every platform.

To implement a custom screenshot upload server, it needs to implement these endpoints:
- POST `/upload/file?prefix=screenshot/` - Endpoint for receiving screenshot using form data, with the image set to the `file` field.
- POST `/upload/raw?prefix=screenshot/` - Endpoint for receiving screenshots as raw data.
- POST `/upload/image-data-uri?prefix=screenshot/` - Endpoint for receiving screenshots encoded as a data URL.

signageOS provides a standalone server that implements all of those methods. It is offered to all of our partners through the
[support ticketing system](https://box.signageos.io/support/).

```ts expandable
takeAndUploadScreenshot(uploadBaseUrl: string, options?: TakeAndUploadScreenshotOptions): Promise<TakeAndUploadScreenshotResult>;
// show-more
interface TakeAndUploadScreenshotResult {
    screenshotUrl: string;
    aHash?: string;
}

interface TakeAndUploadScreenshotOptions {
    computeHash?: boolean;
    headers?: Record<string, string>;
}

```

#### Params

| Name                  | Type                                  | Required         | Description                                                                                                   |
|-----------------------|---------------------------------------|------------------|---------------------------------------------------------------------------------------------------------------|
| `uploadBaseUrl`       | `string`                              |  <div>Yes</div>  | URL to which the screenshot will be uploaded. It can be either a signageOS upload URL or a custom server URL. |
| `options`             | `TakeAndUploadScreenshotOptions`      |  <div>No</div>   | Optional parameters for taking and uploading the screenshot.                                                  |
| `options.computeHash` | `boolean \| undefined`                |  <div>No</div>   | Whether to compute a hash of the screenshot and return it in the response.                                    |
| `options.headers`     | `Record<string, string> \| undefined` |  <div>No</div>   | Additional headers to include in the upload request for POST requests.                                        |

#### Return value

A promise that resolves to an object containing the screenshot URL and optionally a hash of the screenshot.

#### Possible errors


- If `uploadBaseUrl` is not a valid URL
- If `computeHash` is not a boolean
- If `headers` is not a valid object
- If the screenshot cannot be taken or uploaded.

#### Example

```ts
const { screenshotUrl, aHash } = await sos.management.screen.takeAndUploadScreenshot(
  'https://your.upload.server/upload/file?prefix=screenshot/',
  { computeHash: true },
);
console.log(`Screenshot uploaded to: ${screenshotUrl} with aHash: ${aHash}`);

// Upload screenshot with custom headers
const { screenshotUrl } = await sos.management.screen.takeAndUploadScreenshot(
   'https://your.upload.server/upload/file?prefix=screenshot/',
   {
       computeHash: false,
       headers: {
       	'Authorization': 'Bearer yourTokenHere',
         'Custom-Header': 'CustomValue'
       }
   },
);
```

:::note[GitHub Example]

- [ Applet Example with Screenshot Upload](https://github.com/signageos/applet-examples/blob/master/examples/management-js-api/screenshot-upload)

:::

<Separator />

### ~takeAndUploadScreenshot(uploadBaseUrl, computeHash)~

:::danger Deprecated

This method was deprecated. Use `takeAndUploadScreenshot(uploadBaseUrl: string, options: TakeAndUploadScreenshotOptions): Promise<TakeAndUploadScreenshotResult>` instead.

:::

```ts expandable
takeAndUploadScreenshot(uploadBaseUrl: string, computeHash?: boolean): Promise<TakeAndUploadScreenshotResult>;
// show-more
interface TakeAndUploadScreenshotResult {
    screenshotUrl: string;
    aHash?: string;
}

```

<Separator />

### ~takeAndUploadScreenshot(uploadBaseUrl)~

:::danger Deprecated

This method was deprecated. Use `takeAndUploadScreenshot(uploadBaseUrl: string, computeHash?: boolean): Promise<{ screenshotUrl: string; aHash?: string }>` instead.

:::

```ts expandable
takeAndUploadScreenshot(uploadBaseUrl: string): Promise<string>;
```