FST 头文件指南:以开源反向工程 VST2 SDK 构建音频插件
FST 头文件指南:以开源反向工程 VST2 SDK 构建音频插件
导读
本文介绍 noise-suppression-for-voice 仓库内置的 FST(Free Studio Technology) 头文件——一套不依赖 Steinberg 官方 VST2 SDK、通过合法反向工程实现的插件接口头文件。你将理解为什么需要它、它的许可证约束、核心 fst.h 的 API 结构,以及它在本仓库中如何被实际用于构建 VST2 格式的 RNNoise 降噪插件,并掌握用它编译插件与宿主的基础方法。
一、FST 是什么:为什么需要一套"反向工程"的 VST2 头文件
FST 全称 Free Studio Technology,是一组用于构建音频插件(audio plugin)与插件宿主(audio plugin host)的 C/C++ 头文件,其目标是与 Steinberg 的 VST(2) 工业标准保持二进制接口兼容。项目原始说明见 external/FST/README.md。
FST 之所以存在,源于两个现实问题:
- VST2 SDK 的专有许可:Steinberg 提供的 VST2 SDK 采用专有许可证,开发者使用它需要接受其授权条款。
- VST2 SDK 已停止分发:Steinberg 为推动 VST3,已不再提供 VST2 SDK 的下载。
FST 正是对这一困境的回应:它是一个 bona-fide(善意、来源正当)反向工程头文件,即在没有参照官方 VST SDK、其开发者也未同意 VST SDK 许可协议的前提下独立撰写而成的实现。这意味着:
- 用它编译出的插件在二进制层面遵循 VST(2) 调用约定;
- 项目在授权上不依赖 Steinberg 的 SDK 许可;
- 但反向工程的过程与依据全部公开、可审计。
仓库中的 external/FST/docs/REVERSE_ENGINEERING.md 完整记录了每一步反向工程过程——包括如何用 JUCE 编译器错误提取符号名、如何用十六进制转储推演 AEffect 内存布局、如何通过真实插件与宿主(如 REAPER、MrsWatson)逐项确认 opcode 数值。该文档是验证 FST 头文件"来源清白"的原始证据,也是理解 VST2 底层协议的最佳教材。
二、许可证与商标约束(使用前必读)
2.1 源码许可:GPL-3.0-or-later
FST 以 GNU General Public License(version 3 or later) 发布(见 external/FST/LICENSE)。README 明确指出其立场:
如果在你自己的项目中使用 FST 头文件,你的项目也必须采用兼容的开源许可证。
并且没有计划以更宽松的许可发布 FST。因此:
- 想构建闭源插件或宿主,必须使用 Steinberg 官方 VST2 SDK 并遵守其授权条款;
- 使用 FST 的项目应遵循 GPL-3.0-or-later 或兼容许可。
2.2 商标约束:不能说 "VST"
Steinberg 已将 VST 注册为商标,并明确禁止任何人在未同意其许可条款的情况下使用该名称。因此:
- 基于 FST 接口发布的插件,不得命名为
VST,也不得声称其是 "VST Compatible"; - 这正是本仓库中所有插件统一命名为
rnnoise(如rnnoise_mono、rnnoise_stereo),而不使用 VST 字样作为产品名的原因之一(见 src/juce_plugin/CMakeLists.txt)。
三、FST 仓库结构总览
在 external/FST/ 目录下,FST 被组织为清晰的几部分:
| 路径 | 作用 |
|---|---|
| external/FST/fst/fst.h | 唯一的真正头文件:全部类型、枚举、结构体与宏 |
| external/FST/fst/aeffect.h | 兼容层 stub,仅 #include "fst.h" |
| external/FST/fst/aeffectx.h | 兼容层 stub,仅 #include "fst.h" |
| external/FST/src/FstHost/ | 测试用宿主程序(dlopen 加载插件) |
| external/FST/src/FstPlugin/ | 测试用插件实现 |
| external/FST/src/FstProxy/ | 插件代理(转发并打印双向 opcode 调用) |
| external/FST/src/JstHost/ | 基于 JUCE 的宿主示例 |
| external/FST/src/JstPlugin/ | 基于 JUCE 的插件示例 |
| external/FST/src/fst_utils.h | 调试辅助:opcode↔名称映射、十六进制打印等 |
| external/FST/tests/ | C/C++ 编译冒烟测试 |
| external/FST/docs/ | 反向工程全过程文档 |
值得注意的设计:aeffect.h 与 aeffectx.h 只是 #pragma once 后 #include "fst.h" 的占位文件。这样做是为了让那些习惯引入 <pluginterfaces/vst2.x/aeffect.h> 的代码(例如 JUCE 内部)无需改动即可改用 FST——反向工程文档中正是通过符号链接把 FST 目录伪装成 VST3_SDK/pluginterfaces/vst2.x 来让 JUCE 直接使用这些头文件的。
四、核心 API 剖析:fst.h 的关键结构
external/FST/fst/fst.h 是整个 SDK 的核心,约 600 行,包含完整的类型系统。理解它,就等于理解了 VST2 的二进制契约。
4.1 版本与兼容宏
#define FST_MAJOR_VERSION 0
#define FST_MINOR_VERSION 120
#define FST_MICRO_VERSION 0
#define FST_VERSIONNUM(X, Y, Z) ((X)*10000 + (Y)*1000 + (Z))
#define FST_VERSION FST_VERSIONNUM(FST_MAJOR_VERSION, FST_MINOR_VERSION, FST_MICRO_VERSION)
#define kVstVersion 2400
FST_VERSION是 FST 自身版本号(0.120.0)。kVstVersion 2400是 VST2 接口版本常量:宿主在audioMasterVersion回调中返回2400,插件在effGetVstVersion中返回2400,双方以此确认版本兼容。
4.2 状态标记宏:区分"已确认"与"未知"符号
由于 FST 是渐进式反向工程,头文件中用一组宏区分符号的确认状态:
FST_HOST_OPCODE(x, y)/FST_EFFECT_OPCODE(x, y):已确认的 opcode,值为y;FST_*_EXPERIMENTAL(x, y):存疑的取值;FST_*_UNKNOWN(x):尚未探明的符号,被赋予100000 + __LINE__的"假值",并通过编译器 deprecated 属性告警。
#if defined(__GNUC__) || defined(__clang__)
# define FST_DEPRECATE_UNKNOWN(x) x __attribute__ ((deprecated))
#elif defined(_MSC_VER)
# define FST_DEPRECATE_UNKNOWN(x) __declspec(deprecated) x
#endif
这套机制正是 README 所说"未反向工程的 opcode 被标记为 deprecated,使用时会得到编译器警告"的实现细节:给未知符号一个远离合法取值区间(合法 opcode 集中在 0~80 附近)的假值 100000 + __LINE__,一旦运行中捕获到该数值,就能凭行号反查符号名。在 external/FST/src/fst_utils.h 的 effCode2string() 中同样遵循该约定:if(x>100000) snprintf(output, length, "%d[%s?]", x, #x);。
4.3 插件 opcode(eff*):主机→插件
插件必须实现的 dispatcher 会收到以 eff 前缀命名的 opcode。fst.h 中已确认的主要取值如下(括号内为注释中的调用约定):
| opcode | 值 | 说明 |
|---|---|---|
effOpen / effClose |
0 / 1 | 插件初始/销毁 |
effSetProgram / effGetProgram |
2 / 3 | 设置/读取当前 program |
effSetProgramName / effGetProgramName |
4 / 5 | 写入/读取当前 program 名(char[24]) |
effGetParamLabel / effGetParamDisplay / effGetParamName |
6 / 7 / 8 | 参数单位、显示值、名称(char[8]) |
effSetSampleRate / effSetBlockSize |
10 / 11 | 采样率 / 块大小 |
effMainsChanged |
12 | ivalue 为 1 表示 resume,0 表示 suspend |
effEditGetRect / effEditOpen / effEditClose / effEditIdle |
13 / 14 / 15 / 19 | 编辑器窗口管理 |
effIdentify |
22 | 返回大端整数 "NvEf"(0x4E764566) |
effGetChunk / effSetChunk |
23 / 24 | 状态块读写(ivalue 为 chunk 大小) |
effProcessEvents |
25 | 接收 VstEvents(MIDI/SysEx) |
effCanBeAutomated |
26 | 查询参数是否可自动化 |
effString2Parameter |
27 | 用字符串设置参数值 |
effGetProgramNameIndexed |
29 | 按索引取 program 名 |
effGetInputProperties / effGetOutputProperties |
33 / 34 | 返回 VstPinProperties |
effGetPlugCategory |
35 | 返回插件类别 |
effSetSpeakerArrangement / effGetSpeakerArrangement |
42 / 69 | 声道布局设置/查询 |
effGetEffectName |
45 | 效果名(char[64]) |
effGetVendorString / effGetProductString / effGetVendorVersion |
47 / 48 / 49 | 厂商信息 |
effVendorSpecific |
50 | 厂商扩展(如 REAPER 的 Cockos 扩展) |
effCanDo |
51 | 字符串能力协商(receiveVstEvents、bypass 等) |
effGetVstVersion |
58 | 返回 kVstVersion |
effGetCurrentMidiProgram |
63 | 返回 -1 |
effShellGetNextPlugin |
70 | 外壳插件的子插件枚举 |
effStartProcess / effStopProcess |
71 / 72 | 处理会话开始/结束 |
effSetTotalSampleToProcess |
73 | 返回 ivalue |
effSetProcessPrecision |
77 | kVstProcessPrecision64=1 / 32=0 |
其余如 effEditDraw、effEditMouse、effConnectInput、effSetBypass、effGetTailSize、effKeysRequired、effBeginSetProgram 等仍标记为 UNKNOWN,等待后续反向工程。
4.4 宿主 opcode(audioMaster*):插件→主机
插件通过初始化时拿到的回调指针反向调用宿主。已确认的主要 opcode:
| opcode | 值 | 说明 |
|---|---|---|
audioMasterAutomate |
0 | 通知宿主参数值变化(index, fvalue) |
audioMasterVersion |
1 | 返回 2400 |
audioMasterCurrentId |
2 | 返回 shellUID |
audioMasterWantMidi |
6 | 请求 MIDI 输入 |
audioMasterGetTime |
7 | 返回 VstTimeInfo* |
audioMasterProcessEvents |
8 | 向宿主发送事件(如 MIDI out) |
audioMasterTempoAt |
10 | 返回 10000 × BPM |
audioMasterSizeWindow |
15 | 请求调整窗口(index=宽, ivalue=高) |
audioMasterGetSampleRate / audioMasterGetBlockSize |
16 / 17 | 查询采样率/块大小 |
audioMasterGetCurrentProcessLevel |
23 | 返回实时/离线处理级别 |
audioMasterGetVendorString / audioMasterGetProductString |
32 / 33 | 写入宿主名称字符串 |
audioMasterGetVendorVersion |
34 | 宿主版本(如 REAPER 返回 0x0101) |
audioMasterCanDo |
37 | 能力协商(sendVstEvents、sizeWindow 等) |
audioMasterBeginEdit / audioMasterEndEdit |
43 / 44 | 参数编辑手势起止 |
4.5 AEffect:插件的核心句柄
AEffect 是宿主与插件间传递的主结构——由插件入口函数返回给宿主。其成员布局(64 位下的注释偏移见 fst.h):
typedef struct _fstEffect {
t_fstInt32 magic; /* @0 0x56737450, 即 'VstP' */
AEffectDispatcherProc dispatcher; /* 通用分派函数 */
AEffectProcessProc process; /* 就地处理 */
AEffectSetParameterProc setParameter;
AEffectGetParameterProc getParameter;
t_fstInt32 numPrograms, numParams, numInputs, numOutputs;
t_fstPtrInt flags; /* effFlags* 位标志 */
t_fstPtrInt resvd1, resvd2;
t_fstInt32 initialDelay; /* 延迟(采样数) */
float float1; /* 恒为 1.f */
void* object; void* user;
t_fstInt32 uniqueID; /* @112 四字符唯一 ID */
t_fstInt32 version;
AEffectProcessProc processReplacing;
AEffectProcessDoubleProc processDoubleReplacing;
} t_fstEffect;
要点:
magic校验:值必须为0x56737450(字符VstP)。FstHost加载插件后会立即检查effect->magic != 0x56737450并判定失败(见 external/FST/src/FstHost/FstHost.cpp)。dispatcher是通用入口:绝大多数交互(打开、关闭、设置采样率、查询信息)都通过dispatcher(effect, opcode, index, ivalue, ptr, fvalue)这一个函数完成,返回VstIntPtr。这是 VST2 保持 ABI 稳定的核心技巧——新增功能只需新增 opcode,无需改变结构体。- 三个处理函数:
process(就地处理)、processReplacing(替换写入输出)、processDoubleReplacing(双精度版本),后两者需要对应的effFlagsCanReplacing/effFlagsCanDoubleReplacing标志位支持。 flags位标志:effFlagsHasEditor=1<<0、effFlagsCanReplacing=1<<4、effFlagsProgramChunks=1<<5、effFlagsIsSynth=1<<8、effFlagsNoSoundInStop=1<<9、effFlagsCanDoubleReplacing=1<<12。
4.6 事件与时间结构
VstEvent/VstMidiEvent/VstMidiSysexEvent:共享type + byteSize + deltaFrames + flags公共头;MIDI 事件在@0x18处携带 4 字节midiData,SysEx 事件携带指向堆内存的sysexDump与dumpBytes。事件类型常量kVstMidiType=1、kVstSysExType=6。VstEvents:numEvents+ 变长events[]指针数组,经effProcessEvents/audioMasterProcessEvents双向传递。VstTimeInfo:宿主经audioMasterGetTime返回,包含samplePos、sampleRate、nanoSeconds、ppqPos、tempo、barStartPos、cycleStartPos/EndPos等双精度字段,以及timeSigNumerator/Denominator、flags、smpteFrameRate、smpteOffset、currentBar、magic(0xDEADBEEF)。其中flags的位含义也已确认:kVstTransportChanged=1<<0、kVstTransportPlaying=1<<1、kVstTransportCycleActive=1<<2、kVstTransportRecording=1<<3、kVstNanosValid=1<<8、kVstPpqPosValid=1<<9、kVstTempoValid=1<<10、kVstBarsValid=1<<11、kVstCyclePosValid=1<<12、kVstTimeSigValid=1<<13、kVstSmpteValid=1<<14、kVstClockValid=1<<15。VstSpeakerArrangement/VstSpeakerProperties:声道布局描述。VstSpeakerProperties每个占 112 字节(4 个 float +name[64]+int type+ 28 字节填充),type取值如kSpeakerL=1、kSpeakerR=2、kSpeakerC=3;布局类型如kSpeakerArrEmpty=-1、kSpeakerArrMono=0、kSpeakerArrStereo=1、kSpeakerArr102=28、kSpeakerArrUserDefined=-2。ERect:编辑器窗口矩形,short top/left/bottom/right。VstPinProperties:label[64]+flags+arrangementType+shortLabel[8]。
4.7 插件类别与精度常量
kPlugCategUnknown=0, kPlugCategEffect=1, kPlugCategSynth=2, kPlugCategAnalysis=3,
kPlugCategMastering=4, kPlugCategSpacializer=5, kPlugCategRoomFx=6, kPlugSurroundFx=7,
kPlugCategRestoration=8, kPlugCategOfflineProcess=9, kPlugCategShell=10, kPlugCategGenerator=11,
kPlugCategMaxCount=12
kVstProcessPrecision32=0, kVstProcessPrecision64=1
kVstMaxProgNameLen=25, kVstMaxParamStrLen=8
kVstMaxProductStrLen=128, kVstMaxVendorStrLen=128(EXPERIMENTAL)
关于字符串长度上限,fst.h 中有两处有趣的注释:kVstMaxParamStrLen 官方值为 8,但"宿主通常允许更多(如 24)";而 MaxVendorStrLen 是通过 -fsanitize=address 实测压测出的 128(早期估计值 197782 会在真实插件如 GVST 上段错误,实际安全上限约 130)。
五、在本仓库中的实际集成方式
noise-suppression-for-voice 正是 FST 头文件的真实使用者——它用 FST 编译 VST2 格式的 RNNoise 降噪插件。集成方式见 src/juce_plugin/CMakeLists.txt:
# Use open-source reverse-engineered VST2 api headers
juce_set_vst2_sdk_path(${CMAKE_SOURCE_DIR}/external/FST/fst/)
- 该语句告诉 JUCE 使用
external/FST/fst/目录(含aeffect.h、aeffectx.h、fst.h)作为 VST2 SDK 路径,从而让juce_add_plugin(... FORMATS "VST")能产出 VST2 二进制。 - 由于 FST 的许可要求,整个项目以开源形式构建:VST2 插件目标默认启用(
option(BUILD_VST_PLUGIN ... ON),见根 CMakeLists.txt)。 - 插件按声道数拆分编译:
compile_plugins("${FORMATS}" "_mono" 1)与"_stereo" 2,分别生成rnnoise_mono与rnnoise_stereo两个 VST2 插件(src/juce_plugin/CMakeLists.txt)。
5.1 不依赖 JUCE 的裸编译方式
FST 完全可以脱离 JUCE 使用。以测试插件为例,编译命令为(见 external/FST/src/FstPlugin/Makefile):
$(CXX) -shared -I../../fst -I.. -DFST_DONT_DEPRECATE_UNKNOWN=1 -g -O0 -fPIC FstPlugin.cpp -o FstPlugin.so
注意 -DFST_DONT_DEPRECATE_UNKNOWN=1:关闭未知符号的 deprecated 警告(若想获得警告提示以识别未确认 opcode,则去掉该定义)。
插件入口只需实现一个函数(参考 external/FST/src/FstPlugin/FstPlugin.cpp):
extern "C"
AEffect* VSTPluginMain(AEffectDispatcherProc dispatch4host) {
dispatch = dispatch4host; /* 记住宿主回调 */
AEffect* eff = new AEffect;
memset(eff, 0, sizeof(AEffect));
eff->magic = 0x56737450; /* 'VstP' 魔数 */
eff->dispatcher = dispatchme;
eff->process = process;
eff->getParameter = getParameter;
eff->setParameter = setParameter;
eff->numPrograms = 1;
eff->numParams = 3;
eff->numInputs = 6; eff->numOutputs = 6;
eff->float1 = 1.;
eff->object = eff;
eff->uniqueID = 0xf00d;
eff->version = 666;
eff->flags |= effFlagsCanReplacing;
eff->flags |= effFlagsCanDoubleReplacing;
eff->flags |= effFlagsHasEditor;
eff->processReplacing = processReplacing;
eff->processDoubleReplacing = processDoubleReplacing;
return eff;
}
在 dispatcher 中按需响应各 opcode,例如:
static t_fstPtrInt dispatcher(AEffect* eff, t_fstInt32 opcode, int index,
t_fstPtrInt ivalue, void* const ptr, float fvalue) {
switch (opcode) {
case effGetVstVersion: return 2400;
case effGetVendorString: snprintf((char*)ptr, 16, "SuperVendor"); return 1;
case effGetEffectName: snprintf((char*)ptr, 16, "SuperEffect"); return 1;
case effCanDo:
if (!strcmp((char*)ptr, "receiveVstEvents")) return 1;
if (!strcmp((char*)ptr, "sendVstEvents")) return 1;
return 0;
/* 其余 opcode 按需实现,未知的返回 0 */
}
return 0;
}
5.2 测试宿主与调试工具
仓库自带一套可用于验证插件行为的测试工具链:
- FstHost(宿主):external/FST/src/FstHost/FstHost.cpp 是一个极简宿主,通过
dlopen()/dlsym()查找VSTPluginMain(或回退main)入口,构造AEffect后即可用dispatch_v()逐项探测 opcode。其dispatcher()实现了宿主侧的关键回调(audioMasterVersion返回 2400 等),编译命令为g++ -IFST FstHost.cpp -o FstHost -ldl -lrt,运行方式./FstHost path/to/plugin.so。 - FstPlugin(插件):external/FST/src/FstPlugin/FstPlugin.cpp 是一个自带调试打印的最小插件,可用于在真实 DAW(如 REAPER)中观察宿主的启动调用序列:
effOpen → effSetSampleRate → effSetBlockSize → effMainsChanged → effStartProcess → ... → effStopProcess → effClose。 - FstProxy(代理):external/FST/src/FstProxy/FstProxy.cpp 通过环境变量
FST_PROXYPLUGIN指定真实插件文件,劫持插件与宿主的 dispatcher,打印全部双向 opcode 调用,用于观察商业插件与真实宿主之间的实际通信。 - fst_utils.h:external/FST/src/fst_utils.h 提供
effCode2string()、hostCode2string()(数值↔符号名映射)、print_aeffect()、print_timeinfo()、print_speakerarrangement()等调试函数。 - 编译冒烟测试:external/FST/tests/c_test.c 与 external/FST/tests/cxx_test.cpp 分别验证
fst.h能被纯 C 与 C++ 正常编译,防止头文件在两种语言环境下失效。
六、已知局限:尚未完全反向工程的部分
README 明确承认 FST 尚未 feature-complete。从 external/FST/fst/fst.h 的枚举可以看到,以下符号仍以 FST_*_UNKNOWN 标记(值为 100000 + 行号 的假值):
- 宿主侧:
audioMasterCloseWindow、audioMasterOpenWindow、audioMasterSetIcon、audioMasterUpdateDisplay、audioMasterGetParameterQuantization、audioMasterGetAutomationState、audioMasterGetDirectory、audioMasterPinConnected、audioMasterOffline*系列、audioMasterVendorSpecific等; - 插件侧:
effEditDraw、effEditMouse、effEditSleep、effEditTop、effGetNumMidiInputChannels、effGetNumMidiOutputChannels、effSetBypass、effGetTailSize、effConnectInput、effConnectOutput、effIdle、effBeginSetProgram、effEndSetProgram等; - 常量:
kVstAutomationReading、kVstAutomationWriting、kVstPinIsActive、kVstPinIsStereo、kVstPinUseSpeaker、全部kVstSmpte*帧率、大部分kSpeaker*与kSpeakerArr*通道布局值。
按照反向工程文档的实测,常规插件/宿主互操作中真正会用到但尚未确认的 opcode 已经很少(文档总结中仅剩 hostCode 3/13/42 与 effCode 19/53/56/62/66 等少量编号)。若你的项目恰好需要某个未支持 opcode,README 建议向 FST 上游提交 issue 并提供尽量多的复现信息——这正是该项目的迭代机制。
七、结语
FST 的价值在于:它以完全公开、可审计的反向工程流程(见 external/FST/docs/REVERSE_ENGINEERING.md)重建了 VST2 的二进制契约,让开源项目得以绕开已下架且许可受限的官方 SDK。noise-suppression-for-voice 将其作为 VST2 插件的底层接口,配合 JUCE 与 RNNoise 构建出跨格式的实时降噪插件。使用 FST 时请牢记两条红线:项目须采用兼容的开源许可,且产出的插件不得冠以 "VST" 商标名称。对于希望深入理解 VST2 协议底层细节的开发者,fst.h 中逐条带注释的 opcode 枚举与配套的调试工具链,本身就是一份难得的活教材。