> For the complete documentation index, see [llms.txt](https://docs.hello-lisa.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hello-lisa.com/developers/guides/player-communication/message-api-reference/player/player-ui-transition.md).

# Player — UI Transition

The LiSA Player supports a **Picture-in-Picture (PiP)-like floating mode**, allowing users to continue watching while interacting with other content. Depending on the host app / environment, the player remains in place but adjusts its controls to better suit a floating experience.

{% hint style="info" %}
Read the [Picture-in-Picture guide](/developers/guides/integration-guide/app-integration/picture-in-picture.md) on how to utilize the Floating Mode messages in different host apps and environments.
{% endhint %}

### Floating Player States

The following states describe the transition between fullscreen and floating mode:

#### **`requestFloatingMode`**

The player is starting the transition into floating mode.

* Triggered when the user or system requests the player to enter floating mode.
* The player replaces its **onscreen controls** with a more suitable UI for floating mode.
* Once the transition completes, the `floating` state is entered.

#### **`floating`**

The player has fully entered floating mode.

* The **floating mode UI** is now active, providing minimal or more compact controls.
* The user can interact with other content while the video remains visible.
* If the user or system requests fullscreen again, the `requestFullscreenMode` state is triggered.

#### **`requestFullscreenMode`**

The player is starting the transition back to fullscreen mode.

* Triggered when the user or system requests the player to return to fullscreen.
* The **floating mode UI** begins transitioning back to the standard fullscreen controls.
* Once the transition completes, the `fullscreen` state is entered.

#### **`fullscreen`**

The player has fully returned to fullscreen mode.

* The **default fullscreen controls** are now active.
* Any floating mode interactions are reset until `requestFloatingMode` is triggered again.

***

### Properties

Along with all standard [Message properties](/developers/guides/player-communication/message-api-reference.md#properties), a UI Transition message includes the following additional properties:

<table><thead><tr><th width="243" valign="top">Name</th><th width="192" valign="top">Type</th><th valign="top">Description</th></tr></thead><tbody><tr><td valign="top"><code>mediaItemId</code></td><td valign="top"><pre><code>string
</code></pre><p>Required.</p></td><td valign="top">The <code>mediaItemId</code> property uniquely identifies the Media Item from which this message originates.</td></tr><tr><td valign="top"><code>mediaItemType</code></td><td valign="top"><pre><code>MediaItemType
</code></pre><p>Required.</p></td><td valign="top">The <code>mediaItemType</code> property specifies the type of Media Item from which this message originates.<br><br>Refer to <a href="/pages/TzMvWg0wtnzBMpFfvyoN#media-item-type"><code>MediaItemType</code></a> for detailed information.</td></tr><tr><td valign="top"><code>messageType</code></td><td valign="top"><pre><code>Literal
</code></pre><p>Required.</p></td><td valign="top"><code>lsc:player:ui-transition</code></td></tr><tr><td valign="top"><code>playerUiState</code></td><td valign="top"><pre><code>PlayerUiState
</code></pre><p>Required.</p></td><td valign="top"><p>The <code>playerUiState</code> property represents the current UI mode of the video player, determining how its controls and interface are adapted.</p><p><br><strong>Possible values / transitions</strong></p><ul><li><code>fullscreen</code> — The player is in fullscreen mode with standard controls.</li><li><code>floating</code> — The player is in floating mode with an adapted UI.</li><li><code>requestFloatingMode</code> → switches the player to <code>floating</code>.</li><li><code>requestFullscreenMode</code> → transitions the player back to <code>fullscreen</code>.</li></ul></td></tr></tbody></table>

#### Legacy Properties

{% hint style="warning" %}
If your integration uses **LiSA Player Version 1**, none of the properties described above will be available.

For **LiSA Player Version 2**, legacy properties can be ignored.
{% endhint %}

<table><thead><tr><th width="197" valign="top">Name</th><th width="190" valign="top">Type</th><th valign="top">Description</th></tr></thead><tbody><tr><td valign="top"><code>action</code></td><td valign="top"><pre><code>Literal
</code></pre><p>Required.</p></td><td valign="top"><code>maximize</code> or <code>minimize</code><br><br><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> Please use <code>messageType</code> instead.</td></tr><tr><td valign="top"><code>target</code></td><td valign="top"><pre><code>Literal
</code></pre><p>Required.</p></td><td valign="top"><code>app</code><br><br><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> Please use <code>messageType</code> instead.</td></tr></tbody></table>

***

### Type Definition

```typescript
interface PlayerUiTransitionMessage extends Omit<Message, 'messageType'> {
  mediaItemId: string;
  mediaItemType: MediaItemType;
  messageType: 'lsc:player:ui-transition';
  playerUiState: 
    | 'floating'
    | 'fullscreen'
    | 'requestFloatingMode'
    | 'requestFullScreenMode';
}
```

***

### Examples

#### Host App Requests Floating Mode

```json
{
  "messageType": "lsc:player:ui-transition",
  "playerUiState": "requestFloatingMode",
  "recipient": "LiSA",
  "sender": "HostApp",

  "action": "minimize",
  "target": "app"
}
```

#### Host App Confirms Floating Mode Entered

{% hint style="warning" %}
LiSA **Player Version 1** does not support externally confirming when the player host component has completed its transition.
{% endhint %}

```json
{
  "messageType": "lsc:player:ui-transition",
  "playerUiState": "floating",
  "recipient": "LiSA",
  "sender": "HostApp",
}
```

#### LISA Player Requests Fullscreen Mode

Triggered when the user taps the "Back to Fullscreen" CTA in the floating player’s onscreen controls.

{% hint style="warning" %}
LiSA **Player Version 1** does not support requesting the host app to exit the floating state.
{% endhint %}

```json
{
  "clockDriftInMs": 0,
  "mediaItemId": "9f333331-45cb-4289-8bcd-9023c1871111",
  "mediaItemType": "live",
  "messageType": "lsc:player:ui-transition",
  "playerUiState": "requestFullscreenMode",
  "recipient": "HostApp",
  "sender": "LiSA",
}
```

#### Host App Confirms Fullscreen Mode Entered

```json
{
  "messageType": "lsc:player:ui-transition",
  "playerUiState": "fullscreen",
  "recipient": "LiSA",
  "sender": "HostApp",

  "action": "maximize",
  "target": "app"
}
```