`zwplayer` Audio Track (Dubbing) Usage Guide

1. Overview

The Audio Track (Dubbing) feature allows multiple external audio files (such as dubbing in different languages) to be mounted for a video. Users can switch the playing audio track with a single click during playback. Typical scenario: An animation with the original audio in Japanese, with an additional Chinese dub and English dub mounted, allowing users to switch as needed.

zwplayer’s audio track feature shares the same CC entry as the subtitle feature: When both subtitles and dubbing are configured, the dubbing panel will appear to the left of the subtitle panel, with both displayed side-by-side.

Three States

Configuration	CC Menu Behavior
Subtitles Only	Only the subtitle panel is displayed (existing behavior unchanged)
Subtitles + Dubbing	Dubbing panel on the left, subtitle panel on the right, displayed side-by-side
Dubbing Only	Only the dubbing panel is displayed (subtitle panel is not rendered)

2. Dubbing Panel

Click the CC button on the control bar. If dubbing is configured, the dubbing panel will appear on the left side of the menu. The top of the panel displays the “Audio Track” title, and below it lists all available audio tracks. The currently selected track is highlighted and marked with a ✓:

Original Sound: The original audio track included in the video (fixed first item, id=0).
Language Dubbing: External audio files configured via audioTracks.

Click any item to switch playback to that audio track. When switching to dubbing, the original audio is muted and completely replaced by the selected dubbing.

3. Configuring Audio Tracks

3.1 Via Initialization Configuration

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

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

Field Description

Field	Type	Required	Description
`url`	string	Yes	URL of the external audio file. Supports formats natively supported by browsers such as mp3 / m4a / aac / ogg / wav.
`language`	string	No	Language code (e.g., `ja`, `zh`, `en`). Used to display localized language names; if missing, attempts to detect from filename.
`label`	string	No	Display name (e.g., “Japanese Dub”). Has higher priority than `language` derivation.
`default`	boolean	No	Whether it is the default audio track. When `true`, the player automatically switches to this track after loading.

audioTracks also supports shorthand forms for a single object or an array of pure URL strings:

// Single object
audioTracks: { url: 'dub.m4a', language: 'ja', label: '日语配音' }

// Pure URL array (language detected from filename)
audioTracks: ['dub_ja.m4a', 'dub_zh.m4a']

3.2 Adding Dynamically via API

// Add a dubbing track, returns the new track id
var trackId = zwplayer.addAudioTrack('https://example.com/dub_en.m4a', 'en', 'English Dub');

// Switch to this dubbing
zwplayer.setAudioTrack(trackId);

// Switch back to original sound
zwplayer.setAudioTrack(0);

// Remove a dubbing track (id≠0)
zwplayer.removeAudioTrack(trackId);

// Get the list of all audio tracks
var list = zwplayer.getAudioTrackList();

// Clear all dubbing, return to original sound
zwplayer.clearAudioTracks();

4. Synchronization and Volume

After switching audio tracks, the external audio is strictly synchronized with the video:

Progress Sync: When dragging the progress bar or seeking, the dubbing automatically aligns to the current video time.
Speed Sync: When adjusting playback speed, the dubbing follows the change.
Volume/Mute: Dubbing shares the global volume and mute controls with the original audio. When switching dubbing, the original audio is muted and the dubbing takes over; the global volume bar and mute button act on the currently active track.

5. Event Callbacks

Listen for audio track switching via the onAudioTrackChange callback:

var zwplayer = new ZWPlayer({
  playerElm: '#mse',
  url: 'video.mp4',
  audioTracks: [{ url: 'dub_ja.m4a', language: 'ja', label: '日语配音' }],
  onAudioTrackChange: function(newTrack, oldTrack) {
    console.log('Audio track switch:', oldTrack.label, '→', newTrack.label);
  }
});

The callback parameters are audio track objects: { id, url, language, label, isOriginal }.

6. Notes

Audio Format: External audio must be in a format natively supported by the browser (mp3/m4a/aac/ogg/wav). It is recommended to use m4a or mp3 for best compatibility.
CORS: Cross-origin dubbing files require the server to configure CORS headers (Access-Control-Allow-Origin), otherwise they may not play in some browsers. Same-origin files do not have this restriction.
Audio/Video Duration: The duration of the dubbing file should be consistent with the video. If the dubbing is shorter, there will be silence after the dubbing ends while the video continues; if the dubbing is longer, the dubbing stops when the video ends.
Original Sound Item Cannot Be Removed: removeAudioTrack(0) is invalid; the original sound (the video’s built-in audio track) is always available.

zwplayer Audio Track (Dubbing) Usage Guide