仓库地址

功能特性

快速开始

方式一：从源码运行（需要 Python 环境）

环境要求

• Python 3.11+
• Windows / Linux / macOS

安装步骤

# 1. 克隆或下载项目
cd "e:\Projects\TAB Score Viewer"

# 2. 创建虚拟环境
python -m venv venv

# 3. 激活虚拟环境
# Windows:
.\venv\Scripts\activate
# Linux/Mac:
source venv/bin/activate

# 4. 安装依赖（使用国内镜像源）
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

# 5. 下载 SoundFont 音色库（GTP 音频播放必需，约 140MB）
# 程序会在以下位置自动搜索音色库文件:
#   - 项目目录下的 soundfont/ 文件夹（推荐）
#   - 用户主目录 ~/.fluidsynth/
#
# 下载地址（任选其一）:
#   官方源: https://ftp.osuosl.org/pub/musespan/SoundFonts/FluidR3_GM.sf2
#   镜像源: https://github.com/FluidSynth/fluidsynth/wiki/SoundFont
#
# 下载后放到项目的 soundfont/ 目录下，目录结构如下:
#   TAB Score Viewer/
#   ├── soundfont/
#   │   └── FluidR3_GM.sf2          ← 音色库文件放这里
#   ├── TAB Score Viewer.py
#   └── ...

# 6. 下载FluidSynth动态库（Windows/MacOS）
```bash
#macOS:
brew install fluid-synth
/bin/bash prepare_macos_build.sh
#Windows:到https://github.com/FluidSynth/fluidsynth/releases 下载最新版本的cpp后缀的动态库放在项目目录下

7. 运行

python "TAB Score Viewer.py"

方式二：直接运行 EXE（无需 Python 环境）

如果您不想安装 Python 环境，可以直接使用打包好的 EXE 程序。

# 从源码自行打包（需要先安装依赖，见方式一第1-4步）
pip install pyinstaller -i https://pypi.tuna.tsinghua.edu.cn/simple
pyinstaller "TAB Score Viewer.spec"

# 双击运行 TAB Score Viewer.exe

方式三：Linux DEB 安装包（推荐）

预打包的 .deb 文件，自动解决依赖关系，安装后全局可用 tabsv 命令。

# 安装 .deb 包（自动处理依赖）
sudo dpkg -i tab-score-viewer_2.7.6_*.deb
sudo apt-get install -f  # 自动修复缺失的依赖

# 运行（全局命令，无需输入路径）
tabsv

自行构建 DEB 包: 详见 打包发布说明 中 build_deb.sh 的使用方法。

方式四：Linux ZIP 压缩包（便携版）

解压即用，但需要手动安装系统依赖库。

# 1. 先安装系统依赖
sudo apt-get install libfluidsynth3 libsndfile1 libpulse0 libasound2    libqt5widgets5 libqt5gui5 libqt5core5a libc6 libportaudio2

# 2. 解压并运行
unzip tab-score-viewer-linux.zip
cd "TAB Score Viewer"
./"TAB Score Viewer"

注意: Fedora/Arch 等其他发行版的依赖安装命令请参考 打包发布说明。

方式五：macOS DMG 安装包（macOS 推荐）

预打包的 .dmg 磁盘映像，拖拽安装。DMG 包含 .app 应用包和 /Applications 快捷方式，安装方便。

# 从源码自行打包（需要先安装依赖，见方式一第1-4步）

# 1. 运行准备脚本（收集 FluidSynth 动态库并修复 @rpath 路径）
bash prepare_macos_build.sh

# 2. 安装 PyInstaller 并使用 macOS 专用 spec 打包
pip install pyinstaller -i https://pypi.tuna.tsinghua.edu.cn/simple
pyinstaller "TAB Score Viewer_macOS.spec"

# 3. 生成 DMG 安装镜像
bash build_dmg.sh

# 输出: dist/TAB Score Viewer_2.7.6.dmg

安装方式：双击 .dmg → 将 TAB Score Viewer.app 拖入 Applications 文件夹。

使用方法

1. 启动程序后，点击「选择文件夹」按钮选择存放吉他谱的目录
2. 文件列表会显示所有支持的格式文件（PNG/JPG/WEBP/PDF/GP3-GP5/GPX），最近文件列表上方还有独立的「收藏」列表；悬停文件项显示星标按钮（或右键菜单切换收藏）。GTP 文件会自动显示 0–10 星难度评分（鼠标悬停查看 tooltip）。
3. 双击文件打开谱面查看器：
   • 单张图片：直接显示并播放
   • PDF：逐页渲染为图片拼接显示
   • 多张图片：按文件名排序后拼接连续显示
   • GTP 文件：通过 ApolloTab 引擎完整解析渲染为六线谱图像，支持音频播放、音轨切换、播放光标
4. 使用工具栏和控制面板进行播放、调速、标注等操作
5. 「设置 → 快捷键」可重新映射任意按键；「关于」窗口可手动检查更新。

快捷键

默认绑定（所有快捷键均可在「设置 → 快捷键」中重新映射）：

捕获规则、跨平台行为与冲突处理见下方「快捷键自定义」。

鼠标操作

快捷键自定义

打开「设置 → 快捷键」即可重新绑定任意操作。表格中左侧是操作名，右侧是当前绑定。

• 捕获模式：点击右侧单元格进入（黄底高亮），按目标组合键即可绑定。
  • Esc 取消 · Backspace 清空（空串 = 永久禁用该操作）· Enter 确认当前按住的状态。
• 绑定规则：
  • 至少包含 1 个非修饰键。
  • 修饰键（Ctrl / Shift / Alt / Meta / CapsLock / Tab）不能单独成键，必须与至少 1 个普通按键组合。
  • 组合键最多 3 个键。
• 冲突检测：新组合已被其他操作占用时，弹窗提示「替换 / 清空 / 取消」。
• 跨平台语义：Option 等价于 Alt；Command / Win / Super 统一映射为 Meta，存盘后跨平台保持一致。macOS 上自动交换 Ctrl 与 Cmd 的显示名，与物理按键保持一致。
• 重置所有：一键恢复所有操作到默认绑定。
• 持久化：自定义绑定写入 config/settings.json 的 custom_shortcuts 字段。

项目结构

代码库按 4 个顶层子包 + 4 个根目录文件组织。经过 v2.7.5 共 18 个重构 phase，原 4308 行的主入口文件被拆分成清晰的层级架构。

TAB Score Viewer/
├── TAB Score Viewer.py        # 主入口: TabViewerApp + main() + cli_launcher 集成
├── cli_launcher.py            # 无头 CLI 启动器（文件关联 / argv 参数）
├── tuner.py                   # 独立吉他调音器对话框（根目录单例，v2.5+）
├── runtime_hook_macos.py      # macOS 运行时钩子：预加载动态库（PyInstaller）
│
├── core/                      # 纯数据 + 工具（无 UI / 无业务逻辑）
│   ├── constants.py           # 共享常量（路径、默认值、键映射）
│   ├── models.py              # dataclass（Annotation, Settings, FileItem, ...）
│   ├── theme.py               # ThemeManager（深/浅色 + 自定义 JSON/Python 主题）
│   ├── i18n.py                # I18n QObject 单例（zh_CN / en_US / ru_RU）
│   ├── fonts.py               # UI 字体选择 + on_font_changed 回调注册
│   ├── config.py              # settings.json 读写 + Pydantic v2 校验
│   ├── shortcuts.py           # ShortcutAction / ShortcutManager（跨平台）
│   ├── logging_setup.py       # 文件 + 控制台日志配置
│   ├── update_checker.py      # 异步 GitHub Releases 更新检查（5s 超时）
│   └── difficulty_scoring.py  # GTP 难度 0-10 星评分 + SQLite 缓存
│
├── service/                   # 业务逻辑 + 控制器（QObject, pyqtSignal）
│   ├── playback_engine.py     # GTPPlayer 封装（ApolloTab 外观）
│   ├── playback_controller.py # 倒计时状态机 + 播放光标（Phase 19）
│   ├── content_controller.py  # 异步内容加载 + GTP 音轨 + 音量（Phase 20）
│   ├── annotation_controller.py # 标注 UI 协调（QObject + 信号）
│   ├── annotation_manager.py  # 标注数据层（load/save/undo/redo/track）
│   ├── metronome_service.py   # 节拍器音频同步
│   ├── score_surface.py       # DisplayWidget 表面（paint + interactor 适配）
│   ├── shortcut_dispatcher.py # 回调注册表（callback_attr "obj.method" 路由）
│   ├── export_pipeline.py     # 纯函数：collect_export_data, get_page_range
│   ├── page_renderer.py       # render_to_png/jpg/pdf + render_to_printer
│   ├── config_service.py      # SelectionWindow 的 settings.json 包装
│   ├── file_list_service.py   # 文件夹扫描 + 搜索 + 右键菜单
│   ├── recent_files_service.py # 最近文件持久化
│   └── favorites_service.py   # 星标切换 + 收藏列表管理
│
├── ui/                        # 所有 Qt 控件、对话框、主窗口
│   ├── display/               # DisplayWidget（谱面表面）拆 3 文件
│   │   ├── display_widget.py  # QWidget + paintEvent + 事件处理
│   │   ├── display_painter.py # 所有 QPainter 绘制逻辑
│   │   └── display_interactor.py # 鼠标 / 滚轮 / 键盘输入
│   ├── widgets/               # 可复用自定义控件
│   │   ├── widgets.py         # ModernButton, ImageSlider, 文件列表项
│   │   └── speed_curve_editor.py # 贝塞尔曲线编辑器（图/PDF 模式）
│   ├── dialogs/               # 模态对话框
│   │   ├── about_dialog.py    # 关于 + 版本 + 检查更新
│   │   ├── annotation_dialogs.py # 创建 / 编辑 / 批量管理标注
│   │   ├── export_dialogs.py  # 导出选项对话框
│   │   ├── print_dialog.py    # 打印 / 打印预览对话框
│   │   ├── settings_dialog.py # 通用 + 主题 + 快捷键 Tab
│   │   ├── shortcuts_dialog.py # 捕获模式快捷键重映射
│   │   └── soundfont_missing_dialog.py # SoundFont 下载提示
│   └── windows/               # 顶层主窗口
│       ├── selection_window.py # 文件夹选择 + 文件列表
│       └── display_window.py  # 谱面查看器（1850 行，已拆 3 个 controller）
│
├── workers/                   # QRunnable 异步工作线程（QThreadPool）
│   ├── workers.py             # LoadFileListWorker, RenderWorker, ...
│   └── export_worker.py       # ExportWorker（异步 PNG/JPG/PDF 导出 + 进度条）
│
├── tests/                     # pytest 套件（50+ 文件，1316+ 测试）
├── icons/                     # SVG 图标（Lucide 风格工具栏，共 15 个，无 emoji）
├── themes/                    # 自定义主题投放目录（JSON / .py）
├── locales/                   # i18n 翻译文件（JSON）
├── soundfont/                 # SoundFont 目录（FluidR3_GM.sf2，~140MB）
├── readme/                    # 项目文档（功能更新.md, 开发文档.md, ...）
├── tools/                     # 内部脚本（图标生成、版本检查、翻译同步）
├── config/settings.json       # 用户设置（自动生成；Pydantic 校验）
├── data/                      # 标注 + difficulty_cache.db
├── TAB Score Viewer.spec      # PyInstaller 配置（Windows）
├── TAB Score Viewer_linux.spec    # Linux
├── TAB Score Viewer_macOS.spec    # macOS（使用 runtime_hook_macos.py）
├── build_dmg.sh / build_deb.sh # macOS DMG / Linux DEB 打包
├── prepare_macos_build.sh     # macOS：收集动态库 + 修复 @rpath
├── requirements.txt           # Python 依赖（自 2026-07-31 起 AGPL v3）
├── LICENSE                    # AGPL v3 完整文本（2026-07-31 前为 MPL 2.0）
├── icon.ico / icon.icns / icon.png # 应用图标（Windows / macOS / PNG）
├── libfluidsynth-3.dll        # FluidSynth 动态库（LGPL 2.1，Windows）
├── SDL3.dll / sndfile.dll     # FluidSynth 依赖（Windows）
└── venv/                      # Python 虚拟环境（不纳入版本控制）

架构

┌─────────────────────────────────────────────────────────────────┐
│  ui/                                                            │
│  ├── display/  (widget = 仅视图，painter = 绘制，                │
│  │              interactor = 输入处理)                           │
│  ├── widgets/  (ModernButton, ImageSlider, SpeedCurveEditor)     │
│  ├── dialogs/  (模态: about, settings, export, print, ...)        │
│  └── windows/  (SelectionWindow → DisplayWindow)                │
│       │                                                          │
│       │ thin forwarders / signals（薄转发 / 信号）               │
│       ▼                                                          │
│  service/                                                        │
│  ├── *controller.py  (QObject + pyqtSignal; UI 协调)              │
│  │   ├── annotation_controller  (Phase 18)                       │
│  │   ├── playback_controller    (Phase 19: 倒计时 + 播放光标)    │
│  │   └── content_controller     (Phase 20: 加载 + 音轨 + 音量)    │
│  ├── *manager.py     (纯数据层；load/save/undo/redo)              │
│  │   └── annotation_manager                                       │
│  ├── *service.py     (有状态服务；config/list/favorites)           │
│  ├── *engine.py      (引擎封装；playback_engine)                  │
│  └── *_pipeline.py / *_renderer.py  (纯函数；导出)                │
│       │                                                          │
│       │ 使用 models + 通过 core/ 读写                            │
│       ▼                                                          │
│  core/                                                           │
│  ├── models.py        (dataclass: Annotation, Settings, ...)     │
│  ├── config.py        (Pydantic v2 settings.json 校验)           │
│  ├── theme.py         (ThemeManager, 深/浅/自定义)               │
│  ├── i18n.py          (tr() 查询 + language_changed 信号)         │
│  ├── fonts.py         (字体注册表 + on/off_font_changed)         │
│  ├── shortcuts.py     (ShortcutManager, callback_attr 解析)      │
│  └── constants.py     (路径、默认值、键映射)                      │
│                                                                  │
│  workers/  (QRunnable, 在 QThreadPool 中运行)                     │
│  └── LoadFileListWorker / ExportWorker / RenderWorker            │
└─────────────────────────────────────────────────────────────────┘

关键架构决策:

• 4 个子包层级 严格单向: ui → service → core, 永不允许反向。workers/ 仅作为叶子节点被 service 调用。
• Controller vs Manager 分层: controller (QObject + 信号) 协调 UI ↔ 状态, manager (纯 Python) 是纯数据层。参见 service/annotation_controller.py + service/annotation_manager.py 的规范模式。
• 禁止用 if hasattr 控制流程: service 必须在 __init__ 中创建; 只有 QTimer 异步回调和跨类场景允许用 lazy attribute 检查 (由 project_memory 规则强制)。
• pyqtSignal 状态传播: annotation_controller.undo_state_changed / content_controller.content_loaded / i18n.language_changed 等 — UI 订阅而非轮询。
• 禁止 __file__ 相对路径: 每个模块通过 os.path.dirname(os.path.dirname(__file__)) 解析项目根 (core/ 用 2 级, ui/dialogs/ 用 3 级)。

技术栈

架构模式

• MVC 分离: SelectionWindow(视图/控制) + DisplayWidget(视图) + 数据模型(dataclass)
• 观察者模式: PyQt5 信号槽机制实现组件间通信
• 工厂模式: Worker 类统一封装异步任务
• 命令模式: 撤销/重做通过快照栈实现
• 单例模式: I18n 国际化管理器全局唯一实例
• 外观模式: GTPPlayer 封装 ApolloTab 引擎复杂操作
• 异步处理: QThreadPool + QRunnable 多线程加载

关于 ApolloTab 引擎

本项目 GTP（Guitar Pro）功能基于 ApolloTab 引擎构建。ApolloTab 是一个独立的 Python 库，提供：

• 文件解析: 完整支持 GP3/GP4/GP5/GPX 格式
• 六线谱渲染: QPainter 高质量绘制，18 种演奏技巧符号
• 音频播放: FluidSynth MIDI 合成，推弦渐变效果
• 高度可配置: 渲染参数全部可调（线宽/间距/颜色/字体）

# 单独安装 ApolloTab
pip install ApolloTab

# 作为独立库使用
from ApolloTab import parse_gtp, render_gtp, SynthEngine
song = parse_gtp("my_song.gp5")
pages = render_gtp("my_song.gp5", track_index=0)

详见 ApolloTab GitHub。

打包发布说明

支持 Windows (EXE)、Linux (DEB / ZIP) 和 macOS (APP) 三种平台的打包发布。

Windows（EXE 安装包）

无需 Python 环境，直接运行。

# 从源码打包（需要先安装依赖，见方式一第1-4步）
pip install pyinstaller -i https://pypi.tuna.tsinghua.edu.cn/simple
pyinstaller "TAB Score Viewer.spec"

# 双击运行 TAB Score Viewer.exe

macOS（APP 安装包）

原生 .app 应用包，完整 GUI 支持。

前置条件：

# 安装构建工具（如果尚未安装）
xcode-select --install                    # Xcode 命令行工具
pip install pyinstaller -i https://pypi.tuna.tsinghua.edu.cn/simple

构建：

# 使用 macOS 专用 spec 文件打包（含 runtime_hook_macos.py）
pyinstaller "TAB Score Viewer_macOS.spec"

# 生成的 .app 包位于：
#   dist/TAB Score Viewer.app

# （可选）生成 DMG 安装镜像以便分发：
bash build_dmg.sh
# 输出: dist/TAB Score Viewer_2.7.6.dmg

构建组件说明：

运行：

# 方式 A：在 Finder 中双击 TAB Score Viewer.app
# 方式 B：从终端运行
open "dist/TAB Score Viewer.app"

# 如果通过 DMG 安装：从 /Applications 启动
open "/Applications/TAB Score Viewer.app"

系统依赖（GTP 音频播放需要）：

# 通过 Homebrew 安装 FluidSynth
brew install fluid-synth

# 或通过 MacPorts
sudo port install fluid-synth

注意：Qt5（PyQt5 依赖）随 Python 包一起安装，无需系统级 Qt 安装。GTP 音频仍需 SoundFont 文件（soundfont/FluidR3_GM.sf2）——详见快速开始中的下载说明。

macOS 特别说明：

• .app 包包含所有依赖（Python 运行时、PyQt5、动态库、翻译文件、图标等）
• runtime_hook_macos.py 在主脚本之前执行，设置 DYLD_LIBRARY_PATH 并以 RTLD_GLOBAL 模式预加载所有 dylib，确保 pyfluidsynth 能正常加载 FluidSynth
• macOS Gatekeeper 可能阻止未公证的应用：前往 系统设置 → 隐私与安全性，点击「仍然打开」

Linux（DEB 安装包 - 推荐）

自动解决依赖关系，系统级安装，全局可用 tabsv 命令启动。

# 1. 安装构建工具（如果尚未安装）
sudo apt-get install dpkg-dev fakeroot   # Debian/Ubuntu
# 或: sudo dnf install rpm-build fakeroot  # Fedora/RHEL

# 2. 执行构建脚本（自动完成 PyInstaller 打包 + DEB 打包）
chmod +x build_deb.sh && ./build_deb.sh

# 3. 安装生成的 .deb 包
sudo dpkg -i tab-score-viewer_2.7.6_*.deb
sudo apt-get install -f  # 自动修复缺失的依赖

# 4. 运行（全局命令，无需输入完整路径）
tabsv

DEB 包安装后的目录结构：

系统依赖（apt 会自动安装）：

• libfluidsynth3 - FluidSynth 音频合成库
• libsndfile1 - 音频文件格式支持
• libpulse0 / libasound2 - 音频输出（PulseAudio / ALSA）
• libqt5widgets5, libqt5gui5, libqt5core5a - Qt5 图形界面框架
• libportaudio2 - 麦克风音频输入（PortAudio）

Linux（ZIP 压缩包 - 便携版）

免安装，解压即用，但需要手动安装依赖库。

# 1. 先执行 PyInstaller 打包
pyinstaller "TAB Score Viewer_linux.spec"

# 2. 创建 ZIP 压缩包
cd dist
zip -r "../tab-score-viewer-linux.zip" "TAB Score Viewer"
cd ..

# 3. 解压并运行
unzip tab-score-viewer-linux.zip
cd "TAB Score Viewer"
./"TAB Score Viewer"   # 注意：文件名含空格，需要用引号包裹

ZIP 方式需要手动安装的依赖：

# Ubuntu/Debian:
sudo apt-get install libfluidsynth3 libsndfile1 libpulse0 libasound2    libqt5widgets5 libqt5gui5 libqt5core5a libc6 libportaudio2

# Fedora/RHEL:
sudo dnf install fluidsynth-libs libsndfile pulseaudio-libs alsa-lib    qt5-qtbase-gui qt5-qtbase qt5-qtbase

# Arch Linux:
sudo pacman -S fluidsynth libsndfile pulseaudio alsa-lib qt5-base

spec 配置说明 (TAB Score Viewer.spec)

注意：macOS 使用独立的 TAB Score Viewer_macOS.spec 文件（配合 runtime_hook_macos.py 运行时钩子处理动态库加载），而非 Windows 的 spec 文件。构建前需先运行 bash prepare_macos_build.sh 收集并修复动态库。Linux 构建使用独立的 TAB Score Viewer_linux.spec 进行平台特定配置。

第三方组件许可证

FluidSynth

本项目使用 FluidSynth 作为音频合成引擎（通过 ApolloTab 引擎调用）。

• 许可证: LGPL 2.1
• 仓库地址: https://github.com/FluidSynth/fluidSynth
• 使用方式: 预编译的 DLL 文件位于项目根目录（libfluidsynth-3.dll、SDL3.dll、sndfile.dll）
• 用途: 将 MIDI 事件合成音频输出，用于 GTP 吉他谱的音频播放功能（含推弦渐变效果）
• SoundFont: soundfont/FluidR3_GM.sf2（GM 音色样本，约140MB，需单独下载）

FluidSynth 是一个开源的 MIDI 合成器，基于 SoundFont 技术，支持高质量的实时音频生成。

ApolloTab

• 许可证: LGPL 2.1
• 仓库地址: https://github.com/Zhuwenqian/ApolloTab
• 用途: GTP 文件解析、六线谱渲染、音频播放核心引擎

许可证

本项目采用 GNU Affero General Public License v3 (AGPL v3) 许可证。

AGPL v3 网络条款 (Section 13): 若你修改本项目并以网络服务方式提供 (SaaS / web app / remote API), 必须向该服务的用户提供修改后版本的完整源代码。这条比 GPL v3 更严格, 是为了防止「服务化规避开源义务」。

完整许可证文本与依赖兼容性矩阵见 LICENSE 文件。

2026-07-31 之前本项目采用 MPL 2.0 许可证；因 PyMuPDF 1.24+ 切换为 AGPL v3, 为保持依赖一致性, 整体迁移至 AGPL v3。许可证切换不影响现有用户的使用权, 仅影响二次分发与网络服务条款。

作者

Zhu Wenqian

TAB Score Viewer 与 ApolloTab 引擎均为同一作者开发。

联系方式

AI 辅助声明

本项目代码由 AI辅助生成，作者负责架构设计、功能规划、代码审查与整合。AI 工具大幅提升了开发效率，但所有核心设计决策均由人工完成。