98 lines
5.1 KiB
Markdown
98 lines
5.1 KiB
Markdown
# LFMusic
|
||
|
||
一款基于 **Tauri 2 + Vue 3 + TypeScript** 的跨端音乐播放器,主打 **Android 本地播放**与 **USB DAC bit-perfect 直出**,同时支持飞牛 fnOS NAS 曲库与手机遥控。
|
||
|
||
## 功能概览
|
||
|
||
应用包含四个主 Tab:
|
||
|
||
| 模块 | 说明 |
|
||
| --- | --- |
|
||
| **曲库**(LibraryView) | 本地音乐库:扫描共享存储 Music/Download 目录,`lofty` 提取元数据/内嵌封面,SQLite 索引;支持歌曲/专辑/歌手三种视图、封面墙、扫描进度实时推送 |
|
||
| **飞牛**(FeiniuView) | 飞牛 fnOS 音乐曲库接入:登录、曲库浏览(含 DSD 格式徽标)、歌词、封面;曲目经本机 axum 流代理(支持 Range 透传)播放,DSD 系列/加密格式正确标记 |
|
||
| **遥控**(RemoteView) | 手机遥控客户端:UDP beacon 自动发现(`:26123`)、Rust 侧配对(绕开 WebView CORS)、WebSocket 双向控制(播放/暂停/切歌/进度) |
|
||
| **输出**(UacView) | USB DAC bit-perfect 直出:UsbManager 授权 → fd 桥接 libusb → UAC 描述符解析与能力枚举 → iso 传输引擎 + symphonia 解码(PCM 直喂 DAC),支持音量控制 |
|
||
|
||
播放层为**编排式设计**:`tauri-plugin-native-audio`(Media3 ExoPlayer / AVPlayer)只提供原语,队列与播放模式(顺序/随机)由 Rust 侧 `player.rs` 统一决策,所有命令返回最新队列状态。
|
||
|
||
## 技术栈
|
||
|
||
- **前端**:Vue 3(`<script setup>`)+ TypeScript + Pinia + Tailwind CSS v4 + Vite + lucide-vue-next + vue-sonner
|
||
- **后端**:Tauri 2(Rust)——axum、reqwest、lofty、walkdir、rusqlite(bundled)、symphonia、rusb/libusb1-sys
|
||
- **移动端**:Android(Media3 ExoPlayer 原生播放、Kotlin 桥接插件);桌面端同步支持
|
||
- **包管理**:bun(`bun.lock`)
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
src/ # 前端(Vue + TS)
|
||
├── views/ # 四大页面:LibraryView / FeiniuView / UacView
|
||
├── components/ # MiniBar(迷你播放条)、player/(全屏播放器、队列)
|
||
├── stores/ # Pinia:playerStore(播放状态真源镜像)、feiniuStore
|
||
└── lib/ # audio 初始化、uac、remote-proto(遥控协议类型)、
|
||
# format / img / permissions 等工具层
|
||
|
||
src-tauri/
|
||
├── src/
|
||
│ ├── library.rs # 本地曲库:扫描 + 元数据 + SQLite 索引
|
||
│ ├── player.rs # 播放编排:队列 + 播放模式决策(真源)
|
||
│ ├── feiniu/ # 飞牛 fnOS:登录签名、曲库 API、axum 流代理
|
||
│ ├── remote.rs # 遥控:beacon 监听 + 配对(Rust 侧 POST)
|
||
│ └── uac/ # UAC:描述符解析、iso 传输引擎、播放控制
|
||
├── media-plugin/ # 自研「media」插件壳:Android 媒体权限 ACL 载体
|
||
├── usb-plugin/ # 自研「usb」插件壳:Kotlin UsbPlugin 桥(fd 桥接)
|
||
├── capabilities/ # Tauri ACL 权限清单
|
||
└── tauri.conf.json # asset 协议 scope(封面)、bundle 配置
|
||
```
|
||
|
||
关键设计约定:
|
||
|
||
- **协议类型双端对齐**:`src/lib/remote-proto.ts` 与 Rust `remote.rs` 手写镜像,字段变更须同步两处。
|
||
- **飞牛模块字段级对齐**:与参考项目 Thing 的 `music/feiniu/` 保持同一套 NAS API 口径,双端不得私自漂移。
|
||
- **播放 URL 同字段语义**:NAS 曲目 `path` 即本机代理 URL,与本地曲库绝对路径一致,编排层零分支。
|
||
- **凭证存储**:token 存应用私有目录(`feiniu_tokens.json` / `remote_device.json`),keyring 升级留待后续。
|
||
|
||
## 开发
|
||
|
||
### 环境要求
|
||
|
||
- [bun](https://bun.sh)(或 Node.js ≥ 22)
|
||
- [Rust](https://rustup.dev)(stable)
|
||
- Android:Android Studio + SDK/NDK(Tauri 2 移动端开发环境,参考 [Tauri Android 文档](https://tauri.app/start/prerequisites/))
|
||
|
||
### 常用命令
|
||
|
||
```bash
|
||
# 安装依赖
|
||
bun install
|
||
|
||
# 前端开发服务器(Vite,端口 1420)
|
||
bun run dev
|
||
|
||
# 类型检查 + 前端构建
|
||
bun run build
|
||
|
||
# 桌面端开发(自动拉起 Vite)
|
||
bun tauri dev
|
||
|
||
# 桌面端打包
|
||
bun tauri build
|
||
|
||
# Android 开发 / 打包
|
||
bun tauri android init # 首次
|
||
bun tauri android dev
|
||
bun tauri android build
|
||
```
|
||
|
||
### 注意事项
|
||
|
||
- **Android 媒体权限**:本地曲库扫描需要 `READ_MEDIA_AUDIO` 授权,应用内会引导申请。
|
||
- **加密格式**:文件名含 `kgm` / `ncm` / `mflac` 等加密标记的文件会被扫描自动跳过(无法解码)。
|
||
- **封面加载**:走 Tauri asset 协议,scope 限定为 `$APPDATA/covers/**`。
|
||
- **NAS 自签名证书**:飞牛连接使用 rustls + `danger_accept_invalid_certs`,适配 NAS 自签名 HTTPS。
|
||
- **UAC 独占**:播放期间 USB 接口被引擎独占 claim,停止后需重新「接入」设备。
|
||
|
||
## IDE 推荐
|
||
|
||
- [VS Code](https://code.visualstudio.com/) + [Vue - Official](https://marketplace.visualstudio.com/items?itemName=Vue.volar) + [Tauri](https://marketplace.visualstudio.com/items?itemName=tauri-apps.tauri-vscode) + [rust-analyzer](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer)
|