FST 头文件指南:以开源反向工程 VST2 SDK 构建音频插件

原创2026-10-14 12:46:211,709 阅读
文章标签:音频处理音视频

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 枚举与配套的调试工具链,本身就是一份难得的活教材。

登录后查看全文
noise-suppression-for-voice