MiniMusic: A Lightweight Local Music Player

Posted Jul 13, 2026

By Guanlong Ma

14 min read

缘起

我一直在找一个真正”够用”的本地音乐播放器。

市面上的播放器，要么太臃肿——像 iTunes/Apple Music，塞满了在线服务、订阅、推荐算法，打开一个本地 MP3 都要绕半天；要么太简陋——只有一个文件列表，没有歌词、没有封面，甚至没有歌单管理。

我想要的很简单：

选一个文件夹，自动识别里面所有的 MP3
每个子文件夹自动变成一个歌单
播放的时候能看到封面和歌词
界面干净、不打扰

既然找不到，那就自己写一个。

于是，MiniMusic 诞生了。

MiniMusic 是什么

MiniMusic 是一个轻量级本地音乐播放器，用 Tauri 2 + React 18 + TypeScript + Rust 构建，优先面向 macOS，同时也支持 Windows。

它不做在线音乐，不搞推荐算法，不收集用户数据。它只做一件事：把你硬盘上的 MP3 播放好。

项目地址：GitHub

核心设计理念：文件夹就是歌单

MiniMusic 的设计哲学非常简单：

文件夹 = 歌单

你只需要把你的音乐文件按照文件夹整理好：

~/Music/
├── 周杰伦/
│   ├── 晴天.mp3
│   ├── 七里香.mp3
│   └── 稻香.mp3
├── 林俊杰/
│   ├── 江南.mp3
│   └── 一千年以后.mp3
└── 纯音乐/
    ├── River Flows in You.mp3
    └── Kiss the Rain.mp3

打开 MiniMusic，选择 ~/Music/ 目录，它会自动：

把「周杰伦」、「林俊杰」、「纯音乐」变成三个歌单
生成一个「全部歌曲」列表
读取每首歌的标题、歌手、专辑、时长
提取专辑封面
识别同目录下的 .lrc 歌词文件或 MP3 内嵌歌词

没有复杂的数据库，没有手动导入导出，一切自然发生。

功能一览

🎵 播放体验

播放控制：播放/暂停、上一首/下一首、进度拖拽、音量调节
三种播放模式：列表循环、单曲循环、随机播放
Now Playing 全屏模式：大尺寸封面 + 歌词，沉浸式体验
配置持久化：关闭再打开，自动恢复上次播放的歌单、歌曲、音量和播放模式

📝 歌词

支持同名 .lrc 歌词文件（时间轴同步高亮）
支持 MP3 内嵌歌词
无歌词时显示纯文本兜底
歌词自动滚动，当前行高亮

🎨 界面

明暗主题：浅色、深色、跟随系统，一键切换
Dock 最小化：关闭窗口时可选择最小化到 Dock 或退出
响应式布局：左侧歌单、中间歌曲列表、右侧歌词面板

技术选型：为什么是 Tauri + Rust

在开始写之前，我认真考虑过几个方案：

方案	优点	缺点
Electron	生态成熟，前端友好	打包体积大（~150MB+），内存占用高
SwiftUI	原生体验最佳	只支持 macOS，学习成本高
Flutter	跨平台，性能好	桌面端不够成熟，UI 自由度受限
Tauri	轻量（~5MB），跨平台，前端自由	需要 Rust 知识，部分系统 API 需自己封装

最终选择了 Tauri 2：

轻量：不打包 Chromium，直接使用系统 WebView（macOS 用 WKWebView，Windows 用 WebView2），安装包只有几 MB
前端自由：React + TypeScript + Vite，和写网页一样顺手
Rust 后端：需要系统级能力时（扫描目录、读取 ID3 标签、提取封面、解析歌词），用 Rust 写 Tauri Command，性能好且安全
跨平台：一套代码，macOS 和 Windows 都能跑

整体架构：

┌─────────────────────────────────────────┐
│              Tauri 2 (桌面外壳)           │
│  ┌───────────────────────────────────┐  │
│  │     React 18 + TypeScript + Vite  │  │
│  │     (UI / 播放控制 / 状态管理)      │  │
│  │         Zustand (状态管理)          │  │
│  │       HTMLAudioElement (音频)      │  │
│  └──────────────┬────────────────────┘  │
│                 │ Tauri invoke()         │
│  ┌──────────────▼────────────────────┐  │
│  │         Rust 后端能力              │  │
│  │  - 目录扫描 (scanner)              │  │
│  │  - ID3 标签解析 (id3 crate)        │  │
│  │  - 封面提取 (base64)              │  │
│  │  - 歌词读取 (lyrics)               │  │
│  │  - 配置管理 (config)               │  │
│  └────────────────────────────────────┘  │
└─────────────────────────────────────────┘

与 Netease_url + OneDrive 搭配：完整工作流

MiniMusic 本身只做播放，但它可以和另外两个工具组合，形成一套完整的个人音乐工作流：

  Netease_url           OneDrive              MiniMusic
（下载工具）────────▶（同步工具）────────▶（播放工具）
      │                    │                     │
      ▼                    ▼                     ▼
  搜索网易云           跨设备自动同步         扫描本地文件
  解析曲库             保持音乐库一致         按文件夹分歌单
  下载 MP3/FLAC        覆盖所有设备           展示封面和歌词

Netease_url：一个 Python + Flask 项目，可以搜索和下载网易云音乐曲库，支持标准到 Hi-Res 多种音质
OneDrive：把下载目录设为 OneDrive 文件夹，新歌自动同步到所有设备
MiniMusic：扫描 OneDrive 音乐目录，自动识别新歌

三个工具，一条链路，各司其职。

下载与安装

macOS (Apple Silicon)

下载 MiniMusic_0.1.0_aarch64.dmg，双击打开后将 MiniMusic 拖入 Applications 文件夹即可。

首次打开时，由于未经过 Apple 公证，可能需要在「系统设置 → 隐私与安全性」中点击「仍要打开」。

Windows (x64)

下载 MiniMusic_0.1.0_x64-setup.exe 或 MiniMusic_0.1.0_x64-setup.msi，双击安装即可。

后续计划

v0.1.0 是第一版，还有很多想做的功能：

FLAC、WAV、AAC 等更多格式支持
桌面歌词
EQ 均衡器
音频频谱可视化
自定义歌单（不依赖文件夹）
Apple Developer ID 签名和公证
自动更新

如果你有好的建议，欢迎到 GitHub Issues 提出。

许可

MiniMusic 采用非商业使用许可协议，仅限个人、非商业目的免费使用。详见 LICENSE。

最后

从想法到打包，MiniMusic 现在终于可以拿出来见人了。

它不够完美，但够用。

如果你也喜欢听本地音乐，试试看。

The Origin

I’ve always been searching for a truly “good enough” local music player.

The players on the market are either too bloated — like iTunes/Apple Music, packed with online services, subscriptions, and recommendation algorithms, where opening a local MP3 takes forever; or too bare-bones — just a file list, no lyrics, no cover art, not even playlist management.

What I wanted was simple:

Select a folder, and it automatically recognizes all MP3s inside
Each subfolder automatically becomes a playlist
See cover art and lyrics while playing
A clean, non-intrusive interface

Since I couldn’t find one, I decided to build it myself.

And thus, MiniMusic was born.

What is MiniMusic

MiniMusic is a lightweight local music player, built with Tauri 2 + React 18 + TypeScript + Rust, prioritizing macOS while also supporting Windows.

It doesn’t do online music, doesn’t have recommendation algorithms, and doesn’t collect user data. It does one thing only: play the MP3s on your hard drive well.

Project link: GitHub

Core Design Philosophy: Folders are Playlists

MiniMusic’s design philosophy is very simple:

Folder = Playlist

All you need to do is organize your music files by folder:

~/Music/
├── Jay Chou/
│   ├── Sunny Day.mp3
│   ├── Common Jasmine Orange.mp3
│   └── Rice Aroma.mp3
├── JJ Lin/
│   ├── River South.mp3
│   └── A Thousand Years Later.mp3
└── Instrumental/
    ├── River Flows in You.mp3
    └── Kiss the Rain.mp3

Open MiniMusic, select the ~/Music/ directory, and it will automatically:

Turn “Jay Chou”, “JJ Lin”, and “Instrumental” into three playlists
Generate an “All Songs” list
Read each song’s title, artist, album, and duration
Extract album cover art
Recognize .lrc lyric files in the same directory or embedded lyrics in MP3s

No complex databases, no manual import/export — everything happens naturally.

Feature Overview

🎵 Playback Experience

Playback Controls: Play/Pause, Previous/Next, progress scrubbing, volume adjustment
Three Playback Modes: List loop, single repeat, shuffle
Now Playing Full-Screen Mode: Large cover art + lyrics, immersive experience
Persistent Configuration: Close and reopen, automatically restores the last playlist, song, volume, and playback mode

📝 Lyrics

Supports .lrc lyric files with the same filename (timeline-synced highlighting)
Supports MP3 embedded lyrics
Displays text fallback when no lyrics are available
Lyrics auto-scroll with current line highlighted

🎨 Interface

Light/Dark Theme: Light, dark, follow system, one-click toggle
Dock Minimization: When closing the window, choose to minimize to Dock or quit
Responsive Layout: Left sidebar playlists, center song list, right lyrics panel

Technology Choice: Why Tauri + Rust

Before starting to code, I seriously considered several options:

Solution	Advantages	Disadvantages
Electron	Mature ecosystem, frontend-friendly	Large bundle size (~150MB+), high memory usage
SwiftUI	Best native experience	macOS only, steep learning curve
Flutter	Cross-platform, good performance	Desktop not mature enough, limited UI flexibility
Tauri	Lightweight (~5MB), cross-platform, frontend freedom	Requires Rust knowledge, some system APIs need custom wrapping

Ultimately chose Tauri 2:

Lightweight: Doesn’t bundle Chromium, uses the system WebView directly (WKWebView on macOS, WebView2 on Windows), install package is only a few MB
Frontend Freedom: React + TypeScript + Vite, as comfortable as writing web pages
Rust Backend: When system-level capabilities are needed (directory scanning, reading ID3 tags, extracting cover art, parsing lyrics), write Tauri Commands in Rust — performant and secure
Cross-platform: One codebase, runs on both macOS and Windows

Overall Architecture:

┌─────────────────────────────────────────┐
│           Tauri 2 (Desktop Shell)         │
│  ┌───────────────────────────────────┐  │
│  │    React 18 + TypeScript + Vite   │  │
│  │  (UI / Playback Control / State)  │  │
│  │        Zustand (State Mgmt)        │  │
│  │    HTMLAudioElement (Audio)       │  │
│  └──────────────┬────────────────────┘  │
│                 │ Tauri invoke()         │
│  ┌──────────────▼────────────────────┐  │
│  │        Rust Backend Capabilities   │  │
│  │  - Directory Scanning (scanner)   │  │
│  │  - ID3 Tag Parsing (id3 crate)    │  │
│  │  - Cover Extraction (base64)      │  │
│  │  - Lyrics Reading (lyrics)         │  │
│  │  - Config Management (config)     │  │
│  └────────────────────────────────────┘  │
└─────────────────────────────────────────┘

Combined with Netease_url + OneDrive: Complete Workflow

MiniMusic itself only handles playback, but it can be combined with two other tools to form a complete personal music workflow:

  Netease_url           OneDrive              MiniMusic
  (Downloader) ──────▶ (Sync Tool) ──────▶   (Player)
      │                    │                     │
      ▼                    ▼                     ▼
  Search NetEase     Cross-device sync      Scan local files
  Parse music library  Keep library consistent  Folder-based playlists
  Download MP3/FLAC   Cover all devices      Display cover art & lyrics

Netease_url: A Python + Flask project that can search and download from the NetEase Cloud Music library, supporting multiple quality levels from standard to Hi-Res
OneDrive: Set the download directory as a OneDrive folder, and new songs automatically sync to all devices
MiniMusic: Scans the OneDrive music directory, automatically recognizing new songs

Three tools, one pipeline, each doing its own job.

Download & Installation

macOS (Apple Silicon)

Download MiniMusic_0.1.0_aarch64.dmg, double-click to open, then drag MiniMusic into the Applications folder.

On first launch, since it hasn’t been notarized by Apple, you may need to go to “System Settings → Privacy & Security” and click “Open Anyway”.

Windows (x64)

Download MiniMusic_0.1.0_x64-setup.exe or MiniMusic_0.1.0_x64-setup.msi, double-click to install.

Future Plans

v0.1.0 is the first version, and there are many features still to come:

FLAC, WAV, AAC, and more format support
Desktop lyrics
EQ equalizer
Audio spectrum visualization
Custom playlists (not dependent on folders)
Apple Developer ID signing and notarization
Auto-update

If you have suggestions, feel free to submit them at GitHub Issues.

License

MiniMusic is licensed under a Non-Commercial Use License, free for personal, non-commercial use only. See LICENSE for details.

Final Words

From idea to packaged app, MiniMusic is finally ready to be seen.

It’s not perfect, but it’s good enough.

If you also enjoy listening to local music, give it a try.

Portfolio