ZWPlayer Playlist Feature Guide

1. Overview

ZWPlayer includes a built-in playlist feature that supports sequential playback of multiple videos. Users can load online playlists via the ZWMAP protocol or generate playlists automatically by dragging and dropping local files. The playlist panel provides search, favorites, and history management, making it ideal for course series, episodic content, training videos, and other continuous viewing scenarios.

2. Loading Playlists

2.1 Loading via ZWMAP Protocol

Playlists use the ZWMAP protocol format (zwp_type: "playlist") and support single-level or multi-level group structures. Simply pass the playlist JSON URL via the url parameter:

new ZWPlayer({
    playerElm: 'mse',
    url: 'https://example.com/playlist.json'
});

The player automatically detects the ZWMAP protocol header in the JSON and loads it in playlist mode.

Single-level (single group): When the playlist contains only one group, the panel switches to a single-column layout displaying all video items directly.

Two-level (multiple groups): When the playlist contains multiple groups, the panel displays a two-column layout — groups on the left, video items of the selected group on the right. Click a group to switch.

2.2 Local File Drag & Drop

With localPlayback enabled, users can drag video files directly onto the player:

• Multiple video files: Automatically creates a local playlist, sorted by filename
• Single video file: Appends to an existing playlist or creates a new one
• Playlist file: Supports .json format, replaces the current playlist directly
• Auto-matching associated files: Subtitles (.srt/.vtt/.bcc), chapters (.json), annotations and other files with matching names are automatically linked

2.3 Autoplay & Continuous Playback

When the player is configured with autoplay: true:

• After loading an online playlist, the first video plays automatically
• After dragging local files, playback starts automatically if nothing is currently playing
• When the current video ends, the next video in the playlist plays automatically

The player provides four play modes, switchable via the play mode button in the playlist panel header:

• Continuous (default): Automatically plays the next video when the current one ends; stops at the end of the list
• Loop All: Automatically plays the next video; when the last item ends, wraps back to the first item
• Repeat One: The current video repeats indefinitely, does not advance to the next item
• Play Once: Stops after the current video ends, does not auto-play the next item

Additionally, the loop toggle on the player control bar is equivalent to “Repeat One” mode — when enabled, the current video repeats and does not advance.

3. Playlist Panel Features

3.1 Search

A search box at the top of the panel enables real-time keyword search:

• Searches across video names in all groups
• Automatically switches to single-column mode during search, showing results across all groups
• Matched text is highlighted
• Clear the search keyword to restore the original grouped view

3.2 Favorites

• Click the star icon next to a video item to add or remove it from favorites
• Click the favorites button in the panel header to filter and display only favorited videos
• Favorite data is stored locally in the browser and persists across page refreshes

3.3 History

• Click the clock button in the panel header to view recently played videos
• Stores up to 100 history entries, sorted by most recent playback time
• One-click clear all history

3.4 Other Operations

• Refresh playlist: Online playlists can be refreshed to reload from the source URL
• Clear playlist: Locally created playlists support one-click clearing
• Remove individual items: Each video item in a local playlist has a delete button for individual removal
• Playback progress: Each video item displays a progress bar; completed items show a completion mark
• Resume playback: When reopening a video, playback automatically resumes from the last watched position

4. Control Bar Navigation

When a playlist is loaded, previous/next buttons appear automatically in the player control bar:

• Click Next to play the next video in the playlist
• Click Previous to play the previous video in the playlist
• In favorites mode, previous/next buttons cycle only through favorited videos

5. Keyboard Shortcuts

6. Related Configuration

For the complete field definitions of playlist JSON, refer to the ZWMAP Playlist Specification.