<!--
{
  "availability" : [
    "LivePhotosKit JS: 1.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "LivePhotosKitJS",
  "identifier" : "/documentation/LivePhotosKitJS/LivePhotosKit.Player",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "LivePhotosKit JS"
    ],
    "preciseIdentifier" : "cl/LivePhotosKit.Player"
  },
  "title" : "LivePhotosKit.Player"
}
-->

# LivePhotosKit.Player

A player for Live Photos.

```
interface LivePhotosKit.Player
```

## Overview

This class provides a default native control allowing users to play Live Photos.

On a desktop browser, when the user moves the pointer over the native control badge, the video starts playing until the user moves the pointer away from the badge or the video ends. If the user moves the pointer before the video ends, the video stops.

On a mobile device, when the user presses the Live Photo, the video starts playing until the user stops pressing or the video ends.

### Player Events

During the life cycle of a player, several events are generated.  Adding an event listener to the player allows reaction to these events.

#### videoload

The player emits a `videoload` event after the video component of the Live Photo has finished loading but before the minimum number of frames necessary for smooth playback are decoded. Under normal circumstances, the `canplay` event is emitted after the `videoload` event. The event handler is then passed an `Event` object. The `Player` reference is accessible from the event’s target member.

```javascript
player.addEventListener('videoload', (ev) => {
    // Handle event.
})
```

#### photoload

The player emits a `photoload` event when the photo component of the Live Photo has finished loading. The event handler is then passed an `Event` object. The Player reference is accessible from the event’s target member.

```javascript
player.addEventListener('photoload', (ev) => {
    // Handle event.
})
```

#### canplay

The player emits a `canplay` event when the `Player` has obtained just enough video frames and is obtaining them quickly enough for smooth playback. The event handler is then passed an `Event` object. The Player reference is accessible from the event’s target member.

```javascript
player. addEventListener('canplay', (ev) => {
    // Handle event.
})
```

#### ended

The player emits an `ended` event when playback of the Live Photo has completed. The event handler is then passed an `Event` object. The Player reference is accessible from the event’s target member.

```javascript
player.addEventListener('ended', (ev) => {
    // Handle event.
})
```

#### error

The player emits an `error` event when loading of either the photo or video components of the Live Photo has failed. The event handler is then passed an `Event` object, which has a detail member containing error information. If LivePhotosKit JS cannot interpret an internal exception, the `error` member of `detail` will be the exception object. The `Player` reference may be obtained from the event’s target member.

```javascript
player.addEventListener('error', (ev) => {
    if (typeof ev.detail.errorCode === 'number') {
        switch (ev.detail.errorCode) {
        case LivePhotosKit.Errors.IMAGE_FAILED_TO_LOAD:
            // Do something
            break;
        case LivePhotosKit.Errors.VIDEO_FAILED_TO_LOAD:
            // Do something
            break;
        }
    } else {
        // Extract Error object.
        console.error(ev.detail.error);
    }
})
```

## Topics

### Initializers

[`LivePhotosKit.Player`](/documentation/LivePhotosKitJS/LivePhotosKit.Player/LivePhotosKit.Player)

Creates `LivePhotosKit.Player` objects.

### Instance Properties

[`currentTime`](/documentation/LivePhotosKitJS/LivePhotosKit.Player/currentTime)

The current time, in seconds, of the play head.

[`duration`](/documentation/LivePhotosKitJS/LivePhotosKit.Player/duration)

The duration, in seconds, of the entire Live Photo.

[`photoHeight`](/documentation/LivePhotosKitJS/LivePhotosKit.Player/photoHeight)

The height, in pixels, of the photo component.

[`photoTime`](/documentation/LivePhotosKitJS/LivePhotosKit.Player/photoTime)

The nominated time, in seconds, of where the photo component should be within the Live Photo video component.

[`photoWidth`](/documentation/LivePhotosKitJS/LivePhotosKit.Player/photoWidth)

The width, in pixels, of the photo component.

[`canPlay`](/documentation/LivePhotosKitJS/LivePhotosKit.Player/canPlay)

A Boolean value that indicates whether the Player is able to begin playback.

[`errors`](/documentation/LivePhotosKitJS/LivePhotosKit.Player/errors)

An array of errors that occurred when attempting to load resources.

[`frameTimes`](/documentation/LivePhotosKitJS/LivePhotosKit.Player/frameTimes)

An array of timestamps for each second from the beginning of a Live Photo for which the frames reside in the Live Photo.

[`isPlaying`](/documentation/LivePhotosKitJS/LivePhotosKit.Player/isPlaying)

A Boolean value that indicates whether or not the Player is playing.

[`loadProgress`](/documentation/LivePhotosKitJS/LivePhotosKit.Player/loadProgress)

A numeric value that indicates the progress of loading the Live Photo.

[`metadataVideoSrc`](/documentation/LivePhotosKitJS/LivePhotosKit.Player/metadataVideoSrc)

A string or array buffer that contains metadata about the properties of a Live Photo.

[`photo`](/documentation/LivePhotosKitJS/LivePhotosKit.Player/photo)

The renderable, image-bearing DOM element (either an image or a canvas) that the Player consumes to render itself to the screen.

[`photoMimeType`](/documentation/LivePhotosKitJS/LivePhotosKit.Player/photoMimeType)

The MIME type of a photo asset.

[`photoSrc`](/documentation/LivePhotosKitJS/LivePhotosKit.Player/photoSrc)

The source of the photo component of the Live Photo.

[`playbackStyle`](/documentation/LivePhotosKitJS/LivePhotosKit.Player/playbackStyle)

The style of playback that determines the nature of an animation.

[`proactivelyLoadsVideo`](/documentation/LivePhotosKitJS/LivePhotosKit.Player/proactivelyLoadsVideo)

A boolean value that indicates whether the Player downloads bytes before the user begins playback.

[`renderedTime`](/documentation/LivePhotosKitJS/LivePhotosKit.Player/renderedTime)

The current timestamp, as a floating-point number of seconds from the beginning of the animation, that is truly displayed on the screen.

[`showsNativeControls`](/documentation/LivePhotosKitJS/LivePhotosKit.Player/showsNativeControls)

The value of this property indicates whether the Apple-provided playback controls are enabled for the user.

[`video`](/documentation/LivePhotosKitJS/LivePhotosKit.Player/video)

The playable `HTMLVideoElement` that the Player consumes to obtain video frame data to render to the screen while animating a Live Photo.

[`videoHeight`](/documentation/LivePhotosKitJS/LivePhotosKit.Player/videoHeight)

The height, in pixels, of the underlying video asset provided to the Player.

[`videoMimeType`](/documentation/LivePhotosKitJS/LivePhotosKit.Player/videoMimeType)

The MIME type of the video asset.

[`videoRotation`](/documentation/LivePhotosKitJS/LivePhotosKit.Player/videoRotation)

The angle that the video is displayed.

[`videoSrc`](/documentation/LivePhotosKitJS/LivePhotosKit.Player/videoSrc)

A reference to the source of the video component of this Live Photo.

[`videoWidth`](/documentation/LivePhotosKitJS/LivePhotosKit.Player/videoWidth)

The width, in pixels, of an underlying video asset provided to the Player.

[`wantsToPlay`](/documentation/LivePhotosKitJS/LivePhotosKit.Player/wantsToPlay)

A boolean that indicates whether the Player has been instructed to play.

[`autoplay`](/documentation/LivePhotosKitJS/LivePhotosKit.Player/autoplay)

[`effectType`](/documentation/LivePhotosKitJS/LivePhotosKit.Player/effectType)

### Instance Methods

[`beginFinishingPlaybackEarly`](/documentation/LivePhotosKitJS/LivePhotosKit.Player/beginFinishingPlaybackEarly)

Clips the duration of the renderer early so that the animation begins to fade back to the photo component earlier than it would ordinarily.

[`pause`](/documentation/LivePhotosKitJS/LivePhotosKit.Player/pause)

Pauses playback at the current time.

[`play`](/documentation/LivePhotosKitJS/LivePhotosKit.Player/play)

Starts playback if the player is ready, or resumes playback if the player is paused.

[`stop`](/documentation/LivePhotosKitJS/LivePhotosKit.Player/stop)

Stops playback and rewinds to the current time of zero.

[`toggle`](/documentation/LivePhotosKitJS/LivePhotosKit.Player/toggle)

Starts playing the video component of Live Photo if the video is paused, or pauses the video if it is playing.

[`updateSize`](/documentation/LivePhotosKitJS/LivePhotosKit.Player/updateSize)

Updates the size of the player.


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)