mirror of
https://github.com/zhw2590582/ArtPlayer.git
synced 2026-10-14 00:06:17 -08:00
112 lines
6.2 KiB
Markdown
112 lines
6.2 KiB
Markdown
# 独立音轨
|
||
|
||
[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">▶ Run Code</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、更新和销毁；它们不证明所有移动设备、代理播放器、音频格式或长时间同步组合都通过。完整支持范围仍需结合对应浏览器的解码能力与项目验收记录。
|
||
|
||
Windows WebKit 的 MP4/AAC 耗尽缓冲仍有原生媒体验证缺口：该复现中视频停滞不可靠地触发 waiting。换源顺序检查通过不代表这一独立问题已关闭。
|