基于神经网络，将您音乐库中的任何歌曲变成卡拉OK。

---

Nightingale 会扫描您的音乐文件夹，使用 UVR Karaoke 模型（或 Demucs）将主唱与伴奏分离，再通过 WhisperX 将歌词转录并添加词位时间戳，最后以同步高亮显示、音高评分、调性/速度控制、个人资料和动态背景等功能进行播放。

程序以单个二进制文件分发，无需手动安装 Python、ffmpeg 或机器学习模型——所有依赖项都会在首次启动时自动下载并完成初始化。

功能

🎤 音轨分离 — 使用 UVR Karaoke 模型（默认）或 Demucs 将主唱从伴奏中分离，支持调节引导人声的音量。Karaoke 模型会在伴奏中保留和声部分，使声音更自然。

📝 词位级歌词 — 自动转录并对齐歌词；若可用，也可从 LRCLIB 获取。

🎯 音高评分 — 实时麦克风输入配合音高检测，提供星级评价及每首歌的成绩榜。

🎚️ 调性和速度调整 — 分析完成后可调整歌曲的调性和速度，并缓存不同版本以便快速重试。

👤 个人资料 — 创建并切换不同的用户配置文件；分数将按每个资料分别记录。

🎬 视频文件 — 将视频文件（.mp4、.mkv 等）放入音乐文件夹，系统会从音频轨道中分离出人声，并以原始视频作为同步背景播放。

🌌 7 种背景主题 — 包括 5 种基于 GPU 的着色器背景（等离子体、极光、海浪、星云、星空）、5 种来自 Pixabay 的视频背景（自然、水下、太空、城市、乡村），以及针对视频文件的自动源视频播放功能。

🧭 侧边栏 + 库过滤器 — 提供快速筛选、元数据清理分类、艺人/专辑分组，以及用于批量分析的“全部分析”功能。

🎙️ 麦克风镜像 — 可选择将实时麦克风信号路由到播放中，实现低延迟的练习与监听。

🎮 游戏手柄支持 — 完全可通过游戏手柄（方向键、摇杆、按键）进行导航和控制。

📺 自适应 UI 缩放 — 适配任意分辨率，包括 4K 电视。

📦 自包含 — ffmpeg、uv、Python、PyTorch 和机器学习相关包会在安装过程中自动下载。视频背景也会预先下载，确保首次使用即可立即上手。

快速入门

请从发布页面下载适用于您平台的最新版本并运行。首次启动时，Nightingale 会显示设置步骤，让您选择数据文件夹，随后自动安装 Python 环境和机器学习模型。

macOS

macOS 会对从互联网下载的文件进行隔离。由于 Nightingale 未使用 Apple 开发者 ID 签名，Gatekeeper 会阻止其运行，并显示类似“应用已损坏，无法打开”的提示。要解决此问题，在将 Nightingale.app 移至“应用程序”文件夹后，请移除隔离属性：

xattr -cr /Applications/Nightingale.app

支持的格式

音频：.mp3、.flac、.ogg、.wav、.m4a、.aac、.wma。视频：.mp4、.mkv、.avi、.webm、.mov、.m4v。

控制方式

导航

操作	键盘	游戏手柄
移动	方向键	D-pad / 左摇杆
确认 / 选择	Enter	A（南）
返回 / 取消	Escape	B（东） / Start
切换面板	Tab	—
搜索歌曲	输入筛选	—

播放

操作	键盘	游戏手柄
暂停 / 继续	Space	Start
退出到菜单	Escape	B（东）
切换引导人声	G	—
调节引导人声音量	+ / -	—
循环背景主题	T	—
循环视频风格	F	—
切换麦克风	M	—
下一个麦克风	N	—
切换麦克风镜像	R	—
切换全屏	F11	—
跳过前奏 / 跳过后奏	屏幕按钮	A（南）

工作原理

音频或视频文件
        │
        ▼
  ┌─────────────────┐
  │  UVR Karaoke /  │  ──▶  vocals.mp3 + instrumental.mp3
  │  Demucs         │       （从视频中提取音频轨道）
  └─────────────────┘
        │
        ▼
  ┌─────────────────┐
  │  LRCLIB         │  ──▶  若有同步歌词则获取
  └─────────────────┘
        │
        ▼
  ┌─────────────────┐
  │  WhisperX       │  ──▶  转录并进行词位级对齐
  │  (large-v3)     │
  └─────────────────┘
        │
        ▼
  ┌─────────────────┐
  │  Tauri App      │  ──▶  播放伴奏 + 同步歌词
  │  (Rust + React) │       并提供音高评分、调性/速度控制、
  └─────────────────┘       麦克风镜像及动态背景功能，
                            （视频文件会优先使用源视频）

分析结果会使用 blake3 文件哈希进行缓存。只有当源文件发生变化、用户手动触发重新分析，或您选择调整调性/速度并生成不同播放版本时，才会重新进行分析。

硬件要求

Python 分析器使用 PyTorch，并会自动检测最佳后端：

后端	设备	备注
CUDA	NVIDIA GPU	最快
MPS	Apple Silicon	macOS；WhisperX 对齐会回退到 CPU
CPU	任何设备	最慢但始终可用

UVR Karaoke 模型采用 ONNX Runtime，在 NVIDIA GPU 上会自动启用 CUDA 加速，而在 Apple Silicon 上则使用 CoreML。

一首歌通常在 GPU 上需要 2–5 分钟，在 CPU 上则需要 10–20 分钟。

数据存储

在设置过程中，您可以选择 Nightingale 存储数据的位置（默认为 ~/.nightingale）。大多数运行时数据都存储在该选定的数据文件夹中，而 config.json 和 nightingale.log 仍保留在 ~/.nightingale 中。

典型的选定数据文件夹布局如下：

<selected-data-folder>/
├── cache/               # 音高、转录文本、歌词、移调版本、翻唱、可播放视频
├── songs.db             # SQLite 歌曲库及分析元数据
├── profiles.json        # 播放器配置文件和分数
├── videos/              # 缓存的 Pixabay 视频背景
├── sounds/              # 音效（庆祝）
├── vendor/
│   ├── ffmpeg           # 下载的 ffmpeg 二进制文件
│   ├── uv               # 下载的 uv 二进制文件
│   ├── python/          # 通过 uv 安装的 Python 3.10
│   ├── venv/            # 包含机器学习包的虚拟环境
│   ├── analyzer/        # 提取的分析器 Python 脚本
│   └── .ready           # 标记，表示设置已完成
└── models/
    ├── torch/           # Demucs 模型缓存
    ├── huggingface/     # WhisperX 模型缓存
    └── audio_separator/ # UVR 卡拉 OK 模型缓存

~/.nightingale/config.json 存储应用程序设置，包括所选数据文件夹的路径。

视频背景

Pixabay 视频背景使用 Pixabay API。API 密钥已嵌入到发布版本中。在开发环境中，请在项目根目录下创建一个 .env 文件：

PIXABAY_API_KEY=your_key_here

从源代码构建

先决条件

工具	版本
Rust	1.85 及以上（2024 年版）
Node.js	20 及以上
pnpm	最新版本
仅限 Linux	libwebkit2gtk-4.1-dev、libssl-dev、libayatana-appindicator3-dev、librsvg2-dev、libxdo-dev、libasound2-dev

开发

git clone <repo-url> nightingale
cd nightingale
cargo desktop dev

发布构建

cargo desktop build

支持的平台

平台	目标架构
Linux x86_64	x86_64-unknown-linux-gnu
Linux aarch64	aarch64-unknown-linux-gnu
macOS ARM	aarch64-apple-darwin
macOS Intel	x86_64-apple-darwin
Windows x86_64	x86_64-pc-windows-msvc

许可证

GPL-3.0 或更高版本 — 请参阅 LICENSE。

Nightingale 快速上手指南

Nightingale 是一款基于神经网络的开源卡拉 OK 工具，能够自动从音乐库中分离人声与伴奏，生成带时间戳的歌词，并提供实时音高评分、变调变速及动态背景等功能。它以单一二进制文件分发，首次运行会自动下载所需环境。

环境准备

系统要求

支持以下平台：

• Linux: x86_64 或 aarch64 架构
• macOS: Intel 或 Apple Silicon (ARM) 芯片
• Windows: x86_64 架构

硬件建议

工具内置分析器会自动检测最佳后端，性能取决于硬件：

• NVIDIA GPU: 使用 CUDA 后端，速度最快（推荐）。
• Apple Silicon: 使用 MPS 后端（WhisperX 对齐步骤可能回退至 CPU）。
• CPU: 通用兼容，但处理速度较慢（单曲约需 10-20 分钟，GPU 仅需 2-5 分钟）。

前置依赖

普通用户无需手动安装任何依赖。Nightingale 会在首次启动时自动下载并配置 ffmpeg、Python、PyTorch 及机器学习模型。

注意（macOS 用户）：由于应用未签名， macOS Gatekeeper 可能会拦截启动。将 Nightingale.app 移至应用程序文件夹后，需在终端执行以下命令移除隔离属性：

xattr -cr /Applications/Nightingale.app

安装步骤

1. 下载程序 访问项目的 Releases 页面，下载对应操作系统的最新版本压缩包。

2. 解压与运行

   • Windows/Linux: 解压后直接运行可执行文件。
   • macOS: 将 Nightingale.app 拖入 /Applications 文件夹，执行上述“环境准备”中的去隔离命令后双击打开。

3. 初始化配置 首次启动时，程序会引导你选择数据存储目录（默认为 ~/.nightingale 或用户指定路径）。随后它将自动：

   • 下载嵌入式 Python 环境和必要的 ML 模型（UVR Karaoke, Demucs, WhisperX）。
   • 预下载视频背景素材。
   • 完成初始化后即可进入主界面。

基本使用

1. 导入音乐库

将包含音频（.mp3, .flac, .wav 等）或视频（.mp4, .mkv 等）文件的文件夹设置为音乐库目录。

• 在侧边栏使用 Analyze All 功能批量分析歌曲。
• 系统将自动分离人声/伴奏，并从 LRCLIB 获取或通过 WhisperX 生成带词级时间戳的歌词。

2. 开始演唱

• 在歌曲列表中选中一首已分析的歌曲并确认播放。
• 连接麦克风，开启 Mic Mirroring（按 M 键切换麦克风，R 键切换镜像监听）以进行低延迟练习。
• 界面将实时显示同步高亮的歌词和音高评分（星级）。

3. 常用控制

功能	键盘快捷键	游戏手柄
暂停/继续	Space	Start
开关导唱人声	G	-
调节导唱音量	+ / -	-
切换背景主题	T	-
开关麦克风	M	-
全屏模式	F11	-
跳过前奏/尾奏	点击屏幕按钮	A (South)

4. 高级功能

• 变调与变速：在播放界面调整 Key（音调）和 Tempo（速度），系统会缓存变体以便快速重试。
• 多用户档案：创建不同 Profiles 记录各自的得分历史。
• 视频背景：支持直接播放视频文件作为同步背景，或使用内置的 7 种动态主题（如等离子、极光、星空等）。

所有分析结果均通过文件哈希缓存，除非源文件变更或手动触发，否则不会重复分析。