Player

Type: Component

View Source

This component is at the heart of Vime. It's responsible for rendering providers, providing an interface to interact with them, and assisting in normalizing cross-browser and provider differences. It's internally used by the Complete Player.

See the notes page for more information on provider specifics.

Store

All props below are powered behind the scenes by a store. They are plain JS objects that contain a subscribe function and an optional set function. You can subscribe to receive updates of some value as it changes over time. The subscribe function returns an unsubscribe function that you can call to stop listening.

Usage

// All props below are available here.
const { paused } = player.getStore();
const unsubscribe = paused.subscribe(isPaused => {
console.log('paused state changed to:', isPaused);
});
// ...
unsubscribe();

Props

src

Type: any | Default: null

Used to locate media resources to load.

See our guide on how to set this prop.

canSetPoster

Type: boolean | Default: false | Readonly: true

Whether the current provider supports setting a custom poster.

poster

Type: string|null | Default: null

A custom poster to load if a provider supports it. You can check canSetPoster before you try setting this property.

providers

Type: Provider[] | Default: []

The current list of providers that are available to the player.

Provider

Type: Provider|null | Default: null

The current Provider who can play the current src. If it is null then no provider can play the current src.

provider

Type: component|null | Default: null | Readonly: true

The currently active provider instance.

providerConfig

Type: object | Default: {}

Provider specific configuration.

providerVersion

Type: string | Default: 'latest'

The NPM version of a provider package to load into the browser.

origin

Type: string|null | Default: 16:9 | Readonly: true

Where the src request had originated from without any path information.

title

Type: string|null | Default: null | Readonly: true

The title of the current media.

currentSrc

Type: any | Default: null | Readonly: true

The currently loaded media resources.

playbackReady

Type: boolean | Default: false | Readonly: true

Whether the current media is ready for playback.

rebuilding

Type: boolean | Default: false | Readonly: true

If the provider is currently rebuilding itself. This happens if we are forced to send a new parameter to the embed. For example, there is no API for enabling/disabling YouTube controls, so we change it via the controls parameter which requires the embed to reload.

canInteract

Type: boolean | Default: false | Readonly: true

Whether you can interact with the player. If true then the player is ready for playback and it's not currently rebuilding.

useNativeView

Type: boolean | Default: true | Readonly: true

Whether the provider should display any elements outside of the controls, such as titles, logos etc. Not all providers support this.

useNativeControls

Type: boolean | Default: true | Readonly: true

Whether to show/hide native controls.

useNativeCaptions

Type: boolean | Default: true | Readonly: true

Whether to enable/disable native captions. If false then the provider is given an empty set of tracks.

nativePoster

Type: string|null | Default: null | Readonly: true

The absolute URL of the native poster for the current src. For example, the thumbnail for a YouTube video.

mediaType

Type: MediaType | Default: 0 | Readonly: true

The type of the media, see MediaType.

isAudio

Type: boolean | Default: false | Readonly: true

Whether the current media is of type audio.

isVideo

Type: boolean | Default: false | Readonly: true

Whether the current media is of type video.

isLive

Type: boolean | Default: false | Readonly: true

Whether the current media is a live stream.

paused

Type: boolean | Default: true

Whether the player is paused or not.

currentTime

Type: double | Default: 0

The current playback time in seconds, setting this will seek the media to the new time.

buffered

Type: double | Default: 0 | Readonly: true

The length of the media that the browser has loaded in seconds.

duration

Type: double | Default: 0 | Readonly: true

The total playback length of the media in seconds.

muted

Type: boolean | Default: false

Whether the audio is muted or not.

volume

Type: int | Default: 30

An integer (0 - 100) that determines the current volume level of the audio. If 0, the audio is muted. This cannot be set on mobile as it is controlled by system controls.

playing

Type: boolean | Default: false | Readonly: true

Whether the current media is playing or not.

buffering

Type: boolean | Default: false | Readonly: true

Whether the current media is buffering (temporarily paused loading), or not.

playbackStarted

Type: boolean | Default: false | Readonly: true

Whether playback has started or not.

playbackEnded

Type: boolean | Default: false | Readonly: true

Whether playback has ended or not.

seeking

Type: boolean | Default: false | Readonly: true

Whether the player is seeking to a new time or not.

isPlayerActive

Type: boolean | Default: false | Readonly: true

Whether this is the currently active player or not. The player is active if it is the last player to have been interacted with programtically or by the user.

isControlsEnabled

Type: boolean | Default: true

Whether to show or hide controls.

isControlsActive

Type: boolean | Default: true

Whether the the controls are currently visible or not.

state

Type: PlayerState | Default: 1 | Readonly: true

The current state of the player, see PlayerState.

canSetPlaybackRate

Type: boolean | Default: false | Readonly: true

Whether the current provider supports setting the playback rate.

playbackRates

Type: double[] | Default: [1] | Readonly: true

The list of available playback rates.

playbackRate

Type: double | Default: 1

The current playback rate of the media. You can check canSetPlaybackRate before you try setting this property.

canSetVideoQuality

Type: boolean | Default: false | Readonly: true

Whether the current provider supports setting the video quality.

videoQualities

Type: VideoQuality[] | Default: [] | Readonly: true

The list of available video qualities, see VideoQuality.

videoQuality

Type: VideoQuality | Default: 0

The current video quality of the media, see VideoQuality. You can check canSetVideoQuality before you try setting this property.

isVideoView

Type: boolean | Default: false | Readonly: true

If the player is displayed as a video. It is true if there is a video loaded or if a poster is set.

isVideoReady

Type: boolean | Default: false | Readonly: true

If isVideoView is true and the player is ready for playback.

progress

Type: object | Readonly: true

The progress of the current playback and the amount buffered.

// Example to demonstrate the shape of the object.
const progress = {
played: {
seconds: 30,
percent: 25,
},
buffered: {
seconds: 45,
percent: 37.5,
}
};

canSetTracks

Type: boolean | Default: false | Readonly: true

Whether the current provider supports setting tracks/captions.

tracks

Type: object[] | Default: []

A list of tracks to be loaded. Each track is represented as a object that contains any valid TextTrackElement property.

canSetTrack

Type: boolean | Default: false | Readonly: true

Whether the current provider supports changing text tracks.

currentTrackIndex

Type: int | Default: -1

The index of the currently active track. If it is -1, then no track is active.

currentTrack

Type: object|null | Default: null | Readonly: true

The currently active track.

isCaptionsActive

Type: boolean | Default: false | Readonly: true

If captions are currently visible or not. This is false if currentTrackIndex is -1.

canSetPiP

Type: boolean | Default: false | Readonly: true

Whether the current provider supports picture-in-picture (PiP).

This doesn't guarantee that the player will enter PiP. It determines whether the request can be made.

isPiPActive

Type: boolean | Default: false | Readonly: true

Whether the player is in picture-in-picture mode or not.

canSetFullscreen

Type: boolean | Default: false | Readonly: true

Whether fullscreen is supported by the current provider or native Fullscreen API.

This doesn't guarantee that the player will enter fullscreen. It determines whether the request can be made.

isFullscreenActive

Type: boolean | Default: false | Readonly: true

Whether the player is in fullscreen mode or not.

autopause

Type: boolean | Default: true

Whether to pause this player when another player becomes active.

aspectRatio

Type: string|null | Default: 16:9

The aspect ratio of the player expressed as width:height.

playsinline

Type: boolean | Default: true

When the player begins playback on mobile, whether it should play inline or go fullscreen. If autoplay is true then this will be forced to be true.

canAutoplay

Type: boolean | Default: false | Readonly: true

Whether playback can begin immediately. This assumes playsinline is true.

canMutedAutoplay

Type: boolean | Default: false | Readonly: true

Whether playback can begin immediately if the volume is muted. This assumes playsinline is true.

autoplay

Type: boolean | Default: false

Whether playback should begin as soon as it's ready.

This will automatically fallback to muting if canAutoplay returns false. In addition, the playsinline property will be forced to be true.

loop

Type: boolean | Default: false

Whether playback should start over from the beginning when it reaches the end.

Methods

getStore

Return Type: object

Returns an object where each key is a prop listed above, and the corresponding value is a Svelte store.

tick

Return Type: Promise<undefined>

Returns a Promise that will resolve once all pending player state changes are flushed.

requestPiP

Return Type: Promise<string|undefined>

Requests the player to enter picture-in-picture (PiP) mode. Returns a Promise that will resolve if the request is made, or reject with a reason for failure. A resolved Promise doesn't gurantee that it was successful. To know when it is active or not, you can subscribe to isPiPActive. You can also call canSetPiP to see if the current provider supports it.

Possible Rejection Reasons

  • The current provider does not support it.

  • The request is made on an audio track.

  • The player is not ready for playback.

  • The user has not interacted with the page/player yet.

Notes

  • At this time, captions are not supported in PiP.

  • Only supported in Desktop Chrome 70+ and Desktop Safari 10+ at the moment.

Listening to Changes

const { isPiPActive } = player.getStore();
const unsubscribe = isPiPActive.subscribe(isActive => {
console.log('pip change:', isActive);
});
// ...
unsubscribe();

exitPiP

Return Type: Promise<string|undefined>

Requests the player to exit picture-in-picture (PiP) mode. Returns a Promise that will resolve if the request is made, or reject with a reason for failure. See requestPiP for more information.

Possible Rejection Reasons

  • Player is not in PiP mode.

  • Player is out of view and has not mounted yet.

requestFullscreen

Return Type: Promise<string|undefined>

Requests the player to enter fullscreen mode. Returns a Promise that will resolve if the request is made, or reject with a reason for failure. A resolved Promise doesn't gurantee that it was successful. To know when it is active or not, you can subscribe to isFullscreenActive. You can also call canSetFullscreen to see if it is supported or not.

Possible Rejection Reasons

  • The request is made on an audio track.

  • The player is not ready for playback.

  • The user has not interacted with the page yet.

  • The Fullscreen API is not available and the current provider does not support it.

Notes

Listening to Changes

const { isFullscreenActive } = player.getStore();
const unsubscribe = isFullscreenActive.subscribe(isActive => {
console.log('fullscreen change:', isActive);
});
// ...
unsubscribe();

exitFullscreen

Return Type: Promise<string|undefined>

Requests the player to exit fullscreen mode. Returns a Promise that will resolve if the request is made, or reject with a reason for failure. See requestFullscreen for more information.

Possible Rejection Reasons

  • Player is not in fullscreen mode.

  • Player is out of view and has not mounted yet.