> 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/media.md).

# 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>