mirror of
https://github.com/zhw2590582/ArtPlayer.git
synced 2026-10-19 03:11:20 -08:00
docs(audio): [SITE-AUDIO-01] add bilingual track guides and browser coverage
This commit is contained in:
Harvey Zhao committed
1 parent
6af43208af
commit
d3349e83f2
67 files changed
+6011
-1647
No files matched your search
@@ -65,6 +65,13 @@ source failure recovery, and old/native pause/end plus corrected candidate clean
|
||||
See refactor/audio-validation.md for failed baseline probes, Windows WebKit WAV/size limits,
|
||||
physical-device gaps and the remaining 05/06 combination/distribution gates.
|
||||
|
||||
The bilingual VitePress audio-track guides explain the actual deferred update,
|
||||
strict drift threshold, URL truthiness and shared mute behavior. Keep their Run Code
|
||||
source identical to docs/assets/example/audio.track.js. document-audio.spec.js
|
||||
executes that source with local Range-served video/AAC, checking playback, pause,
|
||||
offset seek, rate/volume, source replacement with stable audio identity and terminal
|
||||
updates. This example coverage complements, rather than completes, 05/06 acceptance.
|
||||
|
||||
## Public type compatibility
|
||||
|
||||
The default and /legacy entries preserve the original Result.update(Option) signature,
|
||||
|
||||
@@ -6,6 +6,11 @@ audio-track plugin for ArtPlayer
|
||||
|
||||
[https://artplayer.org](https://artplayer.org/?libs=./uncompiled/artplayer-plugin-audio-track/index.js&example=audio.track)
|
||||
|
||||
The refactor branch includes complete [Chinese](../artplayer-vitepress/docs/plugin/audio-track.md)
|
||||
and [English](../artplayer-vitepress/docs/en/plugin/audio-track.md) guides. They cover
|
||||
time offsets, synchronous partial updates, shared mute/volume, source ownership
|
||||
and the legacy/runtime type split. Their runnable example matches the demo above.
|
||||
|
||||
## TypeScript
|
||||
|
||||
The default import and `/legacy` preserve existing TypeScript behavior, including the
|
||||
|
||||
@@ -13,17 +13,25 @@ not a VitePress page. Keep both URL surfaces compatible.
|
||||
| `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/plugin/dash-control.md`, `docs/en/plugin/dash-control.md` | DASH SDK generations, menus, lifecycle and types | `/document/plugin/dash-control.html`, `/document/en/plugin/dash-control.html` |
|
||||
| `docs/plugin/audio-track.md`, `docs/en/plugin/audio-track.md` | Separate audio synchronization, ownership and update types | `/document/plugin/audio-track.html`, `/document/en/plugin/audio-track.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 32 Markdown pages: 16 Chinese
|
||||
and 16 English. Danmuku, HLS and DASH have dedicated guides and navigation in both languages. Other plugins currently
|
||||
`docs/document/`. The current inventory contains 34 Markdown pages: 17 Chinese
|
||||
and 17 English. Danmuku, HLS, DASH and Audio Track 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.
|
||||
|
||||
Audio Track guide examples match the actual audio.track demo. The dedicated
|
||||
document-audio browser suite substitutes local Range-served media, then checks
|
||||
native video pixels and AAC playback, pause, offset seek, volume/rate, source
|
||||
updates and teardown with both core generations. The navigation suite separately
|
||||
checks both generated guide URLs and the Run Code destination. Tests do not
|
||||
measure physical audibility or replace the package's full device matrix.
|
||||
|
||||
Danmuku guides describe the refactor branch and explicitly distinguish unpublished
|
||||
`/runtime` declarations from current CDN releases. Preserve old Chinese heading
|
||||
anchors when editing. Rebuild site assets (the English route inventory), the
|
||||
|
||||
@@ -80,7 +80,7 @@ const config = {
|
||||
{ text: '视频章节', link: 'https://artplayer.org/?libs=./uncompiled/artplayer-plugin-chapter/index.js&example=chapter' },
|
||||
{ text: '视频背光', link: 'https://artplayer.org/?libs=./uncompiled/artplayer-plugin-ambilight/index.js&example=ambilight' },
|
||||
{ text: '文档画中画', link: 'https://artplayer.org/?libs=./uncompiled/artplayer-plugin-document-pip/index.js&example=document.pip' },
|
||||
{ text: '独立音轨', link: 'https://artplayer.org/?libs=./uncompiled/artplayer-plugin-audio-track/index.js&example=audio.track' },
|
||||
{ text: '独立音轨', link: '/plugin/audio-track' },
|
||||
],
|
||||
},
|
||||
{
|
||||
@@ -152,7 +152,7 @@ const config = {
|
||||
{ text: 'Video Chapters', link: 'https://artplayer.org/?libs=./uncompiled/artplayer-plugin-chapter/index.js&example=chapter' },
|
||||
{ text: 'Video Ambilight', link: 'https://artplayer.org/?libs=./uncompiled/artplayer-plugin-ambilight/index.js&example=ambilight' },
|
||||
{ text: 'Document PIP', link: 'https://artplayer.org/?libs=./uncompiled/artplayer-plugin-document-pip/index.js&example=document.pip' },
|
||||
{ text: 'Audio Track', link: 'https://artplayer.org/?libs=./uncompiled/artplayer-plugin-audio-track/index.js&example=audio.track' },
|
||||
{ text: 'Audio Track', link: '/en/plugin/audio-track' },
|
||||
],
|
||||
},
|
||||
{
|
||||
|
||||
@@ -0,0 +1,109 @@
|
||||
# Audio Track
|
||||
|
||||
[中文](../../plugin/audio-track.md)
|
||||
|
||||
Play a separate audio file in sync with a video. The plugin creates an `HTMLAudioElement` and follows the main video's playback, pause, position, volume and playback rate. It requires no additional SDK and does not add an audio-selection menu.
|
||||
|
||||
This page describes the current refactor branch. Its lifecycle fixes and precise `/runtime` types are not yet published; an unpinned npm or CDN installation does not select this branch.
|
||||
|
||||
## Installation
|
||||
|
||||
```sh
|
||||
yarn add artplayer artplayer-plugin-audio-track
|
||||
```
|
||||
|
||||
```js
|
||||
import Artplayer from 'artplayer';
|
||||
import artplayerPluginAudioTrack from 'artplayer-plugin-audio-track';
|
||||
```
|
||||
|
||||
For script tags, load ArtPlayer before the plugin's `dist/artplayer-plugin-audio-track.js`. The global is `artplayerPluginAudioTrack`. Pin dependency versions and supply an audio URL the browser can access and decode.
|
||||
|
||||
## Complete example
|
||||
|
||||
This is the same code as the [online audio example](https://artplayer.org/?libs=./uncompiled/artplayer-plugin-audio-track/index.js&example=audio.track). The demo site supplies the media files and `.artplayer-app` container; replace both when integrating it into your application.
|
||||
|
||||
<div className="run-code" data-libs="./uncompiled/artplayer-plugin-audio-track/index.js"></div>
|
||||
|
||||
```js
|
||||
// npm i artplayer-plugin-audio-track
|
||||
// import artplayerPluginAudioTrack from 'artplayer-plugin-audio-track';
|
||||
|
||||
var art = new Artplayer({
|
||||
container: '.artplayer-app',
|
||||
url: '/assets/sample/sprite-fight.mp4',
|
||||
plugins: [
|
||||
artplayerPluginAudioTrack({
|
||||
url: '/assets/sample/sprite-fight.aac',
|
||||
offset: 0,
|
||||
sync: 0.3,
|
||||
}),
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
## Options and synchronization
|
||||
|
||||
`artplayerPluginAudioTrack(option)` returns a plugin factory. The options object is required.
|
||||
|
||||
| Field | Type and default | Behavior |
|
||||
| --- | --- | --- |
|
||||
| `url` | Required `string` | Separate audio URL. An empty string at construction leaves the source unloaded. |
|
||||
| `offset` | `number`, default `0` | Target audio time is video time plus this value, in seconds. A positive offset reads further ahead in the audio file. |
|
||||
| `sync` | `number`, default `0.3` | Adjust audio time only when its absolute difference from the target is strictly greater than this threshold, in seconds. |
|
||||
|
||||
For example, video time 10 with offset 0.25 targets audio time 10.25. This corrects media-time drift; it is not a sample-accurate audio clock. Use finite, reasonable offsets and a nonnegative threshold. Negative targets or targets beyond the audio duration depend on browser media behavior; the plugin adds no delayed start, looping or silence padding.
|
||||
|
||||
Playback, completed seeking and playback recovery synchronize the track. Ordinary playing timeupdate events also correct drift. Buffering, source emptying, native pause, starting a seek and reaching the video's end pause the separate audio. It resumes when the main video is playing and ready to recover; canplay alone does not start audio for a paused video.
|
||||
|
||||
## Result and updates
|
||||
|
||||
After installation, access the result at `art.plugins.artplayerPluginAudioTrack`:
|
||||
|
||||
| Member | Behavior |
|
||||
| --- | --- |
|
||||
| `name` | Always `artplayerPluginAudioTrack`. |
|
||||
| `audio` | The actual `HTMLAudioElement`; source updates preserve its identity. |
|
||||
| `update(option)` | Synchronously updates selected fields and returns `undefined`, not a loading Promise. |
|
||||
|
||||
```js
|
||||
const track = art.plugins.artplayerPluginAudioTrack;
|
||||
track.update({ offset: 0.25, sync: 0.1 });
|
||||
track.update({ url: '/audio/another-language.m4a' });
|
||||
```
|
||||
|
||||
Changing offset or sync does not immediately force a seek; the next synchronization event uses the new values. Only a different, nonempty URL replaces the source. Reusing the same URL does not reload it, and an empty URL is not a stop or clear command. Replacing a source while the main video is playing attempts playback; observe the exposed audio element for actual loading, decoding and errors.
|
||||
|
||||
`art.switchUrl()` changes only the main video. Your application must keep video and audio sources paired and select the new audio with `track.update()`. Use native media events when you need to wait for readiness; `await track.update(...)` does not wait for loading.
|
||||
|
||||
## Volume, playback failure and destruction
|
||||
|
||||
The plugin does not remove the video's original sound. Use a video source without its own audio track if the separate track should provide the only sound. Player volume, mute and playback rate also apply to the separate audio. Setting `art.muted = true` mutes both; it cannot selectively mute only the main video.
|
||||
|
||||
Browser playback policies still apply. While the instance is active, a rejected `audio.play()` is reported through `console.warn`; it does not become a rejection from update. Successful main-video playback does not prove that the separate audio is audible. Applications can observe native playing/error events on the audio element.
|
||||
|
||||
Destroying ArtPlayer removes plugin subscriptions, pauses audio, removes its src attribute and releases media loading. A retained result still points to the same element, but later update calls no longer reload or play it. Your application remains responsible for listeners it adds to audio. There is no separate plugin destroy method to call.
|
||||
|
||||
## TypeScript
|
||||
|
||||
The root and `/legacy` entries preserve the old `Result.update(Option)` declaration, including its required URL, to retain parameter extraction and function-assignment behavior. Runtime updates already support partial options. Use `/runtime` for accurate partial-update types over the same implementation:
|
||||
|
||||
```ts
|
||||
import Artplayer from 'artplayer';
|
||||
import audioTrack from 'artplayer-plugin-audio-track/runtime';
|
||||
|
||||
const installTrack = audioTrack({ url: '/audio/dialogue.m4a' });
|
||||
const art = new Artplayer({
|
||||
container: '.artplayer-app',
|
||||
url: '/video/silent.mp4',
|
||||
plugins: [(player) => {
|
||||
const track = installTrack(player);
|
||||
track.update({ offset: 0.25 });
|
||||
return track;
|
||||
}],
|
||||
});
|
||||
```
|
||||
|
||||
Named types include `Option`, `UpdateOption`, the old `Result`, `RuntimeResult` and `RuntimeFactory`. The online editor's default global retains legacy inference too. To select precise update typing, explicitly use `artplayerPluginAudioTrack as artplayerPluginAudioTrack.RuntimeFactory`. This does not create a second plugin implementation.
|
||||
|
||||
Actual desktop tests cover audio/video playback, pause, seeking, updates and destruction. They do not establish support for every mobile device, proxy player, audio format or long-running synchronization combination. Check browser decoding capabilities and the project's validation records for the applicable scope.
|
||||
@@ -0,0 +1,109 @@
|
||||
# 独立音轨
|
||||
|
||||
[English](../en/plugin/audio-track.md)
|
||||
|
||||
为视频同步播放一个单独的音频文件。插件创建一个 `HTMLAudioElement`，跟随主视频的播放、暂停、进度、音量和播放速率，不需要额外 SDK，也不提供音轨选择菜单。
|
||||
|
||||
本页描述当前重构分支。生命周期修复和 `/runtime` 精确类型尚未发布；未固定版本的 npm/CDN 安装不能当作本分支代码。
|
||||
|
||||
## 安装
|
||||
|
||||
```sh
|
||||
yarn add artplayer artplayer-plugin-audio-track
|
||||
```
|
||||
|
||||
```js
|
||||
import Artplayer from 'artplayer';
|
||||
import artplayerPluginAudioTrack from 'artplayer-plugin-audio-track';
|
||||
```
|
||||
|
||||
通过 script 使用时，先加载 ArtPlayer，再加载插件的 `dist/artplayer-plugin-audio-track.js`，全局名称为 `artplayerPluginAudioTrack`。应用应固定依赖版本，并提供浏览器可解码和访问的音频地址。
|
||||
|
||||
## 完整示例
|
||||
|
||||
下面与[在线音轨示例](https://artplayer.org/?libs=./uncompiled/artplayer-plugin-audio-track/index.js&example=audio.track)使用同一份代码。站点提供示例媒体和 `.artplayer-app` 容器；接入自己的应用时替换这些地址和容器。
|
||||
|
||||
<div className="run-code" data-libs="./uncompiled/artplayer-plugin-audio-track/index.js"></div>
|
||||
|
||||
```js
|
||||
// npm i artplayer-plugin-audio-track
|
||||
// import artplayerPluginAudioTrack from 'artplayer-plugin-audio-track';
|
||||
|
||||
var art = new Artplayer({
|
||||
container: '.artplayer-app',
|
||||
url: '/assets/sample/sprite-fight.mp4',
|
||||
plugins: [
|
||||
artplayerPluginAudioTrack({
|
||||
url: '/assets/sample/sprite-fight.aac',
|
||||
offset: 0,
|
||||
sync: 0.3,
|
||||
}),
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
## 配置与同步
|
||||
|
||||
`artplayerPluginAudioTrack(option)` 返回插件工厂，`option` 必须提供。
|
||||
|
||||
| 字段 | 类型与默认值 | 行为 |
|
||||
| --- | --- | --- |
|
||||
| `url` | `string`，必填 | 独立音频文件地址。构造时的空字符串不加载音源。 |
|
||||
| `offset` | `number`，默认 `0` | 音频目标时间为视频时间加上此值，单位秒。正数读取音频中更靠后的内容。 |
|
||||
| `sync` | `number`，默认 `0.3` | 音频与目标时间的差值绝对值严格大于此值时，才调整音频时间。单位秒。 |
|
||||
|
||||
例如视频在10秒、offset为0.25时，目标音频时间是10.25秒。这是纠正媒体时间的阈值同步，不是逐采样的专业音频时钟。使用有限、合理的偏移和非负阈值；负目标时间或超过音频时长的目标依赖浏览器的媒体边界行为，插件没有另加延迟启动、循环或补静音功能。
|
||||
|
||||
播放、seek完成和恢复播放时会同步；正常播放期间也根据 timeupdate 校正漂移。等待缓冲、切源清空、原生暂停、seek开始和结束播放会暂停独立音频；主视频继续播放并达到可恢复状态后再恢复。视频暂停时不会仅因canplay事件自行播放音频。
|
||||
|
||||
## 返回值和更新
|
||||
|
||||
安装后通过 `art.plugins.artplayerPluginAudioTrack` 取得结果：
|
||||
|
||||
| 字段 | 行为 |
|
||||
| --- | --- |
|
||||
| `name` | 固定为 `artplayerPluginAudioTrack`。 |
|
||||
| `audio` | 实际的 `HTMLAudioElement`；更新音源时保持同一个元素。 |
|
||||
| `update(option)` | 同步更新部分字段，返回 `undefined`，不是加载完成的Promise。 |
|
||||
|
||||
```js
|
||||
const track = art.plugins.artplayerPluginAudioTrack;
|
||||
track.update({ offset: 0.25, sync: 0.1 });
|
||||
track.update({ url: '/audio/another-language.m4a' });
|
||||
```
|
||||
|
||||
offset/sync更新不会立即强制seek，下一次同步事件才使用新值。只有非空且不同的url会替换音源；相同url不会重新加载，空url也不是停止或清空命令。若主视频正在播放，替换音源会尝试播放；音频的实际加载、解码和错误可从暴露的元素监听。
|
||||
|
||||
调用 `art.switchUrl()` 只更换主视频，不会自动选择另一份音频；应用需要同时管理视频与音轨的对应关系，并用 `track.update()` 指定新音源。需要等待媒体可用时监听原生媒体事件，不要把 `await track.update(...)` 当作等待加载。
|
||||
|
||||
## 音量、播放失败与销毁
|
||||
|
||||
插件不会自动去掉主视频的原声。如果希望独立音轨是唯一声音，使用没有原声音轨的视频源。播放器的音量、静音和倍速会同步到独立音频；设置 `art.muted = true` 会一起静音，不能用它只关闭主视频声音。
|
||||
|
||||
独立音频的播放仍受浏览器策略约束。活动实例的 `audio.play()` 拒绝会通过 `console.warn` 报告，不会变成 `update()` 的Promise拒绝。主视频播放成功也不等于独立音频已经成功发声；应用可监听 `audio` 的 playing/error 等原生事件。
|
||||
|
||||
销毁ArtPlayer会移除插件订阅、暂停音频、移除src并释放媒体加载。保留的结果对象仍指向同一个audio，销毁后的update不再重新加载或播放。应用自己添加到audio上的监听器仍由应用负责移除；无需另外调用一个不存在的插件destroy方法。
|
||||
|
||||
## TypeScript
|
||||
|
||||
根入口与 `/legacy` 保留旧 `Result.update(Option)` 声明，包含必填url，避免改变旧代码的参数提取与函数赋值。运行时一直支持部分字段更新；需要准确的部分更新类型时，选择同一实现的 `/runtime`：
|
||||
|
||||
```ts
|
||||
import Artplayer from 'artplayer';
|
||||
import audioTrack from 'artplayer-plugin-audio-track/runtime';
|
||||
|
||||
const installTrack = audioTrack({ url: '/audio/dialogue.m4a' });
|
||||
const art = new Artplayer({
|
||||
container: '.artplayer-app',
|
||||
url: '/video/silent.mp4',
|
||||
plugins: [(player) => {
|
||||
const track = installTrack(player);
|
||||
track.update({ offset: 0.25 });
|
||||
return track;
|
||||
}],
|
||||
});
|
||||
```
|
||||
|
||||
命名类型包括 `Option`、`UpdateOption`、旧 `Result`、`RuntimeResult` 与 `RuntimeFactory`。在线编辑器的全局默认类型也保留旧推导；选择精确更新类型时，可显式使用 `artplayerPluginAudioTrack as artplayerPluginAudioTrack.RuntimeFactory`。这不会创建第二份插件实现。
|
||||
|
||||
真实桌面测试覆盖音频/视频播放、暂停、seek、更新和销毁；它们不证明所有移动设备、代理播放器、音频格式或长时间同步组合都通过。完整支持范围仍需结合对应浏览器的解码能力与项目验收记录。
|
||||
@@ -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", "plugin/dash-control.html", "plugin/dash-control", "plugin/hls-control.html", "plugin/hls-control", "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/audio-track.html", "plugin/audio-track", "plugin/danmuku.html", "plugin/danmuku", "plugin/dash-control.html", "plugin/dash-control", "plugin/hls-control.html", "plugin/hls-control", "start/i18n.html", "start/i18n", "start/option.html", "start/option"]);
|
||||
})();
|
||||
Reference in new issue
Block a user