Existing imports from artplayer-plugin-danmuku and /legacy retain the npm 5.3.0 declarations. Use /runtime for declarations that describe the actual factory, asynchronous commands and returned internal owner:

import danmuku from 'artplayer-plugin-danmuku/runtime'
import type { Point, RuntimeOption } from 'artplayer-plugin-danmuku/runtime'

const option: RuntimeOption = { danmuku: [], heatmap: true }
const points: Point[] = [[0, 10], [200, 20]]

The option object is required; each field is optional. Registration returns the plugin facade immediately. await plugin.emit(row) and await plugin.load() return the internal owner, as do synchronous config/hide/show/reset commands. That owner differs from the registered facade. mount(target) returns undefined and requires a valid element or selector. The facade's option/state getters remain live.

The accurate entrypoint also exposes icon types, callback receivers and an explicit EventMap of payload tuples. Filters and visibility callbacks receive the current option as this; beforeEmit does too and accepts only strict true. Importing these types does not automatically alter Artplayer's historical event declarations. Custom points use mutable [number, number] tuples and retain the existing inner-array modifications during rendering.

ESM imports select the existing ESM factory; CommonJS require('artplayer-plugin-danmuku/runtime') returns the existing callable factory directly. No additional runtime implementation is loaded.

Loading and configuration

plugin.load() reloads the configured input and replaces the queue after input succeeds. plugin.load(input) appends; concurrent append operations remain independent. A newer replacement supersedes an unfinished older replacement. Destroy cancels pending loads and prevents late queue changes. Cancelled loads resolve to the same internal Danmuku instance as successful loads, without a late loaded or error event.

Fetch or response-text failures emit artplayerPluginDanmuku:error once and reject the corresponding public load() Promise. Initial automatic loading observes its rejection and logs a warning. XML Worker startup/runtime failures use the existing parser locally and release Worker/Blob resources.

Explicit time: 0 is preserved. Missing time and NaN retain the historical default of the current playback time plus 0.5 seconds. Positive infinity remains unchanged; negative values, including negative infinity, are clamped to zero. A replacement callback passed to config() takes effect, and invalid configuration leaves the current option intact. Existing method return identities, getters, input normalization and XML fields remain compatible. Configuration changes do not automatically reload data.

Scheduling failures and recovery

Playback uses one scheduling loop. Pausing, seeking, hiding, resetting or destroying the player cancels unfinished visibility preparation. Updating beforeVisible also releases an unfinished old callback; seeking and callback changes preserve already displayed comments.

A rejected beforeVisible emits the original artplayerPluginDanmuku:error once for that item in the current run, while other items continue. It is not retried every frame. Pause/resume, reset or a replacement callback permits a retry if the item still matches the display-time rules. A track Worker failure reports once and halts scheduling until pause/resume or reset rebuilds it.

If an error listener synchronously stops, destroys, resets or hides the instance, the interrupted recovery respects that action. A nested start can recover once without the outer call resuming it again or emitting another start event.

Settings and heatmap cleanup

Destroy removes the plugin's external settings panel, cancels its send countdown and prevents an unfinished beforeEmit from clearing input or starting another send. Other instances and later user changes to their shared mount remain intact. The shared stylesheet remains installed for other players. Setting initialization failure also releases the already-created plugin Worker.

Heatmap supports narrow containers with a positive sampling step and uses an independent gradient for each instance. Its existing points event still changes the inner point arrays as before; copy those arrays first if the original values must be retained. Removing or replacing its control releases its listeners.

Dense automatically sampled heatmaps now scale down instead of becoming a tall, flat block over the video (issue #958). When the sampled peak exceeds one quarter of the chart height, the curve fits inside that bottom quarter (25px in the default 100px control). Small curves keep their existing appearance. Explicit finite heatmap.yMin or heatmap.yMax, and custom points events, retain their original coordinate mapping; use these when deliberately controlling the scale.

See ARCHITECTURE.md for module ownership, compatibility constraints and editing/verification commands. All owned runtime modules now use TypeScript, with shared public runtime data types maintained in types/runtime-shared.d.ts. Long-duration load tests, combination/distribution acceptance and release reviews remain separate unfinished stages.

README.md

artplayer-plugin-danmuku

Demo

TypeScript entrypoints

Loading and configuration

Scheduling failures and recovery

Settings and heatmap cleanup

License