应用采用百度网盘开放平台的授权码模式(Authorization Code)访问网盘,使用前需先申请应用并完成一次授权。
第三方应用只能访问网盘中的「我的应用数据 / <应用名> /」目录,本项目默认对应 /apps/musicplayer。按以下四步完成申请:
| 字段 | 填写内容 | 说明 |
|---|---|---|
| 应用名称 | musicplayer | 决定网盘授权目录名,必须与 App 内常量一致 |
| AppKey | 开放平台生成 | 应用标识,配置到「设置 → 百度网盘 → AppKey」 |
| SecretKey | 开放平台生成 | 应用密钥,配置到「设置 → 百度网盘 → SecretKey」 |
| 权限范围 | basic、netdisk | basic 用于获取用户信息,netdisk 用于访问网盘文件 |
| 回调地址 | oob | out-of-band 模式,授权后手动复制授权码 |
应用只能读写自己名下的应用目录,目录结构由你自由组织,App 内按目录原样浏览:
我的应用数据/
└── musicplayer/ ← 应用根目录(对应 /apps/musicplayer)
├── 华语流行/
│ ├── 周华健 - 朋友.flac
│ └── 刘德华 - 冰雨.mp3
├── 欧美经典/
│ └── ...
└── 单曲/
└── 梦驼铃.wav
# 上传方式:百度网盘网页端 / 客户端,进入「我的应用数据 → musicplayer」上传
# App 内「网盘」页会自动打开该目录,支持进入子目录与返回上级
lib/pages/netdisk/netdisk_path.dart 中的 kDefaultNetdiskAppName),否则会提示「路径不在允许访问范围内」。
该页面集中管理密钥、授权与凭证迁移:
点击「打开授权页」,应用携带 AppKey 与 redirect_uri 打开百度登录页。
使用要访问网盘的百度账号登录,确认授权范围并同意。
页面会显示一段授权码(code),复制它。
回到应用粘贴授权码,点击「授权」。应用用授权码换取 access_token / refresh_token 并安全保存,token 过期自动刷新。
状态变为「已授权」后即可浏览网盘并播放;更换账号点击「清除授权」后重新执行。
导出的内容使用口令加密,可在另一台设备粘贴或扫码导入,免去重复申请与授权:
| 操作 | 步骤 |
|---|---|
| 导出凭证 | 旧设备点击「导出凭证」→ 设置口令 → 复制密文或保存二维码 |
| 导入凭证 | 新设备点击「导入凭证」→ 粘贴密文或扫码 → 输入同一口令完成导入 |
| 现象 | 原因与处理 |
|---|---|
| 路径不在允许访问范围内 | 文件不在「我的应用数据 / <应用名>」内,或应用名与默认目录名不一致。确认应用名为 musicplayer。 |
| 权限不足 / 应用未开通网盘权限 | 开放平台应用未勾选 netdisk,或应用审核尚未通过。 |
| access_token 无效 / 未授权 | 点击「清除授权」后重新执行授权流程。 |
| 命中防盗链 | 请求需使用 pan.baidu.com 作为 User-Agent,本项目已内置。 |
| 下载失败提示重新授权 | 授权已失效(HTTP 401 / 403),按提示重新授权即可。 |
| 在线播放卡顿 | 百度网盘存在限流,建议先下载到本地再播放;可在通用设置中降低并发数。 |
AI 能力使用你自己的账号,费用与数据均自行掌握。共分三个场景:大模型(LLM)、朗读模型(TTS)与语音识别(ASR),接口均为 OpenAI 兼容服务。
| 场景 | 作用 | 接口要求 | 未配置时 |
|---|---|---|---|
| 大模型 LLM | AI 聊天、自然语言点歌、元信息补全、歌曲背景故事与解读、AI 生成封面 | OpenAI 兼容,以 /v1 结尾,支持 POST /chat/completions |
聊天、AI 补全、背景故事均不可用,相关入口隐藏 |
| 朗读 TTS | 把文字朗读出来:播放歌曲时朗读背景故事旁白,也可手动朗读内容 | OpenAI 兼容,支持 POST /audio/speech,需填 voice 音色名 |
回退系统朗读;系统朗读不可用时隐藏朗读入口 |
| 语音识别 ASR | 把语音转成文字:聊天页按住麦克风说话,自动转文字后发送 | OpenAI 兼容,支持 POST /audio/transcriptions |
聊天页不显示麦克风按钮 |
打开「启用 AI 能力」后,在页面中分别进入三个场景的配置页:
/v1 结尾deepseek-chat、gpt-4o-mini页面底部提供「测试连通」「分享」「导入」「保存」四个操作,配置可导出到其他设备复用。
POST /v1/images/generations 的图像模型名(默认 dall-e-3)。在歌曲解读页或封面菜单点击「AI 生成封面」,由模型根据歌曲背景与故事创作原创封面设计,不检索、不复制任何现有专辑封面。
大模型(LLM)是 AI 能力的核心后端,聊天、元信息补全与歌曲解读共用同一份配置。启用并填好 Key 后,它通过以下三条链路生效:
在聊天页说「放一首周华健的朋友」,模型解析意图后调用本地 / 网盘搜索并播放,还能批量下载、管理队列、联网查询。
播放或导入曲目时,后台把曲名 / 歌手 / 专辑交给模型,回填元信息并生成歌曲解读,结果写回本地库。封面不自动生成,可在封面菜单或解读页手动让 AI 创作原创封面。
进入解读页查看创作背景、作者故事、歌词解读、一句话摘要与情感 / 主题标签,可一键朗读(TTS)。
| 触发方式 | 入口 / 时机 | 生效条件 | 产出 |
|---|---|---|---|
| 主动对话 | 播放页顶部「悦己搭子」聊天页 | AI 总开关 + 大模型已配置 | 点歌、搜索、下载、队列控制、联网问答 |
| 播放时自动补全 | 开始播放某首曲目时后台触发 | AI 总开关 + 「播放时自动补全」开启 | 元信息 + 歌曲解读 |
| 导入时自动补全 | 新曲目入库后批量投递 | AI 总开关 + 「导入时自动补全」开启 | 元信息 + 歌曲解读 |
| 手动补全 / 更新 | 解读页「强制更新」按钮 | AI 总开关 + 大模型已配置 | 重新生成歌曲解读 |
| 背景故事朗读 | 播放曲目时自动朗读旁白 | 总开关 + 「自动播放背景故事」+ TTS 可用 | 语音旁白(每首只读一次) |
| 类别 | 内容 |
|---|---|
| 元信息 | 发行日期、流派、语言、国家、唱片公司、歌手、专辑(已有内容不覆盖) |
| 歌曲解读 | 创作背景、作者故事、歌词解读、一句话摘要、情感标签、主题标签 |
| 歌词文本 | 编辑页按需生成原创同主题草稿,或转写本地音频;仅作参考,需用户自行打轴 |
| AI 封面(手动) | 在封面菜单或解读页点击「AI 生成封面」,由图像模型根据歌曲背景与故事创作原创设计;不复刻现有专辑封面 |
曲目信息(标题 / 歌手 / 专辑 / 歌词)
│
▼
大模型(LLM,使用你自己的 API Key)
│
┌────┴─────────┐
▼ ▼
元信息 歌曲解读(背景 / 作者 / 歌词 / 摘要 / 标签)
│ │
└──────┬───────┘
▼
写回本地数据库(幂等:已有内容不重复补全)
│
├──▶ 播放页 / 本地库展示元信息
└──▶ 解读页查看内容,并可朗读(TTS)
注:封面不自动生成;可在封面菜单或解读页手动让 AI 基于歌曲背景创作原创封面,
不使用任何现有专辑封面或艺人肖像(版权合规)。
聊天页是 AI 能力最直接的入口。它不只会点歌,还会读懂你的听歌习惯,用有温度的方式和你聊天——像搭子,而不是工具。
| 条件 | 说明 |
|---|---|
| AI 总开关已开启 | 「设置 → AI → 启用 AI 能力」必须打开,否则不发起任何请求 |
| 大模型已配置 | Base URL、模型名、API Key 齐全,聊天入口才会出现 |
| 网络可达 | 对话与联网搜索需要网络;解析点歌意图同样需要调用模型 |
| 能力 | 说明 | 示例说法 |
|---|---|---|
| 找歌搜索 | 在本地曲库与网盘应用目录中搜索,只返回候选不播放 | 「有没有周华健的朋友」 |
| 点歌播放 | 本地歌曲直接播放;网盘歌曲自动下载完成后播放 | 「放一首海阔天空」 |
| 按来源播放 | 播放收藏、指定歌单、全部本地或当前队列 | 「播放我的收藏」 |
| 加入队列 | 把歌曲追加到播放队列,不打断正在播放的歌 | 「这首后面接着放」 |
| 播放控制 | 暂停、继续、上一首、下一首、停止 | 「下一首」「暂停一下」 |
| 批量下载 | 把网盘歌曲下载到本地,可指代上一次搜索结果 | 「把刚搜到的都下载下来」 |
| 联网搜索 | 查询最新新闻、人物近况、网站内容,并标注来源 | 「林俊杰最近有什么动态」 |
| 热点新闻 | 聚合你在设置中勾选的新闻来源,查看当前热点 | 「今天有什么热点」 |
| 语音输入 | 按住麦克风说话自动转文字(需配置 ASR) | 语音点歌 |
| 图片输入 | 上传图片提问(需模型支持视觉) | 发图问「这是什么专辑」 |
对话时,应用会从本机听歌数据聚合一份画像注入上下文,让回答贴合你真实的偏好与状态:
基于近 90 天播放统计,提取常听歌手与偏好风格。
来自歌曲解读标签,识别你偏好的情绪与主题。
最近 30 天在听的曲目与情绪状态,用于接住当下的话题。
凭借这份画像,它能在你说「最近有点怀念」时,顺着你的记忆与心情聊下去,推荐真正对味的歌——这正是「搭子」与「工具」的区别。
图中的搭子结合「最近常听 Beyond、周华健、刘德华、张雨生」与「情绪里带着怀念和一点孤独」,按心情分三组给出推荐,并附上一句推荐理由。
你:最近有点想以前的事,放点能回忆的歌
搭子:看你最近常听 Beyond、周华健、刘德华,情绪里也带着怀念。
给你按心情配几首 ——
· 周华健《朋友》 陪伴与释怀
· Beyond《海阔天空》 理想和自由那口气
· 张雨生《大海》 辽阔,把心事交给海
(点击候选即可播放)
你:把刚才这几首都下载下来
搭子:已加入下载队列,共 3 首;完成后会优先播放本地文件。
聊天、元信息补全、歌曲解读共用同一份大模型配置;TTS 负责把解读念出来,ASR 负责把你的话转成文字。四者配合,构成完整的 AI 体验。
| 字段 | 说明 |
|---|---|
| Base URL | OpenAI 兼容服务地址,需支持 POST /audio/speech |
| 模型名称 | 默认 tts-1,也可填写服务商提供的其他语音合成模型 |
| voice 音色 | 音色名称,如 alloy、nova 等,按服务商支持填写 |
| API Key | 该服务的密钥 |
| 字段 | 说明 |
|---|---|
| Base URL | OpenAI 兼容服务地址,需支持 POST /audio/transcriptions |
| 模型名称 | 默认 whisper-1 |
| API Key | 该服务的密钥 |
录音在本地采集为 16kHz 单声道音频后上传识别,识别结果直接填入聊天输入框。配置成功后,聊天页会出现麦克风按钮。
# 大模型(LLM)—— 用于聊天 / 元信息补全 / 背景故事 Base URL :https://api.deepseek.com/v1 模型名称 :deepseek-chat API Key :sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx (替换为你自己的密钥) # 朗读模型(TTS)—— 文字转语音 Base URL :https://api.openai.com/v1 模型名称 :tts-1 voice :alloy API Key :sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx # 语音识别(ASR)—— 语音转文字 Base URL :https://api.openai.com/v1 模型名称 :whisper-1 API Key :sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
| 现象 | 原因与处理 |
|---|---|
| AI 入口不见了 | 未启用 AI 能力或未配置对应场景的 API Key,相关入口会自动隐藏。 |
| 测试连通失败 | 检查 Base URL 是否以 /v1 结尾、Key 是否有效、网络是否可达。 |
| 朗读没有声音 | TTS 未配置时会回退系统朗读;系统朗读不可用则隐藏朗读入口,请在系统设置中安装语音包。 |
| 聊天页没有麦克风 | ASR 未配置。完成语音识别配置后按钮才会出现。 |
| 用量超出预期 | 关闭「导入时自动补全」可减少不常听歌曲的额度消耗;在用量统计中查看消耗明细。 |
「设置」页其余配置项一览,按需调整即可。
| 设置项 | 说明 | 建议 |
|---|---|---|
| 通用 → 自动下载 | 播放网盘曲目时自动下载到本地 | 建议开启,下载完成后优先播放本地文件 |
| 通用 → 启动时自动下载 | 应用启动后自动继续下载队列中未完成的任务 | 按需开启 |
| 通用 → 同时下载数 | 并发下载任务数量 | 百度网盘免费会员且 API 限流,建议限制在 2 个 |
| 播放 | 播放模式、音量与后台播放行为 | 按收听习惯设置 |
| 歌词 | 歌词显示、导入本地歌词、打轴后行为 | 打轴后可选择继续播放或暂停 |
| 均衡器 | 音频均衡与音效调节 | 按耳机 / 音箱特性微调 |
| 风格 | 播放皮肤(频谱柱 / 梦幻星空)、深色浅色主题、主题色、页面动效 | 选择护眼配色与顺手的过渡效果 |
| 存储 | 本地缓存磁盘使用上限与清理策略 | 按设备剩余空间设置上限 |
| 设备标识 | 用于创建激活码的设备标识 | 仅在本地展示,请勿对外泄露 |
| 使用技巧 | 手势与快捷操作说明 | 首次使用建议浏览 |
| 上报异常 | 查看应用运行中的异常记录 | 反馈问题时提供此信息 |
| 关于 / 用户协议 | 版本信息与用户协议 | — |
播放皮肤支持频谱柱、梦幻星空;主题支持深色 / 浅色 / 跟随系统,并提供紫、蓝、青、绿、橙、粉多套主题色。
设置本地缓存磁盘使用上限,超出后按策略清理;下载目录与缓存占用一目了然。
导入本地歌词、自动识别编码、打轴后继续播放或暂停,进度条支持毫秒级定位。
AppKey / SecretKey、access_token / refresh_token 与各场景 API Key 均保存在系统安全存储(Linux 为 libsecret,Android 为 Keystore),不会明文落盘。
导出的凭证使用口令加密,可在另一台设备粘贴或扫码导入;口令由你自行设置,请妥善保管。
运行异常记录在「设置 → 上报异常」中,便于反馈问题时定位;错误信息不写入通知栏。