ZWPlayer v3.3.2 发布：贴片广告、音乐模式与跨视频字幕搜索

今天，我们很高兴地宣布 ZWPlayer v3.3.2 正式发布！🎉

如果用一句话概括这次更新的核心：

让一个播放器同时胜任视频播放、音频聆听、内容预览和广告变现，让字幕搜索跨越视频边界，让 DASH 内嵌字幕全面可用，并让界面语言从桌面到移动端彻底统一。

本次更新围绕五大方向展开：广告变现、播放模式、字幕深度搜索、DASH 字幕预下载和界面统一改版。前四个方向让能力边界更宽，最后一个方向则把这套能力包装进一套现代、统一、好用的界面里。让我们逐一看看这些新能力。

💡 获取最新版本：除了文末的下载链接，你还可以从我们的发布仓库获取最新构建产物（含离线 ZIP 包和 JS 文件）：

GitHub：zwplayer-release/releases
Gitee：zwplayer-release/releases

1. 贴片广告：让每一帧都有商业价值

在内容为王的时代，如何在提供优质播放体验的同时实现商业变现，是每个视频平台都要面对的问题。v3.3.2 新增的贴片广告功能，让你可以在正片播放前后插入自有宣传片。

适用场景

品牌曝光：正片开始前播放品牌形象片
内容预告：片后播放下集预告，吸引持续观看
赞助回报：为赞助商提供片前/片后广告位

它是怎么工作的

支持片前（正片开始前）和片后（正片结束后）两个插入位置
可配置跳过策略：强制完整观看（不可跳）、立即可跳（用户随时点跳过）、倒计时后可跳（N 秒倒计时结束后出现跳过按钮）
广告播放期间界面清爽干净，结束后无缝衔接正片
支持 clickThrough 点击跳转到指定落地页
循环播放正片时广告只插播一次，不会反复打扰观众

new ZWPlayer({
  playerElm: 'player',
  url: 'main.mp4',
  bumper: {
    preRoll: {
      url: 'https://cdn.example.com/intro.mp4',
      skipOffset: 5,               // 5秒后可跳过
      clickThrough: 'https://brand.com'
    }
  }
});

2. 播放模式：一个播放器，四种形态

不同内容需要不同的呈现方式。v3.3.2 新增 mode 配置项，让你用一个属性在四种播放形态间切换，无需为不同场景开发不同的播放器。

预览模式：鼠标划过即可预览

你是否在视频网站上浏览列表时体验过——鼠标划过一个视频卡片，它就开始自动播放一段预览？v3.3.2 的预览模式就是这样的体验。

适用场景：视频列表、课程目录、影视推荐墙等卡片式布局。

它是怎么实现的：

鼠标悬停在播放器上时，自动开始播放一段预览片段（静音、循环）
鼠标离开时自动暂停
随机从视频中间位置开始预览，跳过片头片尾，直接展示精华内容
可设置每次预览的最长时间，超时自动停止
预览过程强制静音——同一页面上多个卡片同时悬停也不会变成噪音灾难
如果你的布局比较特殊，也可以通过 API 由代码精确控制预览的启停时机

new ZWPlayer({
  playerElm: 'card',
  url: 'video.mp4',
  mode: 'preview',
  preview: {
    startTime: 'random',   // 从 10%-80% 位置开始
    duration: 15           // 每次预览最长 15 秒
  }
});

音乐模式：让纯音频也有沉浸感

当你播放一首歌、一段播客或一个有声书时，看到一个黑色的视频窗口只有控制栏在跳——这体验并不好。v3.3.2 的音乐模式为纯音频内容提供了专业的播放面板。

适用场景：音乐播放页、播客平台、有声读物、在线电台。

它是怎么呈现的：

旋转的唱片封面：从专辑封面自动生成黑胶唱片效果，播放时缓缓旋转（约 20 秒一圈），暂停时停转——就像一台真实的唱片机
逐行滚动的歌词：支持 LRC 格式歌词，当前行高亮放大并自动居中滚动，点击任意歌词行可跳转到对应时间。还支持逐字 karaoke 填充和翻译副行
跳动的频谱：6 种频谱形态可选——LED 栅格、怀旧三色柱、山峰声波、水平柱图、圆形径向、镜像对称，让音频"看得见"
主题皮肤：从封面自动提取主色作为主题色，也提供怀旧复古（银蓝荧光绿）和高保真经典（深海蓝琥珀金）两套预设皮肤
系统媒体键：手机锁屏或息屏状态下也能通过系统媒体键控制播放/暂停/上下曲
毛玻璃背景：封面模糊放大作为背景铺底，营造沉浸氛围

两种面板形态：

panel: 'full'（默认）：大封面 + 歌词 + 频谱 + 毛玻璃背景的全屏面板，适合专注听歌
panel: 'bar'：紧凑的底部信息条（封面 + 标题 + 进度），适合嵌入式场景

new ZWPlayer({
  playerElm: 'player',
  url: 'song.mp3',
  mode: 'music',
  lyrics: 'song.lrc',
  music: {
    panel: 'full',
    visualizer: 'classic',
    theme: 'auto'
  }
});

混合列表：视频和音频自动切换

这是 v3.3.2 最巧妙的能力之一。当一份播放列表里同时包含视频和音频内容时（比如一个课程列表：片头视频 + 主题曲音频 + 正片视频），播放器会自动判断当前播放的内容类型并切换播放形态：

播到视频 → 标准视频播放形态
播到音频 → 自动切换到音乐面板（封面 + 歌词 + 频谱）
播完音频切到下一个视频 → 自动切回标准形态

整个过程完全自动，用户无感知——播放器自己知道"现在播的是视频还是音频"，并呈现最合适的界面。

3. 字幕搜索：从"一个视频内搜"到"跨全集搜索"

痛点

还记得追剧时听到一句经典台词，却死活想不起来是哪一集吗？或者做课程笔记时，想找到老师讲过某个知识点的那段视频，却只能一集一集翻？

v3.3.2 的跨视频字幕搜索，就是为解决这个问题而生的。

同组内搜索

在当前播放列表的同一组内，输入关键词就能搜到所有匹配的字幕条目。结果按视频分组展示，点击任意结果直接跳转到该视频的对应时间点。

跨视频搜索：台词一搜即到 ⭐

这是本次更新的亮点功能。跨播放列表分组搜索多个视频的字幕，快速定位某句台词出现在哪一集的什么时间：

它是怎么工作的：

在搜索框输入台词关键词
播放器在后台同时搜索列表中所有视频的字幕
结果按视频分组展示，每条结果清晰标注：出自哪一集、第几分第几秒
点击任意结果，播放器自动切换到该视频并跳转到台词出现的精确位置

适用场景：

追剧回顾：搜台词定位到集，比翻剧集列表快十倍
课程学习：搜知识点定位到讲过的视频段落
语言学习：搜例句反复听原文发音
会议回放：搜发言内容定位到会议录像片段

字幕片段微调

搜到目标字幕后，还可以对片段进行精细控制：

字幕循环播放：反复播放同一条字幕对应的片段，语言学习场景的利器
A-B 段循环：自定义任意起止点反复播放那段内容
进度条框选：在进度条上可视化地选择片段区间

4. DASH 内嵌字幕预下载：让 DASH 字幕也能搜索、翻译、导出

v3.3.0 起，我们支持 HLS 内嵌字幕的自动预下载（分段字幕拼装成完整文件，搜索、翻译、导出全可用）。v3.3.2 将这一能力带到了 DASH：播放 DASH 流时，播放器自动解析 MPD 清单中声明的全部内嵌字幕轨，并发预下载并解析成完整字幕，进入 ZWPlayer 字幕体系。

为什么需要它：主流打包器（Shaka Packager、Axinom 等）产出的 DASH 字幕大多封装在 mp4 容器里（stpp/TTML 或 wvtt/WebVTT），浏览器与 dash.js 引擎只能"逐段显示"，无法全文搜索、翻译或导出。预下载让这些能力在 DASH 流上同样可用。

支持范围（覆盖主流打包器产出）：

mp4 容器字幕：stpp（TTML-in-mp4）与 wvtt（WebVTT-in-mp4），分段（.m4s + SegmentTemplate/SegmentList）与单文件（SegmentBase）两种寻址均支持
裸文本字幕：WebVTT / TTML 分段或单文件
双编码去重：同一语言同时提供 wvtt + stpp 两种编码（内容相同）时，自动只保留一条（优先 wvtt——解析链路更短、下载体积更小），字幕列表不再出现重复条目
边下边用：并发有序下载，首片就绪字幕即可显示；换源时在途抓取自动作废；直播流（dynamic MPD）不预载

零配置：该能力缺省开启，播放 DASH 流即自动生效，无需任何设置。

new ZWPlayer({
  playerElm: 'player',
  url: 'https://example.com/stream.mpd'
});

5. 播放器界面统一改版：一套设计语言，从桌面到移动

功能越来越多，界面却不该越来越乱。v3.3.2 的后半程，我们完成了一次播放器界面的统一改版——让控制栏、设置菜单、进度条与弹层采用一致的现代化风格，桌面与移动端体验统一。

更现代的控制栏

控制栏更轻盈：显隐过渡更平滑，自动隐藏更快（桌面 4 秒 / 移动 3 秒），暂停时不再自动隐藏——你随时都能找到按钮
进度条、滑块、时间气泡全面翻新，观感更统一

设置菜单升级为「首页 → 子页」

倍速、清晰度等常用设置集中收纳进齿轮菜单，不再散落各处
首页直接显示当前值：「倍速 ▸ 1.0x」「清晰度 ▸ 自动」，一眼可查、一键可改
截图、投屏、画中画等动作功能平铺为磁贴，点击即用

6. 上拉缩略图条：快速定位任意画面

在几十分钟的视频里找某个画面，来回拖进度条试探很低效。现在，只要视频配置了缩略图，按住进度条向上拉动，就会展开一条整行宽的缩略图条：

上拉过程中画面变暗、缩略图变亮，注意力自然聚焦在画面上
一条白色准星对齐当前位置，可以从容拖动缩略图逐帧浏览，或直接点击目标帧跳转
点错也不怕：✕ 或 Esc 取消，回到原进度继续播放

桌面鼠标和触屏的操作方式完全一致。

7. 快捷键完善：数字键百分比跳转

按数字键 1-9 直接跳到视频的 10%-90% 位置：1 是 10%，5 正好是一半，9 是 90%（点播视频有效）
按 0 从头重播
音量条支持鼠标滚轮调节，不用再精确瞄准小滑块
播放器内置的快捷键帮助面板已同步更新

8. 移动端：底部面板与折叠控制栏

移动端不是桌面的缩小版，这次它得到了专门的照顾：

底部面板（Bottom Sheet）：设置菜单、字幕搜索等面板改为从底部滑出，行高和开关更大，手指点按更从容
「‹›」折叠按钮：小屏幕下，播放列表、附注、章节、截图等次常用按钮会收纳进一个折叠组，点按展开——常用功能不再挤作一团
控制条更清爽：触屏设备隐藏屏幕音量按钮（手机音量走系统硬件音量键），把位置留给真正有用的控件
修复了 iPad 等平板设备上菜单显示异常的问题

9. 章节与附注：进度条上的"目录页"

章节分段更清晰：章节在进度条上以分段缝隙呈现，像书页目录的分隔线，播放进度一目了然
悬停信息更全：悬停进度条时可同时查看缩略图、时间、章节标题和附近的附注信息，排列整齐不再重叠
附注标记可点：进度条上的附注标记（测验、信息卡、投票等）更醒目，点击即可跳转到对应时刻

10. 体验优化与问题修复

自动海报：告别黑屏首屏

没有配置 poster 的视频，进入页面第一眼常常是一片黑。v3.3.2 起，播放器会自动用视频首帧作为海报：

本地文件：后台自动提取首帧生成海报图，播放列表里的每个本地视频都有自己的封面
HTTP 点播视频（MP4 等）：激活浏览器原生首帧渲染，iOS/Safari 同样生效

字幕自由拖拽

字幕可以在画面中自由拖动（水平 + 垂直），找到最舒服的阅读位置；松手后位置自动适配窗口缩放与全屏，并避开控制栏不被遮挡。

其他细节

进度条悬停时间提示默认开启

问题修复

修复了若干稳定性与兼容性问题。

11. 配置项一览

属性	说明
`mode`	播放模式：`'standard'`（默认）/ `'music'` / `'preview'` / `'auto'`
`bumper`	贴片广告：片前/片后宣传片配置，含跳过策略与落地页
`pauseAd`	暂停广告：用户暂停时展示的推广素材
`music`	音乐面板参数：面板形态、频谱样式、主题皮肤、唱片旋转等
`preview`	预览参数：起始位置、时长、悬停触发方式等
`lyrics`	歌词（LRC 文件地址或歌词文本），与字幕同级配置
`useProgressTooltip`	进度条悬停时间提示（默认 `true`）
`hideControlbarTimeout`	控制栏自动隐藏延时（毫秒），默认 `4000`（桌面）/ `3000`（移动端）

升级方式

替换 zwplayer.js 文件即可，API 与数据格式完全向后兼容。

需要留意的是，界面改版会带来默认观感上的变化（如控制栏自动隐藏更快、暂停时不隐藏、悬停提示默认开启），如需调整可通过 hideControlbarTimeout、useProgressTooltip 等配置项设置。

📥 下载 v3.3.2：https://cdn.zwplayer.com/v3.3.2/zwplayer.zip

写在最后

v3.3.2 是 ZWPlayer 向"全媒体播放平台"迈出的重要一步。贴片广告让播放器具备了商业闭环能力，播放模式让一个播放器适配了从视频到音频到卡片预览的多种场景，跨视频字幕搜索让内容检索突破了单个视频的边界，DASH 内嵌字幕预下载让两大主流流媒体协议的字幕能力完全对齐；而界面统一改版则把这些能力装进了一套现代、统一、桌面与移动端一致的皮肤里。

我们期待看到你在项目中使用这些新能力。如果你有任何反馈或建议，欢迎通过 GitHub Issues 或社区渠道与我们交流。