Melo

Melo 是一个以本地音乐库为核心的 Rust 命令行播放器，采用 daemon + remote TUI/CLI 架构：

daemon 是唯一的播放与运行态真相来源
CLI 既可以做远程控制，也可以直接打开文件或目录
TUI 是连接 daemon 的遥控前端，而不是独立播放器

当前仓库已经具备可运行的第一阶段闭环：本地数据库、播放控制、目录/文件直开、临时歌单、后台补扫、TUI 聚合状态流、OpenAPI 文档与 daemon 管理命令。

当前已实现

daemon 生命周期管理：start / stop / restart / status / logs / doctor / ps / docs
本地播放器控制：播放、暂停、切换、上下曲、音量、静音、循环、随机
文件/目录 direct-open：melo <音频文件>、melo <目录>、裸 melo
目录直开两阶段扫描：先预热少量曲目进入 TUI，剩余曲目后台补扫
ephemeral playlist：目录/文件直开会生成可复用的临时歌单
TUI 远程控制：通过 WebSocket 持续接收播放器状态和后台任务状态
API 文档：daemon 暴露 /api/openapi.json 与 /api/docs/
配置文件、数据库路径与 daemon 注册文件的用户级管理

架构概览

CLI / TUI
    |
    v
 Melo daemon
    |
    +-- PlayerService        播放、队列、进度、模式
    +-- OpenService          文件/目录直开
    +-- RuntimeTaskStore     后台扫描任务状态
    +-- HTTP / WebSocket API 状态与控制面
    |
    v
 SQLite + 本地音频文件

几个关键设计约束：

播放队列是 daemon 运行态内存数据，不是用户长期资产
direct-open 会把当前上下文物化为 ephemeral playlist，便于复用与提升
TUI 读取的是聚合快照 /api/ws/tui，不是自己维护播放语义
目录直开默认会先同步预热，再后台继续扫描并稳定追加到队列

快速开始

1. 环境要求

Rust 工具链
pnpm 10+
可用音频后端
- 默认可使用 rodio
- 如需 mpv，请保证 mpv 可执行文件在 PATH 中，或在配置里指定 player.mpv.path

2. 安装

开发态推荐：

pnpm install
pnpm setup:dev

只想本地构建一个可执行文件时：

cargo install --path . --force

3. 准备配置

把 config.example.toml 复制到你的 Melo 配置路径，并按需修改。

默认配置文件位置：

Windows: %APPDATA%/melo/config.toml
其他平台: ~/.config/melo/config.toml

也可以通过环境变量覆盖：

MELO_CONFIG_PATH
MELO_CONFIG

4. 启动与使用

启动受管 daemon：

melo daemon start

打开当前目录并进入 TUI：

melo

打开指定目录并进入 TUI：

melo D:/Music

打开单个音频文件：

melo D:/Music/Aimer/Ref-rain.flac

查看当前状态：

melo status

查看 daemon 文档入口：

melo daemon docs --print

常用命令

播放控制

melo play
melo pause
melo toggle
melo next
melo prev
melo stop

模式与音量

melo player volume 55
melo player mute
melo player unmute
melo player mode show
melo player mode repeat all
melo player mode shuffle on

队列操作

melo queue show
melo queue play 0
melo queue remove 3
melo queue move 5 1
melo queue clear

daemon 管理

melo daemon start
melo daemon status
melo daemon status --json
melo daemon status --verbose
melo daemon stop
melo daemon restart
melo daemon logs --tail 50
melo daemon logs --snapshot --tail 50
melo daemon doctor --json
melo daemon ps
melo daemon docs --print
melo daemon docs --print --openapi

日志与 verbose 诊断

melo --verbose
melo --log-level debug status
melo --daemon-log-level trace play
melo --verbose --no-log-prefix D:/Music

说明：

melo --verbose
- 为当前命令打开更详细的启动链路日志，并在可行时把 daemon 日志镜像到当前终端
--log-level <level>
- 精确覆盖当前 CLI 进程的日志等级
--daemon-log-level <level>
- 仅对由当前命令自动拉起的 daemon 生效；不会追溯影响已经在运行的 daemon
--no-log-prefix
- 隐藏终端里的 [cli] / [daemon] 前缀

临时歌单维护

melo playlist promote D:/Music/blue-bird.mp3 Favorites
melo playlist cleanup

direct-open 行为说明

裸 `melo`

当 open.scan_current_dir = true 时，裸 melo 会：

自动确保 daemon 已运行
把当前目录按 cwd_dir 方式 direct-open
先预热少量曲目
输出一条 CLI 扫描提示
进入 TUI，剩余文件继续后台补扫

`melo <目录>`

目录会按 path_dir 模式处理
会生成或复用对应的 ephemeral playlist
后台补扫期间，TUI 顶部会显示单行任务条

`melo <文件>`

文件会按 path_file 模式处理
当前队列与播放上下文会切换到该文件对应的临时歌单

配置重点

完整示例见 config.example.toml。

几个最常用的配置段：

[daemon]
host = "127.0.0.1"
base_port = 38123
port_search_limit = 32
docs = "local"

[player]
backend = "auto"
volume = 100
restore_last_session = true
resume_after_restore = false

[open]
scan_current_dir = true
max_depth = 2
prewarm_limit = 20
background_jobs = 4

[tui]
show_footer_hints = true

[templates.runtime.scan]
cli_start = "Scanning {{ source_label }}..."
cli_handoff = "Launching TUI, background scan continues..."
tui_active = "Scanning {{ source_label }}... {{ indexed_count }} / {{ discovered_count }} · {{ current_item_name }}"
tui_done = "Scan complete: {{ queued_count }} tracks indexed"
tui_failed = "Scan failed: {{ error_message }}"

说明：

daemon.docs
- disabled：不暴露 API 文档
- local：仅 loopback 可访问
- network：允许网络访问
open.prewarm_limit
- 进入 TUI 前同步预热的曲目数
open.background_jobs
- 后台补扫并发度
templates.runtime.scan.*
- 覆盖扫描阶段的高信息量运行时提示

数据库路径也可以通过环境变量覆盖：

MELO_DB_PATH

运行时文件

Melo 会维护几类用户级运行文件：

配置文件：config.toml
数据库：melo.db
daemon 注册：daemon.json
daemon 日志：daemon.log

其中 daemon 运行文件路径由 src/daemon/registry.rs 决定：

Windows: %LOCALAPPDATA%/melo/
其他平台: ~/.local/share/melo/

也可以用环境变量覆盖 daemon 状态文件位置：

MELO_DAEMON_STATE_FILE

如果你希望所有 CLI 都连接到某个固定地址，也可以直接设置：

MELO_BASE_URL

API 与文档

daemon 运行后可以访问：

OpenAPI JSON: /api/openapi.json
Swagger UI: /api/docs/

常用方式：

melo daemon docs --print
melo daemon docs --print --openapi
pnpm docs:api
pnpm docs:api:serve

开发工作流

安装开发依赖并把本地 melo 链接到全局：

pnpm setup:dev

默认假设你已经执行过上面的 pnpm install。

常用脚本：

pnpm qa
pnpm verify
pnpm qa:rs
pnpm qa:ts
pnpm lint:rs:fix
pnpm docs:api

说明：

pnpm qa:code 并行跑只读的 TS/Rust format check、lint、typecheck/test（不写回文件）
pnpm qa = qa:code + docs:api:check（含 OpenAPI 契约门禁）
pnpm verify 等同 pnpm qa
改 HTTP 路由/handler/DTO 后先 pnpm docs:api 再提交
本地自动修复用 pnpm format:ts / pnpm format:rs / pnpm lint:ts:fix / pnpm lint:rs:fix
仓库约定提交前先跑 pnpm qa；发版或契约相关改动再跑 pnpm verify

WebUI（apps/web）

仓库通过 pnpm workspace 接入 React/Vite 前端壳（包名 @melo/web）：

# 安装依赖（根仓 + workspace）
pnpm install

# 启动 WebUI 开发服务器（默认代理 /api → http://127.0.0.1:38123）
pnpm --filter @melo/web dev
# 或
pnpm web:dev

# 冒烟测试 / 类型检查 / 构建
pnpm --filter @melo/web test
pnpm --filter @melo/web typecheck
pnpm --filter @melo/web build

说明：

样式使用 CSS Variables + CSS Modules（不引入 Tailwind）
daemon baseURL 读 VITE_MELO_BASE_URL，默认 http://127.0.0.1:38123
开发时也可把 VITE_MELO_BASE_URL 设为空字符串，走 Vite /api proxy
当前仅 AppShell + 占位路由（/library /playlists /settings），业务页后续任务接入

桌面端（Tauri Sidecar）

顶层 src-tauri/ 使用 Tauri v2 打包同一套 apps/web 前端，并在 app 生命周期内托管 melo daemon sidecar。

# 构建并拷贝 sidecar 二进制（debug）后启动桌面开发
pnpm desktop:dev

# 确保 triple 二进制存在后 cargo check 壳 crate
pnpm desktop:check

# 准备 release sidecar + 打包
pnpm desktop:build

说明：

开发态 WebView 连 Vite http://localhost:5174；生产嵌入 apps/web/dist（base: ./）
sidecar：melo daemon run @ http://127.0.0.1:38123；端口已占用则复用、不二次 spawn
纯 Web 仍用 pnpm --filter @melo/web dev（不强制桌面脚本）
未签名 macOS/Windows 分发限制见 src-tauri/README.md
详细说明见 src-tauri/README.md

项目文档

设计与计划文档主要放在：

如果你想快速了解最近这批功能，可以先看：

当前边界

README 只描述仓库里已经落地、并且从命令行可感知的能力。项目仍在演进中，尤其是：

library / config 命令面目前更像保留入口，不是完整用户工作流
i18n 与更完整的任务中心 UI 还在后续设计范围
README 优先强调已可运行路径，而不是覆盖所有内部模块

Name		Name	Last commit message	Last commit date
.agents/skills		.agents/skills
.cargo		.cargo
.codex		.codex
.husky		.husky
.omp		.omp
.pi		.pi
.trellis		.trellis
.vscode		.vscode
apps/web		apps/web
bin		bin
docs		docs
locales		locales
plugins/melo-plugin-timestamp-template		plugins/melo-plugin-timestamp-template
scripts		scripts
src-tauri		src-tauri
src		src
tests		tests
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.rumdl.toml		.rumdl.toml
AGENTS.md		AGENTS.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
README.md		README.md
biome.json		biome.json
build.rs		build.rs
config.dev.toml		config.dev.toml
config.example.toml		config.example.toml
lint-staged.config.mjs		lint-staged.config.mjs
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Navigation Menu

Repository files navigation

Melo

当前已实现

架构概览

快速开始

1. 环境要求

2. 安装

3. 准备配置

4. 启动与使用

常用命令

播放控制

模式与音量

队列操作

daemon 管理

日志与 verbose 诊断

临时歌单维护

direct-open 行为说明

裸 `melo`

`melo <目录>`

`melo <文件>`

配置重点

运行时文件

API 与文档

开发工作流

WebUI（apps/web）

桌面端（Tauri Sidecar）

项目文档

当前边界

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Melo

当前已实现

架构概览

快速开始

1. 环境要求

2. 安装

3. 准备配置

4. 启动与使用

常用命令

播放控制

模式与音量

队列操作

daemon 管理

日志与 verbose 诊断

临时歌单维护

direct-open 行为说明

裸 melo

melo <目录>

melo <文件>

配置重点

运行时文件

API 与文档

开发工作流

WebUI（apps/web）

桌面端（Tauri Sidecar）

项目文档

当前边界

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

裸 `melo`

`melo <目录>`

`melo <文件>`