BandBuddy 的核心不是“把人声去掉”，而是让一首歌真正变得可练：听清目标声部、放慢困难小节、循环到肌肉记住、跟着准确节拍进入，再在下一次打开时从原来的位置继续。

项目主页 · 下载最新正式版 · 隐私说明 · 源码版本 3.0.1 · Windows x64 / macOS Apple Silicon

本文对应当前源码；GitHub Release 的版本与安装文件以发布页为准。主要入口包括曲库与练习室、排练、练功房和军火库。

从听歌到练琴

flowchart LR
  A["导入歌曲"] --> B["先生成六轨，再补齐三条吉他细分轨"]
  B --> C["听清：Mute / Solo / 增益"]
  C --> D["拆练：变速 / 升降调 / A–B 循环"]
  D --> E["练准：BPM / 节拍器 / 预备拍"]
  E --> F["录下：多轨 Take / 整场排练"]
  F --> G["自动保存，下次继续"]
  G --> H["导出分轨或练习混音"]

BandBuddy 把一次有效练习整理成一条很短的路径：选歌 → 分轨 → 聚焦 → 慢练 → 循环 → 合奏。账号、云曲库和联网播放器都不是这条路径的前提；音乐、模型、练习状态和导出结果都留在你的电脑上。

界面

曲库会记住最近练过什么、练到哪里，并把分轨任务状态、收藏和搜索放在同一个入口。截图使用演示数据，项目不附带其中的音乐。

练习室让已生成的分轨共用一条播放时钟和同一段 A–B 区间。HTDemucs 六轨完成后歌曲就能开始练习，三条吉他细分轨会在后台继续生成；期间“吉他分轨”按钮会显示等待说明，完成后在按钮旁即时通知。打开该模式时，原 Guitar 自动静音并隐藏，切换为 Acoustic、Lead、Rhythm 三轨。所有调整都会自动保存。

为练琴准备的功能

AI 图文对话

• 点击界面右下方的悬浮 AI 图标打开对话窗口，可收起后继续操作软件。支持新建、切换、重命名、删除会话，以及停止和重试回复。
• 图片可通过选择文件、粘贴或拖入添加，支持 PNG、JPEG、WebP、GIF；每条消息最多 4 张，单张不超过 5 MB、合计不超过 12 MB。图片随消息保存，重启后可继续查看。
• 可直接打开 AI 对话。在「设置 → 实验室功能 → AI 对话」填写自己的 Base URL、Token / API Key 和模型名后，点击「检验配置」，通过后自动保存并启用；也可先保存表单稍后检验。支持 OpenAI Chat Completions 兼容接口，仅开放这三个配置，其他参数固定使用软件默认值（流式回复、120 秒超时、图片细节自动，生成参数使用服务商默认值）。旧版保存的高级参数自动恢复为默认值。
• 上下文最多 20 轮（含本次提问）；达到 20 轮或上下文文字（含已有摘要）超过 32768 字符时，自动将较早对话压缩成摘要并保留近期对话。摘要和压缩位置保存在本机，重启后继续使用；完整历史不受压缩影响。压缩失败或取消时保留完整历史，可重试。
• AI 音乐小伙伴「邦邦」会通过当前模型接口识别问题意图：软件功能与操作问题参考随应用打包的指南；当前设置、音频设备、分轨任务和报错问题按需读取脱敏信息；其他问题直接回答。状态查询只读，不修改配置、执行命令或打开麦克风。指南源文件为 resources/ai-assistant-guide.json。
• 邦邦喜欢音乐，语气俏皮亲切，不介绍后台模型身份。密钥不放入参考资料，流式回复与保存内容另有密钥过滤。生成参数使用服务商默认值。图片理解能力由所选模型提供。发送时，会将上下文文字、图片及必要的指南或脱敏状态提交到配置的接口；连接检验会发送一条简短测试消息。
• 会话与图片保存在应用用户目录的独立 ai-chat.db 中，首次使用时才打开数据库；Token 通过 Electron safeStorage 加密保存，不会返回到普通设置对象或写入聊天诊断日志。中断回复会保留已收到的内容，并可在重启后重试。
• 源码不包含共享 API Key。自行构建默认通过上述设置配置接口；如需使用源码中的默认服务，可在启动主进程前设置 BANDBUDDY_AI_TOKEN 环境变量。未提供凭据时会提示配置，不发送默认服务请求。

军火库：搭建音色、监听与快录

• 从八个原生起始音色开始，或搭建最多 24 个模块的效果链；支持重复模块、拖动排序、复制、旁通和删除。
• 使用箱头、箱体、动态、均衡、调制、延迟与混响，并可导入自己的 NAM 模型和 IR。资源逐文件校验，支持名称、标签和备注管理。
• 保留工作台草稿，支持撤销/重做、会话内 A/B 快照、用户预设、收藏、搜索和 .bbtone 导入导出。预设文件包含参数与资源哈希，NAM / IR 文件需另行导入。
• 原生监听可跨页面保持，全局状态条支持返回或停止；重新启动应用不会自动开启输入。调音器使用同一原生输入，调音时静音效果声，伴奏仍可播放。
• 快录保存原始 DI 和开始录制时的音色快照；可选择最长 60 秒片段循环调音，导出 DI 或用当前音色导出效果声。
• 监听开启时，练习伴奏可以与输入共用原生立体声输出。设备面板显示真实输入/输出电平、驱动与 DSP 报告延迟、处理负载和中断次数。

操作与验证范围见军火库工作台验收记录。原生练习室预览、本机 VST3 / Audio Unit 插件与录音保护的使用入口和验收边界见原生音频与本机效果插件；NAM A2 的参考插件对照见NAM A2 数值对照。

练功房：从知识到专项练习

• 按“体系卡片 → 路线图 → 知识正文”学习，教材、图解和谱例随应用打包，可离线阅读。
• 覆盖十个知识体系，提供电吉他、原声吉他、贝斯、尤克里里、鼓、钢琴与键盘的乐器情境；文章包含学习目标、步骤、例子、常见问题和自检。
• 合成器体系包含 9 个阶段、36 课，涵盖减法、FM、波表、加法、采样、颗粒与模块化等内容，操作实验供读者在自己的软硬件合成器中完成。
• 专项练习与合奏练习使用统一 MusicXML 阅读器呈现五线谱、TAB、打击乐谱和钢琴大谱表，并支持播放高亮与谱面内部滚动。
• 指板实验室用于探索音阶与和弦；工具箱提供节拍器、调音器、鼓机、和弦查询、五度圈与持续参考音。

教材目录与维护方法见练功房教材说明。

听清每一个声部

• 分轨分成两个持久化阶段：先生成 Vocal / Drums / Bass / Guitar / Piano / Other 六轨并开放练习室，再在后台补齐 Acoustic / Lead / Rhythm。
• 原六轨模式和吉他细分模式即时切换；隐藏备选轨不参与 Solo、独立输出、快捷键选择或默认混音导出。
• 练习室的「人声分轨」与「吉他分轨」一样是切换按钮：点击开启后显示主唱、和声两轨，再次点击恢复完整人声。尚未生成时按需细分已保存的人声，期间继续使用完整人声，完成后自动开启；后台自动生成只提示就绪。人声音轨菜单保留「去主唱，保留和声」「仅听和声」，播放中切换采用预载和淡化。
• 新歌曲在基础分轨完成后自动细分主唱与和声，期间即可使用基础分轨练习；细分完成后提示就绪，通过练习室「人声分轨」按钮切换。首次使用按需下载模型，沿用全局 FLAC 24 位／MP3 320 kbps 保存选项；模型失败、取消或重试均保留基础分轨。局域网网页支持同一组切换，旧 v1 客户端仍获取完整人声。
• 设置中的「人声分轨档位」提供效率档（Mel-Band RoFormer，aufr33 / viperx）和质量档（BS-RoFormer，frazer / becruily），默认效率档。手动及自动细分均使用所选档位，已排队任务保留创建时的模型。两套模型从 ModelScope BandBuddy-Models 的固定 vocal-v1.0 标签按需下载，由 resources/vocal-model-catalog.json 固定文件大小、版本与哈希；scripts/verify-vocal-split.py 可对已保存人声批量做两模型推理和编码校验。
• 当前模式的同步波形可独立 Mute、Solo 和调节增益，另有主音量控制。
• 选择多通道输出设备后，每条分轨可独立路由到 1–2 / 3–4 / … 立体声通道对，便于通过 Loopback 等虚拟声卡送入 DAW。
• macOS 下选择 Loopback 时会自动修复其全部为“未知”的声道标签，避免 8 路设备被识别为 2 路；保留已配置的声道布局。单声道素材在所选立体声通道对中居中播放。
• Piano 是实验性声部；复杂编曲里可能与 Guitar 或 Other 串音，界面会持续提示这一点。

把难点缩小，反复练会

• 在波形上选择区间，或连续点击同一个 A–B 按钮：第一次设置 A，第二次设置 B 并立即开始循环，第三次取消。按钮会显示等待 B 点和循环中的不同状态，循环边界会随歌曲保存。
• 点击“跳回并播放”可立即重练：循环启用时跳回 A 点，否则跳回歌曲开头；暂停时也会直接开始播放，不重复预备拍。
• 提供 0.5× / 0.8× / 1.0× / 1.2× / 1.5× 快捷速度，以及 0.20×–4.00× 无级变速，播放时保持音高。
• 底部播放栏可直接点 ♭ / ♯ 降低或升高 1 个半音，范围为 -12–+12（上下各一个八度），并可一键恢复原调；点击调值可打开滑轨。使用 Signalsmith Stretch 实时统一调整人声、贝斯、吉他、钢琴及其他分轨，鼓轨保持原音并自动补偿延迟，播放速度不变。
• 已生成轨由同一主时钟校正；后台补齐吉他三轨时会无中断接入当前歌曲，之后的变速、跳转、循环和模式切换仍保持同步。
• 播放位置、速度、升降调、循环、每轨 Mute/Solo/增益/输出通道对、缩放与滚动视图都会自动保存。

看着视频一起练

• 支持导入 MP4 / M4V / MOV / MKV / WebM / AVI。后台先提取音频，再交给本地分轨；原视频文件会保留在受管曲库中。
• 视频歌曲在练习室显示视频画面和当前模式的混音控制，替代波形视图；纯音频歌曲使用同步波形。
• 画面跟随分轨的播放、暂停、跳转、A–B 循环和 0.20×–4.00× 速度变化，原视频音轨静音，避免与分轨重复发声。
• 支持按钮或双击画面进入全屏；全屏内可控制播放、进度、速度、循环和跳回重练。
• 视频必须包含音轨。不兼容的画面编码会在本机转换为可播放副本，处理时间和额外磁盘占用取决于视频长度与分辨率。

跟上节拍再进入

• 可优先分析鼓轨自动检测 BPM，也可以手动修改。
• 可在本机识别歌曲主调与大小调，显示置信度；低置信度时给出前三候选，并按片段提示可能转调的位置。识别结果支持手动纠正，重新分析不会覆盖手动选择。
• 内置节拍器支持拍点提前/延后微调，并随播放速度同步。
• 支持关闭、4 拍或 8 拍预备拍，让手和乐器先准备好再进入歌曲。

录下练习并比较 Take

• 在练习室创建多条录音轨，从任意播放位置开始录制；每条轨可保留多个 Take，并独立选择、命名、Mute、Solo 和调节增益。
• 支持 Windows WASAPI、macOS CoreAudio，以及系统可用时的 ASIO；可以选择输入/输出设备、单声道或立体声通道、采样率与 Buffer，并先做输入电平测试。
• 预备拍不会写入 Take；可按设备保存对齐偏移，分离输入/输出设备时会做时钟校正并显示 xrun 计数。
• 导出当前练习混音时，可以把所有启用的录音轨一起混入，并保持录制时的练习速度、调性与位置关系。

编排和录制整场排练

• 创建多份排练编排单，把曲库歌曲和可调时长的空白衔接拖入队列并重新排序。
• 按每首歌保存的速度、预备拍、节拍器与混音状态连续播放整条时间线，也可以随时进入单曲练习后返回原排练位置。
• 为整场排练建立多条录音轨，从当前时间线位置连续叠录、暂停或继续；每个 Take 绑定当时的编排修订，后续改动不会让旧录音失去上下文。

跟着时间轴歌词练习

• 为歌曲导入或替换标准 .lrc 时间轴歌词。
• 在独立的置顶桌面歌词窗口显示当前句、下一句和歌曲进度；排练连续播放时会随当前歌曲自动切换。

管理自己的练习曲库

• 导入音频 MP3 / WAV / FLAC / M4A / AAC / OGG / OGA / OPUS / AIF / AIFF / WMA / M4B / APE / WV / MP2 / AC3 / CAF，并兼容用户有权使用的本地 .ncm 文件。
• 导入带音轨的视频 MP4 / M4V / MOV / MKV / WebM / AVI / WMV / FLV / MPG / MPEG / TS / MTS / M2TS / VOB / 3GP / 3G2 / OGV / ASF；具体编码须受内置 FFmpeg 支持，不支持 DRM 加密媒体。
• 基础分轨和吉他细分均先用 FFmpeg 解码为 44.1 kHz 双声道浮点 WAV，保留原文件；视频额外保留音画时间对齐。
• 搜索歌曲或艺术家，按收藏、处理中、最近练习筛选，并在列表/卡片布局间切换。
• 后台任务展示分轨和导出进度；支持取消、重试，以及显存不足后使用相同质量参数的 CPU 重试。
• 可从曲库或练习室编辑标题、艺术家、BPM、歌曲调与拍号；歌曲调既可本地识别，也可手动纠正。
• 启动时会核对已保存的播放与录音设备；明确选择的设备与 ASIO 配置会保留，设备异常时停止受影响的监听，不会恢复后自动换用另一支麦克风或扬声器。
• 设置中的 Debug 模式切换后立即生效，会把 renderer、preload、IPC 与进程异常写入 debug.log；设置页可直接在文件管理器中定位该文件，代理凭据、令牌和密码会先脱敏。
• 删除的受管歌曲会先进入系统废纸篓 / 回收站。

带走分轨或当前练习混音

• 分别导出所选标准分轨，或导出应用了 Mute、Solo、每轨增益与主增益的当前混音。
• 导出会自动保留当前 Signalsmith 升降调：所有非鼓轨变调，鼓轨保持原音；当前混音还可选择应用练习速度、只导出 A–B 区间，并在输出前限制峰值避免削波。
• 支持 WAV / FLAC（44.1 kHz、24-bit）和 MP3（320 kbps）。

局域网练琴与移动端同步

在设置中开启「局域网模式」，即可用同一网络的手机、iPad 或电脑访问设置页显示的地址，独立播放曲库中已完成分轨的歌曲。支持播放/暂停、AB 循环、±12 半音升降调、音轨浮窗中的音量/M/S、歌词与视频。默认使用 60232 端口，冲突时自动选择空闲端口。关闭模式或退出 App 后访问地址失效。

桌面端还提供 UDP/HTTP 发现、移动客户端握手、歌曲 manifest、带 SHA-256 校验的分轨和视频下载，以及 Range 断点续传。详见 移动端同步协议 v1。

导入窗口恢复「已分轨数据」入口，支持 2–9 条已有音轨、预设或自定义轨道名称，直接进入标准化队列，无需安装分离模型。

常用快捷键

以下快捷键用于歌曲练习室。

按键	操作
Space	播放 / 暂停
← / →	后退 / 前进 5 秒；按住 Shift 时为 1 秒
↑ / ↓	选择上一条 / 下一条音轨
M / S	切换当前音轨的 Mute / Solo
+ / - / 0	当前音轨增益 +1 dB / -1 dB / 归零
L	依次设置 A、设置 B 并开始循环、取消循环
A / B	重新设置 A 点 / 设置 B 点并开始循环
Home	跳回 A 点（循环中）或歌曲开头，并继续播放
Esc	全屏时退出全屏；其他时候清除循环区间

本地优先

• 无需上传音乐：分轨、波形、BPM 与歌曲调检测、混音和导出全部在本机完成。
• 独立运行环境：应用安装私有 CPython、PyTorch 和 Demucs，不读取系统 Python、PATH 或注册表 Python。
• 按设备自动回退：Windows 优先使用可用的 NVIDIA CUDA，macOS 优先使用 Apple MPS；不可用、设备失效或显存不足时可回退 CPU。
• 加速异常保护：CoreML / CUDA 的 ONNX 模型即使成功加载，运行失败时也会用同一模型在 CPU 重试当前片段。Apple Silicon 的分轨进程默认限制 MPS 内存占用，避免大模型耗尽共享内存后长时间等待；超限后由任务队列使用相同质量参数在 CPU 重试。显式设置的 PyTorch MPS 内存环境变量仍会保留。
• 可验证的依赖：uv、FFmpeg 和模型按固定版本下载并校验 SHA-256；代理凭据会从日志中脱敏。
• 可恢复的数据操作：SQLite 使用 WAL 和迁移备份；重新分轨成功前保留旧版本，删除音乐时先移动到回收站。

曲库首次显示后，应用会在后台检查并准备所需组件；录音或原生监听期间推迟准备。可在“设置 → 运行状态”查看各功能状态、下载进度，暂停、继续、一键修复或导出本地诊断。主动暂停会跨启动保留。

分轨环境会下载私有 Python、Torch 和固定的四份权重。所需空间随 CPU / CUDA 后端及缓存变化，安装前会检查各目标磁盘的可写性与峰值空间。Python、wheel 与模型支持缓存、续传及完整性校验；候选环境通过依赖导入、ONNX CPU 运算和六轨短推理后才启用，修复失败保留此前可用环境。

连续启动失败时会进入兼容启动，暂停后台准备与自动原生设备枚举；数据库异常时提供恢复入口，由用户选择备份。详见环境准备与恢复说明。

设置中的“高音质分轨”决定新任务两个阶段的最终存储格式：关闭时全部轨统一保存为 44.1 kHz、stereo、320 kbps MP3，开启时统一保存为 44.1 kHz、stereo、24-bit FLAC。吉他细分另有“极速 / 平衡 / 高质量”三个推理档位；存储格式开关不会改变所选推理档位，已有歌曲只有重新分轨后才会改变格式。

中国大陆与受限网络

应用默认启用“中国大陆镜像”环境源，也可以在“设置 → 高级网络 → 环境下载源”切换为官方源或逐项填写自定义 HTTPS 地址：

内容	大陆下载源	完整性与回退
私有 CPython	npmmirror 的 python-build-standalone 镜像	平台清单固定版本、大小与 SHA-256；官方文件作为备选，下载可缓存续传
Demucs 与常规 Python 包	清单中已核验的国内镜像及官方备选源	包含间接依赖的 wheel 固定版本、大小与 SHA-256；下载后从本地缓存安装
PyTorch / Torchaudio	固定 wheel 清单中的镜像与官方源	Windows 提供 CPU、CUDA 12.8 / 13.0 清单；结合驱动、GPU 架构与真实运算测试选择后端
六份基础／吉他分轨权重	ModelScope BandBuddy-Models 固定 v2.0.1 标签	固定文件路径、字节数与完整 SHA-256；全部验证后原子写入完成标记
两份主唱／和声细分权重	同仓库固定 vocal-v1.0 标签	按档位下载，校验固定字节数与完整 SHA-256；对应配置随应用附带

环境镜像不可用时，可先切换另一环境下载源再点“修复环境”；已完成的缓存和权重 .part 文件会继续使用。公司网络还可以选择系统代理或填写手动 HTTP(S) 代理。Python 包与桌面工具可切换镜像，权重下载地址和固定版本不可由用户修改，所有完整性校验始终开启。

安装 Windows 版

前往 Releases，按需要下载：

• BandBuddy-<版本>-x64.exe：安装版，可选择安装位置并创建桌面/开始菜单快捷方式。
• BandBuddy-<版本>-x64-portable.exe：便携版，无需运行安装向导。
• SHA256SUMS.txt：用于校验下载文件完整性。

开源 CI 在没有 Authenticode 证书时会发布未签名构建，Windows SmartScreen 可能显示“未知发布者”。Release 说明会标明该版本是否已签名；如果你不接受未签名程序，可从源码构建，或等待 Microsoft Store / 已签名版本。

安装 macOS 版

Releases 提供 Apple Silicon 原生 DMG 和 ZIP：

• BandBuddy-<版本>-macos-arm64.dmg / .zip：Apple Silicon Mac。

签名、公证状态与校验文件以具体 Release 说明为准。应用基础功能的最低版本声明为 macOS 13；Apple Silicon 本地分轨依赖清单采用 ONNX Runtime 1.23.2，完整本地分轨依赖最低版本为 macOS 13.4+（仍需最低系统真机验收）。

从源码运行

需要 Windows 10/11 x64 或 macOS Apple Silicon、Node.js 24+、pnpm 11+、CMake 3.24+ 与 C++20 编译器。Windows 可从微软的 C++ Build Tools 指引 安装 Visual Studio 2022，并勾选“使用 C++ 的桌面开发”和 CMake 工具；构建脚本会自动查找其自带的 cmake.exe，也可通过 CMAKE_EXECUTABLE 指定。macOS 使用 Xcode Command Line Tools。系统无需预装 Python、Torch、CUDA Toolkit 或 FFmpeg。

git clone https://github.com/dourgey/BandBuddy.git
cd BandBuddy
pnpm install
pnpm tools:fetch
pnpm prepare:drums
pnpm native:audio
pnpm test
pnpm dev

pnpm dev 会先构建原生音频宿主；Windows 下还会构建系统辅助程序并准备经过签名验证的微软运行库安装器，因此首次构建需要联网。

pnpm tools:fetch 会下载并逐文件校验固定版本的 uv 与 FFmpeg。鼓机的 34 个 FLAC 音色不存入 Git：先将原始 MODO-DRUM-STUDIO-One-Shots 音源包解压至下载目录，再运行 pnpm prepare:drums；其他位置可用 pnpm prepare:drums /path/to/MODO-DRUM-STUDIO-One-Shots 指定。准备过程逐项验证源文件 SHA-256 和无损压缩前后的 PCM，并更新本机 FLAC 清单。pnpm verify:drums 可独立检查结果，缺少音源包时构建会明确停止。

pnpm native:audio 编译并测试当前平台的原生音频宿主，也让 pnpm test 能运行原生效果器测试。修改 native/effects 后，还需在已激活 Emscripten 的终端运行 pnpm build:effects:wasm 更新仓库中的 WASM 工件；pnpm test:whitebox 比较原生与 WASM 输出及离线导出的一致性。

只查看界面时可运行 pnpm dev:renderer，然后打开 http://localhost:5173/?fixtures=1；fixture 模式只在开发环境启用，不会进入正式构建。

中国大陆可使用下面的流程；镜像配置只对当前命令生效，不会改写用户的全局 .npmrc：

# GitHub 无法直连时，可通过第三方代理克隆；有条件时仍优先使用上面的官方地址
git clone https://ghfast.top/https://github.com/dourgey/BandBuddy.git
cd BandBuddy

# 如果尚未安装 pnpm
npm install --global [email protected] --registry=https://registry.npmmirror.com

pnpm install:cn
pnpm tools:fetch:cn
pnpm prepare:drums
pnpm native:audio
pnpm test
pnpm dev:cn

install:cn 使用 npmmirror 获取 npm、Electron、electron-builder 和 better-sqlite3 的 Node 预构建文件；Electron ABI 没有对应预构建时，会使用前述 C++ 工具在本地重建。tools:fetch:cn 会依次尝试多个 GitHub 代理，原生音频依赖默认使用 ghfast.top；两者都保留断点或构建缓存，并在失败时尝试官方地址。所有固定桌面工具仍按 resources/tool-manifest.json 校验 SHA-256。若需要使用自建 GitHub 代理，可在运行前设置 BANDBUDDY_GITHUB_PROXY（其格式为可直接前置到完整 GitHub URL 的 HTTPS 前缀）。第三方代理不等同于 GitHub 官方服务，请结合可信渠道核对源码 commit。

构建 Windows 包

pnpm package:dir       # 未签名的解包目录：release-unsigned/win-unpacked
pnpm package:unsigned  # 未签名安装版 + 便携版：release-unsigned
pnpm package           # 需要 Authenticode 证书的正式签名包：release
pnpm package:store     # Microsoft Store AppX：release-store

签名构建通过 WIN_CSC_LINK 与 WIN_CSC_KEY_PASSWORD 向 electron-builder 提供 PFX/P12 证书。pnpm package 会在证书缺失、签名无效或任一 .exe/.dll/.node 未签名时失败。

构建 macOS 包

pnpm package:mac:dir        # 强制 Developer ID 签名并验证 .app
pnpm package:mac            # 强制签名、验证 DMG + ZIP：release-macos
pnpm package:mac:notarized  # 签名 + Apple 公证 + 票据及 Gatekeeper 验证
pnpm verify:mac:signatures  # 重新验证 release-macos 的签名、安装包与独立启动
pnpm package:mac:unsigned   # 仅供无证书 CI / 开发测试：release-macos-unsigned
pnpm package:mac:x64        # Intel 原生构建；依赖发布门禁未完成时明确阻止
pnpm package:mac:x64:unsigned  # Intel CI 测试包，同样需要通过依赖门禁

默认构建 Apple Silicon（arm64）包；Intel 命令包含 :x64，也提供 :dir / :notarized 变体。必须在对应架构的原生 Mac 上构建，以便 Electron、better-sqlite3、uv 和 FFmpeg 保持同一架构。发布校验逐一检查 Mach-O 架构和最低部署版本（macOS 13）。

Intel 分轨依赖目前尚未完成原生发布验收，不能仅根据构建脚本宣称已支持。先手动运行 Intel runtime wheel workflow：从固定 SHA-256 的 sphn 0.1.12 官方源码构建 CPython 3.12 / macOS 13 x64 wheel，静态链接 Opus；所有传递依赖准备为 wheel，并在 Intel CPU 上验证中文路径音频往返、真实 ONNX 推理、六轨分离及 fast / balanced / high 吉他分离。该任务仅上传供审查的 CI 产物，不自动发布。

原生验收还必须与已审查 CPU 参考逐轨比较，覆盖六轨和三个吉他质量档位的共 15 个输出；固定输入、种子、模型哈希、生产代码哈希、误差阈值及参考导出命令见环境鲁棒性说明。有限数值或正确形状不能代替输出比较。参考 pin 和真实波形包缺失时 CI 明确阻止验收。

审查通过后，将完整 wheelhouse 发布到固定版本的 GitHub Release，再提交产物中的 resources/runtime-wheels.json、python/runtime/macos-x64.lock、python/runtime/macos-x64-validation.json、python/runtime/macos-x64-cpu-comparison.json 以及已审查的 python/runtime/cpu-reference.json。当前清单为空，正式参考 pin 尚未提交；Intel 打包会明确失败，直到完整锁、匹配的原生及数值验证证据和全部线上 wheel 的哈希均通过校验。用户机器不会编译这些依赖。

签名是默认打包的必经步骤：使用钥匙串中团队 M6M993UYR9 的有效 Developer ID Application 证书，或通过 CSC_LINK / CSC_KEY_PASSWORD 提供该团队的 P12。脚本使用证书指纹，避免同名证书歧义；可用 BANDBUDDY_MAC_SIGN_IDENTITY 明确指定指纹。缺少证书、任何签名/校验失败都会终止构建，不自动降级为未签名包。

脚本按文件头扫描包内所有 Mach-O，包括主程序、Electron Helper / Framework / 动态库、crashpad、SQLite .node、uv、ffmpeg、ffprobe 和原生 audio-host，先签内部代码再签外层容器，启用安全时间戳和 Hardened Runtime。Python、JSON、语言资源等由 App 资源封印保护，不逐个当作可执行文件签名。新增内嵌原生依赖会自动纳入扫描与逐项验证。签名时遵循 Apple 的嵌套代码签名流程。

打包后自动检查 DMG 自身签名、DMG 镜像完整性、DMG/ZIP 内完整应用签名及发布者，并从独立临时目录启动解压后的应用，确认 FFmpeg 不依赖源码目录。按架构生成 SIGNATURE-REPORT-macos-arm64.json / SIGNATURE-REPORT-macos-x64.json 及对应的 SHA256SUMS-macos-<arch>.txt。构建前仍用上游固定 SHA-256 校验工具原件；运行时只有完整 App 的资源封印及指定发布者签名验证通过，才接受签名导致的内嵌工具哈希变化。

默认签名包不等同于 Apple 公证。package:mac:notarized 额外要求 APPLE_KEYCHAIN_PROFILE（可选 APPLE_KEYCHAIN），或 APPLE_ID / APPLE_APP_SPECIFIC_PASSWORD / APPLE_TEAM_ID，或 APPLE_API_KEY / APPLE_API_KEY_ID / APPLE_API_ISSUER。公证票据或 Gatekeeper 检查未通过，构建同样失败。安装时下载到用户数据目录的 Python 及依赖不属于 App 包内签名清单。

CI 与 Release

• Windows CI 在 main、Pull Request 和手动运行时执行资源校验、类型检查、测试与未签名 Electron 打包，并保存构建产物。
• macOS CI 使用 Apple Silicon 与 Intel 原生 runner 运行源码测试。默认只生成 Apple Silicon 测试包；Intel 打包在仓库变量 ENABLE_INTEL_MAC_RELEASE=true 时启用，仍须通过全部依赖与数值验收门禁。
• Release workflow 在推送与 package.json 版本一致的 v* 标签时，默认继续构建和发布 Windows x64、macOS arm64，并明确说明 Intel 尚待验收。完整提交并审查 Intel 证据后，设置仓库变量 ENABLE_INTEL_MAC_RELEASE=true 将 x64 纳入发行；此后必须三个平台及签名、依赖和 CPU 数值门禁全部通过才发布，Intel 失败不会静默退回双平台发行。
• macOS Release 必须配置 MACOS_CSC_LINK 和 MACOS_CSC_KEY_PASSWORD，强制执行签名与安装包验证；缺少凭据会失败，不再发布未签名 macOS Release。
• 如果仓库配置了 WINDOWS_CSC_LINK 和 WINDOWS_CSC_KEY_PASSWORD，Release workflow 会生成并验证签名包；否则会明确发布未签名社区构建。

项目结构

路径	职责
src/main	Electron 主进程、SQLite、任务队列、导入/导出与安全边界
src/preload	经过约束的 renderer ↔ main IPC 桥
src/renderer	React 曲库、练习室、练功房、军火库与播放器
native/audio-host	RtAudio / PortAudio 原生录音宿主与设备时钟协议
native/effects	原生效果处理、NAM / IR 与模块化音色链
native/system-helper	Windows 系统依赖检测、签名验证与授权安装辅助程序
resources/learning	离线教材、MusicXML 谱例与 SVG 图解
resources/runtime-catalog	各平台 Python 与完整 wheel 依赖清单
python/worker	HTDemucs 六轨与吉他三轨两阶段工作进程、固定 ModelScope 权重清单及断点下载协议
python/msr_mvp	模型/轨数无关的 MSS → MSR 实验管线与适配器
python/guitar_separator_hq	生产使用的固定 HQ6 木吉他 / Lead / Rhythm 推理模块与独立审计工具
packages/shared	领域类型、Zod schema 与 IPC 合约
resources / scripts	固定桌面工具清单、下载和验证脚本
tests	音频规则、迁移、路径安全、任务状态和播放器测试

更详细的进程边界、数据原子性、音频管线和 worker 协议见 架构说明；MSS → MSR 独立实验见 MVP 说明 和 实测记录；吉他三轨逆向与最高音质实验见 HQ6 说明 和 完整报告。第三方组件及许可见 THIRD_PARTY_NOTICES.md。

当前边界

当前源码面向 Windows x64 与 macOS Apple Silicon；Intel Mac 仍受上文发布门禁约束。提供桌面端托管的局域网浏览器播放，不提供账号、云同步或自动更新。Piano 分轨仍为实验性功能。

军火库的设备模拟不代表对特定硬件的实测复刻；当前统一伴奏输出为立体声，不提供原生多硬件输出总线。自动测试与模拟声卡验证不能替代真实声卡的延迟、拔插、长时间稳定性和听感验收。干净 Windows、其他 GPU / 驱动及 Apple Silicon 最低支持系统仍需相应机器验收；本次源码更新不等于发布新安装包。

欢迎通过 Issues 提交可复现的问题和练琴场景建议。

许可与音频权利

BandBuddy 源码使用 Apache License 2.0。分轨运行时使用 Demucs 4.1.0 与固定的 MSST 架构代码；相应 MIT 许可和版权声明收录在 THIRD_PARTY_NOTICES.md。四份权重不打入安装包，而是从公开的 ModelScope 权重仓库 v2.0.0 分支下载；该仓库按 GPL-3.0 发布并保留来源与第三方声明。

其他第三方工具、库和模型保留各自许可。BandBuddy 不附带音乐；请只导入、处理和导出你拥有或已获授权使用的音频。

支持 BandBuddy

如果 BandBuddy 对你的练习有所帮助，并且你刚好有余力，欢迎请作者喝杯咖啡，支持项目继续维护和改进。赞助完全自愿，不会影响任何功能的使用。

如果希望在赞助名单中留名，请在付款时备注希望展示的名字或 GitHub 用户名；未备注的赞助将默认匿名。感谢你的支持！