ZWPlayer Interactive Annotation User Guide

1. Feature Overview

ZWPlayer supports adding interactive Annotation features to videos. This allows overlaying interactive nodes on the video screen to enable rich interactive experiences such as click-to-jump, branch selection, quizzes, polls, form collection, etc. It is widely used in scenarios like interactive education, branching storylines, product showcases, and online training.

The interactive annotation feature supports 13 node types, divided into four categories:

After successfully loading annotation data:

1. Video Overlay: Interactive nodes are displayed on the video screen; users can click or long-press to trigger actions.
2. Progress Bar Markers: The player’s progress bar displays the time ranges of the annotation nodes.
3. Annotation Button: If the annotations parameter is set during initialization, an annotation edit button will appear on the control bar. Clicking it opens the online annotation editor.

2. Configuring Annotation Information

2.1 Configuration via Constructor

Pass annotation data via the annotations parameter when creating a ZWPlayer instance:

var player = new ZWPlayer({
    url: 'http://example.com/vod/movie.mp4',
    playerElm: '#mse',
    // Pass annotation JSON URL
    annotations: 'http://example.com/annotations/movie_annotation.json'
});

The singular property name annotation is also supported; the player normalizes it internally.

2.2 Dynamic Loading via Methods

Use the loadAnnotations method to load annotation data dynamically at runtime:

// Load remote JSON file
player.loadAnnotations('http://example.com/annotations/movie_annotation.json');

// Load ZWMAP JSON object
player.loadAnnotations({
    "zwp_protocol": "ZWMAP/1.0",
    "zwp_type": "annotation",
    "nodes": [ /* ... */ ]
});

// Unload annotations
player.unloadAnnotations();

2.3 Configuration via URL Object

Configure both video and annotations within the JS object of the url parameter:

var player = new ZWPlayer({
    playerElm: '#mse',
    url: {
        src: 'http://example.com/vod/movie.mp4',
        annotations: 'http://example.com/annotations/movie_annotation.json',
        chapters: 'http://example.com/chapters/movie_chapter.json',
        subtitles: 'http://example.com/subtitles/movie.vtt'
    }
});

2.4 Loading via Drag-and-Drop

Drag and drop the annotation JSON file directly onto the player to load it. The following drag-and-drop methods are supported:

• Drag annotation JSON only: Drag a *_annotation.json file into the player to load annotations for the currently playing video.
• Drag video and annotations simultaneously: Drag the video file and its corresponding annotation JSON file together; the player automatically matches them by filename (e.g., movie.mp4 matches movie_annotation.json).
• Playlist drag-and-drop: Drag multiple videos and their corresponding annotation files to automatically create a playlist with interactive annotations.

3. Annotation Data Format

3.1 ZWMAP JSON Format

Interactive annotations use the ZWMAP (ZWPlayer Media Application Protocol) standard JSON format. Export files are named {VideoTitle}_annotation.json.

{
  "zwp_protocol": "ZWMAP/1.0",
  "zwp_type": "annotation",
  "zwp_version": "1.0",
  "nodes": [
    {
      "id": "btn001",
      "type": "button",
      "name": "Learn More",
      "time_range": { "start": 10, "end": 30 },
      "position": { "x": 60, "y": 70, "w": 25, "h": 8 },
      "style": {
        "border_radius": 4,
        "opacity": 90,
        "background": "#1890ff"
      },
      "events": [
        {
          "trigger": "click",
          "actions": [
            { "type": "SEEK_TIME", "target": 120 }
          ]
        }
      ]
    },
    {
      "id": "quiz001",
      "type": "quiz",
      "name": "Knowledge Quiz",
      "time_range": { "start": 60, "end": 90 },
      "position": { "x": 20, "y": 20, "w": 60, "h": 60 },
      "content": {
        "question": "Which of the following is correct?",
        "options": [
          { "text": "Option A", "correct": true },
          { "text": "Option B", "correct": false }
        ]
      },
      "events": [
        {
          "trigger": "click",
          "actions": [
            { "type": "PAUSE_MEDIA" }
          ]
        }
      ]
    }
  ]
}

3.2 Protocol Header Fields

3.3 Node Object Fields

3.4 Events and Action Chains

Each node can be configured with one or more events. Each event contains a trigger and an action chain:

{
  "trigger": "click",
  "actions": [
    { "type": "PAUSE_MEDIA" },
    { "type": "SEEK_TIME", "target": 120 },
    { "type": "EMIT_MESSAGE", "data": { "key": "value" } }
  ]
}

Tip: A single trigger can be bound to multiple actions that execute sequentially. For example, clicking a button could first pause the video, then show an info card, and finally jump to a specific time point.

Supported Trigger Types:

Supported Action Types:

Actions are organized into five functional categories:

Media Control

Page Navigation

Interaction Control

Developer Interface

Data Communication

For visual guidance on configuring events, see the interaction settings section in the Online Annotation Tool Help.

3.5 Animation System

Each node supports animations in three phases: Enter (when appearing), Emphasis (while visible), and Exit (when disappearing). All animations support custom durations (100–3000ms), defaulting to 500ms.

Enter Animations

Animations played when the node appears. 7 effects available:

Emphasis Animations

Looping animations played while the node is visible, used to attract user attention. 5 effects available:

Exit Animations

Animations played when the node disappears. 6 effects available:

4. Automatic Recognition Rules

zwplayer automatically identifies the annotation format based on the parameter content:

• String URL: Automatically downloaded and parsed as a remote JSON file.
• Object containing zwp_type: "annotation": Parsed as ZWMAP protocol format, extracting the nodes array.
• Object containing nodes array: Used directly as the node array.
• Dragged File: Filename matching *_annotation.json pattern; automatically parsed as ZWMAP format.

5. Online Annotation Editor

ZWPlayer provides an online annotation editor, which can be accessed via:

1. Clicking the annotation edit button on the player control bar (requires configuring the annotations parameter).
2. Directly accessing the Online Annotation Editor to open the standalone editor.

Editor features include:

• Visual Canvas Drawing: Drag to draw node areas directly on the video screen.
• Property Panel: Configure node position, time range, style, content, and interaction actions.
• Timeline Editing: Visually manage node time ranges on the timeline.
• Real-time Preview: Press P to enter preview mode and test interactive effects in the actual player.
• JSON Import/Export: Support for importing and exporting standard ZWMAP JSON files.
• Keyboard Shortcuts: Press N to quickly create a node, Delete to remove, Ctrl+Z to undo.

6. Usage Examples

Example 1: Load Remote Annotation File

var player = new ZWPlayer({
    url: 'http://example.com/vod/movie.mp4',
    playerElm: '#mse',
    annotations: 'http://example.com/annotations/movie_annotation.json'
});

Example 2: Pass ZWMAP Object Directly

var player = new ZWPlayer({
    url: 'http://example.com/vod/movie.mp4',
    playerElm: '#mse',
    annotations: {
        "zwp_protocol": "ZWMAP/1.0",
        "zwp_type": "annotation",
        "nodes": [
            {
                "id": "node1",
                "type": "button",
                "name": "Click Me",
                "time_range": { "start": 5, "end": 15 },
                "position": { "x": 40, "y": 40, "w": 20, "h": 10 },
                "events": [
                    {
                        "trigger": "click",
                        "actions": [
                            { "type": "SEEK_TIME", "target": 30 }
                        ]
                    }
                ]
            }
        ]
    }
});

Example 3: Runtime Dynamic Loading and Unloading

// Initialize player
var player = new ZWPlayer({
    url: 'http://example.com/vod/movie.mp4',
    playerElm: '#mse'
});

// Load annotations when video starts playing
player.onmediaevent = function(event) {
    if (event.type === 'play') {
        player.loadAnnotations('http://example.com/annotations/movie_annotation.json');
    }
};

// Unload old annotations when switching video
function switchVideo(newUrl) {
    player.unloadAnnotations();
    player.setVideoUrl(newUrl);
}

Example 4: Using Annotations in a Playlist

{
  "zwp_protocol": "ZWMAP/1.0",
  "zwp_type": "playlist",
  "groups": [
    {
      "name": "Interactive Course",
      "items": [
        {
          "name": "Lesson 1",
          "url": "https://cdn.example.com/lesson1.mp4",
          "annotation": "https://cdn.example.com/annotations/lesson1_annotation.json"
        },
        {
          "name": "Lesson 2",
          "url": "https://cdn.example.com/lesson2.mp4",
          "annotation": "https://cdn.example.com/annotations/lesson2_annotation.json"
        }
      ]
    }
  ]
}

7. Notes

1. Required Protocol Headers: The annotation JSON must include zwp_protocol: "ZWMAP/1.0" and zwp_type: "annotation", otherwise it will be rejected.
2. Time Range: start and end in time_range are in seconds; end must be greater than start.
3. Position Coordinates: x, y, w, and h in position are percentage values (0–100) relative to the video screen.
4. Performance: It is recommended not to exceed 20 nodes displayed simultaneously within the same time period to ensure smooth playback.
5. Editor: Use the Online Annotation Editor to visually create and edit annotations.
6. Singular/Plural Compatibility: Configuration parameters support both annotations and annotation (singular); the player normalizes them internally.