ZWMAP Audio Track Type Specification

1. Overview

The audio track type describes a collection of external dubbing tracks for a video. Unlike the subtitle type (which carries text content), the audio content of dubbing is a binary file (mp3/m4a, etc.), so this type is a metadata manifest: a JSON file describing the URLs and attributes of multiple dubbing tracks. The player reads it and mounts all tracks as external audio tracks.

Use cases:

A video has dubbing in multiple languages (Japanese, Chinese, English, etc.), described in a single JSON file
Dubbing is generated by a TTS service, which produces a manifest for the player to load in batch
In playlist scenarios, multiple videos share the same dubbing manifest

2. ZWMAP Header

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

zwp_protocol and zwp_type are required. The player identifies the file as a dubbing manifest by zwp_type: "audiotrack".

3. Data Structure

3.1 Root-level Fields

Field	Type	Required	Default	Description
`zwp_protocol`	string	yes	—	Protocol identifier, fixed `"ZWMAP/1.0"`
`zwp_type`	string	yes	—	Fixed `"audiotrack"`
`zwp_version`	string	no	`"1.0"`	Data format version
`audioTracks`	array	yes	—	Array of audio track entries

3.2 Audio Track Entry

Field	Type	Required	Default	Description
`url`	string	yes	—	Audio file URL (mp3/m4a/aac/ogg/wav/flac/opus)
`language`	string	no	auto-detected	Language code (e.g. `ja`/`zh`/`en`), for localized language name display; auto-detected from the URL filename if omitted
`label`	string	no	language name	Display name (e.g. “Japanese dubbing”), takes priority over `language`
`default`	boolean	no	`false`	Whether this is the default track. When `true`, the player automatically switches to it after loading
`isAI`	boolean	no	`false`	Whether AI-synthesized (TTS output). When `true`, an AI badge is shown in the track panel and download is supported

4. Full Example

{
  "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": "Japanese dubbing",
      "default": true
    },
    {
      "url": "https://cdn.example.com/dub/movie_zh.m4a",
      "language": "zh",
      "label": "Chinese dubbing"
    },
    {
      "url": "https://cdn.example.com/dub/movie_en.m4a",
      "language": "en",
      "label": "English dubbing"
    },
    {
      "url": "https://cdn.example.com/dub/movie_ai_zh.m4a",
      "language": "zh",
      "label": "AI Chinese dubbing",
      "isAI": true
    }
  ]
}

5. Loading Methods

audioTracks is at the same level as url, subtitles, and chapters, passed directly in the new ZWPlayer config object:

5.1 Via a manifest URL

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

When the player detects that audioTracks is a .json URL, it automatically fetches and parses it as a ZWMAP audiotrack manifest.

5.2 Via an inline manifest object

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 Mixed format

The audioTracks array can mix manifest URLs, inline manifest objects, and individual track entries — the player processes each accordingly:

new ZWPlayer({
  playerElm: '#mse',
  url: 'video.mp4',
  audioTracks: [
    'https://cdn.example.com/manifest.json',       // manifest URL → expanded to multiple
    { zwp_type: 'audiotrack', audioTracks: [...] }, // inline manifest → expanded to multiple
    { url: 'https://cdn.example.com/dub.mp3', language: 'ko' } // individual track
  ]
});

6. Relationship with Other Forms

Dubbing audio tracks can be configured in ZWPlayer in multiple ways for different scenarios:

Method	Use case	Description
ZWMAP audiotrack manifest (this spec)	Standalone distribution, TTS output	A JSON describing multiple tracks; can exist independently of the video
`new ZWPlayer` config `audioTracks` field	Initialization config	At the same level as `url`/`subtitles`/`chapters`; pass a track array or manifest URL directly in the config
Playlist VideoItem `audioTracks`	Playlists	Each video item carries its own dubbing; see Playlist Specification
Drag & drop `_audiotrack` suffix	Local playback	Audio files with the `_audiotrack` suffix are auto-recognized as dubbing; see Local Playback

7. Constraints

The audioTracks array must not be empty
Each entry’s url is required and must point to a valid audio file
At most one entry has default: true; if multiple, the last one takes effect
Audio files must be in a browser-native format (mp3/m4a/aac/ogg/wav/flac/opus)
Cross-origin audio files require the server to configure CORS headers (Access-Control-Allow-Origin)
language should use ISO 639-1 two-letter codes (e.g. ja/zh/en) for localized language name display