音乐模式（Music Mode）

1. 概述

音乐模式是 ZWPlayer 为纯音频内容提供的专用播放形态。当 mode: 'music' 时，播放器呈现音乐面板（封面旋转 + 歌词 + 频谱），而非黑色的视频窗口。

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

2. 快速开始

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

3. 两种面板形态

`panel: 'full'`（全屏面板，默认）

画面主体：大封面/唱片（旋转）+ 歌词列 + 频谱可视化 + 毛玻璃背景。桌面宽屏左右分屏（封面 + 歌词），窄屏上下堆叠。标准控制栏在底部。

适合专注听歌、沉浸式音乐体验。

`panel: 'bar'`（紧凑底条）

APlayer 风格的紧凑信息条（在标准控制栏上方）：圆形封面（唱片旋转）+ 标题/艺人。进度条/时间/音量由标准控制栏提供。不含歌词区。

适合嵌入式场景、需要紧凑布局的页面。

4. 歌词（lyrics）

lyrics 是顶层字段（与 subtitles 同级），不在 music 子对象内。

4.1 传值方式

// 方式一：LRC 文件 URL
lyrics: 'https://cdn.example.com/song.lrc'

// 方式二：LRC 文本行数组
lyrics: ['[00:01.00]第一句', '[00:03.50]第二句', '[00:08.00]第三句']

// 方式三：播放列表 item 的 lyrics 字段（切歌时自动加载）

4.2 渲染特性

逐行高亮：当前行放大加粗（主题色），上下行渐隐，自动平滑居中滚动
逐字 karaoke：<mm:ss.xx>字 格式，已唱字实时填充主题色
翻译/罗马音：同时间戳行合并为翻译副行（小字低透明）
点击跳转：点击任意歌词行 seek 到该时间并恢复播放
运行时切换：player.setLyrics(lrc) 动态替换歌词

4.3 LRC 格式示例

[00:00.00]歌名
[00:01.50]<00:01.50>第<00:01.80>一<00:02.10>句   ← 逐字 karaoke
[00:03.00]第二句
[00:05.00]翻译副行

5. 频谱可视化（visualizer）

值	效果	适用场景
`'classic'`（默认）	高保真 LED 栅格点阵：48 柱对数采样 + 圆角 LED 块 + 物理缓动 + 霓虹发光	full 面板底部 / bar 面板
`'vintage'`	怀旧三色下落峰值：绿-黄-红渐变 + 重力下落 Peak Cap，经典怀旧风格	full 面板底部（复古怀旧）
`'mountain'`	全宽山峰声波图：128 高密柱 + 渐变山脉漫射 + 顶点粒子，沉浸感最强	full 面板大屏（视觉体验最佳）
`'bars'`	水平柱状频谱：48 柱对数采样 + Peak Cap 顶点落体	full 面板底部 / bar 面板
`'circular'`	圆形径向频谱：正方形 1:1 容器，48 柱径向辐射	full 面板居中（唱片律动感）
`'mirror'`	中心对称双向频谱：上下双向对称延展	full 面板底部（现代科技感）
`false`	关闭频谱	仅需封面+歌词

'ttplayer' 是 'vintage' 的别名，两者完全等价。

6. 主题皮肤（theme）

值	效果
`'auto'`（默认）	从封面提取主色（`extractDominantColor`），歌词高亮色/按钮色/频谱色联动
`'vintage'`	怀旧银蓝皮肤 + 荧光绿 accent（`#00e676`）
`'classic'`	沉浸深海蓝皮肤 + 琥珀金 accent（`#f59e0b`）
`'#hex'`	自定义 accent 色（如 `'#ff6600'`）

7. 完整配置参数

字段	类型	默认值	说明
`panel`	`'full'` \| `'bar'`	`'full'`	面板形态
`visualizer`	见 §5	`'classic'`	频谱可视化形态
`theme`	见 §6	`'auto'`	主题皮肤
`vinyl`	bool	`true`	唱片旋转动效（~20s/圈，播放时旋转、暂停停止）
`blurBackground`	bool	`true`	毛玻璃背景铺底（full 面板）
`mediaSession`	bool	`true`	系统媒体键/锁屏集成
`title`	string	`''`	曲目标题（面板 + 系统锁屏）
`artist`	string	`''`	艺人

封面：统一用 poster 字段（与视频海报共用），不在 music 内配置。 播放队列：通过播放列表统一管理，不在 music 内配置。

8. 混合播放列表自动切换

一份播放列表同时含视频项和音频项时，播放器自动按内容类型切换播放形态：

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

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

无需手动配置 mode: 'music'——列表含 mediaKind:"audio" 项时自动激活。详见播放模式指南 §5。

9. 注意事项

lyrics 是顶层字段：不在 music 子对象内，与 subtitles 同级。
封面用 poster：不在 music 内单独配置封面，poster 同时用于视频海报和音乐封面。
AudioContext 解冻：频谱/EQ 依赖 Web Audio API，iOS/Android 需用户交互后才能解冻，播放器已内置 touchstart 自动 resume。
控制栏复用：进度条/时间/音量/列表/倍速/设置/全屏均由标准控制栏提供（MUSIC_PRESET: controlbar:true, fixedControlbar:true）。