Class: EvePlayer
Framework-agnostic video player built on Video.js 8 +
@videojs/http-streaming. Wraps a single Video.js Player behind a stable,
typed API so consuming apps never touch Video.js directly.
One instance owns one <video> element, which it creates and appends into
the container passed to the constructor. Call EvePlayer.dispose
when you are done to tear down the DOM and listeners.
Supports progressive MP4/MP3 plus HLS, MPEG-DASH and CMAF (over HLS or DASH).
The stylesheet must be imported separately:
import '@admmedia/eveplayer/style.css'.
Example
import { EvePlayer } from '@admmedia/eveplayer';
import '@admmedia/eveplayer/style.css';
const player = new EvePlayer(document.getElementById('player')!, {
widescreen: true,
});
player.setSource({
sources: [{ src: 'https://example.com/video.m3u8', type: 'application/x-mpegURL' }],
});
player.on('play', () => console.log('playing'));
// later…
player.dispose();
Constructors
Constructor
new EvePlayer(
container,options?):EvePlayer
Parameters
container
HTMLElement
Element the player mounts into. A <video class="video-js">
is created and appended here; Video.js then wraps it in its own root element.
Must be in the DOM (this constructor touches document/window, so never
call it during server-side rendering).
options?
Player configuration. See PlayerOptions.
Returns
EvePlayer
Properties
version
readonlystaticversion:string
Version of this library, as published (the package.json version baked
in at build time). Handy for support/diagnostics (e.g. EvePlayer.version
from the browser console, or to tell which CDN build a page loaded).
Reads '0.0.0-dev' in non-bundled contexts (tests).
Accessors
currentTime
Get Signature
get currentTime():
number
Current playback position, in seconds. Assigning seeks the media.
Returns
number
Set Signature
set currentTime(
value):void
Parameters
value
number
Returns
void
duration
Get Signature
get duration():
number
Total media duration in seconds (0 until metadata has loaded; Infinity for live).
Returns
number
ended
Get Signature
get ended():
boolean
True once playback has run to the end of the media.
Returns
boolean
isFullscreen
Get Signature
get isFullscreen():
boolean
True when the player is in browser fullscreen.
Returns
boolean
isPip
Get Signature
get isPip():
boolean
True when the CSS floating PiP overlay is active.
Returns
boolean
loop
Get Signature
get loop():
boolean
Whether playback restarts from the beginning when it reaches the end.
Returns
boolean
Set Signature
set loop(
value):void
Parameters
value
boolean
Returns
void
muted
Get Signature
get muted():
boolean
Mute state.
Returns
boolean
Set Signature
set muted(
value):void
Parameters
value
boolean
Returns
void
paused
Get Signature
get paused():
boolean
True when playback is paused.
Returns
boolean
playbackRate
Get Signature
get playbackRate():
number
Playback speed multiplier (1 = normal). Also settable from the settings menu.
Returns
number
Set Signature
set playbackRate(
value):void
Parameters
value
number
Returns
void
readyState
Get Signature
get readyState():
number
The underlying HTMLMediaElement.readyState (0–4); 0 when no tech is ready yet.
Returns
number
volume
Get Signature
get volume():
number
Playback volume from 0 to 1. Values assigned outside that range are clamped.
Returns
number
Set Signature
set volume(
value):void
Parameters
value
number
Returns
void
Methods
dispose()
dispose():
void
Tear the player down: exits PiP, stops timers and observers, emits
dispose, destroys the Video.js instance and removes the DOM it created,
and clears all event listeners. Idempotent (safe to call more than once).
Returns
void
exitFullscreen()
exitFullscreen():
void
Exit browser fullscreen.
Returns
void
exitPip()
exitPip():
void
Deactivates the CSS floating PiP window and restores the player in-flow.
Returns
void
getAudioTracks()
getAudioTracks():
AudioTrack[]
The audio tracks exposed by the current source (empty for single-audio media).
Returns
getChapterCues()
getChapterCues():
ChapterCue[]
Returns every cue from any 'chapters'-kind text track (usually just one).
Returns
getPlaybackStats()
getPlaybackStats():
PlaybackStats|undefined
Delivery telemetry for the source currently loaded: how much media has
been fetched, how long it took, and what it cost. The counters start from
zero on every EvePlayer.setSource, since each source gets a fresh
engine handler. See PlaybackStats for
which of the bitrate figures can be trusted as a yardstick (short version:
prefer fetchRate, and never compare throughput against peakBitrate).
Returns undefined where the engine is not in play, i.e. Safari's native
HLS and progressive .mp4 sources.
Returns
PlaybackStats | undefined
getQualityLevels()
getQualityLevels():
QualityLevel[]
The available quality levels for the current source, highest first, with
the Auto (adaptive) level prepended. Only HLS/DASH sources have levels;
returns [] for progressive MP4/MP3 or before the manifest has parsed.
Returns
getSource()
getSource():
SourceDescription|undefined
The source description most recently passed to EvePlayer.setSource, if any.
Returns
SourceDescription | undefined
getTextTracks()
getTextTracks():
TextTrack[]
The subtitle/caption tracks for the current source. metadata and
chapters tracks are excluded; use EvePlayer.getChapterCues
for chapters.
Returns
off()
off<
K>(event,handler):void
Unsubscribe a handler previously registered with EvePlayer.on or EvePlayer.once. Matches by reference.
Type Parameters
K
K extends keyof PlayerEventMap
Parameters
event
K
handler
VjsHandler<PlayerEventMap[K]>
Returns
void
on()
on<
K>(event,handler):void
Subscribe to a player event. The handler's argument type is inferred from PlayerEventMap.
Type Parameters
K
K extends keyof PlayerEventMap
The event name.
Parameters
event
K
Event name, e.g. 'play', 'timeupdate', 'qualitychange'.
handler
VjsHandler<PlayerEventMap[K]>
Called on each occurrence. Pass a stable reference so it can be removed with EvePlayer.off.
Returns
void
once()
once<
K>(event,handler):void
Like EvePlayer.on, but the handler is removed after its first call.
Type Parameters
K
K extends keyof PlayerEventMap
Parameters
event
K
handler
VjsHandler<PlayerEventMap[K]>
Returns
void
pause()
pause():
void
Pause playback.
Returns
void
play()
play():
Promise<void>
Start (or resume) playback. Resolves when playback actually begins; the returned promise rejects if the browser blocks it (e.g. un-muted autoplay).
Returns
Promise<void>
requestFullscreen()
requestFullscreen():
void
Request browser fullscreen for the player. Must be called from a user gesture.
Returns
void
requestPip()
requestPip():
void
Activates the CSS floating PiP window.
The player container becomes position: fixed in the bottom-right corner,
draggable by the user. No native browser PiP API is used.
Returns
void
reset()
reset():
void
Tears the playback engine back to a clean, sourceless state without disposing the player, so the next EvePlayer.setSource loads as a fresh start instead of a swap on top of the media already playing.
Needed between two genuinely different sources (a pre-live placeholder handing over to the live stream, a switch that changes container): Safari keeps a single playback engine across an in-place source swap, and its native-to-VHS hand-off can race the segment loaders, leaving the player frozen on the last frame of the previous source.
The viewer's audio state is carried across. Video.js's own reset puts the
volume back to 100% and re-applies the muted option the player was
constructed with (typically true, to get autoplay past the browser
policy); neither is something the viewer asked for, so both are restored.
Returns
void
setAudioTrack()
setAudioTrack(
id):void
Switch the active audio track: enables the track whose id matches and
disables every other. No-op if no track has that id.
Parameters
id
string
Target track id, from EvePlayer.getAudioTracks.
Returns
void
setAutoQuality()
setAutoQuality():
void
Re-enable adaptive bitrate: all levels become candidates again and the
custom ABR selector resumes choosing. Emits qualitychange with the
Auto level.
Returns
void
setBookmarks()
setBookmarks(
bookmarks):void
Replace the bookmark markers drawn on the progress bar. Markers are
positioned by Bookmark.offset against the current duration and are
re-rendered on loadedmetadata. Pass [] to clear them.
Parameters
bookmarks
Bookmark[]
The bookmarks to show.
Returns
void
setLabels()
setLabels(
labels):void
Replaces this player's label overrides (see PlayerOptions.labels)
and re-renders every label on screen with them. The new set replaces the
previous one entirely: a key left out goes back to its translation, or to
English. Pass {} to drop every override.
Parameters
labels
Overrides keyed by the English text of each label, e.g.
{ 'Settings': 'Options' }.
Returns
void
setPoster()
setPoster(
url):void
Update the poster image shown before playback (and while paused at position 0).
Parameters
url
string
Returns
void
setQualityLevel()
setQualityLevel(
id):void
Pin playback to one quality level, turning off adaptive switching. Forces
an immediate (buffer-clearing) switch and emits qualitychange. No-op for
an unknown id.
Parameters
id
string
A non-'auto' level id from EvePlayer.getQualityLevels.
Returns
void
setSource()
setSource(
source):void
Load a new source. Safe to call at any time, including before the player
is ready and repeatedly to switch content.
Clears bookmark markers and any previously side-loaded text tracks, sets
the poster if given, collapses to audio-only chrome when every source is
audio/*, and emits sourceset. Pass sources: [] for a poster-only
state (skips .src() instead of raising a "source not supported" error).
Parameters
source
The source to load. See SourceDescription.
Returns
void
setTextTrack()
setTextTrack(
id,mode):void
Set a text track's display mode. To show one subtitle track exclusively,
set the others to disabled yourself (this does not touch other tracks).
Parameters
id
string
Target track id, from EvePlayer.getTextTracks.
mode
"hidden" | "disabled" | "showing"
disabled, hidden, or showing.
Returns
void
setVisible()
setVisible(
visible):void
Show or hide the player without unmounting it (toggles a vjsp-hidden
class on the container). Playback state is untouched.
Parameters
visible
boolean
Returns
void
addLanguage()
staticaddLanguage(code,dictionary):void
Registers a UI-string dictionary for a locale (control bar labels, menu
items, etc.), then activate it by passing the same code as
PlayerOptions.language (or leave language unset to follow the
browser's language). Ready-made dictionaries covering both the player's
own labels and the Video.js ones ship in the package's lang/ folder:
import it from '@admmedia/eveplayer/lang/it.json';
EvePlayer.addLanguage('it', it);
Calling it again for the same code merges into the dictionary already
registered.
Video.js is bundled privately inside this package (see the package README),
so a consumer's own import videojs from 'video.js' is a separate module
instance and calling videojs.addLanguage() on it has no effect on players
created by EvePlayer: this static method is the only way to
reach the copy this library actually uses. Registration is global and only
needs to happen once (e.g. at module load), not per player instance.
Parameters
code
string
dictionary
Returns
void