# artplayer-plugin-dash-control

Dash control plugin for ArtPlayer

Complete usage and SDK ownership:
[English guide](../artplayer-vitepress/docs/en/plugin/dash-control.md) /
[中文指南](../artplayer-vitepress/docs/plugin/dash-control.md).
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:

```ts
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](../../refactor/changes/2026-09-12-PKG-DASH-05-sdk-types.md).

## Demo

[https://artplayer.org](https://artplayer.org/?libs=https://cdnjs.cloudflare.com/ajax/libs/dashjs/5.2.1/modern/umd/dash.all.min.js%0A./uncompiled/artplayer-plugin-dash-control/index.js&example=dash.control)

## 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](ARCHITECTURE.md) for module ownership, compatibility rules,
test commands and the remaining real SDK playback validation scope.