`zwplayer` 音轨（配音）使用说明

1. 概述

音轨（配音）功能允许为视频挂载多个外挂音频文件（如不同语言的配音），用户可在播放时一键切换播放哪个音轨。典型场景：原声为日语的动画，额外挂载中文配音、英语配音，用户按需切换。

zwplayer 的音轨功能与字幕功能共用同一个 CC 入口：当同时配置了字幕与配音时，配音面板会出现在字幕面板的左侧，两者并排展示。

三种形态

配置情况	CC 菜单表现
仅有字幕	仅显示字幕面板（现有行为不变）
字幕 + 配音	配音面板在左、字幕面板在右，并排显示
仅有配音	仅显示配音面板（字幕面板不渲染）

2. 配音面板

点击控制条上的 CC 按钮，若已配置配音，配音面板会出现在菜单左侧。面板顶部显示「音轨」标题，下方列出所有可选音轨，当前选中的音轨以高亮 + ✓ 标记：

原声：视频自带的原始音轨（固定首项，id=0）。
各语言配音：通过 audioTracks 配置的外挂音频文件。

点击任一项即可切换播放该音轨。切换到配音时，原声音频会被静音，完全替换为所选配音。

3. 配置音轨

3.1 通过初始化配置

audioTracks 与 url、subtitles、chapters 同级，直接在 new ZWPlayer 的配置对象中传入：

new ZWPlayer({
  playerElm: '#mse',
  url: 'video.mp4',
  subtitles: [{ url: 'subtitle_zh.srt', title: '中文字幕' }],
  audioTracks: [
    { url: 'https://example.com/dub_ja.m4a', language: 'ja', label: '日语配音', default: true },
    { url: 'https://example.com/dub_zh.m4a', language: 'zh', label: '中文配音' }
  ]
});

字段说明

字段	类型	必填	说明
`url`	string	是	外挂音频文件 URL。支持 mp3 / m4a / aac / ogg / wav 等浏览器原生支持的格式。
`language`	string	否	语言代码（如 `ja`、`zh`、`en`）。用于显示本地化语言名，缺省时尝试从文件名探测。
`label`	string	否	显示名称（如「日语配音」）。优先级高于 `language` 推导。
`default`	boolean	否	是否为默认音轨。`true` 时播放器加载后自动切换到该音轨。

audioTracks 也支持单个对象或纯 URL 字符串数组的简写形式：

// 单个对象
audioTracks: { url: 'dub.m4a', language: 'ja', label: '日语配音' }

// 纯 URL 数组（语言从文件名探测）
audioTracks: ['dub_ja.m4a', 'dub_zh.m4a']

3.2 通过 API 动态添加

与字幕一致，音轨的切换与选择由 CC 菜单界面统一处理，API 仅提供添加与清理：

// 添加一条配音，返回新音轨 id
var trackId = zwplayer.addAudioTrack('https://example.com/dub_en.m4a', 'en', 'English Dub');

// 清空所有配音，回到原声
zwplayer.clearAudioTracks();

4. 同步与音量

音轨切换后，外挂音频会与视频严格同步：

进度同步：拖动进度条、跳转时，配音自动对齐到视频当前时间。
倍速同步：调整播放倍速时，配音跟随变化。
音量/静音：配音与原声共享全局音量与静音控制。切换配音时，原声静音、配音接管，全局音量条和静音按钮作用于当前激活的音轨。

5. 注意事项

音频格式：外挂音频须为浏览器原生支持的格式（mp3/m4a/aac/ogg/wav）。建议使用 m4a 或 mp3 以获得最佳兼容性。
CORS：跨域的配音文件需服务端配置 CORS 头（Access-Control-Allow-Origin），否则在部分浏览器中无法播放。同源文件无此限制。
音视频时长：配音文件时长应与视频一致。若配音较短，视频继续播放时配音结束后无声；若配音较长，视频结束后配音停止。
原声始终可用：视频自带的原始音轨（原声）始终保留在列表首项，不可通过 clearAudioTracks() 移除。

zwplayer 音轨（配音）使用说明