ZWPlayer Watermark Setup Guide

1. Feature Overview

ZWPlayer supports overlaying custom watermarks on the video screen, providing the following features:

• Image Watermarks: Overlay logos, QR codes, and custom images
• Text Watermarks: Display custom text with font, color, and size configuration
• Dynamic Roaming Watermarks: Watermarks move across the screen for anti-screen-recording protection
• Tile Watermarks: Text fills the entire screen in a tilted grid pattern, creating a dense watermark matrix
• Template Variables: Support dynamic variables like {user_id}, {sys_time}, etc.
• Multi-watermark Overlay: Simultaneously overlay multiple watermark elements with independent position and opacity
• Playlist Association: Each video in a playlist can have its own watermark
• Drag & Drop Loading: Drag local _watermark.json files for automatic matching and loading

Watermark data uses the ZWMAP (ZWPlayer Media Application Protocol) format. Use the Online Watermark Editor to visually create and export watermark data.

2. Configuration Parameters

2.1 watermarks - Watermark Data (Property)

• Type: String | Array | Object

• Default Value: None

• Description: Pass watermark data through the constructor during player initialization. Supports the following input methods:

  • URL String: A watermark JSON file URL starting with http or https; the player automatically downloads and parses it
  • ZWMAP JSON Object: A protocol object containing zwp_type: "watermark"
  • Watermark Array: An already parsed watermark entries array (no ZWMAP header wrapper needed)

new ZWPlayer({
    playerElm: 'mse',
    url: 'https://cdn.example.com/video.mp4',
    watermarks: 'https://cdn.example.com/watermark/movie_watermark.json'
});

2.2 watermark - Alias Property

watermark (singular) is an alias for watermarks (plural). They are equivalent and the player normalizes them internally:

// These two are completely equivalent
new ZWPlayer({ watermarks: data });
new ZWPlayer({ watermark: data });

2.3 variables - Template Variables

• Type: Object
• Default Value: None
• Description: Provides values for template variables in text watermarks. Keys correspond to {key} placeholders in the text:

new ZWPlayer({
    playerElm: 'mse',
    url: 'https://cdn.example.com/video.mp4',
    watermarks: [
        { type: 'text', text: '{user_id} | {sys_time}', behavior: 'dynamic' }
    ],
    variables: {
        user_id: '138****1234',
        user_name: 'John',
        department: 'Engineering'
    }
});

2.4 Relationship Between logo and watermarks

Both can be used independently or simultaneously. If only logo is set without watermarks, the player automatically converts the logo to watermark format for rendering. watermarks is the enhanced version of logo; new projects are recommended to use watermarks directly.

3. Setting Watermark Information (Method)

You can also use the setWatermarks method for delayed loading after player initialization. It is recommended to call this after the video has finished loading.

3.1 Method Signature

player.setWatermarks(watermarks);

3.2 Parameter Types

The watermarks parameter supports the following formats:

1. URL String: An HTTP address for the watermark JSON file
2. ZWMAP JSON Object: A watermark data object containing the protocol header
3. Watermark Array: An already parsed watermark entries array

// Method 1: URL
player.setWatermarks('https://cdn.example.com/watermark/data.json');

// Method 2: ZWMAP object
player.setWatermarks({
    zwp_protocol: 'ZWMAP/1.0',
    zwp_type: 'watermark',
    watermarks: [{ type: 'text', text: 'Confidential' }]
});

// Method 3: Plain array
player.setWatermarks([
    { type: 'image', icon: 'https://cdn.example.com/logo.png', dock: 'right' }
]);

4. Watermark Data Formats

4.1 ZWMAP JSON Format (Recommended)

ZWMAP (ZWPlayer Media Application Protocol) is the standard JSON format defined by zwplayer. The exported file is named {VideoTitle}_watermark.json. The format is as follows:

{
  "zwp_protocol": "ZWMAP/1.0",
  "zwp_type": "watermark",
  "zwp_version": "1.0",
  "watermarks": [
    {
      "id": "wm-logo",
      "type": "image",
      "behavior": "static",
      "icon": "https://cdn.example.com/logo.png",
      "dock": "right",
      "x": "3%",
      "y": "3%",
      "width": "8%",
      "opacity": 70
    },
    {
      "id": "wm-text",
      "type": "text",
      "behavior": "static",
      "text": "All Rights Reserved",
      "dock": "left",
      "x": "3%",
      "y": "90%",
      "font_size": 16,
      "font_color": "rgba(255,255,255,0.5)",
      "opacity": 60
    }
  ]
}

Protocol Header Fields:

Watermark Entry Common Fields:

4.2 Plain Array Format (No ZWMAP Header)

You can also pass a watermark entries array directly without the ZWMAP protocol header wrapper:

new ZWPlayer({
    playerElm: 'mse',
    url: 'https://cdn.example.com/video.mp4',
    watermarks: [
        {
            type: 'image',
            icon: 'https://cdn.example.com/logo.png',
            dock: 'right',
            opacity: 50
        },
        {
            type: 'text',
            text: 'Internal Use Only',
            font_size: 14,
            font_color: 'rgba(255,255,255,0.3)',
            dock: 'left'
        }
    ]
});

4.3 Automatic Recognition Rules

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

• String starting with HTTP/HTTPS: Treated as a remote watermark JSON file URL, automatically downloaded and parsed
• Object containing zwp_type: "watermark": Parsed as ZWMAP protocol format, extracting the watermarks array
• Array: Used directly as watermark entries

5. Watermark Types and Behavior Modes

5.1 Image Watermark (type: “image”)

Overlays an image on the video screen, suitable for brand logos, QR codes, etc.

{
    "type": "image",
    "icon": "https://cdn.example.com/logo.png",
    "dock": "right",
    "x": "3%",
    "y": "3%",
    "width": "8%",
    "opacity": 70
}

5.2 Text Watermark (type: “text”)

Displays text content on the video screen with font, color, size configuration and template variable support.

{
    "type": "text",
    "text": "{user_name} | {sys_time}",
    "font_size": 16,
    "font_color": "rgba(255,255,255,0.5)",
    "dock": "left",
    "x": "3%",
    "y": "90%",
    "opacity": 60
}

5.3 Static Mode (behavior: “static”)

Watermark is fixed at the specified position, suitable for brand logos and fixed copyright notices.

• dock determines the x-axis reference origin (left or right edge)
• When switching dock direction, x values need to be converted accordingly (e.g., 5% → 95%)

5.4 Dynamic Roaming Mode (behavior: “dynamic”)

Watermark moves across the screen, which is the key means for anti-screen-recording.

• Watermark moves within the container and bounces off boundaries automatically
• Setting interval and duration enables show/hide periodic cycling
• After hiding, the watermark reappears and continues moving from the last position

movement parameters:

{
    "type": "text",
    "behavior": "dynamic",
    "text": "{user_id} | {sys_time}",
    "font_size": 14,
    "font_color": "rgba(255,255,255,0.3)",
    "opacity": 40,
    "movement": {
        "direction": "diagonal",
        "speed": 3
    }
}

5.5 Tile Mode (behavior: “tile”, text only)

Text fills the entire screen in a tilted grid pattern, creating a dense watermark matrix.

• Grid dimensions are calculated based on the screen diagonal to ensure no gaps after rotation
• Only type: "text" supports this mode

tile parameters:

{
    "type": "text",
    "behavior": "tile",
    "text": "Confidential",
    "font_size": 16,
    "font_color": "rgba(255,255,255,0.08)",
    "opacity": 20,
    "tile": {
        "angle": -30,
        "rowSpacing": 120,
        "colSpacing": 300
    }
}

6. Template Variables

The text field in text watermarks supports {key} template variables that are dynamically resolved during playback.

6.1 Built-in Variables

6.2 Custom Variables

Pass custom variables through the player’s variables parameter:

new ZWPlayer({
    url: 'video.mp4',
    watermarks: 'watermark.json',
    variables: {
        user_id: '138****1234',
        user_name: 'John',
        department: 'Engineering'
    }
});

Unresolved variables are displayed as-is.

7. Usage Examples

Example 1: Loading Watermark via URL

new ZWPlayer({
    url: 'https://cdn.example.com/video.mp4',
    playerElm: '#player',
    watermarks: 'https://cdn.example.com/watermark/movie_watermark.json'
});

Example 2: Passing Array via Constructor Property

new ZWPlayer({
    url: 'https://cdn.example.com/video.mp4',
    playerElm: '#player',
    watermarks: [
        {
            type: 'image',
            icon: 'https://cdn.example.com/logo.png',
            dock: 'right',
            opacity: 50
        }
    ]
});

Example 3: Passing ZWMAP Object

new ZWPlayer({
    url: 'https://cdn.example.com/video.mp4',
    playerElm: '#player',
    watermarks: {
        zwp_protocol: 'ZWMAP/1.0',
        zwp_type: 'watermark',
        watermarks: [
            { type: 'text', text: 'Internal Only', font_size: 14, behavior: 'dynamic' }
        ]
    }
});

Example 4: Delayed Loading via setWatermarks Method

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

setTimeout(function() {
    player.setWatermarks('https://cdn.example.com/watermark/movie_watermark.json');
}, 500);

Example 5: Watermark Association in Playlist

Each video item in a playlist can have an independent watermark via the watermark field:

{
    "zwp_protocol": "ZWMAP/1.0",
    "zwp_type": "playlist",
    "groups": [{
        "items": [{
            "title": "Course Video",
            "url": "https://cdn.example.com/video/lesson1.mp4",
            "watermark": "https://cdn.example.com/watermark/lesson1_watermark.json"
        }]
    }]
}

When switching to that video, the player automatically loads the corresponding watermark data.

Example 6: Drag & Drop Local File Loading

With localPlayback enabled, drag a watermark JSON file onto the player to load it:

• Filename matching rules: Suffixes _watermark.json, -watermark.json, _wm.json, -wm.json
• Auto-association: The player matches files by video filename (e.g., movie.mp4 matches movie_watermark.json)
• Format support: Both ZWMAP protocol format and plain array format are supported

8. Online Editor

Use the Online Watermark Editor to visually create and edit watermark configurations:

• WYSIWYG Editing: Drag and drop watermarks directly on the video to adjust position and size
• Multiple Watermark Types: Supports image and text watermarks
• Behavior Mode Configuration: Visually configure static, dynamic roaming, and tile modes
• Template Variable Support: Configure built-in and custom variables
• Export ZWMAP JSON: One-click export of standard format files, ready for player configuration

9. Notes

1. Opacity Recommendations: Static watermarks 30-70, dynamic watermarks 20-40, tile watermarks 10-30
2. Multi-watermark Overlay: Multiple watermarks should not overlap completely to avoid affecting the viewing experience
3. Mouse Passthrough: Watermarks do not respond to mouse events and do not block player interaction
4. Image Format: PNG or SVG images with transparency are recommended for image watermarks
5. Dynamic Watermark Performance: Dynamic and tile watermarks consume some rendering resources; recommended no more than 3 dynamic watermarks
6. Detailed Specification: For the complete watermark data structure specification, see ZWMAP Watermark Specification
7. Logo Watermark: For simple branding, use the lighter logo parameter instead. See Logo Setup