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 (Z&W Media Annotation 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" } }
  ]
}

Supported Trigger Types:

Supported Action Types:

3.5 Animation System

Each node supports animations in three stages:

All animations support custom durations (100–3000ms).

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 annotation/index.html 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: The online annotation tool can be accessed at annotation/index.html to visually create and edit annotations.
6. Singular/Plural Compatibility: Configuration parameters support both annotations and annotation (singular); the player normalizes them internally.