artplayer-plugin-ads
Ads plugin for ArtPlayer
Implementation, resource ownership and regression commands: maintenance guide.
Usage and TypeScript
import Artplayer from 'artplayer'
import ads from 'artplayer-plugin-ads'
new Artplayer({
container: '#player',
url: '/content.mp4',
plugins: [ads({ video: '/advertisement.mp4', url: '/details', playDuration: 5, totalDuration: 10 })],
})
Use html for HTML or an image element string. When both are present, video takes
precedence. playDuration controls when closing is allowed; totalDuration controls
the countdown. Durations are numeric seconds. Plugin play() and pause() control
only the countdown; skip() completes the advertisement once. All three return void.
For accurate options without historical declaration mistakes, import the same runtime
from artplayer-plugin-ads/runtime. Root and /legacy retain old input acceptance:
the old totalDuration: string declaration compiles but strings still fail runtime
validation; old workspace source/type fields are ignored. Use video or html.
An i18n object must supply close, countdown, detail and canBeClosed together.
CommonJS supports both require('artplayer-plugin-ads')(options) and
require('artplayer-plugin-ads').default(options). ESM uses the default export.
Migrating inferred option types
The maintainer approved correcting conflicting historical inference on 2026-09-12.
Existing option calls remain accepted, but Parameters<typeof ads>[0].totalDuration
now reads as number | string | undefined; historical workspace source/type are
optional. Code that assumed only one old declaration's field types may need adjustment.
This does not make string durations or source/type runtime aliases valid.
Prefer accurate options for new or migrated code:
import type { Option } from 'artplayer-plugin-ads'
import ads from 'artplayer-plugin-ads/runtime'
const option: Option = { video: '/advertisement.mp4', totalDuration: 10 }
const duration: number | undefined = option.totalDuration
const plugin = ads(option)
For a generic wrapper receiving historical input, narrow totalDuration before numeric
operations and check source/type before reading them as required fields. Do not use a
cast to hide string durations: the runtime validator rejects them. LegacyOption and
WorkspaceOption remain available for code explicitly representing those historical
declarations; Option describes the implemented configuration.
Demo
License
MIT © Harvey Zhao