Build from Source 从源码构建

This page covers everything you need to clone, install, run, test, and package SXSEditor from source. SXSEditor is built with Electron Forge (webpack plugin) and Babel, with no manual build step required.

本页介绍克隆、安装、运行、测试和打包 SXSEditor 源码所需的全部步骤。SXSEditor 基于 Electron Forge（webpack 插件）和 Babel 构建，无需手动编译步骤。

ℹ️

SXSEditor is licensed under the MIT License. Entry point src/main.js, preload src/preload.js. Built on Electron 42.4.1 and ONNX Runtime 1.27.0. Version numbers are auto-incremented by GitHub CI.

SXSEditor 采用 MIT 许可证。入口 src/main.js，预加载脚本 src/preload.js。基于 Electron 42.4.1 和 ONNX Runtime 1.27.0 构建。版本号由 GitHub CI 自动递增。

Prerequisites 环境要求

Tool工具	Minimum Version最低版本	Notes说明
Node.jsNode.js	>= 18	Required by Electron 42 and webpack plugin.Electron 42 和 webpack 插件所必需。
npmnpm	>= 9	Comes bundled with Node.js 18+.随 Node.js 18+ 一并安装。
GitGit	Any recent version任意较新版本	Required to clone the repository.克隆仓库所需。
OS操作系统	Windows (primary), macOS, LinuxWindows（主要）、macOS、Linux	Native DirectML execution provider is Windows-only. macOS/Linux can still build and run with CPU fallback.DirectML 原生执行提供者仅支持 Windows。macOS/Linux 仍可构建并以 CPU 回退方式运行。
Windows SDKWindows SDK	Optional可选	Only required when rebuilding native modules (e.g. `nan`) for a non-default Electron ABI.仅在为非默认 Electron ABI 重新编译原生模块（如 `nan`）时需要。

💡

ONNX models are not stored in the Git repository (they are git-ignored). They are downloaded automatically on first launch, or you can place them manually in onnx_models/.

ONNX 模型不包含在 Git 仓库中（已被 gitignore）。首次启动时会自动下载，你也可以手动放入 onnx_models/ 目录。

Clone the Repository 克隆仓库

Two mirrors are available. Use GitCode if you are inside mainland China for faster download speeds.

提供两个镜像源。中国大陆用户建议使用 GitCode 镜像以获得更快的下载速度。

GitHub (primary)GitHub（主仓库）

git clone https://github.com/Henley04/SXSEditor.git
cd SXSEditor

GitCode mirror (China acceleration)GitCode 镜像（国内加速）

git clone https://gitcode.com/qq_50331623/SXSEditor.git
cd SXSEditor

Install Dependencies 安装依赖

Run the following from the repository root:

在仓库根目录执行以下命令：

npm install

Key runtime dependencies installed:

安装的主要运行时依赖：

onnxruntime-node — ONNX Runtime with DirectML/CPU execution providers (main process)— ONNX Runtime，提供 DirectML/CPU 执行提供者（主进程）
onnxruntime-web — ONNX Runtime with WebNN EP for NPU/GPU inference (renderer process)— ONNX Runtime，提供 WebNN EP 用于 NPU/GPU 推理（渲染进程）
@tensorflow/tfjs — Basic Pitch MIDI extraction— Basic Pitch MIDI 提取
pinyin-pro — Chinese character → pinyin conversion— 汉字转拼音
decibri — WASAPI audio output (Windows)— WASAPI 音频输出（Windows）
systeminformation — GPU/VRAM detection— GPU/显存检测

⚠️

If you encounter native module build errors after npm install (e.g. nan or segfault-handler), rebuild native modules against the installed Electron ABI:

如果 npm install 后遇到原生模块编译错误（如 nan 或 segfault-handler），请针对已安装的 Electron ABI 重新编译原生模块：

npx electron-rebuild

Run in Development Mode 开发模式运行

The start script launches Electron Forge with the webpack plugin, which compiles main and renderer bundles on the fly and reloads on file changes:

start 脚本通过 Electron Forge 的 webpack 插件启动，实时编译主进程与渲染进程 bundle，并在文件变更时自动重载：

npm start

In development mode:

在开发模式下：

CSP allows 'unsafe-eval' for scripts and connects to the webpack dev server.CSP 允许脚本 'unsafe-eval' 并允许连接 webpack 开发服务器。
The splash screen is skipped — the main window appears immediately after did-finish-load.跳过启动画面，主窗口在 did-finish-load 后立即显示。
Source maps and hot reload are available through @electron-forge/plugin-webpack.通过 @electron-forge/plugin-webpack 提供 source map 与热重载。

Run Tests 运行测试

SXSEditor uses Mocha + Chai + Sinon + JSDOM for testing. Tests live in test/**/*.test.js.

SXSEditor 使用 Mocha + Chai + Sinon + JSDOM 进行测试。测试文件位于 test/**/*.test.js。

npm test                  # Full test suite (30000ms timeout, spec reporter)
npm run test:coverage     # With NYC coverage report (text + html)
npm run test:watch        # Watch mode

Run a single test file:

运行单个测试文件：

npx mocha --require ./test/setup.js "test/trackManager.test.js" --timeout 30000

ℹ️

test/setup.js configures JSDOM, mocks HTMLCanvasElement.getContext, and provides automatic Sinon sandbox cleanup via mocha root hooks. See Testing & CLI for the full test layout.

test/setup.js 配置 JSDOM、模拟 HTMLCanvasElement.getContext，并通过 mocha root hook 自动清理 Sinon sandbox。完整测试布局见测试与命令行。

Packaging 打包

Packaging is handled by Electron Forge. The packagerConfig uses asar with native modules (.node, .dll) and the onnx_models/ directory unpacked.

打包由 Electron Forge 处理。packagerConfig 使用 asar，并将原生模块（.node、.dll）和 onnx_models/ 目录解包。

Lite package (skip ONNX models)精简打包（跳过 ONNX 模型）

Recommended for quick local testing — produces a much smaller output by excluding the multi-gigabyte onnx_models/ directory:

推荐用于本地快速测试——通过排除数 GB 的 onnx_models/ 目录，生成明显更小的输出：

npm run package:lite

Internally this runs cross-env SKIP_ONNX_MODELS=1 electron-forge package. When SKIP_ONNX_MODELS=1 is set, the packager's ignore filter drops onnx_models/ from the keep list, and packagerConfig.asar.unpackDir no longer marks it for unpacking.

内部执行 cross-env SKIP_ONNX_MODELS=1 electron-forge package。设置 SKIP_ONNX_MODELS=1 后，打包器的 ignore 过滤器会将 onnx_models/ 从保留列表中移除，packagerConfig.asar.unpackDir 也不再标记其为解包目录。

Full package (with models)完整打包（含模型）

npm run package

Make installers生成安装包

npm run make

Makers configured in forge.config.js:

forge.config.js 中配置的 maker：

Platform平台	MakerMaker	Output产物
WindowsWindows	`@electron-forge/maker-squirrel`	Squirrel installer (`.exe`)Squirrel 安装程序（`.exe`）
macOSmacOS	`@electron-forge/maker-zip`	Zip archive (`.zip`)ZIP 压缩包（`.zip`）
LinuxLinux	`@electron-forge/maker-deb`	Debian package (`.deb`)Debian 包（`.deb`）
LinuxLinux	`@electron-forge/maker-rpm`	RPM package (`.rpm`)RPM 包（`.rpm`）

💡

The build also runs node scripts/generate-build-info.js before packaging (prepackage / prepackage:lite hooks) to write a build-info.json consumed by the CLI version command.

打包前还会通过 prepackage / prepackage:lite 钩子运行 node scripts/generate-build-info.js，生成供 CLI version 命令读取的 build-info.json。

Project Structure 项目结构

High-level layout of the repository:

仓库的高层目录结构：

SXSEditor/
├── assets/                    # App icons and images
├── docs/                      # Documentation & official website (GitHub Pages)
│   ├── css/  js/  images/
│   ├── user/                  # User-facing docs
│   ├── dev/                   # Developer docs (this page)
│   └── wiki/                  # Wiki source markdown
├── onnx_models/               # ONNX model files (git-ignored, auto-downloaded)
│   ├── fp16/ fp32/ int8/      # Precision subdirectories
│   ├── ja/                    # Japanese model variants
│   └── preprocess/            # RMVPE & ROSVOT pitch detection models
├── scripts/                   # Build helpers (generate-build-info.js)
├── src/
│   ├── main.js                # Electron main process entry point
│   ├── preload.js             # contextBridge IPC API
│   ├── main/                  # Main process modules (windowManager, security,
│   │                          #   settingsIpc, svsIpc, audioIpc, themeIpc, ...)
│   ├── renderer/              # Main window renderer (timeline, project IO)
│   ├── fragmentEditor/        # Fragment editor renderer (piano roll)
│   ├── editor/                # Shared editor modules (trackManager, pianoRoll,
│   │                          #   envelopeEditor, historyManager)
│   ├── inference/             # Neural inference pipelines
│   │   ├── pipeline/          # Main SVS pipeline (OnnxSVSPipeline)
│   │   ├── webnn/             # WebNN NPU pipeline
│   │   ├── rmvpePitchDetector.js
│   │   ├── fcpeDetector.js    # FCPE pitch detector (default MIDI extraction)
│   │   ├── basicPitch.js
│   │   └── phone_set.json     # Phoneme vocabulary (2820 entries)
│   ├── audio/                 # AudioOutputManager (WASAPI), wavEncoder, lrcExport
│   ├── themes/                # Theme system (builtins, manager, tokens)
│   ├── i18n/                  # Internationalization (en, zh-CN)
│   └── utils/                 # Shared utilities
├── test/                      # Test suite (~61 files, 1500+ cases)
├── forge.config.js            # Electron Forge config (packaging, makers)
├── webpack.*.config.js        # Webpack configs (main + renderer)
└── package.json

ℹ️

The packaged app's main field in package.json points to .webpack/main (built bundle). During npm start, the webpack plugin compiles src/main.js into .webpack/main transparently.

package.json 中的 main 字段指向 .webpack/main（构建产物）。运行 npm start 时，webpack 插件会自动将 src/main.js 编译到 .webpack/main。

Linting 代码检查

ESLint (Flat Config) lints src, test, scripts, and root config files:

ESLint（Flat Config）会对 src、test、scripts 以及根目录配置文件进行检查：

npm run lint

Next Steps 下一步

Architecture Overview架构概览 — main/renderer process model, IPC pattern, security model.— 主/渲染进程模型、IPC 模式、安全模型。
Inference Pipeline推理管线 — SVS pipeline stages and key constants.— SVS 推理管线各阶段与关键常量。
Testing & CLI测试与命令行 — test framework and CLI debug mode.— 测试框架与 CLI 调试模式。