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 — Can be sent by the player to indicate that playback has been paused or received to trigger a pause.

• Progress — Sent by the player to report the current playback position.

• Resume — Can be sent by the player to indicate playback has begun or resumed or received to trigger resumption.

• Complete — 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, a Media message includes the following additional properties:

Name	Type	Description
mediaItemId	String Required.	The mediaItemId property uniquely identifies the Media Item from which this message originates.
mediaItemType	MediaItemType Required.	The mediaItemType property specifies the type of Media Item from which this message originates. Refer to MediaItemType for detailed information.
progress	MediaProgress Required.	The progress property is an object that holds additional metadata related to the media playback progress of the current media item. Please refer to MediaProgress for detailed information.

For messages sent by the host app or environment, the mediaItemId, mediaItemType and progress properties can be omitted.

Legacy Properties

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.

Name	Type	Description
action	Literal Required.	The distinct action of the player message. ⚠️ Please use messageType instead.
target	Literal Required.	app or player ⚠️ Please use messageType instead.

---

Type Definition

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.

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

interface MediaProgress {
  bufferedTimeInMs: number;
  currentTimeInMs: number;
  durationInMs: number;
  elapsedTimeInMs: number;
  isLive: boolean;
  isPlaying: boolean;
  skipTimeInMs: boolean;
  visitorDwellTimeInMs: boolean;
}