SynthV 对话工作台

面向 Synthesizer V Studio 2 Pro 独立版 / Windows 的本地调教助手，以 2.2.1 为开发与宿主验证基准。通过官方 Lua 脚本读取工程和选区、调整少量参数，再采集软件输出，用 A/B 试听、信号指标和可选音频模型评审检查结果。本项目为独立开发的实验性工具，与 Dreamtonics 没有官方关联；不包含 SynthV 软件、声库或示例歌曲。

本版提供三栏浏览器工作台及本地 stdio MCP 入口：左侧导航会话、音频素材、录音、回收站和设置，中间展示所选主页面，右侧“工程工具”保留选区、手动调参和 A/B 试听。黑白主题默认跟随系统，也可选择浅色或深色；桌面窗口两侧边栏可拖动调宽。会话刷新后仍可读取。默认只读，模型服务默认停用。

可以只发送文字，也可以显式附带当前选区或音频。纯文字咨询与参数规划可使用支持所选协议的文字模型；附带音频时才要求模型支持音频输入。 模型先提出建议，实际参数预览由 SynthV 桥接生成，每一项应用都由用户确认。对话流程使用模拟模型和隔离模拟宿主验证，真实云模型尚未验证。真实 SynthV 验证仅覆盖短选区上的气声预览、应用、恢复及按进程录音；不代表模型已经听过或改善了歌声。

当前能做什么

选中音符之间有空隙时，参数会影响从第一个选中音符开始到最后一个选中音符结束的整个连续区间。本版不是逐字智能调教器，也不自动识别应修改哪个音素。共享于多个位置的音符组会拒绝写入。

本版不开放轨道/音符组克隆、和声生成或通用事务；不调用未知原生接口，不直接改写 .svp 工程文件。官方脚本 API 的稳定性仍依赖 SynthV 版本和声库，精简桥接并不等于已修复宿主原生缺陷。

Related MCP server: MusicMCP.AI MCP Server

环境要求

• Python 3.10 或更高版本，项目依赖安装在本目录 .venv。

• Windows build 20348 或以上；Windows 11 满足这一最低版本条件。常见 Windows 10 build 19045 不满足本版按进程回录要求。

• Synthesizer V Studio 2 Pro 独立版及可用声库；此原型面向 2.2.1 开发，其他版本需重新验收。

• 按进程采集器为 x64 .NET 10 程序：源码构建需要 .NET SDK 10；运行已构建文件需要相应 .NET 10 x64 运行时。SDK 包含运行时。

• 本机浏览器。控制台只监听 127.0.0.1，默认端口 8765。

源码安装需要在自己的机器上构建采集器，并确认运行时、声卡驱动和音频输出路径可用。已完成的短片段回录验证不涵盖所有 ASIO 设置、声卡或工程。MP3 导入另外需要自行安装 FFmpeg 并加入 PATH；仅使用 PCM WAV 时不需要 FFmpeg。

页面、外观与素材管理

左侧导航在中间切换会话、音频素材、录音、回收站和设置，原会话的未发送草稿会保留。设置和素材选择使用主页面，无需在弹窗中操作。离开模型设置页会清空尚未保存的密钥输入；保存中的配置会先完成当前请求。

在设置页选择“跟随系统”“浅色”或“深色”。默认跟随系统，并随系统外观即时更新。主题选择与两侧栏宽度只保存在当前浏览器；拖动边栏分隔线可改变宽度，也可聚焦分隔线后用方向键调整，双击可恢复默认宽度。窄窗口改用可展开的侧栏，避免把中央页面挤出屏幕。

会话与素材可设置名称、星标和备注。备注用于本地整理，不会自动加入 AI 请求。删除时可选择“移到回收站”或“永久删除”，回收站也支持逐项永久删除。移入回收站可恢复；永久删除需在页面内确认，随后移除本机对应会话文件或音频及索引，不能恢复。删除会话不会连带删除音频，也不会撤销已经应用到 SynthV 的参数或删除工程、备份。历史消息保留已删除附件的名称，但不能继续播放该音频。

音频素材页的底部操作栏与列表滚动区域分开，便于确认已选附件。请求过程中显示阶段、等待时间和实际接收进度；这些信息不表示模型已经完成响应或参数已经写入。

“录音”页控制 SynthV 播放并采集其输出，不开启麦克风。页面内的“读取选区”会直接读取 SynthV 当前选区并填入起点与时长，无需先到右侧读取。读取失败或没有选区时清空旧范围，避免误录上一次片段；也可以手动填写范围。选区不足 1 秒时按最少 1 秒填写，超过 30 秒时只填前 30 秒并显示提示。填写名称后开始录音，完成后可试听、到素材库管理或附到会话；附到会话还不等于发送给模型。现有右侧 A/B 录制与比较仍可使用。

首次准备

使用 Git 时，先在准备存放项目的目录打开 PowerShell；也可以下载仓库压缩包并进入解压目录。

# 获取源码并进入项目目录；已经下载源码时跳过这两行。
git clone https://github.com/blockshy/synthv-assistant.git
Set-Location -LiteralPath .\synthv-assistant

以下命令在含 pyproject.toml 的项目根目录执行，只在项目 .venv 安装 Python 依赖，不安装全局依赖；需要网络下载依赖。本项目按源码目录运行，网页、Lua 与原生采集器源码应保留在同一目录树内。

# 仅在尚无 .venv 时创建；本机默认 Python 应满足 3.10+ 要求。
py -3 -m venv .venv

# 使用项目解释器安装本地包及声明的依赖，不需要激活虚拟环境。
.\.venv\Scripts\python.exe -m pip install -e .

# 首次安装或更新采集器源码后执行；需要本机已有 .NET SDK 10。
.\.venv\Scripts\python.exe -m synthv_assistant build-capture

# 打包 Lua，并安装到 SynthV 2 的脚本目录；已有同名脚本会先备份。
.\scripts\install-bridge.ps1

安装目录为：

%APPDATA%\Dreamtonics\Synthesizer V Studio 2\scripts\SynthVAssistant.lua

安装脚本不会打开 SynthV，不会修改用户工程，也不会修改任何 AI 客户端的全局配置。可先运行 scripts/install-bridge.ps1 -WhatIf 查看目标路径。

随后在 SynthV 中执行以下操作：

1. 手动打开一个测试工程，先另存一份 .svp 副本。

2. 在“脚本 / Scripts”菜单重新扫描脚本；若未出现，可重启 SynthV。

3. 运行 SynthV Assistant。同一工程会话只运行一个桥接实例。

4. 在钢琴卷帘中选中一小段音符，等待软件完成合成，并停止播放。

项目路径或 SYNTHV_ASSISTANT_DATA 改变后，需要重新运行安装脚本。Lua 打包文件包含本机 IPC 目录，不能直接拿另一台机器生成的 Lua 文件使用。

启动工作台

# 在当前 PowerShell 中启动本地服务；Ctrl+C 停止服务。
.\scripts\start.ps1

# 端口被占用时，可以显式选择其他本地端口。
.\scripts\start.ps1 -Port 8766

建议使用 Chrome 打开 本地工作台。启动脚本只使用已经准备好的 .venv，不会自动安装依赖、启动 SynthV 或读取 .env。

Chrome 已用于界面和音频播放验证。部分内嵌浏览器曾出现音频播放崩溃，兼容性尚未确认；遇到该问题时，请用独立 Chrome 窗口打开同一地址。

第一次使用对话工作台，可按以下顺序操作：

1. 在左侧“模型设置”编辑默认平台，或“新建平台”保存名称、服务协议、默认模型和密钥；需要时将已配置平台设为新会话默认。回到会话后，在输入区选择平台、模型和推理强度；模型留空使用平台默认值。纯文字任务可选择文字模型，需要发送音频时选择支持音频输入的模型。

2. 点击“新会话”，输入调教要求，每条最多 4000 字符。一般咨询可取消“附带当前选区”，无需连接 SynthV；需要可执行调教提案时，在 SynthV 选中音符并保留该选项。勾选后若桥接未连接或没有选区，服务会明确拒绝，不会悄悄省略选区。

3. 如需听音，打开“音频素材”上传片段或选择已有录音，再把所需文件附加到本次消息。不附音频也能发送文字；历史消息中的音频不会自动再次发送。

4. 发送后可查看等待时间与实际回复进度；如果供应商返回可见思考摘要，也会显示。正式解释和提案要等完整回复通过校验后才出现。点击某一项的预览按钮，核对宿主返回的范围、音符数和调整量后再确认应用。每次只处理一项；生成新预览后，旧提案需要重新预览。

5. 需要写入时，从右侧“工程工具”开启“允许修改选区”。后端会先自动备份磁盘上的已保存工程；尚未保存为可访问 .svp 的工程会被拒绝。助手不会替你开启写入。应用后可试听或录制 B，也可继续讨论下一步。

桥接重启、选区变化或目标参数摘要变化会使旧提案失效，需重新生成方案。显示“结果未知”的提案不可重复应用：先在 SynthV 检查实际状态或撤销，再重新规划。提案绑定的是连续选区范围，仍遵循最多 128 个音符、30 秒及共享音符组拒绝写入的限制。

右侧手动工具仍可独立完成 A/B 流程：

1. 检查“调教桥接”状态，点击“读取工程”和“读取选区”。

2. 指定片段起点与时长，先“录制 A”，并确认能听到目标声音。

3. 开启“允许修改选区”。服务会先自动备份磁盘上的已保存工程，备份成功后才请求宿主开启写入。这份备份不包含尚未保存的编辑，重要工程仍建议先在 SynthV 保存或另存工作副本。

4. 选择一个参数，小幅调整并预览。核对音符数量、时间范围和调整量，再应用。

5. 保持相同起点、时长和工程混音设置，录制 B；试听并比较指标。

6. 需要恢复时，回到上次修改的音符组，使用“恢复最后修改”；如曲线已被手动改动或在 SynthV 中撤销，助手会拒绝覆盖。

“恢复最后修改”仅保留当前桥接会话中本助手最后一次成功修改的快照，不是完整工程版本管理。重启桥接会丢失该内存快照。参数写入不会自动保存 .svp，最终结果由你在 SynthV 中确认和保存。

录音实际包含什么

采集器使用 Windows WASAPI 进程树回录，目标为 SynthV 进程及其子进程。它不打开麦克风，也不会在进程回录失败后自动改录整个系统。

录到的是 SynthV 当前完整混音，包括未静音的伴奏和其他轨道。需要单独评审人声时，请在录制 A 之前自行设置静音或独奏，并在 A/B 之间保持一致；工作台不会擅自改变轨道混音。

WAV 格式为 44100 Hz、双声道、PCM16。每段文件比指定播放时长多约 1 秒准备/尾部余量。播放控制与音频采集之间存在小量延迟，本版不保证样本级起点同步，不应用于毫秒级音素对齐。A/B 不做自动对齐、响度归一化或重采样。

如果 SynthV 使用 ASIO 等绕过受支持 Windows 路径的输出方式，回录可能为空或失败。先确认录音，再考虑使用能被该接口捕获的输出模式；不要把空录音当作“没有调教差异”。RMS 不是 LUFS，变响也不等于更自然或更好听。

多个 SynthV 实例同时运行时，需在启动助手前通过 SYNTHV_ASSISTANT_PID 指定目标进程号，并确保正在运行桥接的工程属于该进程；第一版建议只打开一个实例。

模型平台、会话选择与音频附件

左侧 “模型设置” 可管理最多 20 个平台，含原有“默认平台”。默认平台继续使用原来的加密配置，旧版 A/B 听评与 MCP review_recordings 仍使用它；会话可另外选择命名平台。新建或切换会话平台不会改写默认平台，也不会自动切换其他会话。本地工程读取、手动调参、录音、试听和指标比较不依赖模型配置。

1. 在“编辑平台”中选择已有平台，或点击“新建平台”。自定义平台需要名称；默认平台名称固定。

2. 选择 OpenAI / OpenAI 兼容服务 或 Google Gemini，填写平台默认模型、HTTPS Base URL、API key 和 5～180 秒请求超时。切换协议会填入对应默认值，但不会自动保存。只发文字时模型无需支持音频；附带音频或使用 A/B 听评时，需使用兼容音频输入的模型。

3. 点击 “保存并立即生效”。设置在本机由当前 Windows 账户加密保存，下次启动保留，无需重启服务。仅保存设置不会调用供应商、验证密钥或上传音频。 保存后可点击 “设为新会话默认”。之后新建的会话自动使用该平台的默认模型与默认推理设置；已有会话继续使用原来的选择。此偏好不改变独立 A/B 听评的原有配置。

4. 回到会话，在输入区选择平台、模型及推理强度。这三个选择随会话保存；模型留空沿用平台默认模型，推理选“模型默认”时不额外指定强度。每次请求读取所选平台的完整配置快照，新设置从下一次请求生效。界面的“已配置”不表示“连接验证通过”。

模型输入框既可手动填写，也可点击旁边的刷新按钮获取所选平台的模型目录。只有显式刷新目录才会向该平台发送模型列表请求，请求会使用该平台密钥，但不附带会话、选区或音频；打开页面、切换平台、查询本地能力规则和保存设置都不会自动访问供应商。列表失败时仍可手动填写模型 ID。

模型目录通常不提供完整的音频、推理或流式能力。界面的能力说明来自本地保守规则，不能保证每个兼容平台都实现了同名模型的全部参数。已知不支持的推理档位会被拒绝，明确不支持音频的模型不能提交音频附件；能力未知时需以平台实际支持为准。非默认推理强度只在用户选择后传递，失败不会自动降级、换模型或重试。

聊天请求显示实际阶段、等待秒数和已收到的字符数量，不模拟完成百分比。思考摘要仅展示 API 实际返回的可见内容；没有返回时会明确说明，不代表请求没有进行，也不保证每个平台都提供摘要。摘要只供查看，不进入下一轮历史提示词，不作为可执行调教计划。流式回复完整结束并通过校验后，才生成正式消息和可预览提案；此处“流式”指接收模型回复，音频仍以完整附件发送。

密钥不会回显，也不会写入浏览器 localStorage 或 URL。保持同一服务协议和 API 根地址时，密码框留空可保留已保存密钥；更换协议或地址必须重新填写。取消、关闭或保存失败都会清空本次输入的密钥；保存失败保留其他字段供修正。若其他页面更新过设置，本页会拒绝覆盖，需手动“重新加载已保存设置”。

“清除密钥并停用”只清除当前编辑平台的凭据并保存停用状态，不影响其他平台；默认平台停用后也不会退回使用环境中的旧密钥。再次启用需重新配置。选择“暂不启用模型服务”再保存同样会停用该平台并清除其密钥。本地录音、试听和指标比较继续可用。

默认平台尚无网页本机配置时，仍支持读取启动进程的环境变量；新增命名平台不继承环境密钥。.env.example 仅是字段说明，程序和 PowerShell 脚本不会自动读取 .env。环境变量方式的变更需要重启对应进程；网页保存的默认平台配置优先于环境变量，立即供后续使用该平台的请求读取。

# 显式选择供应商后才启用模型请求；把占位值替换为账户可用的模型 ID。
$env:SYNTHV_AUDIO_PROVIDER = 'openai'
$env:SYNTHV_AUDIO_MODEL = 'your-model-id'

# OPENAI_API_KEY 应由当前进程环境或你的凭据管理工具提供。
# 不要把密钥写进 README、MCP 示例、源代码或可提交的配置文件。
.\scripts\start.ps1

已实现 openai 和 gemini 的文字与音频输入分支。默认模型仅是配置起点，实际可用性取决于所选服务和账户。纯文字请求不附加音频字段；OpenAI 兼容服务用于听音时，还须支持本项目的 input_audio 格式。具体字段与限制见 模型与音频说明。

上传素材时，仅向本地工作台传输文件并进行校验/转换，不会调用模型。支持 WAV 和 MP3，单个原文件与转换后的 WAV 均不得超过 12,000,000 字节，时长须大于 0 且不超过 60 秒。WAV 使用 16/24/32 位整数 PCM；MP3 依赖本机已安装且可从 PATH 找到的 FFmpeg，程序不会自动下载安装。缺少 FFmpeg 或转换失败会明确提示，可改传 PCM WAV；超长文件整体拒绝，不会悄悄截断。

每条消息最多附带 2 个文件，实际发送的 WAV 合计不得超过 12,000,000 字节。只有发送消息时本次显式选中的附件，或显式提交的 A/B 听评录音，才会发往模型服务。历史音频不自动重发；纯文字消息只发送文字和勾选的安全选区摘要，不包含本机工程路径、进程号或完整工程。当前真实云模型尚未验证，模型建议也不会自动应用到工程。

接入支持本地 MCP 的 AI 客户端

本项目使用 stdio MCP，与浏览器工作台共用同一业务层及 Lua 桥接。客户端需要能够启动本地进程。示例见 MCP 配置示例，其中占位路径必须替换为自己的实际绝对路径。

该 JSON 是通用 mcpServers 结构，不是自动安装器；各客户端可能使用其他格式。请在客户端中添加以下进程配置，程序不会自动修改 Codex 或其他客户端的全局配置：

command: <项目绝对路径>\.venv\Scripts\python.exe
args:    -m synthv_assistant mcp

MCP 客户端与工作台应使用相同的 SYNTHV_ASSISTANT_DATA，或共同使用默认项目 data 目录。operation.lock 跨进程串行化参数变更、写入模式切换、预览和整段录音；其他入口忙时会明确拒绝新操作，不会并行修改或插入另一段录音。client.lock 另外保证单个 IPC 请求排他。

跨进程锁已经过测试，但不自动替用户安排整轮 A/B 工作流。仍建议顺序完成“录制 A → 预览并应用 → 录制 B → 比较/恢复”；遇到忙碌提示，应等待当前操作完成再读取状态，不要反复提交。同一数据目录可以被多个入口使用，后台任务仍需通过创建它的服务进程查询。

可向 AI 描述任务：“读取当前选区，先录制 A；把气声增加 0.05，给我看范围和预览，等我确认后再应用并录制 B、比较。”MCP 提供独立的预览和应用工具；是否逐次询问确认由客户端的工具审批策略负责，接入时应要求用户确认写入，不能把工具调用本身视为独立的人工确认机制。模型不能仅凭曲线数据声称已经听到声音；需要调用实际录音与听评流程。

如果客户端与主模型支持 MCP AudioContent 和音频输入，还可调用 get_recording_audio，直接取得真实 WAV。服务器能返回音频不代表每个客户端都会把它交给模型；不支持时使用 review_recordings 调用单独配置的音频模型。

常用工具按流程分为：status / get_project / get_selection；set_write_mode / preview_parameter / apply_preview / restore_last_edit；start_recording / get_job / list_recordings；compare_recordings / review_recordings / get_recording_audio。后台任务必须在创建它的同一服务进程中查询；服务重启后录音文件仍保留，但任务编号不再有效。

数据与验证

运行数据默认保存在项目 data 目录：

日常状态检查不需要测试依赖。首次运行完整测试前，请安装项目的 test 可选依赖，其中 lupa 用于在 Lua 5.4 虚拟机中验证桥接行为；该依赖不属于运行工作台的必需项。安装仍仅作用于项目 .venv。

# 仅读取助手状态，不更改 SynthV 工程。
.\.venv\Scripts\python.exe -m synthv_assistant status

# 首次执行完整测试前安装 test 可选依赖，包含 Lua 虚拟机测试所需的 lupa。
.\.venv\Scripts\python.exe -m pip install -e '.[test]'

# 在项目目录执行本地测试；音频模型测试使用 mock，不会产生云端调用。
.\.venv\Scripts\python.exe -m unittest discover -s tests -v

验证范围

自动化测试覆盖 Lua 桥接、MCP stdio、跨进程锁、Windows DPAPI、会话状态机、永久删除、平台配置、本地音频分析、采集生命周期和模拟模型协议。浏览器流程使用隔离数据、合成音频和模拟宿主验收。测试命令见上方；测试数量随代码变化，以实际运行结果为准。

真实宿主验证基准为 SynthV Studio 2 Pro 2.2.1 / Windows：已在测试工程副本的短选区验证读取、气声小幅预览、应用、写后校验、恢复及非静音 A/B 回录。该验证不涵盖所有声库、其他四个参数、复杂工程、ASIO 路径或原生撤销操作，也不证明听感改善。真实云模型请求与音频听评尚未完成验证。 仓库不分发私人测试工程、录音、截图或本地验收记录。

隐私与数据管理

默认数据目录及其会话、音频、操作日志、备份和 IPC 内容均属于本机私人数据。只有模型平台配置使用 Windows DPAPI 加密；会话、歌词摘要、音频、工程备份和操作记录并非全部加密，应按作品及个人资料管理。DPAPI 保护与当前 Windows 账户绑定，不能保证把文件复制到其他机器或账户后仍能解密；迁移时请重新配置密钥。

只有用户发送消息、提交 A/B 听评或主动刷新模型目录时，才会访问配置的供应商。纯文字请求包含当前文本和受限文字历史；勾选时还包含安全选区摘要。音频仅来自本次明确选中的附件；本地上传、录音、保存设置本身不会上传给模型。自定义 API 地址会收到对应凭据与请求内容，请使用可信服务。MCP 客户端可读取工程信息及显式请求的录音，客户端怎样转交给模型由其自身决定。

永久删除仅清理选定的本地资料，不级联工程备份、其他会话、操作日志或已经发送给供应商的内容；历史消息仍可能保留附件名称。它不是磁盘安全擦除工具。发布问题、截图或代码改动时，请移除真实密钥、私人路径、歌曲内容和运行数据，详见 安全与隐私说明。

常见问题

• 桥接未连接： 确认 SynthV 已打开，并从脚本菜单启动当前安装的 SynthV Assistant；移动项目或更换数据目录后需重新打包安装。

• 无法录音或没有声音： 确认 Windows build、.NET 10 运行时及采集器构建成功，等待 SynthV 合成完成，检查当前混音及音频输出路径。不会自动改用麦克风或全系统录音。

• 模型请求失败： 检查协议、模型、密钥和端点；聊天要求 SSE 流式响应，音频附件要求对应音频输入格式。已配置状态不等于云端连接验证。

• 应用超时或结果未知： 先检查 SynthV 实际状态，必要时撤销，再重新读取选区和规划；不要立即重复应用。

• 端口被占用： 使用 scripts/start.ps1 -Port 8766 等其他本地端口，不要终止不相关进程。

更多实现细节见 架构说明，模型及音频限制见 模型与音频说明，界面开发见 前端设计与实现规范，开发与问题反馈见 贡献指南。

许可证

本项目以 MIT 许可证 发布，Copyright (c) 2026 blockshy。随源码提供的第三方组件保留各自版权与许可，详见 第三方声明。Synthesizer V、声库、模型服务及其他外部软件不属于本项目授权范围。