`zwplayer` 播放模式（mode）使用说明

1. 概述

ZWPlayer 通过顶层 mode 配置属性支持四种播放模式，适配不同媒体内容场景：

模式	标识	定位
标准模式	`'standard'`	标准视频播放，功能最完整（默认）
音乐模式	`'music'`	音乐播放面板：封面旋转 + LRC 歌词 + 频谱可视化 + 唱片风格
预览模式	`'preview'`	B 站式悬停预览：鼠标悬停时静音循环预览片段
自动模式	`'auto'`	按媒体类型自动判定：纯音频→music，卡片场景→preview，其余→standard

快速选择

你的场景	推荐模式
普通视频播放（mp4/hls/直播）	`'standard'`（默认，无需配置）
纯音频 / 音乐播放	`'music'`
视频列表卡片悬停预览	`'preview'` 或 `'auto'`（+ `data-zwp-context="card"`）
一份列表混合视频+音频	`'auto'` 或不传 mode（列表含 `mediaKind:"audio"` 项时自动切换）

2. 标准模式（standard）

默认模式，无需显式配置。完整视频播放功能：控制栏、进度条、字幕、章节、标注、VR、截图等。

new ZWPlayer({ playerElm: 'mse', url: 'video.mp4' });
// mode 默认 'standard'，可省略

3. 音乐模式（music）

音频播放专用模式。渲染音乐面板（封面旋转 + LRC 歌词 + 频谱可视化），复用标准控制栏（播放/进度条/时间/音量/播放列表等），裁掉视频专属按钮（截图/放大镜/VR等）。

new ZWPlayer({
  playerElm: 'mse',
  url: 'song.mp3',
  mode: 'music',
  poster: 'cover.jpg',         // 封面（顶层字段）
  lyrics: 'song.lrc',          // 歌词（顶层字段，与 subtitle 同级）
  music: {
    panel: 'full',             // 'full'(全屏面板，默认) 或 'bar'(紧凑底条)
    visualizer: 'classic',     // 频谱形态
    theme: 'auto'              // 主题皮肤
  }
});

音乐模式的完整配置（面板形态、频谱 6 种形态、主题皮肤、歌词、混合列表自动切换等），详见音乐模式专题指南。

4. 预览模式（preview）

鼠标悬停时自动播放预览片段（静音、循环），离开时暂停。适用于视频列表的卡片场景。

4.1 基本用法

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

强制静音：预览模式始终静音（videoEl.muted = true，不可配置——避免列表多卡片同时出声）。

4.2 preview 配置参数

字段	类型	默认值	说明
`hoverToPlay`	bool	`true`	播放器自监听 mouseenter/mouseleave；`false` 时由宿主调 `startPreview()`/`stopPreview()`
`startTime`	number \| `'random'`	`0`	预览起始秒；`'random'` 在 10%-80% 区间随机
`duration`	number	`0`	单次预览最长时长（秒）；`0`=不限
`resetOnLeave`	bool	`false`	鼠标离开时重置进度回 `startTime`

4.3 手动控制（API）

hoverToPlay: false 时，由宿主代码控制预览启停：

player.startPreview({ startTime: 30, duration: 10 });
player.stopPreview();

5. 自动模式（auto）

按媒体类型自动判定播放模式。适合不确定内容是视频还是音频的通用场景。

5.1 检测规则

loadedmetadata 后判定：
  容器带 data-zwp-context="card" → preview（卡片/列表场景）
  videoWidth === 0 && videoHeight === 0 → music（纯音频流）
  否则 → standard（视频流）

5.2 混合播放列表自动切换

一份 ZWMAP playlist 同时含视频项和音频项时，切歌会自动切换播放模式：

{
  "zwp_protocol": "ZWMAP/1.0",
  "zwp_type": "playlist",
  "groups": [{
    "items": [
      { "name": "片头视频", "url": "intro.mp4", "mediaKind": "video" },
      { "name": "主题曲", "url": "theme.mp3", "mediaKind": "audio", "lyrics": "theme.lrc" },
      { "name": "正片", "url": "main.mp4", "mediaKind": "video" }
    ]
  }]
}

播放效果：片头视频（standard）→ 主题曲（自动切 music：封面+歌词+频谱）→ 正片（自动切回 standard）。

5.3 自动切换的触发条件

构造参数 `mode`	行为
显式 `'standard'`	永不自动切换（即使播到 audio 项）
显式 `'music'`	永不自动切换（即使播到 video 项）
`'auto'`	每首歌按 `mediaKind` 自动切换
未传（默认 standard）	列表含 `mediaKind:"audio"` 项时自动切换；纯视频列表不变

用户手动锁定：用户手动调 setMode() 切换模式后，自动切换会被锁定（直到换新播放列表），尊重用户的选择。

6. 模式预设

每种模式会自动投射配置预设，覆盖默认值（用户的显式配置优先）：

MUSIC_PRESET（音乐模式）

配置项	预设值	说明
`controlbar`	`true`	复用标准控制栏
`showProgress`	`true`	显示进度条
`fixedControlbar`	`true`	控制栏常驻（不自动淡出）
`snapshotButton`	`false`	裁掉截图
`zoomButton`	`false`	裁掉放大镜
`vr`	`false`	裁掉 VR
`infoButton`	`false`	裁掉媒体信息
`annotationButton`	`false`	裁掉标注
`castButton`	`false`	裁掉投屏
`recordButton`	`false`	裁掉录制
`optionButton`	`false`	裁掉设置按钮（含镜像/色彩调节等子项）

PREVIEW_PRESET（预览模式）

配置项	预设值	说明
`controlbar`	`false`	隐藏控制栏
`showProgress`	`false`	隐藏进度条
`autoplay`	`false`	不自动播放（等悬停触发）
`muted`	`true`	静音
`loop`	`true`	循环播放
`hideBigPlayButton`	`true`	隐藏大播放按钮

7. 注意事项

向后兼容：不传 mode 时默认 'standard'，行为与未引入模式系统前完全一致。
lyrics 位置：歌词是顶层字段（与 subtitle 同级），不在 music 子对象内。
预览强制静音：预览模式始终静音，不可通过配置取消（设计如此，避免多卡片同时出声）。
AudioContext 解冻：音乐模式的频谱/EQ 依赖 Web Audio API，iOS/Android 浏览器需用户交互（点击/触摸）后才能解冻 AudioContext，播放器已内置 touchstart 自动 resume 逻辑。
混合列表 mediaKind 缺省推断：playlist item 不写 mediaKind 时，按 URL 扩展名推断（.mp3/.flac/.m4a/.aac/.ogg/.wav/.opus → audio，其余 → video）。

zwplayer 播放模式（mode）使用说明