5.1 KiB
5.1 KiB
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与 Rustremote.rs手写镜像,字段变更须同步两处。 - 飞牛模块字段级对齐:与参考项目 Thing 的
music/feiniu/保持同一套 NAS API 口径,双端不得私自漂移。 - 播放 URL 同字段语义:NAS 曲目
path即本机代理 URL,与本地曲库绝对路径一致,编排层零分支。 - 凭证存储:token 存应用私有目录(
feiniu_tokens.json/remote_device.json),keyring 升级留待后续。
开发
环境要求
- bun(或 Node.js ≥ 22)
- Rust(stable)
- Android:Android Studio + SDK/NDK(Tauri 2 移动端开发环境,参考 Tauri Android 文档)
常用命令
# 安装依赖
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,停止后需重新「接入」设备。