Otter Music

水獭音乐

基于 GD Studio's API 的多音源聚合音乐播放器

核心功能

• 多音源聚合与回退：支持多源检索与播放失败回退（本地下载/缓存/直连/代理/下一首）。
• 智能音源自动匹配：可自动切换到可用免费音源，并同步队列/歌单/喜欢状态。
• 歌单广场与播客：支持网易云歌单、我的歌单，以及本地 RSS 播客入口。
• 歌单管理增强：支持搜索、去重、导出、封面设置、URL 添加歌曲，支持主流音乐平台的歌单导入。
• 下载管理: 支持选择下载音质、下载目录、是否嵌入歌词或封面
• 播放生态：支持播放列表、最近播放、个人歌单、歌词显示、音质选择、倍速调节、睡眠定时、主题切换与数据同步配置。
• 移动端体验完整：支持 PWA 安装、Android 打包与 Media Session 集成，网页端也能接近原生体验。

数据同步功能：通过管理员手动分配的 SYNC_KEY 接入。存储基于 Cloudflare KV（上限 25 MB），单用户理论可稳定同步 5 万首歌曲

音源支持

[!NOTE] 兼容性说明

最低支持版本：minSdkVersion = 24 (Android 7.0)

若出现界面排版错乱、图标异常等问题，请先更新 Android System WebView 至较新版本（建议 WebView 100+ 的版本）。

[!IMPORTANT] 在线体验：Otter Music

支持 PWA，可添加到主屏幕（iOS 请使用 Safari）

快速开始

npm install
npm run dev

常用脚本

# 构建
npm run build

# 类型检查
npm run typecheck

# 代码检查
npm run lint

# 测试
npm run test

Android 构建

# 生成资源
npm run resources

# 首次添加 Android 平台
npm run cap:add:android

# 同步 Android 工程
npm run cap:sync:android

# 构建 Debug APK
npm run build:android:debug

Debug APK 输出路径：

• android/app/build/outputs/apk/debug/app-debug.apk

项目结构

src/
├── components/                 # 页面与业务组件
├── hooks/                      # 音频加载相关 Hook
├── lib/                        # 核心能力（重点）
│   ├── music-api.ts            # 统一音乐能力入口（搜索/URL/歌词/封面）
│   ├── audio-match.ts          # 自动换源与匹配结果回写
│   ├── api/                    # 服务端配置、同步、更新、播客接口
│   ├── bilibili/               # B站 API 客户端与播放适配
│   ├── kugou/                  # 酷狗 API 客户端
│   ├── kuwo/                   # 酷我 API 客户端
│   ├── migu/                   # 咪咕 API 客户端
│   ├── netease/                # 网易云 API 适配层
│   ├── qqmusic/                # QQ音乐 API 客户端
│   ├── music-provider/         # Provider 抽象与实现
│   ├── sync.ts                 # 数据同步核心逻辑
│   ├── storage-*.ts            # 存储适配与统一存储管理
│   ├── clipboard.ts            # 跨平台剪贴板
│   ├── crypto-storage.ts       # 加密存储
│   └── utils/                  # 缓存、下载、检索、歌名匹配等工具
├── plugins/                    # Capacitor 插件封装
├── routes/                     # 路由定义
├── store/                      # Zustand 全局状态
└── types/                      # 类型定义
functions/                 # Cloudflare Workers 后端
shared/                     # 跨端共享类型

📦 部署指南 (Cloudflare Pages)

1. 创建项目：Fork 本仓库，在 Cloudflare Dashboard 创建 Pages 项目。
2. 构建配置：
3. Build command: npm run build
4. Build output directory: dist
5. 环境变量：
6. PASSWORD: 设置你的管理员密码，用于管理SYNC_KEY（必须）
7. KV 绑定：
8. 创建 KV Namespace 命名为 oh_file_url
9. 在 Pages 设置中绑定该 KV，变量名设为 oh_file_url

自建后端可在前端页面「设置 → API 地址」中填入自定义域名。

https://<你的域名>/admin 路径用于管理 SYNC_KEY。

TODO

...

Not TODO

• 不接入 JOOX、KUWO 等官方接口：当前网易云官方接口够用，无需增加复杂度；接入 JOOX 还需要做代理
• 不接入 musicfree/洛雪 的插件生态（可以手动维护其音源）
• 不做网易云「每日推荐」（已有「私人雷达」）
• 不做 B 站 UP 主歌手页（风控校验容易失败）
• 不做视频 MV 模式（避免臃肿，专注于听歌）
• 不做自定义缓存功能（开关、歌曲缓存最大占用/个数、缓存过期时间），因为难以控制 Web View 默认的 Disk Cache
• 不实现音效选择：Web 端限制多，且收益低

参考资料

• GD Studio：免费音源 API 服务支持
• 洛雪音乐音源
• Listen1：网易云/咪咕/B站官方接口实现参考

🤝 贡献

欢迎提交 Issue 或 Pull Request！

免责声明

本项目不存储任何音频资源，接口均来自互联网公开资料，仅供技术交流。

严禁商业用途，由此产生的版权风险由使用者自行承担。

License

MIT