FAQ & Troubleshooting 常见问题与故障排查
Common questions and troubleshooting steps for SXSEditor. If your issue isn't covered here, please open an issue on GitHub.
SXSEditor 的常见问题与故障排查步骤。如果此处未涵盖你的问题，请在 GitHub 上提 issue。
General 通用
What is SXSEditor? 什么是 SXSEditor？
SXSEditor is an open-source desktop application for singing voice synthesis (SVS). You create MIDI notes with lyrics on a piano-roll editor, and the application synthesizes singing voice audio using the SoulX-Singer neural model running on ONNX Runtime.
SXSEditor 是一个开源的歌声合成（SVS）桌面应用。你在钢琴卷帘编辑器中创建带歌词的 MIDI 音符，应用使用运行在 ONNX Runtime 上的 SoulX-Singer 神经模型合成歌声音频。
Is SXSEditor free? SXSEditor 是免费的吗？
Yes. SXSEditor is open-source under the MIT License.
是的。SXSEditor 是 MIT 许可证的开源软件。
What platforms are supported? 支持哪些平台？
- Windows: Primary target with pre-built installers. Windows 10/11 64-bit required.Windows：主要平台，提供预构建安装包。需要 Windows 10/11 64 位。
- macOS / Linux: Can be built from source using Electron Forge. See the Developer Guide.macOS / Linux：可使用 Electron Forge 从源码构建。详见开发者指南。
What languages can it sing? 支持哪些演唱语言？
| Language语言 | Status状态 |
|---|---|
| Chinese (Mandarin)中文（普通话） | Supported — Chinese characters with optional tone digit (1–5)支持——汉字，可附加声调数字（1–5） |
| English英语 | Supported — English words, auto-converted to phonemes支持——英文单词，自动转换为音素 |
| Japanese日语 | Supported — hiragana/katakana, auto-converted to phonemes via Hybrid Phonemes (default, per-kana ARPAbet/Cantonese selection) or English Phoneme Migration; JP LoRA model in development支持——平假名/片假名，通过混合音素（默认，按假名在 ARPAbet/粤语间挑选）或英语音素迁移自动转换为音素；日语 LoRA 模型开发中 |
Models 模型
What models do I need? 需要哪些模型？
SXSEditor requires 9 ONNX model files for the SVS synthesis pipeline, plus optional models for pitch detection (RMVPE) and MIDI extraction (Basic Pitch). On first launch, the Model Download window opens automatically to download them.
SXSEditor 的 SVS 合成管线需要 9 个 ONNX 模型文件，外加可选的音高检测（RMVPE）和 MIDI 提取（Basic Pitch）模型。首次启动时，模型下载窗口会自动打开进行下载。
How much disk space do models need? 模型需要多少磁盘空间？
- FP32: Largest (~3 GB)FP32：最大（约 3 GB）
- FP16: Medium (~1.5 GB)FP16：中等（约 1.5 GB）
- INT8: Smallest (~1 GB)INT8：最小（约 1 GB）
Multiple precisions can coexist — each has its own subdirectory.
多种精度可共存——每种精度有独立子目录。
Which model precision should I choose? 应该选择哪种模型精度？
| Your hardware你的硬件 | Recommended precision推荐精度 |
|---|---|
| Discrete GPU, 4GB+ VRAM独立显卡，4GB+ 显存 | FP32 (recommended, highest quality)FP32（推荐，最高音质） |
| Discrete GPU, 8GB+ VRAM独立显卡，8GB+ 显存 | FP32 (highest quality)FP32（最高音质） |
| Integrated GPU / low VRAM集成显卡 / 低显存 | FP16 or INT8FP16 或 INT8 |
| NPU hardwareNPU 硬件 | INT8-NPUINT8-NPU |
If unsure, start with FP32 for the best quality. You can switch later without re-downloading.
如不确定，请先选 FP32 以获得最佳音质。之后可切换而无需重新下载。
Can I use custom models? 可以使用自定义模型吗？
No. SXSEditor is designed specifically for the SoulX-Singer model architecture. Custom model support is not available.
不可以。SXSEditor 专为 SoulX-Singer 模型架构设计。不支持自定义模型。
Singer Creation 歌手创建
What audio format do I need for the reference audio? 参考音频需要什么格式？
- Format: WAV (
.wav) only格式：仅限 WAV（.wav） - Duration: 30 seconds maximum时长：最长 30 秒
- Content: Pure vocals only — no background music, instruments, reverb, or effects内容：仅纯人声——无背景音乐、乐器、混响或效果
- Quality: Clean recording with minimal noise, 44100 Hz sample rate recommended质量：干净录音，噪音尽可能少，推荐 44100 Hz 采样率
Why must the reference audio be pure vocals? 为什么参考音频必须是纯人声？
The SVS model learns voice characteristics from the reference audio. Any non-vocal content (music, noise, effects) is treated as part of the voice and will cause artifacts in the synthesized output. Use audio isolation tools (vocal removers) if needed to extract clean vocals from mixed recordings.
SVS 模型会从参考音频中学习声音特征。任何非人声内容（音乐、噪音、效果）都会被当作声音的一部分学习，导致合成输出出现伪影。如有必要，使用人声分离工具从混音中提取纯净人声。
Do I need to fill in lyrics during preprocessing? 预处理时必须填写歌词吗？
Yes. The preprocessing step extracts MIDI notes and F0 pitch from the audio, but it does not detect lyrics. You must manually type the lyrics for each note in the preprocessing MIDI editor. This is mandatory — without lyrics, the synthesis cannot generate proper phonemes.
是的。预处理步骤会从音频中提取 MIDI 音符和 F0 音高，但不会识别歌词。必须在预处理 MIDI 编辑器中手动为每个音符输入歌词。这是必填项——没有歌词，合成无法生成正确的音素。
Can I skip preprocessing? 可以跳过预处理吗？
No. Preprocessing is required to create a singer. It extracts the F0 curve and MIDI note data that the SVS model uses to understand the singer's voice.
不可以。创建歌手必须进行预处理。它会提取 SVS 模型用于理解歌手声音的 F0 曲线和 MIDI 音符数据。
My WAV file is longer than 30 seconds. What do I do? 我的 WAV 文件超过 30 秒，怎么办？
A trim dialog opens automatically. Use it to select a 30-second segment:
会自动弹出裁剪对话框。用它选择 30 秒片段：
- Drag the selection to choose the position.拖动选区选择位置。
- Drag the edges to adjust start/end.拖动边缘调整起始/结束。
- Enter exact values in the input fields.在输入框中填入精确数值。
- Click Preview Clip to listen to the selection.点击 Preview Clip 试听所选片段。
- Click Confirm Trim to apply.点击 Confirm Trim 应用。
What makes a good reference audio? 什么样的参考音频是好的？
- Clear, dry vocal recording清晰、干涩的人声录音
- No background noise无背景噪音
- No reverb or echo无混响或回声
- Varied pitch range (the model learns from what it hears)多变的音域范围（模型从听到的内容中学习）
- Good articulation咬字清晰
- 10–30 seconds of continuous singing10–30 秒的连续演唱
Fragment Editing 片段编辑
How do I add notes? 如何添加音符？
In the Fragment Editor, click on the piano roll grid to create a note. Drag while clicking to set the note length. Notes snap to the beat grid.
在片段编辑器中，点击钢琴卷帘网格创建音符。点击时拖动可设置音符长度。音符会吸附到节拍网格。
How do I add lyrics to notes? 如何为音符添加歌词？
Double-click a note to open an inline text editor. Type the lyric and press Enter. You can also edit lyrics in the Inspector panel on the right side.
双击音符打开内联文本编辑器。输入歌词后按 Enter。也可在右侧检查器面板中编辑。
For Chinese singing, enter Chinese characters (e.g., 你好). You may append a digit 1–5 after a character to force a specific tone (e.g., 你2 好3), where 1–4 are the four tones and 5 is the neutral tone (轻声). Pinyin text (e.g., ni hao) is not accepted as Chinese — ASCII input is routed to the English G2P path. For English singing, enter English words (e.g., hello).
中文演唱请输入汉字（如 你好）。可在汉字后加数字 1–5 强制指定声调（如 你2 好3），其中 1–4 为四声，5 为轻声。不接受拼音（如 ni hao）作为中文输入——ASCII 输入会走英文 G2P 路径。英文演唱请输入英文单词（如 hello）。
What is a slur note? 什么是连音音符？
A slur (continuation) note extends the previous note's sound without re-attacking. Create one by adding a note with an empty lyric or a dash -. The note continues the phoneme of the previous note.
连音（延续）音符延续前一个音符的声音而不重新起音。创建方法是添加一个空歌词或破折号 - 的音符。该音符延续前一个音符的音素。
How do I draw pitch curves? 如何绘制音高曲线？
Switch to Pitch mode (press 2):
切换到音高模式（按 2）：
- Click to add anchor points.点击添加锚点。
- Drag anchors to move them.拖动锚点可移动。
- Right-click to delete anchors.右键点击删除锚点。
- Shift+drag for freehand brush drawing.Shift+拖动可手绘画笔。
- Use the Smoothing slider to control brush smoothness.使用 Smoothing 滑块控制画笔平滑度。
How do I undo/redo? 如何撤销/重做？
Press Ctrl+Z to undo and Ctrl+Y to redo. The editor supports up to 200 undo steps.
按 Ctrl+Z 撤销，Ctrl+Y 重做。编辑器最多支持 200 步撤销。
Synthesis 合成
Synthesis is very slow 合成速度很慢
- First synthesis is always slower — the pipeline must load 9 ONNX models into GPU memory. Subsequent syntheses are faster.首次合成总是较慢——管线需要将 9 个 ONNX 模型加载到 GPU 显存。之后的合成会更快。
- Use a discrete GPU if available. CPU inference is significantly slower.如有 独立显卡 请使用。CPU 推理明显较慢。
- Reduce diffusion steps in Settings > Preview Inference Parameters. Default is 16; try 8 for faster preview.在设置 > 预览推理参数中 减少扩散步数。默认 16；可尝试 8 以加快预览。
- Set CFG Strength to 0 to skip unconditional prediction, roughly doubling speed.将 CFG Strength 设为 0 可跳过无条件预测，速度约提升一倍。
- Update GPU drivers to the latest version.更新显卡驱动 到最新版本。
The synthesized voice sounds wrong or has artifacts 合成声音异常或有伪影
- Check the reference audio: Ensure it contains pure vocals with no background music or effects.检查参考音频：确保为纯人声，无背景音乐或效果。
- Check lyrics: Make sure every note has the correct lyric. Missing or wrong lyrics cause phoneme errors.检查歌词：确保每个音符都有正确歌词。缺失或错误歌词会导致音素错误。
- Check MIDI notes: Verify that note pitches and timing match the intended melody.检查 MIDI 音符：确认音高和时序与预期旋律一致。
- Check model precision: If using INT8 or FP16, try FP32 for higher quality.检查模型精度：如使用 INT8 或 FP16，可尝试 FP32 以获得更高音质。
- Increase diffusion steps: More steps = better quality (try 32 or 48 for export).增加扩散步数：更多步数 = 更高音质（导出可尝试 32 或 48 步）。
What hardware do I need? 需要什么硬件？
| Component组件 | Minimum最低 | Recommended推荐 |
|---|---|---|
| CPUCPU | Any modern multi-core任意现代多核 | Recent Intel/AMD 6+ cores较新的 Intel/AMD 6 核以上 |
| RAM内存 | 8 GB8 GB | 16 GB16 GB |
| GPUGPU | None (CPU fallback)无（CPU 回退） | Discrete GPU with 4GB+ VRAM独立显卡，4GB+ 显存 |
| Storage存储 | 3 GB (app + models)3 GB（应用 + 模型） | SSD with 10+ GB freeSSD，剩余 10 GB 以上 |
A discrete GPU is strongly recommended for reasonable synthesis speed.
强烈推荐使用独立显卡以获得合理的合成速度。
Does it work without a GPU? 没有 GPU 能用吗？
Yes. ONNX Runtime falls back to CPU automatically. However, synthesis will be significantly slower — a discrete GPU is recommended.
可以。ONNX Runtime 会自动回退到 CPU。但合成速度会明显变慢——推荐使用独立显卡。
Which GPUs are supported? 支持哪些 GPU？
DirectML supports NVIDIA, AMD, and Intel GPUs (both discrete and integrated). NPU support is available via WebNN on compatible hardware.
DirectML 支持 NVIDIA、AMD 和 Intel GPU（独立显卡和集成显卡均支持）。NPU 通过 WebNN 在兼容硬件上支持。
Audio 音频
What audio output modes are available? 有哪些音频输出模式？
- Shared Mode (WASAPI Shared): Standard Windows audio. Other apps can play audio simultaneously. Default mode.共享模式（WASAPI Shared）：标准 Windows 音频。其他应用可同时播放。默认模式。
- Exclusive Mode (WASAPI Exclusive): Direct hardware access with lower latency (1–3ms). Blocks other apps from using the audio device. Falls back to shared mode if the device doesn't support the selected settings.独占模式（WASAPI Exclusive）：直接硬件访问，延迟更低（1–3ms）。会阻止其他应用使用音频设备。如设备不支持所选设置，则回退到共享模式。
What is the output sample rate? 输出采样率是多少？
Synthesis runs at 24 kHz internally (model rate). The default playback sample rate is now 48 kHz. Export sample rate is selectable (24 / 44.1 / 48 / 96 kHz) with linear upsampling from the model rate. In exclusive mode, the device must support the selected rate.
合成内部以 24kHz（模型速率）运行。默认播放采样率现为 48kHz。导出采样率可选（24 / 44.1 / 48 / 96 kHz），从模型采样率线性上采样。独占模式下设备必须支持所选采样率。
What format is the exported WAV? 导出的 WAV 是什么格式？
48 kHz, 16-bit PCM WAV by default (the model runs at 24 kHz internally, with linear upsampling to the selected export rate). Export sample rate is selectable: 24 / 44.1 / 48 / 96 kHz.
默认为 48kHz、16-bit PCM WAV（模型内部以 24kHz 运行，线性上采样到所选导出采样率）。导出采样率可选：24 / 44.1 / 48 / 96 kHz。
Audio to MIDI 音频转 MIDI
What is Audio to MIDI? 什么是音频转 MIDI？
A feature that converts an existing audio file into MIDI notes. It extracts note pitches and timing, creating a new track with the detected notes. Supported input formats: WAV, MP3, FLAC, OGG, AAC, M4A.
将现有音频文件转换为 MIDI 音符的功能。它提取音符音高和时序，创建包含检测音符的新轨道。支持输入格式：WAV、MP3、FLAC、OGG、AAC、M4A。
Which extraction tool should I use? 应该使用哪个提取工具？
- FCPE (default, recommended): ONNX-based pitch detector with a configurable post-processing pipeline (loudness normalization, silence gating, median smoothing, note quantization). Best extraction quality.FCPE（默认，推荐）：基于 ONNX 的音高检测器，配有可配置的后处理流水线（响度归一化、静音门控、中值平滑、音符量化）。提取质量最佳。
- Basic Pitch: Neural network-based, stable results for most scenarios.Basic Pitch：基于神经网络，大多数场景结果稳定。
- RMVPE: Converts F0 pitch curve to notes. Experimental, results may be suboptimal.RMVPE：将 F0 音高曲线转为音符。实验性，结果可能不理想。
Change this in Settings > Audio > MIDI Extraction Tool.
在设置 > 音频 > MIDI 提取工具中更改。
Can I extract a pitch curve too? 可以同时提取音高曲线吗？
Yes. When using Audio to MIDI, choose "Extract Pitch (RMVPE)" to also extract an F0 pitch curve that is applied to the fragment.
可以。使用音频转 MIDI 时，选择 "Extract Pitch (RMVPE)" 可同时提取 F0 音高曲线并应用到片段。
Projects 项目
What file formats are used? 使用什么文件格式？
| File文件 | Extension扩展名 | Description说明 |
|---|---|---|
| Project项目 | .sxsproj | Contains all singers, fragments, and project settings包含所有歌手、片段和项目设置 |
| Singer歌手 | .sxssinger | Contains singer metadata, reference audio, and preprocessed data包含歌手元数据、参考音频和预处理数据 |
Should I embed singer files in the project? 应该在项目中嵌入歌手文件吗？
- Embed: Makes the project self-contained. Good for sharing or archiving. Increases file size.嵌入：使项目自包含。便于分享或归档。文件体积更大。
- Don't embed: Smaller file. Requires
.sxssingerfiles to be accessible at their stored paths.不嵌入：文件更小。要求.sxssinger文件在存储路径可访问。
My singer file is missing when I open a project 打开项目时歌手文件丢失
If you didn't embed singer files and the .sxssinger file was moved or deleted:
如果未嵌入歌手文件且 .sxssinger 文件已被移动或删除：
- The singer row shows "⚠ Singer file not found".歌手行显示 "⚠ Singer file not found"。
- Click Relocate to browse for the file at its new location.点击 Relocate 浏览并选择文件的新位置。
Troubleshooting 故障排查
The app crashes on startup 应用启动时崩溃
- Ensure all model files are in the
onnx_models/directory.确保所有模型文件位于onnx_models/目录。 - Check that your GPU drivers are up to date.检查显卡驱动是否为最新。
- Try deleting the settings file at
%APPDATA%\sxseditor\settings.jsonto reset to defaults.尝试删除设置文件%APPDATA%\sxseditor\settings.json以重置为默认值。 - Open an issue on GitHub Issues with error logs.在 GitHub Issues 提交 issue 并附上错误日志。
Model download fails 模型下载失败
- Check your internet connection.检查网络连接。
- The download uses chunked parallel transfer — if it fails, retry by clicking Start Download again. Completed files are skipped.下载采用分片并行传输——如果失败，再次点击 Start Download 重试。已完成的文件会跳过。
- Try changing the download directory.尝试更改下载目录。
- If behind a proxy, ensure the proxy settings allow connections to ModelScope.如果使用代理，确保代理设置允许连接 ModelScope。
- Users in China can use the GitCode mirror for faster access.中国大陆用户可使用 GitCode 镜像 加速访问。
Audio playback has glitches or dropouts 音频播放有爆音或断续
- Increase the buffer size in Settings > Audio > Buffer Size.在设置 > 音频 > 缓冲区大小中增大缓冲区。
- If using exclusive mode, try switching to shared mode.如果使用独占模式，尝试切换到共享模式。
- Close other audio-intensive applications.关闭其他音频密集型应用。
- Check that your audio device drivers are up to date.检查音频设备驱动是否为最新。
GPU black screen / TDR error (0x887A0006) GPU 黑屏 / TDR 错误（0x887A0006）
This usually indicates VRAM exhaustion. Try:
通常表示显存耗尽。可尝试：
- Enable Release diffStep Before Vocoder in Settings > Model (frees ~3–4GB VRAM for the vocoder pass). Strongly recommended for SiFiGAN and low-VRAM GPUs.在设置 > 模型中启用 Release diffStep Before Vocoder（为 vocoder 推理释放约 3–4GB 显存）。SiFiGAN 和低显存显卡强烈建议开启。
- Switch to a lower model precision (FP16 or INT8).切换到更低的模型精度（FP16 或 INT8）。
- Use Vocoder Chunk Smart mode to let SXSEditor pick a smaller chunk size for your VRAM.使用 Vocoder 分片智能模式，让 SXSEditor 根据显存选择更小的分片。
How do I report a bug? 如何报告 bug？
Open an issue on GitHub Issues with:
在 GitHub Issues 提交 issue，包含：
- A clear description of the problem问题的清晰描述
- Steps to reproduce复现步骤
- Your system configuration (OS, GPU, RAM)系统配置（操作系统、GPU、内存）
- Screenshots or error messages if applicable截图或错误信息（如有）