Instance Properties
Here, Instance Properties refer to the first-level properties mounted on the instance, which are commonly used.
Instance identity and lifecycle
Artplayer.instances returns the shared array of successfully constructed, still-registered instances. The constructor adds an instance only after synchronous initialization finishes; a constructor plugin does not yet find its own instance there. It is not a copy or a list of ready players. Read or copy it rather than editing it: registration, duplicate-container checks and mutex playback use this array. Destruction removes only that instance.
art.constructor is the same Artplayer constructor and its prototype is the instance prototype. Artplayer.version is the package version string, not a capability test. The historical root declarations still name Artplayer.env and Artplayer.build, but neither is supplied by the frozen npm 5.4.0 runtime or the current 6.0.0 runtime; their reads return undefined. The runtime declaration view omits them. The build process's NODE_ENV replacement does not create these public properties.
art.id is an incrementing numeric identifier within one loaded constructor, allocated before option validation. Failed construction can leave gaps; independent bundle copies have independent counters/registries. It is unrelated to option.id, which is a playback-memory key. Do not use it as a globally unique persistent identifier.
State fields and owned services
These six fields start as false and are ordinary writable fields, not commands or capability promises. Assigning them does not run the corresponding feature or perform cleanup.
| Field | Core meaning |
|---|---|
| isReady | Set before the first ready event after canplay. Not reset to false by reset, source changes or normal destruction, so it does not prove the current URL is ready |
| isDestroy | Set after core teardown and instance removal, before the destroy event. Internal closing guards start earlier; it can still be false while cleanup is executing |
| isFocus | Updated by player focusin/focusout and inside/outside document click/contextmenu paths. Not a direct alias of document.activeElement |
| isInput | Tracks INPUT targets in those paths, not every editable target. Keyboard filtering separately checks editable content |
| isLock | Updated by the mobile lock helper alongside its CSS state. Assigning this field alone does not create the lock UI or emit lock |
| isRotate | Tracks the CSS rotation used by web auto-orientation. Native screen-orientation locking does not make this a general device-orientation flag |
Optional flv/m3u8/hls/ts/mpd/torrent fields are integration slots for caller-installed adapters. The core does not initialize those SDKs or automatically call arbitrary objects' destroy methods. Follow each adapter's ownership contract and register its cleanup. runtime describes unknown integration values so that consumers check them before use.
art.player is the descriptor installer object, with no public operational methods; playback APIs are installed on art itself. info/loading/mask are existing component services with show and toggle(). Their show setters update CSS state and synchronously emit their named event, including identical assignments. They are not promises and do not fetch media or control buffering. Native media handlers may subsequently change their visibility.
The info service initializes on desktop, polls data-video fields at INFO_LOOP_TIME even while hidden, formats numbers to two decimals, and updates textContent. Its runtime init() restarts the owned polling/listener scope rather than creating an independent extra loop. Loading mounts the configured loading icon. Mask mounts state/error icons, requests play on state-button click, and switches to its terminal error presentation on destruction; a thrown user destroy listener does not skip its final cleanup. These services are not custom-entry containers like layers or controls.
plugins.add remains the registry method documented in the plugin guide: a synchronous result is immediately installed, a same-realm Promise returns a Promise of the registry, and neither shape is converted into a universal async API. The runtime Plugins.add type accepts accurate and legacy factories without wrapping the actual function. Plugin result objects are not automatically disposed merely because they contain a destroy method.
Reset, destruction, and failure
reset() only calls video.removeAttribute('src') followed by video.load(). It returns undefined, keeps the UI, registration, option.url, readiness flag and user subscriptions, and does not revoke caller URLs, destroy SDKs or rebuild plugins. Native media events may still follow. Use the source-switch APIs for coordinated source changes; reset is not a full player restart or an asynchronous cancellation receipt.
destroy(removeHtml = true) synchronously starts teardown. When REMOVE_SRC_WHEN_DESTROY is enabled and a media node is available it first calls reset, then releases owned scopes, handles the template, removes the instance, marks isDestroy, emits destroy, and finalizes remaining resources. Browser promises already in flight are not synchronously made complete by its return. Both reset and destroy use the method receiver; keep them bound to the instance when passing them elsewhere.
With true, destruction empties the container; it does not remove the caller's container node or restore its pre-mount content. With false, it keeps the generated DOM and marks the player art-destroy while still stopping core resources. A repeated/reentrant destroy is a no-op, so destroy(false) followed by destroy(true) does not later remove the retained DOM. Reusing the released container requires a new player. The old instance must not be treated as revived, and later property access is not uniformly guaranteed to be a no-op.
Cleanup continues after a failure, then throws the first caught value and logs additional failures. A failing synchronous constructor instead restores its captured DOM/attributes and rethrows the original initialization error. User event registrations are not all erased by destroy: retaining an instance also retains those callbacks until removed. Caller-created timers, native listeners and external SDK resources need their own cleanup; the core-owned listener manager and scopes only release resources registered with them.
import Artplayer from 'artplayer/runtime';
const art = new Artplayer({ container: '#player' });
const instances: Artplayer[] = [...Artplayer.instances];
const identifier: number = art.id;
art.info.show = true;
art.loading.toggle();
const dispose = art.destroy.bind(art);
const retained: void = dispose(false);
void [instances, identifier, retained];Playback, progress and source contracts
Method results and media state
play() returns a Promise that waits for the current media play() result. Native rejection still reaches the caller. Only after success does it show the play notice, emit the custom play event and pause other instances when mutex is enabled. If source replacement or destruction makes the request obsolete, the caller still receives the media result, but obsolete notice, play event and mutex effects stop. Errors from later logic, including custom listeners, can also reject this Promise; rejection does not always mean decoding failed.
pause() calls media pause() synchronously, then shows the notice, emits the custom pause event and returns the media method result. Native media normally returns undefined; a proxy may differ. toggle() selects play() or pause() from playing at call time and returns that branch's result directly, so it does not always return a Promise. Root Player.toggle keeps its historical void signature. PlaybackControls exported from the root is a type-only view for accurate native playback results, not a runtime object. The runtime entry also preserves proxy results through its media generic.
These three methods capture their owning instance and can be called after extraction. Custom play/pause events differ from video:play/video:pause: the browser dispatches native events, whose order cannot be inferred from method calls alone. playing uses a proxy's boolean playing value when available; otherwise it requires currentTime > 0, paused false, ended false and readyState > 2. It is not simply !paused and can be false at time zero or while buffering.
Time, volume and buffer values
| Interface | Actual behavior |
|---|---|
| currentTime | Reads media time with a falsy fallback of 0; writes use parseFloat, clamp to 0 through art.duration and ignore NaN input. The runtime entry accepts number/string; the root keeps number |
| duration | Reads media duration with Infinity and falsy values reported as 0; infinite live duration is not exposed as a finite seek endpoint |
| seek | Write-only; writes currentTime, shows a progress notice and synchronously emits seek(actual time, original input). It does not return a Promise waiting for native seeked |
| forward / backward | Write-only; forward currentTime + seconds or currentTime - seconds to seek. Pass numbers: historical JavaScript addition and subtraction coercion differ |
| volume | Clamps writes to [0, 1] and uses the accepted media value in its notice; only nonzero values update the storage volume key. Zero retains the previous nonzero stored value and does not change muted |
| muted | Writes the media field and synchronously emits muted, including repeated equal writes. Pass a boolean; native coercion does not change the original input carried by the event |
| playbackRate | Writes a truthy value only when it differs from the current rate, then shows a notice; falsy input restores 1. Unsupported native rates can still throw; menu configuration is not a browser capability guarantee |
| loadedTime | The end of the last buffered range, or 0 with no ranges; neither the sum of ranges nor a guarantee that the buffer is continuous |
| loaded | loadedTime divided by raw media duration, without clamping or invalid-value normalization |
| played | currentTime divided by art.duration; a position ratio, not accumulated viewing time or native played ranges |
loaded/played can be NaN/Infinity before readiness, for zero duration or with unusual proxy state. Check Number.isFinite before displaying a percentage; these ratios do not prove playability. seek, forward, backward, switch and quality have no getters and read as undefined. Root declarations retain historical read types; runtime describes the write-only behavior accurately. Direct currentTime assignment does not synchronously emit custom seek, though native media events still occur.
attr(key, value) directly accesses properties on the media object captured during construction; it is not an HTML attribute API. Omitted or explicit undefined means read; writes return undefined. Symbol keys work, and underlying property errors propagate. Direct media writes bypass the player facade's notices, storage and custom events. Do not replace template.$video to switch sources: most descriptors capture the original node while duration reads the current template, which would split their state.
URL assignment, completion and cancellation
url reads media src, normally a browser-resolved absolute URL for native media; proxies can return null. option.url stores caller input, so these values need not match. type reads/writes option.type; a nonempty value overrides extension detection when selecting customType. Changing type alone does not reload media.
Direct url assignment supersedes the current source operation. Native sources write src; customType runs on a later turn with the instance as this and video, input URL and art as arguments. A returned Promise is not a media readiness signal, but its rejection is handled by the owning operation. option.url changes only when actual src differs from its previous value. With an already-ready player and a previous URL, canplay for the current operation triggers restart. Adapters must still update media and dispatch events correctly; the core cannot infer external SDK readiness.
switchUrl(url) starts at 0; switchQuality(url) captures the current position. Both pause, assign the URL, wait for readiness and any required seek, restore rate and aspect ratio, and attempt playback according to current intent. An explicit pause during loading cancels automatic resume; newer public seek/currentTime writes take precedence over automatic position restoration. Both return Promise<void>. Normal completion means the source operation has finished, but internal play recovery is best effort: its rejection does not reject the source-switch Promise.
A later switch, direct url assignment or destroy ends the old operation and resolves its Promise normally; late callbacks cannot restore obsolete state. A request strictly equal to current art.url also completes as a no-op; relative input need not equal a resolved absolute URL. An empty URL switch completes and shows loading without clearing the old src, so it is not a substitute for reset. Media errors, adapter failures and state-restoration errors can still reject; handle them. Resolution alone does not prove the requested source is playing: inspect current source and media state as required by the application.
switch is a write-only compatibility entry for switchUrl. Its assignment expression does not return the switch Promise; use the method to observe completion or errors. Direct url setter failures are logged, and assignment does not provide an awaitable Promise either. URL/Blob URL ownership remains with the provider; switching or destroying the player does not revoke caller-owned URLs.
Quality lists and selection
quality accepts an array of html, url and optional default fields; html can be a string or HTMLElement. Assignment updates the right-side control named quality, using the first default item's label or the first item. This updates UI only: it neither switches to that URL nor infers highlighting from the current source. Arrays and entries follow the control's reference and default-mutation semantics rather than becoming immutable copies.
A selector click updates default flags and the label before calling switchQuality. Completion updates the notice and returned label only for a still-active selection. Replacing the control, selecting a newer item or destroying the player makes older asynchronous updates obsolete. An empty array leaves an empty quality control; it is not controls.remove('quality'). Reading art.quality does not return the list, so retain application configuration separately. A static URL list is not HLS/DASH adaptive-track discovery; use the corresponding SDK plugins.
import Artplayer from 'artplayer/runtime';
import type LegacyArtplayer from 'artplayer';
import type { PlaybackControls } from 'artplayer';
const art = new Artplayer({ container: '#player', url: '/assets/sample/video.mp4' });
function nativeCommands(player: LegacyArtplayer): PlaybackControls {
return player;
}
async function togglePlayback(): Promise<void> {
await art.toggle(); // May reject when the branch requests play.
}
async function changeSource(url: string): Promise<void> {
await art.switchUrl(url);
// Completion includes cancellation; inspect art.url and media state as needed.
}
const progress: number | null = Number.isFinite(art.played) ? art.played : null;
art.currentTime = '12.5';
const unreadable: undefined = art.seek;
void [nativeCommands, togglePlayback, changeSource, progress, unreadable];Display, sizing and image contracts
Display modes and browser capabilities
state returns the first truthy mode in mini, pip, fullscreen, fullscreenWeb order, or standard. Assignment closes active modes with a different name; it does not enable the named mode. Enter mini with mini = true. standard or an unknown name requests all active modes to close, and native exit may complete asynchronously. This is not an atomic mode transition or a guarantee of immediate completion.
fullscreen is installed on the first video:loadedmetadata event using capabilities available then; it may be undefined beforehand. It prefers document fullscreen, then WebKit video fullscreen, otherwise reads false and shows an unsupported notice. Root types retain boolean; runtime marks it optional. Native requests remain subject to user activation and permissions, and a boolean assignment expression is not an awaitable request result. Native state events drive fullscreen emission; the document path then updates exclusive state, CSS and resize. Errors may show a notice and produce fullscreenError. Property presence or desktop WebKit execution does not prove mobile support.
fullscreenWeb is a CSS page mode, read from the art-fullscreen-web class. Entry saves the player node's placement and inline style, optionally moves it to its owner document's body according to FULLSCREEN_WEB_IN_BODY, then changes dimensions and class. Exit restores the original snapshot, so temporary inline style changes made during the mode can be overwritten on exit. It synchronously emits fullscreenWeb then resize; repeated assignments can emit again. Destruction restores ownership and cleans up. This is not native browser fullscreen.
mini is a draggable page overlay, not operating-system PiP. The core moves the same media node into it and restores its original parent and sibling position on exit; subsequent entries reuse the overlay. Position uses storage left/top and is constrained to the viewport. Hiding cancels dragging; destruction removes only core-created overlays, while caller-provided nodes remain caller-owned. mini events describe overlay state, not successful playback.
pip prefers standard native PiP and reads as the media element when owned by this instance, otherwise null. WebKit presentation mode reads as a boolean; unsupported implementations read false. Root types retain boolean; runtime exposes Element/null/boolean. Assignment still takes a boolean and provides no observable Promise: preserve the user-click call stack and observe notices/pip events instead of treating assignment as a returned window. Cancellation/destruction exits only owned or late requests, not another player's window. This is video PiP; use the Document PiP plugin for a document window. Synchronous native errors may throw; asynchronous rejection is shown through the notice.
airplay() checks WebKit availability events and the picker method to request a target picker. It normally returns undefined; the subsequent airplay event does not prove a receiver connection. Unavailability only shows a notice. Call from appropriate user interaction and allow for method exceptions. Safari/iOS, receiver devices, iframe permissions and proxy support require separate verification.
Geometry, aspect ratio and poster
rect reads the player node's getBoundingClientRect each time; bottom/top/left/right/width/height use this viewport rectangle. x/y add page scroll offsets to left/top, giving page coordinates rather than simple aliases of rect.x/rect.y. These are not decoded media dimensions or a fixed snapshot; separate reads may span layout changes.
autoSize() contains the player within its caller container using valid video dimensions, writes player percentage width/height and emits autoSize({width, height}). autoHeight() keeps container clientWidth, writes a proportional pixel height on the container and emits autoHeight(height). Both return undefined and support extracted calls. Missing finite positive dimensions or hidden containers produce no invalid sizing writes/events; call again when visible or ready. These methods do not install a persistent automatic observer.
aspectRatio computes media width, height and margin from a ratio string and stores data-aspect-ratio. default or falsy input clears those three inline properties and the dataset. Valid ratios use current player dimensions; malformed/nonpositive ratios avoid invalid geometry but still retain the input dataset, notice and event, so the getter is not validation. flip uses data-flip; normal or falsy input clears it, and built-in CSS handles horizontal/vertical. Other strings can be retained and emitted without having a corresponding transform. Neither property changes source pixels. Both show the notice before synchronously emitting their named event, including repeated values.
poster reads/writes the poster layer's inline background-image, not video.poster. It neither loads a new media source nor automatically shows the poster again. Reading depends on the browser's quoted URL serialization and returns an empty string if parsing fails; it does not read backgrounds supplied by external stylesheets.
Capture results and ownership
getDataURL() and getBlobUrl() synchronously draw the current media frame into an internal canvas at call time, then return Promises. The first resolves to a PNG data URL; the second encodes asynchronously and creates a Blob URL. Dimensions come from media videoWidth/videoHeight. Capture contains the media frame, not player controls, CSS flip/aspect effects or DOM subtitles. Missing decoded frames, unavailable canvas or cross-origin media tainting can fail; successful playback does not imply readable pixels, and the core does not bypass CORS.
The getBlobUrl caller must use URL.revokeObjectURL when finished. Destroying the player does not revoke that URL or invalidate an encoding result already in progress. Data URLs need no revocation. Encoding failures reject, and a still-current instance/source shows an error notice. Do not treat an empty image from unavailable dimensions as a successful capture.
screenshot(name?) waits for getDataURL, requests a download, emits screenshot(dataURL) and returns the same string. The filename uses the supplied name or artplayer_ plus formatted time, and always appends .png: chosen.png becomes chosen.png.png. Actual download storage remains browser-controlled. Source replacement or destruction during the wait suppresses obsolete download/event effects, but the Promise can still return the captured frame. All three methods support extracted calls; handle rejection.
Sprite previews and subtitle offset
The thumbnails getter returns the actual option.thumbnails object. Its setter replaces the whole object and resets image loading only while the instance is open, url is truthy and the player is not live. It does not merge settings; an empty URL is not a clearing command. Loading/rendering starts only with an existing control and hover, or an event-bearing played update on mobile. Replacing configuration/control or destroying releases internal scaled Blob URLs and prevents stale writes. Failures log warnings and a later hover can retry.
number is the total cell count and column is the column count, with zero-based rows/cells. Cell width prefers width times scale, otherwise loaded image width divided by column; height prefers height times scale, otherwise uses the video ratio. Provide a valid positive grid and usable video dimensions. Preview updates require progress strictly between the endpoints; placement is constrained by progress-bar width. scale uses canvas resampling, so a cross-origin image being displayable does not prove it can be scaled. Configuration does not generate a sprite; use the relevant tool or plugin.
subtitleOffset writes only when a track and cues exist. Stored offset is clamped to [-10, 10]; each write recalculates from retained original cue times, then clamps cue boundaries to [0, duration], rather than accumulating offsets. Paused subtitles also refresh. The notice and subtitleOffset event carry the original input; the getter returns the stored clamped offset. A new track supplies its own state, and missing cues do not store an offset for future loading. The remaining reset declaration refers to the earlier lifecycle contract, not restoration of these display settings.
import Artplayer from 'artplayer/runtime';
const art = new Artplayer({ container: '#player' });
const fullscreen: boolean | undefined = art.fullscreen;
const pip: Element | null | boolean = art.pip;
const viewportRect: DOMRect = art.rect;
const pagePosition = { x: art.x, y: art.y };
function showMini(): void { art.mini = true; }
function closeModes(): void { art.state = 'standard'; }
async function inspectFrame(): Promise<number> {
const url = await art.getBlobUrl();
try {
return (await (await fetch(url)).blob()).size;
} finally {
URL.revokeObjectURL(url);
}
}
void [fullscreen, pip, viewportRect, pagePosition, showMini, closeModes, inspectFrame];play
- Type:
Function
Play the video.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
muted: true,
});
art.on('ready', () => {
art.play();
});pause
- Type:
Function
Pause the video.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
muted: true,
});
art.on('ready', () => {
art.play();
setTimeout(() => {
art.pause();
}, 3000);
});toggle
- Type:
Function
Toggle video play and pause.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
muted: true,
});
art.on('ready', () => {
art.toggle();
setTimeout(() => {
art.toggle();
}, 3000);
});destroy
- Type:
Function - Parameter:
Boolean
Destroy the player. Accepts a parameter indicating whether to also remove the player's html after destruction. Defaults to true.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
});
art.on('ready', () => {
art.destroy();
});reset
- Type:
Function
Reset the player's video element: removes the current src and calls load() once. Commonly used to manually release media resources or reinitialize the video tag in single-page applications.
Note: The global configuration
Artplayer.REMOVE_SRC_WHEN_DESTROYwill also automatically execute similar logic whendestroy()is called.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
});
art.on('ready', () => {
// Only reset the video, do not remove the interface
art.reset();
});seek
- Type:
Setter - Parameter:
Number
Seek to a specific time in the video, in seconds.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
});
art.on('ready', () => {
art.seek = 5;
});forward
- Type:
Setter - Parameter:
Number
Fast-forward the video time, in seconds.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
});
art.on('ready', () => {
art.forward = 5;
});backward
- Type:
Setter - Parameter:
Number
Rewind the video time, in seconds.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
});
art.on('ready', () => {
art.seek = 5;
setTimeout(() => {
art.backward = 2;
}, 3000);
});volume
- Type:
Setter/Getter - Parameter:
Number
Set and get the video volume, range: [0, 1].
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
});
art.on('ready', () => {
console.info(art.volume);
art.volume = 0.5;
console.info(art.volume);
});url
- Type:
Setter/Getter - Parameter:
String
Set and get the video URL.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
});
art.on('ready', () => {
art.url = '/assets/sample/video.mp4?t=0';
});switch
- Type:
Setter - Parameter:
String
Set the video URL. Similar to art.url when setting, but performs some optimization operations.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
});
art.on('ready', () => {
art.seek = 10;
setTimeout(() => {
art.switch = '/assets/sample/video.mp4?t=0';
}, 3000);
});switchUrl
- Type:
Function - Parameter:
String
Set the video URL. Similar to art.url when setting, but performs some optimization operations.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
});
art.on('ready', () => {
art.seek = 10;
setTimeout(() => {
art.switchUrl('/assets/sample/video.mp4?t=0');
}, 3000);
});Note
art.switch and art.switchUrl use the same operation, but only the method returns an observable Promise. Normal completion, replacement, destruction, an equal URL or an empty URL can all resolve; failed automatic playback recovery does not itself reject the switch. Handle rejection and inspect current source/media state as needed; see source transitions.
switchQuality
- Type:
Function - Parameter:
String
Sets the video quality URL. Similar to art.switchUrl, but retains the previous playback progress.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
});
art.on('ready', () => {
art.seek = 10;
setTimeout(() => {
art.switchQuality('/assets/sample/video.mp4?t=0');
}, 3000);
});muted
- Type:
Setter/Getter - Parameter:
Boolean
Sets or gets whether the video is muted.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
});
art.on('ready', () => {
console.info(art.muted);
art.muted = true;
console.info(art.muted);
});currentTime
- Type:
Setter/Getter - Parameter:
Number
Sets or gets the current playback time of the video. Setting the time is similar to seek, but it does not trigger additional events.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
});
art.on('ready', () => {
console.info(art.currentTime);
art.currentTime = 5;
console.info(art.currentTime);
});duration
- Type:
Getter
Gets the duration of the video.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
});
art.on('ready', () => {
console.info(art.duration);
});Note
Some videos may not have a duration, such as live streams or videos that have not been fully decoded. In such cases, the obtained duration will be 0.
screenshot
- Type:
Function
Downloads a screenshot of the current video frame. An optional parameter specifies the screenshot filename.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
});
art.on('ready', () => {
art.screenshot('your-name');
});getDataURL
- Type:
Function
Gets the base64 URL of a screenshot of the current video frame. Returns a Promise.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
});
art.on('ready', async () => {
const url = await art.getDataURL();
console.info(url)
});getBlobUrl
- Type:
Function
Gets the blob URL of a screenshot of the current video frame. Returns a Promise.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
});
art.on('ready', async () => {
const url = await art.getBlobUrl();
console.info(url);
});fullscreen
- Type:
Setter/Getter - Parameter:
Boolean
Sets or gets the player's window fullscreen state.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
controls: [
{
position: 'right',
html: 'Fullscreen Switch',
click: function () {
art.fullscreen = !art.fullscreen;
},
},
],
});Note
Due to browser security mechanisms, a user interaction (e.g., a click on the page) must occur before triggering window fullscreen.
fullscreenWeb
- Type:
Setter/Getter - Parameter:
Boolean
Sets or gets the player's web page fullscreen state.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
fullscreenWeb: true,
});
art.on('ready', () => {
art.fullscreenWeb = true;
setTimeout(() => {
art.fullscreenWeb = false;
}, 3000);
});pip
- Type:
Setter/Getter - Parameter:
Boolean
Sets or gets the player's Picture-in-Picture (PIP) mode.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
controls: [
{
position: 'right',
html: 'PIP',
click: function () {
art.pip = !art.pip;
},
},
],
});Note
Due to browser security mechanisms, a user interaction (e.g., a click on the page) must occur before triggering Picture-in-Picture.
poster
- Type:
Setter/Getter - Parameter:
String
Sets and gets the video poster. The poster effect is only visible before the video starts playing.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
poster: '/assets/sample/poster.jpg',
});
art.on('ready', () => {
console.info(art.poster);
art.poster = '/assets/sample/poster.jpg?t=0';
console.info(art.poster);
});mini
- Type:
Setter/Getter - Parameter:
Boolean
Sets and gets the player's mini mode.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
});
art.on('ready', () => {
art.mini = true;
});playing
- Type:
Getter - Parameter:
Boolean
Gets whether the video is currently playing.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
muted: true,
});
art.on('ready', () => {
console.info(art.playing);
});state
- Type:
Setter/Getter - Parameter:
String
Gets or sets the player's current state. Supported values: standard (normal), mini (mini window), pip (picture-in-picture), fullscreen (window fullscreen), fullscreenWeb (webpage fullscreen).
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
});
art.on('ready', () => {
console.info(art.state); // Default is 'standard'
art.mini = true;
console.info(art.state); // mini
art.state = 'standard';
});autoSize
- Type:
Function
Sets whether the video adapts its size automatically.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
});
art.on('ready', () => {
art.autoSize();
});rect
- Type:
Getter
Gets the player's dimensions and coordinate information.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
});
art.on('ready', () => {
console.info(JSON.stringify(art.rect));
});Note
The dimension and coordinate information is obtained via getBoundingClientRect.
bottom / top / left / right / x / y / width / height
- Type:
Getter
These properties provide quick access to rect:
bottom,top,left,right,x,y: Correspond to the fields of the same name inDOMRect.width,height: The player's current visible width and height.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
});
art.on('ready', () => {
console.info(art.width, art.height, art.left, art.top);
});flip
- Type:
Setter/Getter - Parameter:
String
Sets and gets the player's flip state. Supported values: normal, horizontal, vertical.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
});
art.on('ready', () => {
console.info(art.flip);
art.flip = 'horizontal';
console.info(art.flip);
});playbackRate
- Type:
Setter/Getter - Parameter:
Number
Sets and gets the player's playback speed.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
});
art.on('ready', () => {
console.info(art.playbackRate);
art.playbackRate = 2;
console.info(art.playbackRate);
});aspectRatio
- Type:
Setter/Getter - Parameter:
String
Sets and gets the player's aspect ratio.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
});
art.on('ready', () => {
console.info(art.aspectRatio);
art.aspectRatio = '16:9';
console.info(art.aspectRatio);
});autoHeight
- Type:
Function
When the container only has a defined width, this property can automatically calculate and set the video's height.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
});
art.on('ready', () => {
art.autoHeight();
});
art.on('resize', () => {
art.autoHeight();
});Note
This property is useful when your container has only a width but the exact height is unknown. It can automatically calculate the video height, but you need to determine the timing for setting this property.
attr
- Type:
Function - Parameter:
String
Dynamically get and set attributes of the video element.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
});
art.on('ready', () => {
console.info(art.attr('playsInline'));
art.attr('playsInline', true);
console.info(art.attr('playsInline'));
});type
- Type:
Setter/Getter - Parameter:
String
Dynamically get and set the video type.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
});
art.on('ready', () => {
console.info(art.type);
art.type = 'm3u8';
console.info(art.type);
});theme
- Type:
Setter/Getter - Parameter:
String
Dynamically get and set the player's theme color.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
});
art.on('ready', () => {
console.info(art.theme);
art.theme = '#000';
console.info(art.theme);
});airplay
- Type:
Function
Initiate AirPlay.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
controls: [
{
position: 'right',
html: 'AirPlay',
click: function () {
art.airplay();
},
},
],
});loaded
- Type:
Getter
The proportion of video buffered, ranging from [0, 1]. Often used with the video:timeupdate event.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
});
art.on('video:timeupdate', () => {
console.info(art.loaded);
});loadedTime
- Type:
Getter
The buffered media duration in seconds. Typically used alongside loaded to display detailed buffering progress.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
});
art.on('video:timeupdate', () => {
console.info(art.loadedTime);
});played
- Type:
Getter
The proportion of video played, ranging from [0, 1]. Often used with the video:timeupdate event.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
});
art.on('video:timeupdate', () => {
console.info(art.played);
});proxy
- Type:
Function
A proxy function for DOM events, essentially proxying addEventListener and removeEventListener. When using proxy to handle events, the event is automatically cleaned up when the player is destroyed.
var container = document.querySelector('.artplayer-app');
var art = new Artplayer({
container: container,
url: '/assets/sample/video.mp4',
});
art.proxy(container, 'click', event => {
console.info(event);
});Note
If you need certain DOM events to exist only for the player's lifecycle, it is strongly recommended to use this function to avoid memory leaks.
query
- Type:
Function
A DOM query function, similar to document.querySelector, but the search is scoped to the current player, preventing errors with duplicate class names.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
});
console.info(art.query('.art-video'));video
- Type:
Element
Quickly returns the player's video element.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
});
console.info(art.video);Native and proxy media capabilities
art.video is the current template media node, identical to art.template.$video; it may be an adapted canvas rather than an HTMLVideoElement. The root entry retains its historical video type. runtime exports MediaSurface as NativeMedia | CanvasMedia: CanvasMedia describes an actual canvas plus media state, source, dimensions, buffered ranges, volume/rate, load and playback methods supplied by an adapter. A bare canvas does not satisfy that contract, and the type does not install an adapter.
PlaybackMethods allows an adapter's own play/pause return types. Calling art.video.play/pause acts directly on that surface, with its native or adapter result; the Artplayer method facade separately applies notices, custom events, operation ownership and mutex behavior. MediaState describes currentTime/duration/paused/ended/readyState and an optional boolean playing hint; when that hint is absent, the core derives playing from time greater than zero, not paused/ended, and readyState greater than two. These state fields do not prove decoded frames are being presented.
| Optional capability | Meaning and check |
|---|---|
| textTracks, error | Track-list-like data / native or adapter error value. Proxies may omit either; error is unknown, not guaranteed to be an Error instance |
| requestVideoFrameCallback, cancelVideoFrameCallback | Optional paired frame-callback methods. Detect each function and preserve the media receiver; no timer fallback is promised by these types |
| requestPictureInPicture | Optional native PiP request returning a Promise; availability does not remove user-activation, policy or media requirements |
| webkitEnterFullscreen, webkitExitFullscreen, webkitSupportsFullscreen | WebKit media-fullscreen methods and capability flag; detect before use |
| webkitSupportsPresentationMode, webkitSetPresentationMode, webkitPresentationMode | WebKit presentation-mode capability, request and observed mode; a supported method does not guarantee the requested mode succeeds |
| webkitDisplayingFullscreen | Optional observed media-fullscreen state, not a request |
| webkitShowPlaybackTargetPicker | Optional AirPlay picker. The core additionally checks availability events; calling it is not proof of a receiver connection |
Keep optional native calls bound to the media object, handle Promise failures, and use the public display APIs for normal player integration. Capability detection or Windows WebKit execution is not physical Safari/iOS/AirPlay acceptance. The following type-only consumer keeps access optional without issuing a display request:
import Artplayer from 'artplayer/runtime';
import type { MediaSurface, NativeMedia, CanvasMedia } from 'artplayer/runtime';
const art = new Artplayer({ container: '#player' });
const media: MediaSurface = art.video;
const error: unknown = media.error;
const tracks: ArrayLike<TextTrack> | undefined = media.textTracks;
const supportsFrames = typeof media.requestVideoFrameCallback === 'function'
&& typeof media.cancelVideoFrameCallback === 'function';
const surface: NativeMedia | CanvasMedia = media;
void [error, tracks, supportsFrames, surface];cssVar
- Type:
Function
Dynamically get or set CSS variables.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
});
art.on('ready', () => {
console.log(art.cssVar('--art-theme'));
art.cssVar('--art-theme', 'green');
console.log(art.cssVar('--art-theme'));
});Values, writes, and cascade
art.cssVar(name) reads getComputedStyle from art.template.$player and returns a string, including for opacity, scale and z-index. It returns the computed custom-property text, not a parsed number or necessarily a normalized color. A missing variable returns an empty string. art.theme delegates to '--art-theme'.
The second argument uses a historical truthiness check. A truthy value calls style.setProperty and returns undefined; numeric 0, an empty string, false, null, undefined or NaN instead read the current value. Use the string '0' to write zero. To remove an inline override, use art.template.$player.style.removeProperty(name); cssVar(name, '') does not remove it. Values are passed to CSS rather than validated against CssVar; invalid CSS tokens may be stored while the consuming property falls back or becomes invalid.
Writes affect this player's inline style and its descendants, not other instances. They do not update art.option.cssVar or art.option.theme, emit a theme event, or install a plugin. At construction, nonempty option.theme takes precedence over the initial '--art-theme' option. External styles follow normal CSS cascade rules: scope overrides to the actual .art-video-player, because the built-in defaults declared on that node can override values merely inherited from its container. Inline overrides generally win ordinary stylesheet declarations; !important declarations can still change the result.
The root cssVar signature retains historical numeric/literal types, including the 9999 literal for '--art-fullscreen-web-index'. Runtime values are not limited to that literal. The runtime entry exposes string reads and string-or-void writes without changing behavior; the constructor's legacy cssVar option shape remains distinct.
Built-in defaults and consumers
These are the base stylesheet values, before constructor overrides, mobile/fullscreen classes, user CSS and inline styles. Length values need CSS units where applicable. Naming a variable here does not prove support for a browser-specific pseudo-element or feature.
| Variable | Base value | Used for |
|---|---|---|
--art-theme | #f00 | Accent color for progress and selected items |
--art-font-color | #fff | Base text, links and SVG fill |
--art-background-color | #000 | Player background |
--art-text-shadow-color | rgba(0, 0, 0, 0.5) | Base text shadow color |
--art-transition-duration | 0.2s | Duration for transitions that consume it, not every animation |
--art-padding | 10px | Spacing for the bottom area, menus and info |
--art-border-radius | 3px | Corner radius for panels and tips |
--art-progress-height | 6px | Progress control height; inner track starts at half height |
--art-progress-color | rgba(255, 255, 255, 0.25) | Progress track background |
--art-progress-top-gap | 10px | Top interaction padding above the progress track |
--art-hover-color | rgba(255, 255, 255, 0.25) | Progress hover range color |
--art-loaded-color | rgba(255, 255, 255, 0.25) | Buffered range color |
--art-state-size | 80px | Central playback-state button size |
--art-state-opacity | 0.8 | State-button opacity when shown |
--art-bottom-height | 100px | Bottom gradient background height, not total control layout height |
--art-bottom-offset | 20px | Translation of bottom controls while hidden |
--art-bottom-gap | 5px | Gap below progress and around related overlays |
--art-highlight-width | 8px | Timestamp marker width |
--art-highlight-color | rgba(255, 255, 255, 0.5) | Timestamp marker color |
--art-control-height | 46px | Control-item minimum height/width and layout fallback |
--art-control-opacity | 0.75 | Control-item opacity outside hover |
--art-control-icon-size | 36px | Control icon width and height |
--art-control-icon-scale | 1.1 | Control icon scale, with a further pressed-state factor |
--art-volume-height | 120px | Volume panel height |
--art-volume-handle-size | 14px | Volume slider handle size |
--art-lock-size | 36px | Mobile lock-button size |
--art-indicator-scale | 0 | Base progress indicator scale; hover/active rules can override it |
--art-indicator-size | 16px | Progress indicator width and height |
--art-fullscreen-web-index | 9999 | Web-fullscreen stacking level, not native fullscreen permission |
--art-settings-icon-size | 24px | Left-side setting icon size |
--art-settings-max-height | 300px | CSS setting-panel maximum; JS also constrains available space |
--art-selector-max-height | 300px | Control selector maximum height |
--art-contextmenus-min-width | 250px | Context-menu minimum width |
--art-subtitle-font-size | 20px | Subtitle font size |
--art-subtitle-gap | 5px | Gap between subtitle lines |
--art-subtitle-bottom | 15px | Base subtitle bottom offset; controls can add layout height |
--art-subtitle-border | #000 | Subtitle outline text-shadow color, not border width |
--art-widget-background | rgba(0, 0, 0, 0.85) | Menu, setting and thumbnail panel background |
--art-tip-background | rgba(0, 0, 0, 0.7) | Progress tip, notice and lock-button background |
--art-scrollbar-size | 4px | Width/height of WebKit scrollbar pseudo-elements |
--art-scrollbar-background | rgba(255, 255, 255, 0.25) | WebKit scrollbar thumb color |
--art-scrollbar-background-hover | rgba(255, 255, 255, 0.5) | Hovered WebKit scrollbar thumb color |
--art-mini-progress-height | 2px | Retained historical value; current core styles do not consume it |
Mode overrides and measured layout
The mobile class changes bottom-gap to 10px, control-height to 38px, control-icon-scale to 1, state-size to 60px, settings/selector-max-height to 180px, indicator-scale to 1, and control-opacity to 1. Fullscreen styles change progress-height to 8px, indicator-size to 20px, control-height to 60px and control-icon-scale to 1.3; web fullscreen reuses those styles. When classes overlap, specificity and stylesheet order decide the result, and explicit inline values can suppress these mode defaults. These are style changes, not device or fullscreen-capability detection.
The control-layout observer additionally writes '--art-controls-height' from the rendered control area's offsetHeight. Subtitle and panel positioning use that measurement, falling back to '--art-control-height'. It is an internal measured value, not one of the 43 declared input variables; manual writes can be replaced by a later resize observation. Changing CSS dimensions does not change layout constants such as SETTING_ITEM_HEIGHT or configure player features.
'--art-mini-progress-height' remains declared with a 2px default for compatibility, but has no current core consumer. The mini progress presentation uses the normal progress/control geometry; changing that unused variable alone has no effect.
import Artplayer from 'artplayer/runtime';
const art = new Artplayer({ container: '#player' });
const opacity: string = art.cssVar('--art-control-opacity');
const result: string | void = art.cssVar('--art-control-opacity', '0');
art.cssVar('--art-fullscreen-web-index', '10001');
art.theme = 'green';
const theme: string = art.theme;
art.template.$player?.style.removeProperty('--art-control-opacity');
void [opacity, result, theme];quality
- Type:
Setter - Parameter:
Array
Dynamically set the quality list.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
quality: [
{
default: true,
html: 'SD 480P',
url: '/assets/sample/video.mp4',
},
{
html: 'HD 720P',
url: '/assets/sample/video.mp4',
},
],
});
art.on('ready', () => {
setTimeout(() => {
art.quality = [
{
default: true,
html: '1080P',
url: '/assets/sample/video.mp4',
},
{
html: '4K',
url: '/assets/sample/video.mp4',
},
];
}, 3000);
})thumbnails
- Type:
Setter/Getter - Parameter:
Object
Dynamically set thumbnails.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
});
art.on('ready', () => {
art.thumbnails = {
url: '/assets/sample/thumbnails.png',
number: 60,
column: 10,
};
});subtitleOffset
- Type:
Setter/Getter - Parameter:
Number
Dynamically set subtitle offset.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
subtitle: {
url: '/assets/sample/subtitle.srt',
},
});
art.on('ready', () => {
art.subtitleOffset = 1;
});