mirror of
https://github.com/zhw2590582/ArtPlayer.git
synced 2026-10-19 19:51:20 -08:00
docs(hls): [SITE-HLS-01] add bilingual guides and fix example SDK ownership
This commit is contained in:
Harvey Zhao committed
1 parent
2802cbacc5
commit
4ea0ba94ae
68 files changed
+5308
-1677
No files matched your search
@@ -86,6 +86,24 @@ The plugin owns its two reserved menu names. Applications should use distinct na
|
||||
entries. Hls instances and third-party SDK listeners remain owned by their callers. No minimum
|
||||
core/SDK version has been newly imposed; the tested historical core is 5.4.0 and SDK is 1.5.17.
|
||||
|
||||
## Documentation and example ownership
|
||||
|
||||
The bilingual `artplayer-vitepress/docs/{en/,}plugin/hls-control.md` guides contain
|
||||
the exact `docs/assets/example/hls.control.js` setup. The example selects Hls.js
|
||||
versus native HLS once per player, installs controls only for the Hls.js path,
|
||||
releases each replaced SDK and registers one final player cleanup listener.
|
||||
`test/hls-example.test.js` guards the previously duplicated destroy calls and the
|
||||
invalid native-fallback plugin registration. `document-hls.spec.js` checks exact
|
||||
example parity and real SDK playback/replacement against published/candidate core;
|
||||
its WebKit no-MSE branch is capability evidence, not native HLS playback.
|
||||
|
||||
Update both guides whenever changing the example. Run the Node regression,
|
||||
`yarn test:browser document-hls.spec.js document-site.spec.js --workers=1`,
|
||||
`yarn build:llm`, `yarn build:docs`, and refresh/check the site inventory.
|
||||
Full source-topology, native-device and intermittent Firefox acceptance remain
|
||||
separate tasks. The native crash checkpoint now has xul.dll exception metadata;
|
||||
it still does not have a resolved stack or proven cause.
|
||||
|
||||
## Validation and next changes
|
||||
|
||||
Use the repository's pinned Node and Yarn:
|
||||
|
||||
@@ -4,6 +4,11 @@ Implementation boundaries and regression commands are documented in [ARCHITECTUR
|
||||
|
||||
Hls control plugin for ArtPlayer
|
||||
|
||||
Usage, SDK ownership, configuration and TypeScript examples:
|
||||
[English guide](../artplayer-vitepress/docs/en/plugin/hls-control.md) /
|
||||
[中文指南](../artplayer-vitepress/docs/plugin/hls-control.md).
|
||||
The guides describe this refactor branch; its fixes have not yet been published.
|
||||
|
||||
## Demo
|
||||
|
||||
[https://artplayer.org](https://artplayer.org/?libs=https://cdnjs.cloudflare.com/ajax/libs/hls.js/1.5.17/hls.min.js%0A./uncompiled/artplayer-plugin-hls-control/index.js&example=hls.control)
|
||||
|
||||
@@ -11,14 +11,15 @@ not a VitePress page. Keep both URL surfaces compatible.
|
||||
| `docs/index.md`, `docs/start`, `docs/component`, `docs/advanced` | Chinese API documentation | `/document/` |
|
||||
| `docs/en` | English counterparts | `/document/en/` |
|
||||
| `docs/plugin/danmuku.md`, `docs/en/plugin/danmuku.md` | Danmuku options, callbacks, commands, heatmap and types in both languages | `/document/plugin/danmuku.html`, `/document/en/plugin/danmuku.html` |
|
||||
| `docs/plugin/hls-control.md`, `docs/en/plugin/hls-control.md` | HLS SDK setup, menus, lifecycle and types | `/document/plugin/hls-control.html`, `/document/en/plugin/hls-control.html` |
|
||||
| `docs/.vitepress/config.js` | Navigation, base URL, output path, page head | Repository `docs/document/` |
|
||||
| `docs/vite.config.ts` | Search plugin configuration | VitePress/Vite integration; real search acceptance remains pending |
|
||||
| `docs/public/main.js` | Run Code links and first-visit language redirect | Copied into the built site |
|
||||
| `docs/public/style.css` | Documentation presentation | Copied into the built site |
|
||||
|
||||
Edit Markdown and public sources here. Do not edit the generated repository
|
||||
`docs/document/`. The current inventory contains 28 Markdown pages: 14 Chinese
|
||||
and 14 English. Danmuku has a dedicated guide and navigation in both languages. Other plugins currently
|
||||
`docs/document/`. The current inventory contains 30 Markdown pages: 15 Chinese
|
||||
and 15 English. Danmuku and HLS have dedicated guides and navigation in both languages. Other plugins currently
|
||||
use their package README, architecture notes and linked editor examples;
|
||||
navigation links alone are not complete API documentation.
|
||||
|
||||
@@ -123,3 +124,10 @@ SITE-02/03 own generators and browser source organization; SITE-04 owns bilingua
|
||||
API completeness; SITE-05 owns build, links and real search; SITE-07 owns vendor
|
||||
provenance and distribution notices; EX-03 owns complete demo execution. Three
|
||||
release review rounds and remote CI/Pages evidence remain separate requirements.
|
||||
|
||||
The HLS guides at `docs/plugin/hls-control.md` and `docs/en/plugin/hls-control.md`
|
||||
share the exact runnable `docs/assets/example/hls.control.js` source at repository
|
||||
root. `test/browser/document-hls.spec.js` enforces that parity and checks the
|
||||
source lifecycle with frozen real SDKs. `document-site.spec.js` checks both sidebar
|
||||
links and the two-library Run Code destination. Preserve the native-HLS capability
|
||||
boundary and SDK ownership explanation when editing either language.
|
||||
@@ -70,7 +70,7 @@ const config = {
|
||||
{ text: '弹幕遮罩', link: 'https://artplayer.org/?libs=./uncompiled/artplayer-plugin-danmuku/index.js%0A./uncompiled/artplayer-plugin-danmuku-mask/index.js&example=danmuku.mask' },
|
||||
{ text: '视频广告', link: 'https://artplayer.org/?libs=./uncompiled/artplayer-plugin-ads/index.js&example=ads' },
|
||||
{ text: 'Iframe 控制', link: 'https://artplayer.org/?libs=./uncompiled/artplayer-tool-iframe/index.js&example=iframe' },
|
||||
{ text: 'HLS 控制', link: 'https://artplayer.org/?libs=https://cdnjs.cloudflare.com/ajax/libs/hls.js/1.5.17/hls.min.js%0A./uncompiled/artplayer-plugin-hls-control/index.js&example=hls.control' },
|
||||
{ text: 'HLS 控制', link: '/plugin/hls-control' },
|
||||
{ text: 'DASH 控制', link: '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' },
|
||||
{ text: 'VTT 缩略图', link: 'https://artplayer.org/?libs=./uncompiled/artplayer-plugin-vtt-thumbnail/index.js&example=vtt.thumbnail' },
|
||||
{ text: '多重字幕', link: 'https://artplayer.org/?libs=./uncompiled/artplayer-plugin-multiple-subtitles/index.js&example=multiple.subtitles' },
|
||||
@@ -142,7 +142,7 @@ const config = {
|
||||
{ text: 'Danmuku', link: '/en/plugin/danmuku' },
|
||||
{ text: 'Advertise', link: 'https://artplayer.org/?libs=./uncompiled/artplayer-plugin-ads/index.js&example=ads' },
|
||||
{ text: 'Iframe Control', link: 'https://artplayer.org/?libs=./uncompiled/artplayer-tool-iframe/index.js&example=iframe' },
|
||||
{ text: 'HLS Control', link: 'https://artplayer.org/?libs=https://cdnjs.cloudflare.com/ajax/libs/hls.js/1.5.17/hls.min.js%0A./uncompiled/artplayer-plugin-hls-control/index.js&example=hls.control' },
|
||||
{ text: 'HLS Control', link: '/en/plugin/hls-control' },
|
||||
{ text: 'DASH Control', link: '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' },
|
||||
{ text: 'VTT Thumbnail', link: 'https://artplayer.org/?libs=./uncompiled/artplayer-plugin-vtt-thumbnail/index.js&example=vtt.thumbnail' },
|
||||
{ text: 'Multiple Subtitles', link: 'https://artplayer.org/?libs=./uncompiled/artplayer-plugin-multiple-subtitles/index.js&example=multiple.subtitles' },
|
||||
|
||||
@@ -0,0 +1,165 @@
|
||||
# HLS Control
|
||||
|
||||
[中文说明](../../plugin/hls-control.md)
|
||||
|
||||
Add quality and audio-track menus to an Hls.js player. This plugin controls the Hls.js instance you provide at `art.hls`; it does not download, create or destroy the SDK.
|
||||
|
||||
This guide describes the current refactor branch. The automatic refresh and lifecycle fixes described here have not yet been published. An unversioned npm/CDN install still uses the published release.
|
||||
|
||||
## Installation
|
||||
|
||||
```sh
|
||||
yarn add artplayer hls.js artplayer-plugin-hls-control
|
||||
```
|
||||
|
||||
```js
|
||||
import Artplayer from 'artplayer';
|
||||
import Hls from 'hls.js';
|
||||
import artplayerPluginHlsControl from 'artplayer-plugin-hls-control';
|
||||
```
|
||||
|
||||
For script tags, load ArtPlayer, Hls.js and the plugin's `dist/artplayer-plugin-hls-control.js` before running your setup. The plugin global is `artplayerPluginHlsControl`. Pin versions in your application and use media URLs that permit browser access.
|
||||
|
||||
## Complete example
|
||||
|
||||
The example uses the site's player container and the same source as the [online HLS example](https://artplayer.org/?libs=https://cdnjs.cloudflare.com/ajax/libs/hls.js/1.5.17/hls.min.js%0A./uncompiled/artplayer-plugin-hls-control/index.js&example=hls.control). Replace the container and stream URL in your application.
|
||||
|
||||
<div className="run-code" data-libs="https://cdnjs.cloudflare.com/ajax/libs/hls.js/1.5.17/hls.min.js
|
||||
./uncompiled/artplayer-plugin-hls-control/index.js"></div>
|
||||
|
||||
```js
|
||||
// npm i hls.js
|
||||
// npm i artplayer-plugin-hls-control
|
||||
|
||||
// import Hls from 'hls.js';
|
||||
// import artplayerPluginHlsControl from 'artplayer-plugin-hls-control';
|
||||
|
||||
const useHls = Hls.isSupported()
|
||||
let hls
|
||||
|
||||
function destroyHls() {
|
||||
const previous = hls
|
||||
hls = undefined
|
||||
if (previous)
|
||||
previous.destroy()
|
||||
}
|
||||
|
||||
const art = new Artplayer({
|
||||
container: '.artplayer-app',
|
||||
url: 'https://playertest.longtailvideo.com/adaptive/elephants_dream_v4/index.m3u8',
|
||||
setting: true,
|
||||
plugins: useHls
|
||||
? [
|
||||
artplayerPluginHlsControl({
|
||||
quality: {
|
||||
// Show quality choices in the controls
|
||||
control: true,
|
||||
// Show quality choices in settings
|
||||
setting: true,
|
||||
// Get the quality name from level
|
||||
getName: level => `${level.height}P`,
|
||||
// I18n
|
||||
title: 'Quality',
|
||||
auto: 'Auto',
|
||||
},
|
||||
audio: {
|
||||
// Show audios in control
|
||||
control: true,
|
||||
// Show audios in setting
|
||||
setting: true,
|
||||
// Get the audio name from track
|
||||
getName: track => track.name || track.lang || 'Audio',
|
||||
// I18n
|
||||
title: 'Audio',
|
||||
auto: 'Auto',
|
||||
},
|
||||
}),
|
||||
]
|
||||
: [],
|
||||
customType: {
|
||||
m3u8: function playM3u8(video, url, art) {
|
||||
destroyHls()
|
||||
if (useHls) {
|
||||
hls = new Hls()
|
||||
art.hls = hls
|
||||
hls.loadSource(url)
|
||||
hls.attachMedia(video)
|
||||
}
|
||||
else if (video.canPlayType('application/vnd.apple.mpegurl')) {
|
||||
video.src = url
|
||||
}
|
||||
else {
|
||||
art.notice.show = 'Unsupported playback format: m3u8'
|
||||
}
|
||||
},
|
||||
},
|
||||
})
|
||||
|
||||
art.on('destroy', destroyHls)
|
||||
```
|
||||
|
||||
Only install the control plugin when Hls.js is supported. If the browser instead plays HLS natively, the example assigns `video.src` without installing a plugin that requires `art.hls`. Native quality/audio selection is not supplied by this plugin. Keep `useHls` fixed for that player instance; recreate the player if the playback integration changes.
|
||||
|
||||
## Configuration
|
||||
|
||||
`artplayerPluginHlsControl(option?)` returns a synchronous plugin factory. Both `quality` and `audio` accept these fields:
|
||||
|
||||
| Field | Meaning and default |
|
||||
| --- | --- |
|
||||
| `control` | Show the bottom control; omitted means hidden. |
|
||||
| `setting` | Show the settings entry; omitted means hidden. Enable the player's `setting: true` as well. |
|
||||
| `title` | Menu title; quality defaults to `Quality`, audio to `Audio`. |
|
||||
| `auto` | Fallback text, default `Auto`. Quality also uses it for its Auto option. Audio does not gain a synthetic Auto track. |
|
||||
| `getName(item, index?)` | Return a string from the original SDK level or track. The current-label call omits `index`; list calls include it. |
|
||||
|
||||
Without a quality formatter, labels use `level.name` or `level.height + 'P'`. Audio labels use `track.name`, `track.lang`, then `track.language`. Empty titles/Auto text fall back to their defaults. Give formatters a string fallback when your source lacks metadata.
|
||||
|
||||
The formatter is a plain callback; it does not receive the player as `this`. Avoid using its optional index as a required field. Equal labels collapse into one displayed choice, so include bitrate or other distinguishing metadata when separate variants have the same height. Empty track lists remove their menus.
|
||||
|
||||
Choosing a quality writes `hls.currentLevel`; Auto writes `-1`. The selected label reflects automatic mode when `autoLevelEnabled` is true. Choosing audio writes `hls.audioTrack` with the SDK track ID. A menu selection is synchronous and does not mean the new stream has finished buffering or decoding.
|
||||
|
||||
## Refresh after external changes
|
||||
|
||||
The plugin updates on player `ready` and `restart`. When the SDK provides its event API, manifest, level, audio and destruction events also refresh or clear the menus. Current SDK state determines the selected choice.
|
||||
|
||||
After attaching a replacement instance to the same video and assigning `art.hls`, use the existing synchronous method when an immediate refresh is needed:
|
||||
|
||||
```js
|
||||
art.plugins.artplayerPluginHlsControl.update();
|
||||
```
|
||||
|
||||
`update()` returns `undefined`; it is not a Promise. Calling it without an attached Hls.js instance can throw. SDK-like integrations without supported event hooks must call it when their state changes. Reserve menu names `hls-quality` and `hls-audio` for this plugin.
|
||||
|
||||
## SDK ownership and source switching
|
||||
|
||||
Use the player's existing `switchUrl()` or `switchQuality()` for source changes and handle the returned Promise. The example's custom loader destroys the previous SDK before creating the next one, updates `art.hls`, and keeps one final cleanup listener per player. Each instance is destroyed once. Do not add a new player `destroy` listener on every load while also destroying replaced instances yourself.
|
||||
|
||||
The control plugin releases its own SDK subscriptions and makes retained menu callbacks inert after replacement or player destruction. It does not destroy the SDK, remove other consumers' SDK listeners, or implement Hls.js error recovery. Your application remains responsible for SDK fatal errors and playback policy.
|
||||
|
||||
## TypeScript
|
||||
|
||||
The default callback types include level height/name and audio id/name/language fields. Applications can specify their actual SDK metadata types through the existing generic factory. The example below uses only fields it needs and works without importing Hls.js declarations:
|
||||
|
||||
```ts
|
||||
import hlsControl from 'artplayer-plugin-hls-control';
|
||||
|
||||
interface Level { height: number; bitrate: number }
|
||||
interface Track { id: number; name: string; lang?: string }
|
||||
|
||||
const plugin = hlsControl<Level, Track>({
|
||||
quality: {
|
||||
control: true,
|
||||
getName: level => level.height + 'p / ' + level.bitrate,
|
||||
},
|
||||
audio: {
|
||||
setting: true,
|
||||
getName: track => track.name || track.lang || 'Audio',
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
Public `Option`, `Config`, `QualityLevel`, `AudioTrack` and `Result` types are exported from the root entry. The root and legacy import paths remain available. The types do not pretend every ArtPlayer instance already owns an Hls.js engine; describe `art.hls` in your application's integration types.
|
||||
|
||||
## Validation scope
|
||||
|
||||
The refactor tests Hls.js 1.5.17 and 1.7.2 with local media and real workers; these are tested points, not a newly declared supported range. Firefox grouped-stream crashes and a separate switching stall remain under investigation. Windows Playwright WebKit lacks the MSE path used in those tests; it does not establish Safari/iOS native-HLS acceptance. Verify your actual streams and target devices before adopting the unpublished refactor.
|
||||
@@ -0,0 +1,165 @@
|
||||
# HLS 控制
|
||||
|
||||
[English](../en/plugin/hls-control.md)
|
||||
|
||||
为 Hls.js 播放器添加画质与音轨菜单。插件控制你放在 `art.hls` 上的 Hls.js 实例，不负责下载、创建或销毁 SDK。
|
||||
|
||||
本页描述当前重构分支。这里说明的自动刷新与生命周期修复尚未发布；未固定版本的 npm/CDN 安装仍使用已发布版本。
|
||||
|
||||
## 安装
|
||||
|
||||
```sh
|
||||
yarn add artplayer hls.js artplayer-plugin-hls-control
|
||||
```
|
||||
|
||||
```js
|
||||
import Artplayer from 'artplayer';
|
||||
import Hls from 'hls.js';
|
||||
import artplayerPluginHlsControl from 'artplayer-plugin-hls-control';
|
||||
```
|
||||
|
||||
通过 script 标签使用时，先加载 ArtPlayer、Hls.js 和插件的 `dist/artplayer-plugin-hls-control.js`。插件全局名称为 `artplayerPluginHlsControl`。应用中应固定依赖版本，并使用允许浏览器访问的视频地址。
|
||||
|
||||
## 完整示例
|
||||
|
||||
下面与[在线 HLS 示例](https://artplayer.org/?libs=https://cdnjs.cloudflare.com/ajax/libs/hls.js/1.5.17/hls.min.js%0A./uncompiled/artplayer-plugin-hls-control/index.js&example=hls.control)使用同一份代码和站点容器。接入自己的应用时替换容器与视频地址。
|
||||
|
||||
<div className="run-code" data-libs="https://cdnjs.cloudflare.com/ajax/libs/hls.js/1.5.17/hls.min.js
|
||||
./uncompiled/artplayer-plugin-hls-control/index.js"></div>
|
||||
|
||||
```js
|
||||
// npm i hls.js
|
||||
// npm i artplayer-plugin-hls-control
|
||||
|
||||
// import Hls from 'hls.js';
|
||||
// import artplayerPluginHlsControl from 'artplayer-plugin-hls-control';
|
||||
|
||||
const useHls = Hls.isSupported()
|
||||
let hls
|
||||
|
||||
function destroyHls() {
|
||||
const previous = hls
|
||||
hls = undefined
|
||||
if (previous)
|
||||
previous.destroy()
|
||||
}
|
||||
|
||||
const art = new Artplayer({
|
||||
container: '.artplayer-app',
|
||||
url: 'https://playertest.longtailvideo.com/adaptive/elephants_dream_v4/index.m3u8',
|
||||
setting: true,
|
||||
plugins: useHls
|
||||
? [
|
||||
artplayerPluginHlsControl({
|
||||
quality: {
|
||||
// Show quality choices in the controls
|
||||
control: true,
|
||||
// Show quality choices in settings
|
||||
setting: true,
|
||||
// Get the quality name from level
|
||||
getName: level => `${level.height}P`,
|
||||
// I18n
|
||||
title: 'Quality',
|
||||
auto: 'Auto',
|
||||
},
|
||||
audio: {
|
||||
// Show audios in control
|
||||
control: true,
|
||||
// Show audios in setting
|
||||
setting: true,
|
||||
// Get the audio name from track
|
||||
getName: track => track.name || track.lang || 'Audio',
|
||||
// I18n
|
||||
title: 'Audio',
|
||||
auto: 'Auto',
|
||||
},
|
||||
}),
|
||||
]
|
||||
: [],
|
||||
customType: {
|
||||
m3u8: function playM3u8(video, url, art) {
|
||||
destroyHls()
|
||||
if (useHls) {
|
||||
hls = new Hls()
|
||||
art.hls = hls
|
||||
hls.loadSource(url)
|
||||
hls.attachMedia(video)
|
||||
}
|
||||
else if (video.canPlayType('application/vnd.apple.mpegurl')) {
|
||||
video.src = url
|
||||
}
|
||||
else {
|
||||
art.notice.show = 'Unsupported playback format: m3u8'
|
||||
}
|
||||
},
|
||||
},
|
||||
})
|
||||
|
||||
art.on('destroy', destroyHls)
|
||||
```
|
||||
|
||||
仅在支持 Hls.js 时安装控制插件。若改用浏览器原生 HLS，示例直接设置 `video.src`，不安装必须依赖 `art.hls` 的插件；该插件不会为原生播放提供画质或音轨选择。单个播放器实例保持固定的 `useHls`，更换播放集成方式时重新创建播放器。
|
||||
|
||||
## 配置
|
||||
|
||||
`artplayerPluginHlsControl(option?)` 同步返回插件工厂。`quality` 与 `audio` 都可以使用以下字段：
|
||||
|
||||
| 字段 | 含义与默认行为 |
|
||||
| --- | --- |
|
||||
| `control` | 显示底部控制器；省略时不显示。 |
|
||||
| `setting` | 显示设置项；省略时不显示，同时需要播放器的 `setting: true`。 |
|
||||
| `title` | 菜单标题，画质默认 `Quality`，音轨默认 `Audio`。 |
|
||||
| `auto` | 当前项未知时的文字，默认 `Auto`；画质还用于自动选项。音轨不会因此新增一个虚拟 Auto 轨道。 |
|
||||
| `getName(item, index?)` | 根据原始 SDK 档位或轨道对象返回字符串。当前标签调用没有 `index`，列表调用带有索引。 |
|
||||
|
||||
省略画质回调时，标签取 `level.name` 或 `level.height + 'P'`；音轨依次取 `track.name`、`track.lang`、`track.language`。空标题和空 Auto 文字会使用默认值。媒体没有相关字段时，自定义回调应提供字符串回退。
|
||||
|
||||
回调按普通函数调用，`this` 不会绑定到播放器，不能把可选索引视为必传字段。相同标签会合并成一个选项；如果想区分同高度的多个档位，可在标签中加入码率。轨道列表变空时会移除对应菜单。
|
||||
|
||||
选择画质会写入 `hls.currentLevel`，Auto 对应 `-1`；当 `autoLevelEnabled` 为 true 时，当前标签反映自动模式。选择音轨会把 SDK 轨道 ID 写入 `hls.audioTrack`。菜单选择是同步操作，不代表新流已经完成缓冲或解码。
|
||||
|
||||
## 外部修改后的刷新
|
||||
|
||||
播放器 `ready`、`restart` 会刷新菜单；SDK 提供事件接口时，清单、档位、音轨与销毁事件也会刷新或清除菜单。选中项来自当前 SDK 状态。
|
||||
|
||||
把替换后的实例绑定到同一个 video 并赋给 `art.hls` 后，如需立即刷新，可以调用已有同步方法：
|
||||
|
||||
```js
|
||||
art.plugins.artplayerPluginHlsControl.update();
|
||||
```
|
||||
|
||||
`update()` 返回 `undefined`，不是 Promise；在没有已绑定 Hls.js 实例时调用可能抛错。没有对应事件接口的自定义适配器需要在状态变化后手动刷新。菜单名 `hls-quality` 和 `hls-audio` 由插件使用，其他菜单请使用不同名称。
|
||||
|
||||
## SDK 所有权与换源
|
||||
|
||||
换源继续使用播放器已有的 `switchUrl()` 或 `switchQuality()`，并处理返回的 Promise。示例在创建新 SDK 前销毁旧实例，再更新 `art.hls`，每个播放器只保留一个最终清理监听器，每个 SDK 实例只销毁一次。不要在每次加载时累积新的播放器 `destroy` 监听器，同时又自行销毁被替换的实例。
|
||||
|
||||
控制插件只释放自己的 SDK 订阅；替换或销毁播放器后，旧菜单回调不再修改 SDK。插件不会销毁 SDK、移除其他使用者的监听器或实现 Hls.js 错误恢复；应用仍负责处理 SDK 致命错误和播放策略。
|
||||
|
||||
## TypeScript
|
||||
|
||||
默认回调类型包含画质高度/名称和音轨 ID/名称/语言字段。可以通过泛型使用应用所需的 SDK 元数据类型；下面的示例只声明实际使用的字段，无需导入 Hls.js 声明：
|
||||
|
||||
```ts
|
||||
import hlsControl from 'artplayer-plugin-hls-control';
|
||||
|
||||
interface Level { height: number; bitrate: number }
|
||||
interface Track { id: number; name: string; lang?: string }
|
||||
|
||||
const plugin = hlsControl<Level, Track>({
|
||||
quality: {
|
||||
control: true,
|
||||
getName: level => level.height + 'p / ' + level.bitrate,
|
||||
},
|
||||
audio: {
|
||||
setting: true,
|
||||
getName: track => track.name || track.lang || 'Audio',
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
根入口导出 `Option`、`Config`、`QualityLevel`、`AudioTrack` 和 `Result` 类型，原根入口及 legacy 路径继续保留。声明不会假定每个 ArtPlayer 实例都有 Hls.js；请在应用的集成类型中描述 `art.hls`。
|
||||
|
||||
## 验证范围
|
||||
|
||||
重构使用本地媒体和真实 worker 验证 Hls.js 1.5.17 / 1.7.2；这两个版本是验证点，不是新定义的支持范围。Firefox 的分组播放崩溃和另一项切组停滞仍在排查。Windows Playwright WebKit 缺少测试所需的 MSE 路径，不能代表 Safari/iOS 原生 HLS 已验收。采用尚未发布的重构前，应验证实际媒体与目标设备。
|
||||
@@ -50,5 +50,5 @@
|
||||
}
|
||||
|
||||
// <stdin>
|
||||
installNavigation(window, ["advanced/built-in.html", "advanced/built-in", "advanced/class.html", "advanced/class", "advanced/event.html", "advanced/event", "advanced/global.html", "advanced/global", "advanced/plugin.html", "advanced/plugin", "advanced/property.html", "advanced/property", "component/contextmenu.html", "component/contextmenu", "component/controls.html", "component/controls", "component/layers.html", "component/layers", "component/setting.html", "component/setting", "", "index.html", "plugin/danmuku.html", "plugin/danmuku", "start/i18n.html", "start/i18n", "start/option.html", "start/option"]);
|
||||
installNavigation(window, ["advanced/built-in.html", "advanced/built-in", "advanced/class.html", "advanced/class", "advanced/event.html", "advanced/event", "advanced/global.html", "advanced/global", "advanced/plugin.html", "advanced/plugin", "advanced/property.html", "advanced/property", "component/contextmenu.html", "component/contextmenu", "component/controls.html", "component/controls", "component/layers.html", "component/layers", "component/setting.html", "component/setting", "", "index.html", "plugin/danmuku.html", "plugin/danmuku", "plugin/hls-control.html", "plugin/hls-control", "start/i18n.html", "start/i18n", "start/option.html", "start/option"]);
|
||||
})();
|
||||
Reference in new issue
Block a user