ter-music 快速上手
==================

1. 启动
--------
  ter-music [选项]

  选项:
    -o, --open <路径>  启动时打开指定音乐目录或音频文件
    -d, --debug        启用调试日志
    -h, --help         显示帮助信息

  示例:
    ter-music -o ~/Music
    ter-music -o /path/to/song.mp3
    ter-music ftp://user:pass@host/path/to/music

2. 界面布局
-----------
  +---------------------------+-------------------+
  | 播放列表/队列窗格          | 歌词显示面板      |
  | (按Tab切换视图)            | (右侧，可开关)    |
  |                           |                   |
  | 控制栏（底部）             |                   |
  | [<<] [>||] [>>] [停止]    |                   |
  | [模式] [速度] [进度条]     |                   |
  +---------------------------+-------------------+
  | F1:主页 F2:设置 ... F8:帮助 F9:退出          |
  +----------------------------------------------+

3. 焦点切换
-----------
  按键           功能
  C             切换到控制栏
  L             切换到列表区
  Tab/Shift+Tab  切换文件浏览 / 播放队列视图

4. 列表区操作（文件浏览或队列）
-------------------------------
  导航:
  ↑/↓  或  j/k      选择上/下一曲
  Enter 或  Space    播放选中曲目

  播放控制:
  n                下一曲
  p                上一曲
  h                显示播放历史弹窗

  队列管理:
  a                将曲目追加到播放队列
  i                将曲目插入为队列下一首
  d                从队列中移除曲目
  D                清空整个队列
  J                将曲目在队列中下移
  K                将曲目在队列中上移

  歌单与收藏:
  A                将曲目加入自定义歌单（弹出选择列表）
  F / f            将曲目加入收藏
  O / o            打开音乐文件夹

  搜索与浏览:
  S  或  /         搜索曲目（支持拼音搜索）
  M                切换音乐库浏览器

  快捷播放模式:
  1                顺序播放
  2                单曲循环
  3                列表循环
  4                随机重复
  5                文件夹顺序

5. 控制栏操作（按C键聚焦后）
-----------------------------
  ←/→              选择控制按钮
  Space            激活按钮 / 打开弹出菜单
  ,                后退 5 秒
  .                前进 5 秒
  +/=              增加音量
  -/_              减少音量
  D                跳转到当前歌词行

  控制按钮说明:
  [<<]    上一曲
  [>||]   播放 / 暂停
  [>>]    下一曲
  [停止]  停止播放
  [模式]  播放模式（按Enter从17种模式中选择）
  [速度]  播放速度（弹出菜单：0.75x - 3.0x）
  [音量]  音量滑动条（弹出菜单）

6. 播放模式（17种）
--------------------
  基础模式（始终可用）:
    顺序播放      顺序播放，列表播完停止
    单曲循环      重复播放当前曲目
    列表循环      列表播完从头开始
    随机一次      随机播放，每曲一次不重复
    随机重复      持续随机播放

  高级模式（需SQLite库元数据）:
    文件夹*       限定在当前目录
    专辑*         按专辑标签限定
    艺术家*       按艺术家标签限定
    (* 每种都有顺序/循环/随机/随机重复变体)

  按Enter打开控制栏的[模式]按钮弹出菜单进行选择。
  在 设置 → 播放模式 中开启高级模式。

7. 功能键（F1-F9）
-------------------
  F1  主页（返回主界面）
  F2  设置（主题、路径、播放、均衡器等）
  F3  历史（浏览播放历史）
  F4  歌单（管理和创建播放列表）
  F5  收藏（查看和管理收藏的歌曲）
  F6  关于（版本和项目信息）
  F7  中/EN（切换界面语言）
  F8  帮助（本页面）
  F9  退出程序

8. 音乐库浏览器
---------------
  按 M 键切换音乐库浏览器。
  导航层级：首页 → 艺术家 → 专辑 → 曲目。
  用 ↑/↓ 选择，Enter 深入浏览。
  再次按 M 或 Esc 返回文件夹浏览。

9. 搜索功能
-----------
  在主界面按 S 或 / 键进入搜索模式。
  输入关键词后按 Enter 确认，结果即时过滤显示。
  用 ↑/↓ 选择，Enter 播放。
  按 Esc 取消搜索。
  支持拼音搜索（如输 "zhou" 可找到 "周杰伦"）。

10. 歌词显示
------------
  优先级：内嵌歌词（FFmpeg/APE 标签）> .lrc 文件 > 黑胶动画
  自动加载同目录下的 .lrc 文件。
  内嵌歌词优先显示（ID3/APE 标签中的歌词）。
  设置中可开关歌词面板。
  支持歌词对齐：居左 / 居中 / 居右。

11. CUE 分轨支持
-----------------
  FLAC/APE/WV 的 CUE 文件自动解析。
  子曲目在列表中显示 [CUE] 前缀。
  CUE 编码自动检测（可在设置中配置）：
    自动 / UTF-8 / GB18030 / GBK / BIG5 / Shift-JIS

12. 均衡器
-----------
  10 段 ISO 图示均衡器（31Hz - 16kHz）。
  在 设置 → 均衡器 中调节。
  ←/→ 选择频段，↑/↓ 调节增益（±12dB）。
  前置放大范围：±12dB。

13. 远程播放
------------
  支持 SMB/SFTP/FTP/WebDAV/HTTP 协议。
  在 设置 → 远程设备 中配置连接。
  也支持命令行直接传入远程 URL：
    ter-music ftp://user:password@host/path/

14. 歌单管理
------------
  F4 进入歌单管理。
  支持新建、重命名、删除歌单。
  在主页按 A（大写）将曲目加入自定义歌单。

15. 收藏功能
------------
  选中曲目后按 F/f 添加到收藏。
  F5 查看和管理收藏列表。

16. 专辑封面
------------
  设置中可开关专辑封面显示。
  封面以点阵图形式绘制在终端中。
  支持 PNG 和 JPEG 格式。

17. 信息栏与音频后端
---------------------
  底部信息栏显示当前音频的技术参数：
    采样率、位深、比特率、编码格式

  音频后端自动检测优先级：PipeWire > PulseAudio > ALSA
  在 设置 → 音频后端 中手动切换：
    自动 / PipeWire / PulseAudio / ALSA

18. 配置与数据
--------------
  配置文件：  ~/.config/ter-music/config.xml  （v2.2 XML 格式）
  音乐库：    ~/.config/ter-music/library.db   （SQLite）
  队列：      ~/.config/ter-music/queue.txt    （持久化队列）
  封面缓存：  ~/.config/ter-music/album_cover_cache/

  首次运行 v2.0 时会自动从 v1（config.json + JSON 文件）迁移。

19. 更多技巧
------------
  按 ? 或 h 可查看快捷键帮助（在主界面中）。
  调整终端大小后界面自动适应。
  退出时自动保存当前播放状态（可在设置中关闭）。
  Ctrl+C 安全退出。
  设置中使用 Enter 打开选项菜单（不再需要 +/- 键调节）。
