Files
LFMusic/README.md
T
2026-09-28 00:20:16 +08:00

98 lines
5.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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)