ZWMAP Watermark Type Specification

1. Overview

The watermark type is used to describe watermark elements superimposed on the video screen. It supports image watermarks, text watermarks, and dynamic anti-screen-recording watermarks. Watermark data is passed to the player via the watermark property using a URL.

2. ZWMAP Header

{
  "zwp_protocol": "ZWMAP/1.0",
  "zwp_type": "watermark"
}

zwp_protocol and zwp_type are required fields.

3. Data Structure

3.1 Root Level Fields

Field	Type	Required	Default	Description
`zwp_protocol`	string	Yes	—	Protocol identifier, fixed to `"ZWMAP/1.0"`
`zwp_type`	string	Yes	—	Fixed to `"watermark"`
`zwp_version`	string	No	`"1.0"`	Data format version
`watermarks`	array	Yes	—	Array of watermark entries

3.2 Watermark Entry Object (WatermarkItem)

Field	Type	Required	Default	Description
`type`	string	Yes	—	Watermark type: `"image"` (image) or `"text"` (text)
`content`	string	Yes	—	Image URL (when type is image) or text content (when type is text)
`x`	string	No	`"5%"`	Horizontal position, supports pixel values or percentages
`y`	string	No	`"5%"`	Vertical position, supports pixel values or percentages
`width`	string	No	`"10%"`	Width (for image watermarks), supports pixel values or percentages
`height`	string	No	`"10%"`	Height (for image watermarks), supports pixel values or percentages
`opacity`	number	No	`50`	Opacity, 0-100 (0: fully transparent, 100: fully opaque)
`dock`	string	No	`"right"`	Dock area: `"left"` or `"right"`, affects the origin reference for x/y
`fontSize`	string	No	`"16px"`	Font size (for text watermarks)
`fontColor`	string	No	`"#ffffff"`	Font color (for text watermarks)
`rotation`	number	No	`0`	Rotation angle (degrees), used for dynamic anti-screen-recording effects
`drift`	boolean	No	`false`	Whether to enable dynamic drifting (anti-screen-recording)

3.3 Anti-Screen-Recording Mode

When drift: true is enabled, the watermark will periodically change its position on the video screen, effectively preventing the removal of watermarks via fixed-area cropping.

4. Complete Examples

4.1 Image Logo Watermark

{
  "zwp_protocol": "ZWMAP/1.0",
  "zwp_type": "watermark",
  "zwp_version": "1.0",
  "watermarks": [
    {
      "type": "image",
      "content": "https://cdn.example.com/logo.png",
      "dock": "right",
      "x": "5%",
      "y": "5%",
      "width": "10%",
      "height": "10%",
      "opacity": 60
    }
  ]
}

4.2 Text Watermark + Anti-Screen-Recording

{
  "zwp_protocol": "ZWMAP/1.0",
  "zwp_type": "watermark",
  "zwp_version": "1.0",
  "watermarks": [
    {
      "type": "image",
      "content": "https://cdn.example.com/logo.png",
      "dock": "right",
      "x": "5%",
      "y": "5%",
      "width": "10%",
      "height": "10%",
      "opacity": 50
    },
    {
      "type": "text",
      "content": "ZWPlayer Demo",
      "x": "30%",
      "y": "50%",
      "fontSize": "24px",
      "fontColor": "#ffffff",
      "opacity": 30,
      "rotation": -25,
      "drift": true
    }
  ]
}

5. Constraints

The watermarks array must not be empty
Each entry must contain type and content
When type is image, content must be a valid image URL
When type is text, content must be the text content to be displayed
opacity value range is 0-100; recommended value is 20-60
Multiple watermarks can be used simultaneously, but their positions should not overlap completely
For anti-screen-recording watermarks, it is recommended to use lower opacity (20-40) and enable drift