Video Annotation Editor — User Guide

Getting Started

The Video Annotation Editor is a free online tool that lets you overlay interactive annotation nodes on video, enabling branching narratives, quizzes, information displays, voting, and other interactive experiences. Exported ZWMAP JSON works directly with ZWPlayer.

Quick Start Steps

1. Load a video

   Drag and drop a local video file (MP4, WebM) onto the window, or paste a remote video URL into the address bar and press Enter.

2. Add nodes

   Draw a hotspot by dragging on the canvas, or press N to create a default node. You can also drag preset templates from the component library. to create a default node. You can also drag preset templates from the component library.

3. Configure properties and actions

   Select a node and adjust its position, time range, style, and interactive actions in the properties panel. Supports chained action sequences.

4. Preview and export

   Press P to enter preview mode and test interactions. When ready, export the ZWMAP JSON or copy the ZWPlayer config directly. to enter preview mode and test interactions. When ready, export the ZWMAP JSON or copy the ZWPlayer config directly.

Node Types

The Annotation Editor supports 13 node types in 4 categories:

Basic Nodes

Interactive Nodes

Advanced Nodes

System Nodes

Keyboard Shortcuts

Speed up your workflow with these keyboard shortcuts:

Actions & Triggers

Each node can be configured with one or more actions that fire sequentially when the user interacts with it.

Action Types

Trigger Types

• Click — fires when user clicks the node
• Long Press — fires when user holds down on the node
• Slide — fires when user slides on the node
• Drag — fires when user drags the node
• Passivity — fires automatically via other actions or events
• Gesture — fires when a specific gesture (e.g., pinch) is recognized

Animation System

Each node supports three animation phases: enter, emphasis, and exit. Multiple preset effects and custom duration are available.

Enter Animations

Emphasis Animations

Exit Animations

Animation Duration

Duration of the animation in milliseconds (ms). Default: 300ms. Range: 100–3000ms.

ZWMAP Annotation Protocol Specification

The ZWMAP (Z&W Media Annotation Protocol) annotation type defines a standard JSON format for describing interactive video annotations. This protocol enables interoperability between annotation editing tools and video players.

Protocol Header

Every ZWMAP annotation document begins with a protocol identifier:

{
  "zwp_protocol": "ZWMAP/1.0",
  "zwp_type": "annotation",
  "zwp_version": "1.0"
}

Node Object Fields

Complete Example

This example shows a simple ZWMAP document with a text annotation and a button:

{
  "zwp_protocol": "ZWMAP/1.0",
  "zwp_type": "annotation",
  "zwp_version": "1.0",
  "nodes": [
    {
      "id": "a1b2c3d4",
      "type": "text",
      "name": "Title Card",
      "time_range": { "start": 0, "end": 5 },
      "position": { "x": 10, "y": 10, "w": 80, "h": 15 },
      "style": { "opacity": 1 },
      "content": {
        "text": "Welcome to the interactive video!",
        "color": "#ffffff",
        "fontSize": 24
      },
      "animation": {
        "enter": { "type": "fadein", "duration": 300 },
        "exit": { "type": "fadeout", "duration": 300 }
      }
    },
    {
      "id": "e5f6g7h8",
      "type": "button",
      "name": "Skip Intro",
      "time_range": { "start": 2, "end": 8 },
      "position": { "x": 70, "y": 80, "w": 25, "h": 10 },
      "events": [
        {
          "trigger": "click",
          "actions": [
            { "type": "SEEK_TIME", "time": 10 },
            { "type": "PAUSE_MEDIA" }
          ]
        }
      ]
    }
  ]
}

ZWPlayer Integration

ZWPlayer is a full-featured JavaScript video player that supports interactive video annotations out of the box. Here's how to integrate the generated annotation config with ZWPlayer.

Player Configuration

Add the annotations property to your ZWPlayer initialization config:

var player = new ZWPlayer({
  playerElm: 'mse',
  url: 'https://cdn.example.com/video.mp4',
  annotations: {
    "zwp_protocol": "ZWMAP/1.0",
    "zwp_type": "annotation",
    "nodes": [
      {
        "id": "a1b2c3d4",
        "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": "PAUSE_MEDIA" }
            ]
          }
        ]
      }
    ]
  }
});

Copy Config from Tool

In the tool's JSON panel, click the copy button to get a ready-to-use ZWPlayer configuration snippet.

Live Preview

Press P or click the Preview button to open a full ZWPlayer instance with your annotation config. Click annotations to test interactions. Press Esc to exit.

Using ZWMAP JSON

Store the exported ZWMAP JSON on a server. Your application can fetch it and pass the parsed nodes array directly to ZWPlayer's annotations config property.

Using a JSON URL

Instead of passing an object, you can pass the ZWMAP JSON file URL directly as a string. ZWPlayer will fetch and parse it automatically:

var player = new ZWPlayer({
  playerElm: 'mse',
  url: 'https://cdn.example.com/video.mp4',
  annotations: 'https://cdn.example.com/annotations/movie_annotation.json'
});

Drag & Drop Loading

You can also load annotations by dragging files directly onto the ZWPlayer instance:

• Annotation JSON only: Drop a *_annotation.json file onto the player to load annotations for the currently playing video.
• Video + Annotation together: Drag a video file along with its annotation JSON — the player will auto-match them by filename (e.g., movie.mp4 matches movie_annotation.json).
• Playlist drag: Drop multiple videos with their annotation files to create a playlist with interactive annotations for each item.

Frequently Asked Questions