一款聚合音乐播放器，整合网易云、QQ 音乐、咪咕等多个音源，具备音源自动切换、歌单跨平台导入、音频下载、滚动歌词、定时播放、RSS 播客订阅、本地音乐播放等功能。
基于 React + Capacitor 的免费音乐 App，支持多音源搜索、网易云登录、主流平台歌单导入，以及 B 站音源搜索播放，安装包仅 2.5 MB。基于 GD Studio's Online Music Platform API。
https://otter-music.pages.dev/
水獭音乐
基于 GD Studio's API 的多音源聚合音乐播放器
核心功能
- 多音源聚合与回退：支持多源检索与播放失败回退（本地下载/缓存/直连/代理/下一首）。
- 智能音源自动匹配：可自动切换到可用免费音源，并同步队列/歌单/喜欢状态。
- 歌单广场：支持网易云歌单、RSS 播客订阅、Alist 站点配置，以及 Billboard、台湾金曲奖、格莱美奖榜单查询。
- 歌单管理增强：支持搜索、去重、导出、封面设置、URL 添加歌曲，支持主流音乐平台的歌单导入。
- 下载管理: 支持选择下载音质、下载目录、是否嵌入歌词或封面（FLAC 无损按原生流式重写标签，不占 JS 内存）
- 播放生态：支持播放列表、最近播放、个人歌单、歌词显示、音质选择、倍速调节、睡眠定时、横屏播放模式、车载蓝牙歌词、桌面歌词（Android 悬浮窗）与主题切换。
- 数据备份：支持导出/导入本地 JSON 文件，以及配置 WebDAV 手动上传和恢复备份。
- 移动端体验完整：支持 PWA 安装、Android 打包与 Media Session 集成，网页端也能接近原生体验。
数据同步功能：通过管理员手动分配的
SYNC_KEY接入。存储基于 Cloudflare KV（上限 25 MB），单用户理论可稳定同步 5 万首歌曲
音源支持
| 音源 | 搜索 | 播放 | 歌词 | 歌单导入 | 备注 |
|---|---|---|---|---|---|
| 网易云音乐🌟 | ✅ | ✅ | ✅ | ✅ | GD Studio API |
| Netease | ✅ | ✅ | ✅ | ✅ | 网易云官方，搜索建议/专辑/歌手详情 |
| Joox🌟 | ✅ | ✅ | ✅ | ❌ | GD Studio API |
| B站🌟 | ✅ | ✅ | ✅ | ❌ | 支持视频分P/合集、账号登录（字幕歌词） |
| 酷我音乐 | ✅ | ✅ | ✅ | ✅ | GD Studio API |
| 咪咕音乐 | ✅ | ✅ | ✅ | ✅ | 仅移动端 |
| QQ音乐 | ✅ | ✅ | ✅ | ✅ | QQ音乐官方；需 Cookie 登录 |
| Higequ | ✅ | ✅ | ✅ | ❌ | Hi歌曲音乐网，仅标准音质 |
| Jamendo | ✅ | ✅ | ❌ | ❌ | 独立音乐人 CC 曲库，仅标准音质 |
| 酷狗音乐 | ❌ | ❌ | ❌ | ✅ | |
| 本地音乐 | ❌ | ✅ | ✅ | ❌ | 仅移动端支持 |
| 播客（歌单广场） | ✅ | ✅ | ❌ | ❌ | RSS 播客订阅，支持小宇宙链接与 OPML 批量导入 |
| Alist（歌单广场） | ✅ | ✅ | ❌ | ❌ | 仅音频，如 ASMR 站 |
Note
兼容性说明
最低支持版本：minSdkVersion = 24 (Android 7.0)
若出现界面排版错乱、图标异常等问题，请先更新 Android System WebView 至较新版本（建议 WebView 100+ 的版本）。
快速开始
npm install
npm run dev常用脚本
# 构建
npm run build
# 类型检查
npm run typecheck
# 代码检查
npm run lint
# 测试
npm run testAndroid 构建
# 生成资源
npm run resources
# 首次添加 Android 平台
npm run cap:add:android
# 同步 Android 工程
npm run cap:sync:android
# 构建 Debug APK
npm run build:android:debugDebug APK 输出路径：
android/app/build/outputs/apk/debug/app-debug.apk
项目结构
src/
├── components/ # 页面与业务组件
├── hooks/ # 播放控制与应用行为 Hook
├── lib/ # 核心能力（重点）
│ ├── music-api.ts # 统一音乐能力入口（搜索/URL/歌词/封面）
│ ├── audio-match.ts # 自动换源与匹配结果回写
│ ├── api/ # 服务端配置、同步、更新、播客接口
│ ├── alist/ # Alist 网盘 API 客户端
│ ├── apple-music/ # Apple Music 歌单导入
│ ├── awards/ # 金曲奖/格莱美奖榜单数据与解析
│ ├── billboard/ # Billboard 榜单 API 客户端
│ ├── bilibili/ # B站 API 客户端与播放适配
│ ├── higequ/ # Hi歌曲音乐网页面抓取与解析
│ ├── jamendo/ # Jamendo 网页接口客户端（免鉴权）
│ ├── kugou/ # 酷狗 API 客户端
│ ├── kuwo/ # 酷我 API 客户端
│ ├── migu/ # 咪咕 API 客户端
│ ├── netease/ # 网易云 API 适配层
│ ├── qqmusic/ # QQ音乐 API 客户端
│ ├── webdav/ # WebDAV 备份客户端
│ ├── music-provider/ # Provider 抽象与实现
│ ├── navigation/ # 详情页导航跳转逻辑
│ ├── sync.ts # 数据同步核心逻辑
│ ├── storage-*.ts # 存储适配与统一存储管理
│ ├── clipboard.ts # 跨平台剪贴板
│ ├── crypto-storage.ts # 加密存储
│ └── utils/ # 缓存、下载、检索、歌名匹配等工具
├── plugins/ # Capacitor 插件封装
├── routes/ # 路由定义
├── store/ # Zustand 全局状态
└── types/ # 类型定义
functions/ # Cloudflare Workers 后端
shared/ # 跨端共享类型
📦 部署指南 (Cloudflare Pages)
- 创建项目：Fork 本仓库，在 Cloudflare Dashboard 创建 Pages 项目。
- 构建配置：
- Build command:
npm run build - Build output directory:
dist
- Build command:
- 环境变量：
PASSWORD: 设置你的管理员密码，用于管理SYNC_KEY（必须）
- KV 绑定：
- 创建 KV Namespace 命名为
oh_file_url - 在 Pages 设置中绑定该 KV，变量名设为
oh_file_url
- 创建 KV Namespace 命名为
自建后端可在前端页面「设置 → API 地址」中填入自定义域名。
https://<你的域名>/admin路径用于管理 SYNC_KEY。
TODO
- 重构为仅安卓端，清理冗余 Web 适配代码（Web端使用Listen1插件即可，方便下载）
- 嵌入 AI DJ Claudio
Not TODO
- 不接入 JOOX、KUWO 等官方接口
- 不接入 musicfree/洛雪 的插件生态（可以手动维护其音源）
- 不做网易云「每日推荐」（已有「私人雷达」）
- 不做视频 MV 模式（避免臃肿，专注于听歌）
- 不做自定义缓存功能（开关、歌曲缓存最大占用/个数、缓存过期时间），因为难以控制 Web View 默认的 Disk Cache
- 不实现音效选择：Web 端限制多，且收益低
参考资料
- GD Studio：免费音源 API 服务支持
- Listen1：网易云/咪咕/B站官方接口实现参考
- Chartly API：金曲奖/格莱美奖 API
from https://github.com/DJChanahCJD/otter-music
No comments:
Post a Comment