ZWMAP 配音音轨类型规范

1. 概述

配音音轨类型用于描述视频的外挂配音音轨集合。与字幕类型承载文本内容不同，配音的音频内容是二进制文件（mp3/m4a 等），因此本类型是一个元数据清单（manifest）：一个 JSON 文件描述多条配音音轨的 URL 和属性，播放器读取后批量挂载为外挂音轨。

适用场景：

一个视频有多个语言的配音（日语、中文、英语等），用一个 JSON 文件统一描述
配音由 TTS 服务生成，产出清单后交给播放器批量加载
播放列表场景下，多个视频共享同一份配音清单

2. ZWMAP 头部

{
  "zwp_protocol": "ZWMAP/1.0",
  "zwp_type": "audiotrack"
}

zwp_protocol 和 zwp_type 为必填字段。播放器通过 zwp_type: "audiotrack" 识别此文件为配音清单。

3. 数据结构

3.1 根级别字段

字段	类型	必填	默认值	说明
`zwp_protocol`	string	是	—	协议标识，固定 `"ZWMAP/1.0"`
`zwp_type`	string	是	—	固定 `"audiotrack"`
`zwp_version`	string	否	`"1.0"`	数据格式版本
`audioTracks`	array	是	—	配音条目数组

3.2 配音条目对象 (AudioTrack)

字段	类型	必填	默认值	说明
`url`	string	是	—	音频文件 URL（mp3/m4a/aac/ogg/wav/flac/opus）
`language`	string	否	自动探测	语言 code（如 `ja`/`zh`/`en`），用于显示本地化语言名；未提供时从 URL 文件名探测
`label`	string	否	语言名	显示名称（如「日语配音」），优先级高于 `language`
`default`	boolean	否	`false`	是否默认音轨。`true` 时播放器加载后自动切换到该音轨
`isAI`	boolean	否	`false`	是否 AI 合成（TTS 产物）。`true` 时音轨面板显示 AI 标志并支持下载

4. 完整示例

{
  "zwp_protocol": "ZWMAP/1.0",
  "zwp_type": "audiotrack",
  "zwp_version": "1.0",
  "audioTracks": [
    {
      "url": "https://cdn.example.com/dub/movie_ja.m4a",
      "language": "ja",
      "label": "日语配音",
      "default": true
    },
    {
      "url": "https://cdn.example.com/dub/movie_zh.m4a",
      "language": "zh",
      "label": "中文配音"
    },
    {
      "url": "https://cdn.example.com/dub/movie_en.m4a",
      "language": "en",
      "label": "英语配音"
    },
    {
      "url": "https://cdn.example.com/dub/movie_ai_zh.m4a",
      "language": "zh",
      "label": "AI 中文配音",
      "isAI": true
    }
  ]
}

5. 加载方式

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

5.1 通过清单 URL 加载

new ZWPlayer({
  playerElm: '#mse',
  url: 'https://example.com/video.mp4',
  audioTracks: 'https://cdn.example.com/dub/tracks.json'
});

播放器检测到 audioTracks 为 .json URL 时，自动拉取并解析为 ZWMAP audiotrack 清单。

5.2 通过内联清单对象加载

new ZWPlayer({
  playerElm: '#mse',
  url: 'https://example.com/video.mp4',
  audioTracks: {
    zwp_protocol: 'ZWMAP/1.0',
    zwp_type: 'audiotrack',
    audioTracks: [
      { url: 'https://cdn.example.com/dub_ja.m4a', language: 'ja', default: true },
      { url: 'https://cdn.example.com/dub_zh.m4a', language: 'zh' }
    ]
  }
});

5.3 混合格式

audioTracks 数组可混合清单 URL、内联清单对象和单个配音项，播放器会分别处理：

new ZWPlayer({
  playerElm: '#mse',
  url: 'video.mp4',
  audioTracks: [
    'https://cdn.example.com/manifest.json',      // 清单 URL → 展开为多条
    { zwp_type: 'audiotrack', audioTracks: [...] }, // 内联清单 → 展开为多条
    { url: 'https://cdn.example.com/dub.mp3', language: 'ko' } // 单个配音
  ]
});

6. 与其他形式的关系

配音音轨在 ZWPlayer 中有多种配置方式，适用于不同场景：

方式	适用场景	说明
ZWMAP audiotrack 清单（本规范）	独立分发、TTS 产出	一个 JSON 描述多条配音，可独立于视频存在
`new ZWPlayer` 配置的 `audioTracks` 字段	初始化配置	与 `url`/`subtitles`/`chapters` 平级，直接在配置中传入配音数组或清单 URL
播放列表 VideoItem 的 `audioTracks`	播放列表	每个视频项携带自己的配音，详见播放列表规范
拖拽 `_audiotrack` 后缀文件	本地播放	文件名带 `_audiotrack` 后缀的音频自动识别为配音，详见本地播放

7. 约束规则

audioTracks 数组不得为空
每个条目的 url 必填，指向有效的音频文件
default: true 的条目最多一个；多个时以最后一个为准
音频文件须为浏览器原生支持的格式（mp3/m4a/aac/ogg/wav/flac/opus）
跨域音频文件需服务端配置 CORS 头（Access-Control-Allow-Origin）
language 建议使用 ISO 639-1 双字母 code（如 ja/zh/en），播放器据此显示本地化语言名