feat: 音频波形进度条 #190
Description
- 背景与目标
EchoPlayer 作为一款语言学习播放器，用户在精听/反复听某句话时，单靠字幕和时间轴定位效率不高。波形图可以直观展现音频能量，辅助用户：
快速定位句子起止位置；
可视化当前播放进度；
配合字幕增强对齐感；
提供 A-B 循环的直观交互（框选波形区间）。
目标：
在播放器中提供可缩放、可交互的波形展示，与字幕时间轴无缝联动，增强学习体验。
- 功能范围
基础功能
音频波形展示（全局视图）。
播放进度条叠加，实时刷新。
支持点击波形跳转播放位置。
自动与字幕对齐（当前句子在波形上高亮）。
进阶功能
A-B 循环：用户在波形上框选区间，播放器循环播放。
缩放/拖动：长音频可缩放波形查看局部。
缓存机制：波形数据生成一次后，保存 JSON，避免重复计算。
字幕联动：鼠标 hover 波形某段时，显示对应字幕。
- 技术方案
3.1 数据生成
离线生成（推荐）
使用 audiowaveform 工具（BBC 开源，快，C++实现）。
命令示例：
audiowaveform -i input.mkv -o waveform.json --pixels-per-second 10
输出文件示例：
{
"version": 2,
"channels": 1,
"sample_rate": 44100,
"samples_per_pixel": 512,
"bits": 8,
"length": 30000,
"data": [0, 5, 10, 7, ...]
}
在线生成（备用）
Web Audio API 或 Node.js 解码 PCM，采样并压缩。
成本高，不适合大文件，但适合本地“立即播放”的场景。
3.2 存储与缓存
波形文件命名规则：
{video_hash}/waveform.json
缓存目录：
macOS/Windows/Linux: ~/.echoplayer/cache/waveform/
判断逻辑：
打开视频 → 检查缓存 → 有则直接加载 → 无则生成。
3.3 前端渲染
库选型
wavesurfer.js（推荐）
支持 peaks 数据直接渲染；
内置进度条、缩放、区域标记。
自研 Canvas 渲染
灵活可控，但开发周期长。
组件设计
WaveformViewer
props: audioUrl, peaksData, currentTime, onSeek
事件：点击波形跳转、区间选择。
与 SubtitleOverlay 联动：在波形上高亮当前字幕区间。
3.4 播放器联动
currentTime 同步
播放器每次 timeupdate 事件 → 更新波形游标位置。
seek 操作
用户点击波形 → player.seekTo(time).
A-B 循环
用户在波形上拖动选择区间；
onRegionSelected(start, end) → 播放器设置循环模式。
- 界面交互
全局波形：默认显示完整音频缩略波形。
局部波形（可选）：切换为“当前字幕窗口”模式，只展示前后 10 秒。
字幕联动：
当前字幕背景高亮波形区域；
鼠标 hover 波形 → tooltip 显示字幕文本。
交互示例：
单击：跳转。
拖动：创建循环区间。
双击：清除循环。
- 性能与优化
大文件优化：
生成多分辨率波形数据（低分辨率用于缩略图，高分辨率用于局部放大）。
wavesurfer.js 自带虚拟渲染，支持长音频。
内存优化：
波形数据存 JSON，前端只加载需要的部分。
渲染优化：
使用 requestAnimationFrame 更新播放游标，避免频繁 DOM 更新。
- 非功能需求
跨平台一致性：macOS / Windows / Linux 显示效果统一。
本地化：UI 文字需支持中英文切换。
无障碍：颜色选择需考虑色盲用户（提供浅色/深色主题适配）。
- 未来扩展
多轨波形（音轨选择）。
语音分离后显示不同声道的波形（便于区分角色）。
与 AI 自动切句联动（自动生成字幕时间戳并在波形上标注）。
👉 总结：
方案上推荐 后端/本地生成 waveform.json → 前端 wavesurfer.js 渲染 → 与字幕/播放器联动，这是开发成本和性能的最佳平衡。