ArtPlayer/packages/artplayer-plugin-dash-control/README.md

artplayer-plugin-dash-control

Dash control plugin for ArtPlayer

Complete usage and SDK ownership: English guide / 中文指南. These guides describe the current refactor branch; its fixes are not published yet.

Accepts a caller-owned dash.js instance at art.dash. Quality selection adapts to the dash.js 4.x quality methods or 5.x representation methods. Version 5 selection uses representation IDs so bitrate filtering does not change the selected quality.

Quality, track and stream events from the SDK refresh the control and setting menus. Refreshes are coalesced after the current synchronous selection finishes. During playback, the plugin also checks for changes to the SDK's Auto setting without redrawing menus on unchanged time updates. When changing only SDK configuration while paused (with no SDK event), call the existing synchronous art.plugins.artplayerPluginDashControl.update() to refresh immediately. The plugin removes only its own SDK listeners and never destroys your SDK instance.

For dash.js 4.5.2, the plugin compensates for stale buffer metrics when a paused seek reaches an empty buffered range. Existing setup and seek calls remain the same. This targeted recovery retains the caller's SDK configuration and media time.

TypeScript

The formatter receives the original SDK object. For dash.js 5.2.1 types:

import type { MediaInfo, Representation } from 'dashjs'
import dashControl from 'artplayer-plugin-dash-control'

dashControl<Representation, MediaInfo>({
  quality: { getName: level => `${level.height}p` },
  audio: { getName: track => track.lang || String(track.id) },
})

dash.js 4.5.2 uses BitrateInfo for quality instead of Representation. Audio metadata id, index, and lang may be null; custom formatters must return strings. The original object-based formatters and synchronous update() remain supported. Actual 5.2.1 SDK types resolve with TypeScript 5.9.3 NodeNext/Bundler in our matrix; Node10 resolution and TypeScript 4.3.5 have upstream SDK declaration limitations. See the tested type matrix.

Demo

https://artplayer.org

License

MIT © Harvey Zhao

Maintenance

Automatic SDK refresh keeps an open quality or audio settings menu usable while updating its selected item. Explicit update() keeps its existing behavior.

See ARCHITECTURE.md for module ownership, compatibility rules, test commands and the remaining real SDK playback validation scope.