# Media

The LiSA Player facilitates two-way communication by both sending and receiving messages related to media playback, ensuring synchronization with the host app or environment. These messages include:

* [Pause](/developers/guides/player-communication/message-api-reference/media/media-pause.md) — Can be sent by the player to indicate that playback has been paused or received to trigger a pause.
* [Progress](/developers/guides/player-communication/message-api-reference/media/media-progress.md) — Sent by the player to report the current playback position.
* [Resume](/developers/guides/player-communication/message-api-reference/media/media-resume.md) — Can be sent by the player to indicate playback has begun or resumed or received to trigger resumption.
* [Complete](/developers/guides/player-communication/message-api-reference/media/media-complete.md) — Sent by the player to indicate that media playback has ended.

While **Pause** and **Resume** messages can be both sent by the host app to control playback and sent by the player to reflect playback state changes, the other messages are exclusively **sent by the LiSA Player** to the host app/environment:

### Properties

Along with all standard [Message properties](/developers/guides/player-communication/message-api-reference.md#properties), a **Media** 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>progress</code></td><td valign="top"><pre><code>MediaProgress
</code></pre><p>Required.</p></td><td valign="top">The <code>progress</code> property is an object that holds additional metadata related to the media playback progress of the current media item.<br><br>Please refer to <a href="/pages/rMD8D7mCXjBlgew5J7ms#media-progress"><code>MediaProgress</code></a> for detailed information.</td></tr></tbody></table>

{% hint style="info" %}
For messages sent by the host app or environment, the `mediaItemId`, `mediaItemType` and `progress` properties can be omitted.
{% endhint %}

#### 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">The distinct action of the player message.<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> or <code>player</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 MediaMessage extends Omit<Message, 'messageType' | 'sender'> {
  messageType:
    | 'lsc:media:pause'
    | 'lsc:media:progress'
    | 'lsc:media:resume'
    | 'lsc:media:start'
    | 'lsc:media:stop';
  progress: MediaProgress;
}
```

#### Media Progress

The `MediaProgress` object provides detailed playback state information for a media item, including live streams, replays, and stories. It tracks the current playback position, buffering status, and total time spent on the media.

<table><thead><tr><th width="243" valign="top">Name</th><th width="175" valign="top">Type</th><th valign="top">Description</th></tr></thead><tbody><tr><td valign="top"><code>bufferedTimeInMs</code></td><td valign="top"><pre><code>Number
</code></pre><p>Required.</p></td><td valign="top"><p>The <code>bufferedTimeInMs</code> property represents the amount of media content, in milliseconds, that has been buffered beyond the current playback position.</p><ul><li><strong>For on-demand content</strong> (e.g., replays, stories), this represents the duration of buffered media ahead of the current playback position.</li><li><strong>For live streams</strong>, this value is always <code>0</code> since playback happens in real time without pre-buffering.</li></ul></td></tr><tr><td valign="top"><code>currentTimeInMs</code></td><td valign="top"><pre><code>Number
</code></pre><p>Required.</p></td><td valign="top"><p>The <code>currentTimeInMs</code> property represents the current playback position of the media item, measured in milliseconds from the start.</p><ul><li><strong>For on-demand content</strong> (e.g., replays, stories), this value indicates the exact position the user is watching.</li><li><strong>For live streams</strong>, this value represents the current timestamp relative to the live broadcast</li></ul></td></tr><tr><td valign="top"><code>durationInMs</code></td><td valign="top"><pre><code>Number
</code></pre><p>Required.</p></td><td valign="top"><p>The <code>durationInMs</code> property represents the total duration of the media item, measured in milliseconds.</p><ul><li><strong>For on-demand content</strong> (e.g., replays, stories), this value reflects the full length of the media item.</li><li><strong>For live media items</strong>, this value is always <code>-1</code>, as the total duration is undefined while the stream is ongoing.</li></ul></td></tr><tr><td valign="top"><code>elapsedTimeInMs</code></td><td valign="top"><pre><code>Number
</code></pre><p>Required.</p></td><td valign="top"><p>The <code>elapsedTimeInMs</code> property represents the total accumulated playback time, in milliseconds, since the media started playing.</p><ul><li>This includes any time added when a user seeks forward or backward in the media.</li><li>It does not reset when seeking but continues to track the total time spent playing the media.</li><li><strong>For live streams</strong>, this value reflects the time spent watching the stream, independent of the actual live position.</li></ul></td></tr><tr><td valign="top"><code>isLive</code></td><td valign="top"><pre><code>Boolean
</code></pre><p>Required.</p></td><td valign="top"><p>The <code>isLive</code> property indicates whether the media item is a live stream.</p><ul><li><strong><code>true</code></strong> – The media item is a live stream, meaning playback occurs in real time.</li><li><strong><code>false</code></strong> – The media item is not live (e.g., a replay or story).</li></ul></td></tr><tr><td valign="top"><code>isPlaying</code></td><td valign="top"><pre><code>Boolean
</code></pre><p>Required.</p></td><td valign="top">The <code>isPlaying</code> property indicates, whether the current media item is playing or paused.</td></tr><tr><td valign="top"><code>skipTimeInMs</code></td><td valign="top"><pre><code>MediaProgress
</code></pre><p>Required.</p></td><td valign="top"><p>The <code>skipTimeInMs</code> property represents the amount of time, in milliseconds, that is skipped at the beginning of a live stream recording.</p><ul><li>This can be used to bypass countdown intro video segments or other non-essential content in recordings of live streams.</li><li>The skipped time does not affect the actual media duration but adjusts the playback start position when viewing the recording.</li></ul></td></tr><tr><td valign="top"><code>visitorDwellTimeInMs</code></td><td valign="top"><pre><code>Number
</code></pre><p>Required.</p></td><td valign="top"><p></p><p>The <code>visitorDwellTimeInMs</code> property represents the total time, in milliseconds, that a visitor has spent on the current media item, including any paused segments.</p><ul><li>This value accumulates even when the media is paused, reflecting the total time the visitor remained on the media item.</li><li>It is independent of <code>elapsedTimeInMs</code>, which tracks only active playback time.</li></ul></td></tr></tbody></table>

<pre class="language-typescript"><code class="lang-typescript"><strong>interface MediaProgress {
</strong>  bufferedTimeInMs: number;
  currentTimeInMs: number;
  durationInMs: number;
  elapsedTimeInMs: number;
  isLive: boolean;
  isPlaying: boolean;
  skipTimeInMs: boolean;
  visitorDwellTimeInMs: boolean;
}
</code></pre>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.hello-lisa.com/developers/guides/player-communication/message-api-reference/media.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.