XiStudio · Source 模块前端实现说明 v1.1
文档定位
本文档不再沿用旧的 Source/Sink 联合规范，而是直接以 frontend_vue3 当前代码为准，描述 Source 模块在前端中的真实实现状态。目标不是定义理想态，而是回答“现在的代码到底怎么工作”。
本版结论
当前 Source 的真实实现是 tone / noise / file / device 四分支；旧文档中关于 wav upload、统一状态灯与 useSourceStateStore 的描述，并未在当前前端代码里落地。
1. 实现入口
| 类型 | 文件 | 作用 |
|---|---|---|
| 调参对话框 | src/components/SourceTuningDialog.vue |
Source 主交互入口 |
| 内建模块定义 | src/stores/moduleLibrary.ts |
定义 source_v1 及拆分 source_*_v1 |
| 链路与端口传播 | src/stores/linkStore.ts |
默认加点、参数写入、端口传播 |
| 输入设备缓存 | src/stores/deviceStore.ts |
维护输入设备列表与驱动分组缓存 |
| 图标定义 | src/utils/moduleIcons.ts |
为拆分 Source 模块提供独立图标 |
2. 当前模块模型
2.1 source_v1
source_v1 是当前默认 Source 入口，定义如下：
| 项目 | 当前实现 |
|---|---|
mode |
builtin_normal |
category |
source |
| 输入端口 | 无 |
| 输出端口 | 1 个动态输出端口 |
默认 sourceType |
tone |
默认 runMode |
pc |
输出端口的关键 Argument 参数由 moduleLibrary.ts 给出：
numChannelsblockSizesampleRatesignalTypedataTypeisComplex
2.2 已进入模块库的拆分 Source
当前模块库已经包含拆分后的 Source 定义：
| 分组 | 模块 |
|---|---|
| Tone | source_sine_v1 / source_sweep_v1 / source_triangle_v1 / source_square_v1 / source_saw_v1 |
| Noise | source_noise_white_v1 / source_noise_pink_v1 / source_noise_brown_v1 |
| 其他 | source_wav_v1 / source_device_v1 |
这些模块在模块库中已经可见，并有独立图标，但默认画布初始化依旧优先使用 source_v1。
3. 调参窗口的真实行为
3.1 固定骨架
SourceTuningDialog.vue 的界面结构是固定的：
- 顶部启用/禁用按钮
- 标题与关闭按钮
PresetPanel- Source 类型切换栏
- 当前激活状态栏
- 参数区域
- 底部统一的
runMode切换
3.2 Source 类型切换
当前前端写死了 4 个 Source 类型：
| 值 | 标签 |
|---|---|
tone |
音调 |
noise |
噪声 |
file |
音频文件 |
device |
声卡输入 |
切换逻辑：
- 先写入
linkStore.setParamValue(instanceId, 'sourceType', type)； - 再发送 WebSocket
set_param； - 若切到
device，会立即请求输入设备列表； - 若引擎正在运行：
device参与切换时，调用engineStore.startEngine()重启引擎；- 非
device之间切换时，调用engineStore.syncSourceSignal()热更新。
3.3 Tone 分支
Tone 分支支持以下参数：
| 参数 | 说明 |
|---|---|
activeChannels |
有效通道数量 |
toneWaveform |
sweep / sine / triangle / sawtooth / square |
toneStartFreq |
单频或扫频起始频率 |
toneEndFreq |
扫频终止频率 |
sweepDurationSec |
扫频时长 |
toneAmplitude |
幅度，单位 dBFS |
toneDurationSec |
播放时长，0 表示循环 |
toneFadeInMs / toneFadeOutMs |
淡入淡出 |
3.4 Noise 分支
Noise 分支支持：
| 参数 | 说明 |
|---|---|
activeChannels |
有效通道数量 |
noiseType |
black / white / pink / brown |
noiseDist |
gaussian / uniform |
noiseChannelMode |
uncorrelated / correlated |
noiseAmplitude |
幅度，单位 dBFS |
noiseDurationSec |
播放时长 |
noiseFadeInMs / noiseFadeOutMs |
淡入淡出 |
3.5 File 分支
当前代码中的文件源不是拖拽上传，而是路径输入型实现：
| 参数 | 说明 |
|---|---|
filePath |
文本路径 |
playMode |
loop / once |
fileGain |
文件增益，单位 dBFS |
重要区分
旧文档把这一分支描述为 wav 加载器，包含拖拽上传、进度条和元信息表；当前前端代码没有这套 UI。若后续重新做文件上传，应该另起一版文档，不应继续沿用过时描述。
3.6 Device 分支
设备输入分支包含以下行为：
| 能力 | 当前实现 |
|---|---|
| 设备刷新 | 按钮触发 get_audio_devices |
| 驱动类型 | DirectX / ASIO |
| 设备列表显示 | 显示 name、channels、sampleRate |
| 设备选择参数 | inputDeviceId |
| 错误反馈 | 监听 set_param_ack 失败消息，显示 devError |
4. 设备与 WebSocket 行为
4.1 主动发送的消息
| 场景 | 消息 |
|---|---|
| 切换 Source 类型 | set_param |
| 修改普通参数 | set_param |
| 刷新输入设备列表 | get_audio_devices（direction: 'input'） |
| 运行中切换输入设备 | set_audio_input_device |
4.2 监听的消息
| 消息 | 用途 |
|---|---|
audio_devices |
回填输入设备列表 |
set_param_ack |
检查设备切换失败 |
5. 与链路系统的关系
5.1 默认工程骨架
linkStore.addDefaultModules() 会自动向空链路加入 source_v1 与 sink_v1。因此 Source 不是可选配角，而是默认拓扑的一部分。
5.2 端口传播
linkStore.ts 中 Source 相关的关键点：
resolveOutputChannels()、resolveOutputSampleRate()等函数会从 Source 输出端开始向下游传播；setParamValue()修改到端口属性参数时，会重建ports并触发propagatePortInfo()；- Source 输出端运行时的
channels / blockSize / sampleRate由参数值决定，而非静态写死。
6. 模块库与兼容态
6.1 模块库面板
ModuleLibraryPanel.vue 在正常模式下会显示 source 分类下的所有内建 Source 模块；在兼容模式下则只展示 source / sink 两类重点入口。
6.2 图标策略
moduleIcons.ts 已为以下拆分模块提供独立图标：
source_sine_v1source_sweep_v1source_triangle_v1source_square_v1source_saw_v1source_noise_white_v1source_noise_pink_v1source_noise_brown_v1source_wav_v1source_device_v1
这意味着前端视觉层已经为拆分态做好准备，只是默认交互入口尚未完全切换。
7. 当前已知差距
| 主题 | 当前状态 |
|---|---|
wav upload |
未在当前前端实现 |
| Source 状态灯 | 未看到独立 SourceStatusDot 体系落地 |
| 采样率不匹配告警 | 未看到独立 UI 呈现 |
| 拆分模块专属调参窗 | 当前仍以 source_v1 专属调参体验为主 |
8. 结论
结论
当前 Source 前端实现的关键词不是“统一规范”，而是“兼容入口仍在服役，拆分模块已经入库，文件源仍是路径输入，设备源具备基本枚举与切换能力”。任何后续文档、测试与 PR 说明，都应以上述事实为准。