ZWMAP 水印类型规范

1. 概述

水印类型用于描述视频画面上叠加的水印元素，支持图片水印、文字水印、动态游走水印和铺满水印。常用于品牌标识、版权声明、用户追踪和防录屏保护。使用 在线水印编辑工具 可以可视化配置和导出水印数据。

水印数据通过 watermarks 参数传入播放器，支持三种输入格式：

1. URL 字符串：指向一个 ZWMAP JSON 文件的地址
2. ZWMAP 对象：包含完整协议头的 JSON 对象
3. 水印数组：直接传入 watermarks 数组（无协议头）

2. ZWMAP 头部

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

3. 数据结构

3.1 根级别字段

3.2 水印条目通用字段

3.3 图片水印字段（type: "image"）

3.4 文字水印字段（type: "text"）

3.5 动态行为字段（behavior: "dynamic"）

3.6 铺满行为字段（behavior: "tile"，仅 type: "text"）

4. 行为模式

4.1 static — 静态水印

水印固定在指定位置，适合品牌 Logo 和固定版权声明。

• dock 决定 x 坐标的参考原点（左边缘或右边缘）
• 切换 dock 方向时，x 值需相应转换（如 5% → 95%）

4.2 dynamic — 动态游走

水印在画面上移动，是防录屏的关键手段。

• 水印在容器内移动，碰到边界自动反弹
• 设置 interval 和 duration 可实现显示/隐藏的周期循环
• 隐藏后重新出现时，从上次消失的位置继续移动

4.3 tile — 铺满水印（仅文字）

文字以倾斜网格铺满整个画面，形成密集水印矩阵。

• 网格尺寸按画面对角线计算，确保旋转后无空白
• 仅 type: "text" 支持

5. 模板变量

文字水印的 text 字段支持 {key} 模板变量，在播放时动态解析。

5.1 内置变量

5.2 自定义变量

通过播放器的 variables 参数传入：

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

未解析的变量原样显示。

6. 完整示例

{
  "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": "{user_name} | {department}",
      "dock": "left",
      "x": "3%",
      "y": "90%",
      "font_size": 16,
      "font_color": "rgba(255,255,255,0.5)",
      "opacity": 60
    },
    {
      "id": "wm-dynamic",
      "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,
        "interval": 0,
        "duration": 0
      }
    },
    {
      "id": "wm-tile",
      "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
      }
    }
  ]
}

7. 约束规则

1. watermarks 数组不得为空
2. 每个条目必须包含 type 字段
3. type 为 image 时，必须提供 icon
4. type 为 text 时，必须提供 text
5. opacity 取值范围 0-100，推荐值 20-70
6. behavior: "tile" 仅适用于 type: "text"
7. 动态水印推荐透明度 20-40，平衡防录屏效果与观看体验
8. 多个水印可同时使用，位置不应完全重叠
9. 水印不响应鼠标事件，不阻塞播放器交互