Version: 5.x

vm-player

The root component that encapsulates all providers, plugins and UI components. This is the primary component you will interact with to set properties on the player, listen for events and call methods.

Usage#

<vm-player controls autoplay muted current-time="30">
<!-- Provider component is placed here. -->
<vm-ui>
<!-- UI components are placed here. -->
</vm-ui>
</vm-player>
<script>
const player = document.querySelector('vm-player');
// Listening to an event.
player.addEventListener('vmCurrentTimeChange', (event) => {
const currentTime = event.detail;
// ...
});
// Example function to showcase updating property.
const seekForward = () => {
player.currentTime += 5;
};
// Example function to showcase calling player method.
const enterFullscreen = () => {
player.enterFullscreen();
};
</script>

Properties#

PropertyDescriptionTypeDefault
aspectRatioThe aspect ratio of the player expressed as width:height (16:9). This is only applied if the viewType is video and the player is not in fullscreen mode.string'16:9'
audioTracks (readonly)The audio tracks associated with the current media.never[][]
autopauseWhether the player should automatically pause when another Vime player starts/resumes playback.booleantrue
autoplayWhether playback should automatically begin playing once the media is ready to do so. This will only work if the browsers autoplay policies have been satisfied. It'll generally work if the player is muted, or the user frequently interacts with your site. You can check if it's possible to autoplay via the canAutoplay() or canMutedAutoplay() methods. Depending on the provider, changing this prop may cause the player to completely reset.booleanfalse
buffered (readonly)The length of the media in seconds that has been downloaded by the browser.number0
buffering (readonly)Whether playback has temporarily stopped because of a lack of temporary data.booleanfalse
controlsIndicates whether a user interface should be shown for controlling the resource. Set this to false when you want to provide your own custom controls, and true if you want the current provider to supply its own default controls. Depending on the provider, changing this prop may cause the player to completely reset.booleanfalse
currentAudioTrack (readonly)Gets the index of the currently active audio track. Defaults to -1 to when the default audio track is used. If you'd like to set it than see the setCurrentAudioTrack method.number-1
currentPoster (readonly)The absolute URL of the poster for the current media resource. Defaults to undefined if no media/poster has been loaded.string ∣ undefinedundefined
currentProvider (readonly)The current provider name whose responsible for loading and playing media. Defaults to undefined when no provider has been loaded.Provider.Audio ∣ Provider.Dailymotion ∣ Provider.Dash ∣ Provider.HLS ∣ Provider.Video ∣ Provider.Vimeo ∣ Provider.YouTube ∣ undefinedundefined
currentSrc (readonly)The absolute URL of the media resource that has been chosen. Defaults to undefined if no media has been loaded.string ∣ undefinedundefined
currentTextTrack (readonly)Gets the index of the currently active text track. Defaults to -1 to when all text tracks are disabled. If you'd like to set it than see the setCurrentTextTrack method.number-1
currentTimeA double indicating the current playback time in seconds. Defaults to 0 if the media has not started to play and has not seeked. Setting this value seeks the media to the new time. The value can be set to a minimum of 0 and maximum of the total length of the media (indicated by the duration prop).number0
debugWhether the player is in debug mode and should console.x information about its internal state.booleanfalse
duration (readonly)A double indicating the total playback length of the media in seconds. Defaults to -1 if no media has been loaded. If the media is being streamed live then the duration is equal to Infinity.number-1
i18n (readonly)A dictionary of translations for the current language.Translationen
iconsThe default icon library to be used throughout the player. You can use a predefined icon library such as vime, material, remix or boxicons. If you'd like to provide your own see the <vm-icon-library> component. Remember to pass in the name of your icon library here.string'vime'
isAudio (readonly)Whether the current media is of type audio, shorthand for mediaType === MediaType.Audio.booleanfalse
isAudioView (readonly)Whether the current view is of type audio, shorthand for viewType === ViewType.Audio.booleanfalse
isControlsActiveWhether the controls are currently visible. This is currently only supported by custom controls.booleanfalse
isFullscreenActive (readonly)Whether the player is currently in fullscreen mode.booleanfalse
isLive (readonly)Whether the current media is being broadcast live (duration === Infinity).booleanfalse
isMobile (readonly)Whether the player is in mobile mode. This is determined by parsing window.navigator.userAgent.booleanfalse
isPiPActive (readonly)Whether the player is currently in picture-in-picture mode.booleanfalse
isSettingsActive (readonly)Whether the settings menu has been opened and is currently visible. This is currently only supported by custom settings.booleanfalse
isTextTrackVisible (readonly)Whether the current text tracks is visible. If you'd like to set it than see the setTrackTrackVisibility method.booleantrue
isTouch (readonly)Whether the player is in touch mode. This is determined by listening for mouse/touch events and toggling this value.booleanfalse
isVideo (readonly)Whether the current media is of type video, shorthand for mediaType === MediaType.Video.booleanfalse
isVideoView (readonly)Whether the current view is of type video, shorthand for viewType === ViewType.Video.booleanfalse
languageThe current language of the player. This can be any code defined via the extendLanguage method or the default en. It's recommended to use an ISO 639-1 code as that'll be used by Vime when adding new language defaults in the future.string'en'
languages (readonly)The languages that are currently available. You can add new languages via the extendLanguage method.string[]['en']
loopWhether media should automatically start playing from the beginning every time it ends.booleanfalse
mediaTitle (readonly)The title of the current media. Defaults to undefined if no media has been loaded.string ∣ undefinedundefined
mediaType (readonly)The type of media that is currently active, whether it's audio or video. Defaults to undefined when no media has been loaded or the type cannot be determined.MediaType.Audio ∣ MediaType.Video ∣ undefinedundefined
mutedWhether the audio is muted or not.booleanfalse
pausedWhether playback should be paused. Defaults to true if no media has loaded or playback has not started. Setting this to true will begin/resume playback.booleantrue
playbackEnded (readonly)Whether media playback has reached the end. In other words it'll be true if currentTime === duration.booleanfalse
playbackQualities (readonly)The media qualities available for the current media.string[][]
playbackQualityIndicates the quality of the media. The value will differ between audio and video. For audio this might be some combination of the encoding format (AAC, MP3), bitrate in kilobits per second (kbps) and sample rate in kilohertz (kHZ). For video this will be the number of vertical pixels it supports. For example, if the video has a resolution of 1920x1080 then the quality will return 1080p. Defaults to undefined which you can interpret as the quality is unknown. The value can also be Auto for adaptive bit streams (ABR), where the provider can automatically manage the playback quality. The quality can only be set to a quality found in the playbackQualities prop. Some providers may not allow changing the quality, you can check if it's possible via canSetPlaybackQuality().string ∣ undefinedundefined
playbackRateA double indicating the rate at which media is being played back. If the value is <1 then playback is slowed down; if >1 then playback is sped up. Defaults to 1. The playback rate can only be set to a rate found in the playbackRates prop. Some providers may not allow changing the playback rate, you can check if it's possible via canSetPlaybackRate().number1
playbackRates (readonly)The playback rates available for the current media.number[][1]
playbackReady (readonly)Whether media is ready for playback to begin.booleanfalse
playbackStarted (readonly)Whether the media has initiated playback. In other words it will be true if currentTime > 0.booleanfalse
playing (readonly)Whether media is actively playing back. Defaults to false if no media has loaded or playback has not started.booleanfalse
playsinlineWhether the video is to be played "inline", that is within the element's playback area. Note that setting this to false does not imply that the video will always be played in fullscreen. Depending on the provider, changing this prop may cause the player to completely reset.booleanfalse
ready (readonly)Whether the player has loaded and is ready to be interacted with.booleanfalse
seeking (readonly)Whether the player is in the process of seeking to a new time position.booleanfalse
shouldRenderNativeTextTracksWhether text tracks should be rendered by native player, set to false if using custom display.booleantrue
textTracks (readonly)The text tracks associated with the current media.never[][]
themeThis property has no role other than scoping CSS selectors.string ∣ undefinedundefined
translationsContains each language and its respective translation map.{ [x: string]: Translation; }{ en }
viewType (readonly)The type of player view that is being used, whether it's an audio player view or video player view. Normally if the media type is of audio then the view is of type audio, but in some cases it might be desirable to show a different view type. For example, when playing audio with a poster. This is subject to the provider allowing it. Defaults to undefined when no media has been loaded.ViewType.Audio ∣ ViewType.Video ∣ undefinedundefined
volumeAn int between 0 (silent) and 100 (loudest) indicating the audio volume.number50

Methods#

MethodDescriptionSignature
canAutoplayDetermines whether the player can start playback of the current media automatically.canAutoplay() => Promise<boolean>
canMutedAutoplayDetermines whether the player can start playback of the current media automatically given the player is muted.canMutedAutoplay() => Promise<boolean>
canPlayDetermines whether the current provider recognizes, and can play the given type.canPlay(type: string) => Promise<boolean>
canSetAudioTrackReturns whether the current providers allows changing the audio track.canSetAudioTrack() => Promise<boolean>
canSetFullscreenReturns whether the native browser fullscreen API is available, or the current provider can toggle fullscreen mode. This does not mean that the operation is guaranteed to be successful, only that it can be attempted.canSetFullscreen() => Promise<boolean>
canSetPiPReturns whether the current provider exposes an API for entering and exiting picture-in-picture mode. This does not mean the operation is guaranteed to be successful, only that it can be attempted.canSetPiP() => Promise<boolean>
canSetPlaybackQualityReturns whether the current provider allows setting the playbackQuality prop.canSetPlaybackQuality() => Promise<boolean>
canSetPlaybackRateReturns whether the current provider allows setting the playbackRate prop.canSetPlaybackRate() => Promise<boolean>
canSetTextTrackReturns whether the current provider allows changing the text track.canSetTextTrack() => Promise<boolean>
canSetTextTrackVisibilityReturns whether the current providers allows setting the text track visibility.canSetTextTrackVisibility() => Promise<boolean>
enterFullscreenRequests to enter fullscreen mode, returning a Promise that will resolve if the request is made, or reject with a reason for failure. This method will first attempt to use the browsers native fullscreen API, and then fallback to requesting the provider to do it (if available). Do not rely on a resolved promise to determine if the player is in fullscreen or not. The only way to be certain is by listening to the vmFullscreenChange event. Some common reasons for failure are: the fullscreen API is not available, the request is made when viewType is audio, or the user has not interacted with the page yet.enterFullscreen(options?: FullscreenOptions ∣ undefined) => Promise<any>
enterPiPRequest to enter picture-in-picture (PiP) mode, returning a Promise that will resolve if the request is made, or reject with a reason for failure. Do not rely on a resolved promise to determine if the player is in PiP mode or not. The only way to be certain is by listening to the vmPiPChange event. Some common reasons for failure are the same as the reasons for enterFullscreen().enterPiP() => Promise<void ∣ undefined>
exitFullscreenRequests to exit fullscreen mode, returning a Promise that will resolve if the request is successful, or reject with a reason for failure. Refer to enterFullscreen() for more information.exitFullscreen() => Promise<any>
exitPiPRequest to exit picture-in-picture mode, returns a Promise that will resolve if the request is successful, or reject with a reason for failure. Refer to enterPiP() for more information.exitPiP() => Promise<void ∣ undefined>
extendLanguageExtends the translation map for a given language.extendLanguage(language: string, translation: Partial<Translation>) => Promise<void>
getContainerReturns the inner container.getContainer() => Promise<HTMLDivElement ∣ undefined>
getProviderReturns the current media provider.getProvider<InternalPlayerType = any>() => Promise<AdapterHost<InternalPlayerType> ∣ undefined>
pausePauses playback of the media.pause() => Promise<void ∣ undefined>
playBegins/resumes playback of the media. If this method is called programmatically before the user has interacted with the player, the promise may be rejected subject to the browser's autoplay policies.play() => Promise<void ∣ undefined>
setCurrentAudioTrackSets the currently active audio track given the index.setCurrentAudioTrack(trackId: number) => Promise<void>
setCurrentTextTrackSets the currently active text track given the index. Set to -1 to disable all text tracks.setCurrentTextTrack(trackId: number) => Promise<void>
setTextTrackVisibilitySets the visibility of the currently active text track.setTextTrackVisibility(isVisible: boolean) => Promise<void>

Events#

EventDescriptionType
vmAudioTracksChangeEmitted when the audioTracks prop changes value.CustomEvent<any[]>
vmBufferedChangeEmitted when the buffered prop changes value.CustomEvent<number>
vmBufferingChangeEmitted when the buffering prop changes value.CustomEvent<boolean>
vmControlsChangeEmitted when the isControlsActive prop changes value.CustomEvent<boolean>
vmCurrentAudioTrackChangeEmitted when the currentAudioTrack prop changes value.CustomEvent<number>
vmCurrentPosterChangeEmitted when the currentPoster prop changes value.CustomEvent<string ∣ undefined>
vmCurrentProviderChangeEmitted when the currentProvider prop changes value.CustomEvent<Provider.Audio ∣ Provider.Dailymotion ∣ Provider.Dash ∣ Provider.HLS ∣ Provider.Video ∣ Provider.Vimeo ∣ Provider.YouTube ∣ undefined>
vmCurrentSrcChangeEmitted when the currentSrc prop changes value.CustomEvent<string ∣ undefined>
vmCurrentTextTrackChangeEmitted when the currentTextTrack prop changes value.CustomEvent<number>
vmCurrentTimeChangeEmitted when the currentTime prop changes value.CustomEvent<number>
vmDurationChangeEmitted when the duration prop changes value.CustomEvent<number>
vmErrorEmitted when an any error has occurred within the player.CustomEvent<any>
vmFullscreenChangeEmitted when the isFullscreenActive prop changes value.CustomEvent<boolean>
vmI18nChangeEmitted when the i18n prop changes value.CustomEvent<Translation ∣ { [x: string]: string; }>
vmLanguageChangeEmitted when the language prop changes value.CustomEvent<string>
vmLanguagesChangeEmitted when the languages prop changes value.CustomEvent<string[]>
vmLiveChangeEmitted when the isLive prop changes value.CustomEvent<boolean>
vmLoadStartEmitted when the provider starts loading a media resource.CustomEvent<void>
vmMediaTitleChangeEmitted when the mediaTitle prop changes value.CustomEvent<string ∣ undefined>
vmMediaTypeChangeEmitted when the mediaType prop changes value.CustomEvent<MediaType.Audio ∣ MediaType.Video ∣ undefined>
vmMutedChangeEmitted when the muted prop changes value.CustomEvent<boolean>
vmPausedChangeEmitted when the paused prop changes value.CustomEvent<boolean>
vmPiPChangeEmitted when the isPiPActive prop changes value.CustomEvent<boolean>
vmPlayEmitted when the media is transitioning from paused to playing. Event flow: paused -> play -> playing. The media starts playing once enough content has buffered to begin/resume playback.CustomEvent<void>
vmPlaybackEndedEmitted when playback reaches the end of the media.CustomEvent<void>
vmPlaybackQualitiesChangeEmitted when the playbackQualities prop changes value.CustomEvent<string[]>
vmPlaybackQualityChangeEmitted when the playbackQuality prop changes value.CustomEvent<string ∣ undefined>
vmPlaybackRateChangeEmitted when the playbackRate prop changes value.CustomEvent<number>
vmPlaybackRatesChangeEmitted when the playbackRates prop changes value.CustomEvent<number[]>
vmPlaybackReadyEmitted when the media is ready to begin playback. The following props are guaranteed to be defined when this fires: mediaTitle, currentSrc, currentPoster, duration, mediaType, viewType.CustomEvent<void>
vmPlaybackStartedEmitted when the media initiates playback.CustomEvent<void>
vmPlayingChangeEmitted when the playing prop changes value.CustomEvent<boolean>
vmReadyEmitted when the player has loaded and is ready to be interacted with.CustomEvent<void>
vmSeekedEmitted directly after the player has successfully transitioned/seeked to a new time position. Event flow: seeking -> seeked.CustomEvent<void>
vmSeekingChangeEmitted when the seeking prop changes value.CustomEvent<boolean>
vmTextTracksChangeEmitted when the textTracks prop changes value.CustomEvent<TextTrack[]>
vmTextTrackVisibleChangeEmitted when the isTextTrackVisible prop changes value.CustomEvent<boolean>
vmThemeChangeEmitted when the theme prop changes value.CustomEvent<string ∣ undefined>
vmTouchChangeEmitted when the isTouch prop changes value.CustomEvent<boolean>
vmTranslationsChangeEmitted when the translations prop changes value.CustomEvent<{ [x: string]: Translation; }>
vmViewTypeChangeEmitted when the viewType prop changes value.CustomEvent<ViewType.Audio ∣ ViewType.Video ∣ undefined>
vmVolumeChangeEmitted when the volume prop changes value.CustomEvent<number>

Slots#

SlotDescription
Used to pass in providers, plugins and UI components.

CSS Custom Properties#

NameDescription
--vm-blocker-z-indexThe blocker's position in the root z-axis stack inside the player.
--vm-player-bgThe background color of the player, has no effect on audio players.
--vm-player-border-radiusThe border radius of the player.
--vm-player-box-shadowThe shadow cast around the player frame.
--vm-player-font-familyA custom font family to be used throughout the player.
--vm-player-themeA custom theme (color) to be used throughout the player. Any valid CSS color property (HEX, RGBA, HLS, ...) can be used.