ezkaraoke

家用 KTV 点歌系统 — 简单易用的家庭卡拉 OK 解决方案。

功能特性

• 本地曲库管理：自动扫描指定文件夹，构建歌手-歌曲索引
• 本地 SQLite 曲库：秒开启动（无需重复扫描），重新扫描自动重建
• 歌手头像点歌：自动从网络获取歌手头像并本地缓存，加载失败显示占位图标
• A–Z/拼音首字母索引点歌：左侧支持按歌手或按歌名首字母（拼音）浏览
• 经典点歌台界面：左侧歌手列表 / 中间歌曲浏览 / 右侧播放队列
• 多种点歌方式：支持按歌手浏览、实时搜索、点歌/插播/立即播放
• 歌曲表拼音排序：点击"歌手"/"歌名"表头按拼音排序（再点一次反转），万首级曲库切换/排序均 < 0.1s
• 后台任务进度提示：状态栏进度条实时显示扫描与头像下载进度（"正在获取歌手头像 i/n"）
• 播放队列管理：支持队列内上移、下移、删除，双击切歌
• 升调/降调：半音步进变调（±12 半音），偏好跨歌曲保留；VLC ≥ 4 为纯变调，VLC < 4 变调同时改变速度
• 原唱/伴奏切换：双音轨视频歌曲一键切换原唱与伴奏，播放窗口与点歌台同步，偏好跨歌曲保留
• 双窗口模式：独立的视频播放窗口 + 点歌台窗口
• 深色 KTV 主题：沉浸式暗色界面，搭配暖色点缀

文件名约定

扫描器按以下格式识别歌曲文件：

歌手-歌曲名称-xxxxx.xxx

例如：周杰伦-晴天-OfficialMV.mp4

横杠 - 用于分隔歌手与歌名，后面的附加信息会被忽略。

环境要求

• Python 3.10 或更高版本
• PySide6 6.6+（.deb 安装时由系统包自动满足）
• VLC 媒体播放器（用于视频解码，.deb 安装时自动满足）

Ubuntu / Debian

sudo apt update
sudo apt install vlc

安装与运行

方法一：安装 .deb 包（推荐）

# 构建（需要 dpkg-deb，Ubuntu/Debian 自带）
./packaging/build_deb.sh

# 安装（自动拉取依赖：python3-pyside6.qtwidgets、python3-pypinyin、libvlc5）
sudo apt install ./dist/ezkaraoke_0.1.0_amd64.deb

# 启动：桌面菜单中的 "EzKaraoke"，或终端执行
ezkaraoke

用户数据（不在包内）：配置文件 ~/.config/ezkaraoke/，曲库数据库 ~/.local/share/ezkaraoke/。

方法二：从源码运行

# 克隆仓库后进入目录
cd ezkaraoke

# 创建虚拟环境
python3 -m venv .venv
source .venv/bin/activate

# 安装依赖
pip install -r requirements.txt

# 启动程序
python -m ezkaraoke

使用说明

1. 在点歌台窗口点击 "选择文件夹…"，指定存放歌曲的文件夹
2. 程序自动扫描并建立本地曲库（SQLite），之后启动直接秒开；点击 "重新扫描" 可随时重建。扫描与头像下载均为后台任务，状态栏底部进度条实时显示进度，不阻塞界面操作
3. 左侧面板可在两种模式间切换：
   • 歌手：按歌手浏览（带头像，头像首次启动时自动从网络获取并缓存）
   • 首字母：按歌名拼音首字母 A–Z 浏览（无歌曲的字母置灰）
4. 浏览列表或直接在搜索框输入关键词查找歌曲（搜索优先于左侧列表）；点击歌曲表的 "歌手" / "歌名" 表头可按拼音排序，再点一次同一表头反转排序方向
5. 选中歌曲后点击：
   • 点歌：将歌曲加入播放队列末尾
   • 插入播放：将歌曲插到当前播放的下一首
   • 立即播放：立即播放该歌曲
6. 在右侧播放队列中可调整顺序或删除歌曲，双击队列歌曲可切歌
7. 播放器窗口支持双击视频区域切换全屏，按 Esc 退出全屏，按 Space 暂停/播放
8. 用播放器控制栏的 "降调"/"升调" 按钮以半音为单位变调（±12 半音，标签显示 原调/升N/降N），变调偏好跨歌曲保留；VLC ≥ 4 为纯变调，VLC < 4 变调的同时会改变播放速度
9. 带两条音轨的歌曲可通过播放器窗口或点歌台的 "原唱/伴奏" 按钮切换音轨（当前音轨显示在按钮提示中）

注意事项

• 视频输出策略按会话自动选择：
  • X11 / XWayland：使用窗口句柄硬件加速直出（set_hwnd）。
  • 原生 Wayland：自动切换为软件渲染模式（VLC 解码后回读帧到 Qt 显示，CPU 占用略高，功能完整）。
• 若提示缺少 VLC，请确保系统已安装 VLC 并可通过命令行调用。