ZWPlayer 水印设置使用说明

1. 功能概述

ZWPlayer 支持在视频画面上叠加自定义水印，提供以下功能：

• 图片水印：叠加 Logo、二维码等自定义图片
• 文字水印：显示自定义文本内容，支持字体、颜色、大小配置
• 动态游走水印：水印在画面上移动，有效防止录屏盗用
• 铺满水印：文字以倾斜网格铺满整个画面，形成密集水印矩阵
• 模板变量：支持 {user_id}、{sys_time} 等动态变量
• 多水印叠加：同时叠加多个水印元素，位置、透明度独立控制
• 播放列表关联：播放列表中每个视频可配置独立水印
• 拖拽加载：支持拖拽本地 _watermark.json 文件自动匹配加载

水印数据采用 ZWMAP（ZWPlayer 媒体应用协议）格式，可通过 在线水印编辑工具 可视化创建和导出。

2. 配置参数

2.1 watermarks - 水印数据（属性）

• 类型：String | Array | Object

• 默认值：无

• 说明：在播放器初始化时通过构造函数传入水印数据，支持以下三种输入方式：

  • URL 字符串：以 http 或 https 开头的水印 JSON 文件地址，播放器自动下载解析
  • ZWMAP JSON 对象：包含 zwp_type: "watermark" 的协议对象
  • 水印数组：已解析的水印条目数组（无需 ZWMAP 协议头包装）

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

2.2 watermark - 别名属性

watermark（单数）是 watermarks（复数）的别名，两者等价，播放器内部自动归一化：

// 以下两种写法完全等价
new ZWPlayer({ watermarks: data });
new ZWPlayer({ watermark: data });

2.3 variables - 模板变量参数

• 类型：Object
• 默认值：无
• 说明：为文字水印中的模板变量提供值。键名对应模板中的 {key} 占位符：

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: '张三',
        department: '技术部'
    }
});

2.4 logo 与 watermarks 的关系

两者可独立使用，也可同时使用。如果仅设置了 logo 而未设置 watermarks，播放器会自动将 Logo 转换为水印格式渲染。watermarks 是 logo 的增强版本，推荐新项目直接使用 watermarks。

3. 设置水印信息（方法）

也可以在播放器初始化后通过 setWatermarks 方法延迟加载，建议在视频加载完成后调用。

3.1 方法签名

player.setWatermarks(watermarks);

3.2 参数类型

watermarks 参数支持以下格式：

1. URL 字符串：水印 JSON 文件的 HTTP 地址
2. ZWMAP JSON 对象：包含协议头的水印数据对象
3. 水印数组：已解析的水印条目数组

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

// 方式 2：ZWMAP 对象
player.setWatermarks({
    zwp_protocol: 'ZWMAP/1.0',
    zwp_type: 'watermark',
    watermarks: [{ type: 'text', text: 'Confidential' }]
});

// 方式 3：裸数组
player.setWatermarks([
    { type: 'image', icon: 'https://cdn.example.com/logo.png', dock: 'right' }
]);

4. 水印数据格式

4.1 ZWMAP JSON 格式（推荐）

ZWMAP（ZWPlayer 媒体应用协议）是 zwplayer 定义的标准 JSON 格式，导出文件命名为 {视频标题}_watermark.json。格式如下：

{
  "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": "版权所有",
      "dock": "left",
      "x": "3%",
      "y": "90%",
      "font_size": 16,
      "font_color": "rgba(255,255,255,0.5)",
      "opacity": 60
    }
  ]
}

协议头字段：

水印条目通用字段：

4.2 裸数组格式（无 ZWMAP 头）

也可以直接传入水印条目数组，无需 ZWMAP 协议头包装：

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: '内部资料',
            font_size: 14,
            font_color: 'rgba(255,255,255,0.3)',
            dock: 'left'
        }
    ]
});

4.3 自动识别规则

zwplayer 根据参数内容自动识别水印格式：

• 以 HTTP/HTTPS 开头的字符串：作为远程水印 JSON 文件 URL，自动下载解析
• 对象且含 zwp_type: "watermark"：按 ZWMAP 协议格式解析，提取 watermarks 数组
• 数组：直接作为水印条目数组使用

5. 水印类型与行为模式

5.1 图片水印（type: “image”）

在视频画面上叠加图片，适合品牌 Logo、二维码等场景。

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

5.2 文字水印（type: “text”）

在视频画面上显示文本内容，支持字体、颜色、大小配置和模板变量。

{
    "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 静态模式（behavior: “static”）

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

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

5.4 动态游走模式（behavior: “dynamic”）

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

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

movement 参数：

{
    "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 铺满模式（behavior: “tile”，仅文字）

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

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

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
    }
}

6. 模板变量

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

6.1 内置变量

6.2 自定义变量

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

new ZWPlayer({
    url: 'video.mp4',
    watermarks: 'watermark.json',
    variables: {
        user_id: '138****1234',
        user_name: '张三',
        department: '技术部'
    }
});

未解析的变量原样显示。

7. 使用示例

示例 1：通过 URL 加载水印

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

示例 2：通过构造函数属性传递数组

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
        }
    ]
});

示例 3：传递 ZWMAP 对象

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

示例 4：通过 setWatermarks 方法延迟加载

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);

示例 5：播放列表中的水印关联

在播放列表的每个视频项中可通过 watermark 字段关联独立水印：

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

切换到该视频时，播放器会自动加载对应的水印数据。

示例 6：拖拽本地文件加载

开启 localPlayback 后，将水印 JSON 文件拖拽到播放器即可加载：

• 文件名匹配规则：后缀为 _watermark.json、-watermark.json、_wm.json、-wm.json
• 自动关联：播放器按文件名匹配视频文件（如 movie.mp4 自动匹配 movie_watermark.json）
• 格式支持：同时支持 ZWMAP 协议格式和裸数组格式

8. 在线编辑工具

使用 在线水印编辑工具 可以可视化创建和编辑水印配置：

• 所见即所得编辑：直接在视频画面上拖拽调整水印位置和大小
• 多种水印类型：支持图片水印和文字水印
• 行为模式配置：可视化设置静态、动态游走和铺满模式
• 模板变量支持：配置内置变量和自定义变量
• 导出 ZWMAP JSON：一键导出标准格式文件，可直接用于播放器配置

9. 注意事项

1. 透明度推荐：静态水印推荐透明度 30-70，动态水印推荐 20-40，铺满水印推荐 10-30
2. 多水印叠加：多个水印的位置不应完全重叠，避免影响视频观看体验
3. 鼠标穿透：水印不响应鼠标事件，不阻塞播放器交互操作
4. 图片格式：建议使用带透明通道的 PNG 或 SVG 图片作为图片水印
5. 动态水印性能：动态水印和铺满水印会消耗少量渲染资源，建议不超过 3 个动态水印
6. 详细规范：完整的水印数据结构规范请参见 ZWMAP 水印规范
7. Logo 水印：如仅需简单的品牌标识，可使用更轻量的 logo 参数，参见 Logo 设置