功能详解
听咚咚把"听本地音乐"这件事做扎实、做顺手。下面按功能模块详细介绍每个能力，包括可选项和默认行为。
本地音乐扫描
扫描机制
听咚咚通过 Android 系统的 MediaStore 扫描设备里的音频文件，所有歌曲信息（标题、歌手、专辑、时长、文件大小、所在目录）都来自文件本身，然后存进本地数据库。
- 增量扫描：每次启动只拉取自上次扫描以来新增或修改过的文件，避免每次全量扫描，速度快、耗电低。
- 目录来源（SAF）：用系统目录选择器添加你想扫描的文件夹，App 只会在你授权的目录范围内读取，不碰其他文件。
- 自动续扫：系统媒体库更新后，下次打开 App 会自动补上新歌；也可以在「音乐来源」页手动点重新扫描。
音乐来源管理
在 侧边菜单 → 音乐来源 里管理扫描目录，每个来源支持：
| 操作 | 说明 |
|---|---|
| 添加目录 | 用系统选择器选一个文件夹加入扫描范围 |
| 启用/停用 | 开关控制是否参与扫描，停用后该目录的歌不再显示 |
| 设置类型 | 给目录标记媒体类型（音乐/播客/录音/学习），扫描进来的歌自动归类 |
| 删除来源 | 移除该扫描目录 |
说明：如果一个目录都不加，App 会扫描设备全部音频；加了目录后只在所选范围内扫描。
媒体分类
主页支持按媒体类型筛选，内置四类，也可以在 设置 → 通用设置 → 管理分类 里自定义：
| 类型 | 默认 key | 用途 |
|---|---|---|
| 音乐 | music | 一般歌曲，默认显示这一类 |
| 播客 | podcast | 播客节目 |
| 录音 | recording | 自己录的音频 |
| 学习 | study | 学习材料、听力素材 |
主页顶部的筛选条可以一键「全部」或勾选某几类组合显示。
播放器
播放控制
播放页（点迷你播放器展开）和迷你播放器都能控制播放：
- 播放/暂停：迷你播放器右下角圆形按钮、播放页中间大圆按钮。
- 上一首 / 下一首：播放页左右两个按钮；迷你播放器支持左右拖动切歌；播放页也支持左右滑动翻页切歌。
- 进度跳转：拖动播放页的细进度条，或点完整歌词页的任意一行跳到该时间点。
- 当前歌曲信息：播放页顶部显示歌名和歌手，点「更多」可以打开歌曲操作菜单。
播放模式
播放页左下角的模式按钮，循环切换三种模式：
| 模式 | 说明 |
|---|---|
| 随机播放 | 打乱队列顺序随机播 |
| 单曲循环 | 当前这一首播完自动重播 |
| 顺序播放 | 按列表顺序依次播完 |
主页顶部的快捷播放按钮也支持「全部播放」「随机播放」「顺序播放」三种起播方式，点一下从当前列表第一首开始进队列。
播放队列
播放页点「播放列表」图标打开队列面板，可以看到完整的播放队列、当前正在播放的高亮显示，支持拖动排序、移除单首、清空队列。队列会随播放自动续接，也能跨页面保持。
定时关闭
播放页点「定时」图标设置睡眠定时：
- 预设时长：15 / 30 / 45 / 60 分钟，一键选择。
- 自定义时长：拖动滑块在 1–120 分钟之间任意设置。
- 延长到整首歌播完：开启后，到点时如果当前歌曲还没播完，会等这首歌自然结束再暂停，不会拦腰截断。
- 设置后页面显示剩余倒计时，可随时取消。
后台播放与通知
听咚咚用 Android 的前台媒体服务播放，切到别的 App 或锁屏都不会中断。系统通知栏会显示一个媒体控制通知，包含上一首/播放暂停/下一首，锁屏界面也有同样的控制。
歌单管理
创建和编辑
- 新建：侧边菜单点「新建歌单」，或在添加歌曲时选「新建歌单」。需要填名称，并从内置封面图标里选一个。
- 重命名 / 删除：在 侧边菜单 → 管理歌单 里操作。
- 添加歌曲：单首歌「更多 → 添加到歌单」；主页多选模式勾选后点「加歌单」；也可以新建歌单的同时把当前选中的歌一并加进去。
- 移除歌曲：进入歌单详情，单首歌「更多 → 从歌单移除」。
歌单展示
侧边菜单直接列出所有歌单，前面是封面图标，后面是歌曲数量。点进歌单详情看到完整歌曲列表，操作方式和主页一致（播放、多选、删除等）。
收藏与历史
我的收藏
每首歌都可以标记「喜欢」，标记后集中在 侧边菜单 → 我的收藏 里。支持多选批量收藏：主页进入多选模式勾选多首，点底部「收藏」一次搞定。收藏状态在全 App 同步，播放页、列表里都会显示红心。
听歌历史
侧边菜单的「听歌历史」记录你最近听过的歌，按播放时间倒序排列，方便回找刚才听过、想再听一遍的曲子。
资料库浏览
侧边菜单的「资料库」从不同维度浏览你的曲库：
| 视图 | 维度 | 说明 |
|---|---|---|
| 专辑 | album + artist | 按专辑分组，点进去看专辑下所有歌 |
| 文件夹 | folderPath | 按文件所在目录分组 |
| 媒体类型 | type | 按音乐/播客/录音/学习分类 |
专辑视图可以在 设置 → UI 设置 里切换成「网格」或「列表」两种排版。
歌词显示
歌词来源
听咚咚只读取音乐文件内嵌的歌词，不联网下载。支持的写入位置：
| 文件格式 | 歌词字段 |
|---|---|
| MP3 等（ID3v2） | USLT（同步/非同步歌词） |
| FLAC | LYRICS / UNSYNCEDLYRICS / SYNCEDLYRICS 等 Vorbis Comment 字段 |
第一次播放某首歌时，App 会解析文件读出歌词并存进本地缓存，之后命中缓存秒开。
歌词显示方式
播放页有两种看歌词的方式：
- 封面页底部预览：封面下方显示当前行和前后各一句，点击这块区域可切到完整歌词页。
- 完整歌词页：左右滑动封面区切换。当前行高亮加粗，逐字按演唱进度点亮（卡拉OK 效果），自动滚动定位。点任意一行可跳到那一句。
没有歌词的歌会显示「这首歌暂时没有歌词」。可以用「音乐标签」之类的工具把歌词写进文件，回 App 重扫即可。
搜索
主页右上角搜索图标进入搜索页：
- 支持按歌名、歌手、专辑关键词搜索本地曲库。
- 专辑匹配结果单独列在最上面，方便直接进专辑。
- 搜索结果和主页一样支持播放、多选、更多操作。
- 输入框为空时显示引导，输入后实时匹配。
个性化设置
设置分四个分组，覆盖外观、曲库、播放和高级。
通用设置
| 选项 | 可选值 | 说明 |
|---|---|---|
| 主题 | 跟随系统 / 浅色 / 深色 | 全局配色模式 |
| 主页显示分类 | 多选媒体类型 | 控制主页显示哪几类音频 |
| 管理分类 | — | 新建、重命名、排序、删除自定义媒体类型 |
UI 设置
| 选项 | 可选值 | 默认 | 说明 |
|---|---|---|---|
| 封面形状 | 圆角 / 圆形 | 圆角 | 全局封面外观 |
| 播放页背景 | 纯色 / 渐变 / 毛玻璃 | 渐变 | 毛玻璃为 PRO 功能 |
| 专辑视图 | 网格 / 列表 | 网格 | 资料库专辑页排版 |
播放设置
| 选项 | 默认 | 说明 |
|---|---|---|
| 自动播放音乐 | 开 | 打开 App 时继续播放上次的音乐和进度 |
| 点击歌曲直接打开播放页 | 关 | 开启后点列表歌曲会播放并跳进播放页 |
支持与高级
| 入口 | 用途 |
|---|---|
| 导出日志 | 把本地日志发出来，方便排查启动/扫描/播放问题 |
| 播放页配色实验室 | 调试封面提取色和白色文字效果 |
| 工程调试 | 清除歌词/封面缓存、强制重扫，排查标签问题 |
账号与权益
听咚咚不强制登录，本地音乐库和离线播放完全不受影响。登录咕咚账号可以解锁跨应用通用的 PRO 权益，主要带来播放页毛玻璃背景等高级外观。
- 入口：设置 → 账号与权益，或侧边菜单的「账号」。
- 权益：免费版和 PRO 两档，沿用和 MusicPlus 相同的套餐体系。
- 账号信息页支持修改昵称、查看账号信息、退出登录。
横屏与沉浸式
- 横屏自适应：转成横屏时，侧边菜单自动变成常驻侧边栏，迷你播放器保持全屏宽，不用反复点开菜单。
- 沉浸式状态栏/导航栏：边到边显示，状态栏和导航栏图标颜色会跟着主题（浅色/深色）自动切换。