JUCE 内置 VST3 SDK 的 ModuleInfoLib 深度指南解析与生成 moduleinfo.json【免费下载链接】JUCEJUCE is an open-source cross-platform C application framework for desktop and mobile applications, including VST, VST3, AU, AUv3, LV2 and AAX audio plug-ins.项目地址: https://gitcode.com/GitHub_Trending/ju/JUCE导读本文聚焦于 JUCE 仓库内嵌的 Steinberg VST3 SDK 所提供的ModuleInfoLib——一个用于解析与创建moduleinfo.jsonVST3 插件模块清单文件的 C17 库。moduleinfo.json描述了 VST3 模块的名称、版本、工厂信息厂商/网址/邮箱/标志、导出的组件类CID、分类、快照以及新旧 CID 兼容映射是宿主程序识别、加载与迁移插件的关键元数据。读完本文你将掌握 ModuleInfoLib 的完整 API 调用方式、JSON 结构规范、严格校验规则以及如何在自有工程中集成解析与生成能力。一、背景什么是 moduleinfo.json 与 ModuleInfoLibmoduleinfo.json是 Steinberg 定义的 VST3 模块描述文件伴随.vst3二进制模块分发向宿主提供模块的声明式元数据。它解决了传统上需要动态加载模块、实例化工厂才能获得的信息如厂商、类列表、快照路径的静态化描述问题也用于表达 CID 迁移关系帮助宿主在插件标识符变更后仍能正确恢复会话。ModuleInfoLib 正是 VST3 SDK 中负责读写这份 JSON的官方库其说明文档位于 modules/juce_audio_processors_headless/format_types/VST3_SDK/public.sdk/source/vst/moduleinfo/ReadMe.md。该目录下同时提供了全部实现源码文件职责moduleinfo.h定义ModuleInfo及其嵌套结构数据模型moduleinfoparser.cpp/.h解析 JSON →ModuleInfo严格校验moduleinfocreator.cpp/.h从已加载的VST3::Hosting::Module生成ModuleInfo并输出 JSONjson.h/jsoncxx.h底层 JSON 解析引擎sheredom/json.h 单头库及 C 封装二、数据模型ModuleInfo 结构总览解析与创建两端共享同一套数据模型定义在 moduleinfo.h 的Steinberg::ModuleInfo结构体中包含四个部分struct ModuleInfo { struct FactoryInfo { std::string vendor; // 厂商名 std::string url; // 厂商网址 std::string email; // 联系邮箱 int32_t flags {0}; // 工厂标志位见下文 }; struct Snapshot { double scaleFactor {1.}; // 快照缩放因子默认 1.0 std::string path; // 快照图片路径 }; using SnapshotList std::vectorSnapshot; struct ClassInfo { std::string cid; // 组件类唯一标识CIDUUID 字符串 std::string category; // 分类如 kAudioEffectClass std::string name; // 类名 std::string vendor; // 该类所属厂商 std::string version; // 版本号字符串 std::string sdkVersion; // 编译所用 SDK 版本 std::vectorstd::string subCategories; // 子分类列表 SnapshotList snapshots; // 快照列表 int32_t cardinality {0x7FFFFFFF}; // 可实例化数量默认取极大值表示不限 uint32_t flags {0}; // 类标志位 }; struct Compatibility { std::string newCID; // 新 CID std::vectorstd::string oldCID; // 被取代的旧 CID 列表 }; std::string name; // 模块名 std::string version; // 模块版本 FactoryInfo factoryInfo; // 工厂信息 ClassList classes; // 类列表 CompatibilityList compatibility; // CID 兼容映射表 };从源码结构看Compatibility与ClassInfo是可选的集合解析器允许缺省而模块名、版本、工厂信息和类列表属于必填顶层字段。三、解析 moduleinfo.json接入步骤与 API3.1 需要包含的文件按 ReadMe.md 的说明解析端需要把以下五个文件加入工程moduleinfoparser.cppmoduleinfoparser.hmoduleinfo.hjson.hjsoncxx.h同时需要把VST SDK 的根目录加入头文件搜索路径moduleinfoparser.cpp内部依赖pluginterfaces/base/ipluginbase.h中的PFactoryInfo标志定义该头位于 SDK 根目录下。3.2 解析调用方式先把moduleinfo.json的完整内容读入内存缓冲区然后调用parseJson或parseCompatibilityJsonauto moduleInfo ModuleInfoLib::parseCompatibilityJson (std::string_view (buffer, bufferSize), std::cerr);parseCompatibilityJson的完整签名见 moduleinfoparser.hstd::optionalModuleInfo::CompatibilityList parseCompatibilityJson ( std::string_view jsonData, std::ostream* optErrorOutput);若解析成功返回的std::optional含有值失败则返回空 optional并把错误信息写入可选的错误输出流。与之并行的还有解析完整模块信息的parseJsonstd::optionalModuleInfo parseJson (std::string_view jsonData, std::ostream* optErrorOutput);optErrorOutput可为nullptr静默模式。两个函数的行为一致绝不抛异常任何错误都以空 optional 错误流输出的方式返回因此调用方只需检查 optional 是否有值。3.3 底层解析引擎json.h jsoncxx.h解析器并非手写 JSON 扫描而是建立在单头库 sheredom/json.h 之上json.h并经由 jsoncxx.h 封装为类型安全的 C 接口。值得注意的实现细节JSON::Document::parse在调用json_parse_ex时启用了两个解析标志——json_parse_flags_allow_json5允许 JSON5 语法如单引号字符串、C 风格注释、十六进制数字、尾随逗号等宽松写法和json_parse_flags_allow_location_information为每个值记录 offset/line/row 位置信息。这意味着解析器能接受 JSON5 风格的 moduleinfo 文件同时能在出错时给出精确的行列号定位。jsoncxx.h还提供了便捷的类型访问接口Value::asObject/asArray/asString/asNumber/asBoolean/asNull、Object/Array的范围 for 迭代、Number::getInteger/getDouble整数优先走std::from_chars浮点走std::stod以及errorToString把json_parse_error_e错误码转为可读字符串。四、严格校验moduleinfo.json 的字段规范moduleinfoparser.cpp内置了非常严格的 schema 校验解析失败时抛出parse_error携带 offset/line/row 定位信息或std::logic_error。理解这些规则是手写或调试moduleinfo.json的关键。4.1 顶层必填字段解析器只接受以下五个顶层键其余任何键都会报Unexpected JSON Token顶层键类型必填Name字符串✅Version字符串✅Factory Info对象✅Compatibility数组可选Classes数组✅且每个键只允许出现一次重复出现即报错。4.2 Factory Info 规范Factory Info对象包含四个键全部必填且不可重复键类型说明Vendor字符串厂商名URL字符串厂商网址E-Mail字符串联系邮箱Flags对象三个布尔标志位Flags对象只接受以下三个布尔键对应PFactoryInfo的标志位键对应标志Classes DiscardablePFactoryInfo::kClassesDiscardable类可被宿主丢弃按需重建Component Non DiscardablePFactoryInfo::kComponentNonDiscardableUnicodePFactoryInfo::kUnicode标志值必须是布尔类型出现未知键会报Unknown flag。注意Classes Discardable与后续创建 API 的includeDiscardableClasses参数语义直接相关。4.3 Classes 数组规范Classes是对象数组每个类对象支持九个键其中快照与子分类可选其余必填键类型必填CID字符串✅Category字符串✅Name字符串✅Vendor字符串✅Version字符串✅SDKVersion字符串✅Sub Categories字符串数组可选Class Flags整数✅Cardinality整数✅Snapshots对象数组可选Snapshots数组内每个对象恰有两个键Path字符串与Scale Factor双精度浮点数二者缺一不可scaleFactor 0.或path为空均报Missing Snapshot keys。4.4 Compatibility 数组规范Compatibility是对象数组每个对象包含键类型说明New字符串新 CIDOld字符串数组一个或多个旧 CIDNew与Old均不可为空否则分别报Expect New CID here/Expect Old CID here。4.5 错误输出格式无论是 JSON 语法错误还是字段语义错误错误信息都会通过你传入的std::ostream*输出并附带定位信息error : json_parse_error_expected_colon offset : 42 line no: 3 row no : 10语法错误来自json.h的json_parse_result_sprintJsonParseError输出 error/offset/line no/row no 四行语义错误来自parse_errorwhat()包含消息及 offset/line/row 三行。五、创建 moduleinfo.json从 VST3 模块生成清单5.1 依赖与接入按 ReadMe 说明生成端需要链接 VST3 SDK 的sdk_hosting库并包含以下文件moduleinfocreator.cppmoduleinfocreator.hmoduleinfo.h此外还需要从 hosting 目录加入模块平台实现三选一对应所在平台module_win32.cppWindowsmodule_mac.mmmacOSmodule_linux.cppLinux这三个平台实现文件在当前仓库中均真实存在module_linux.cpp、module_mac.mm、module_win32.cpp它们负责跨平台加载 VST3 模块二进制、解析导出表与工厂信息。5.2 两个核心方法moduleinfocreator.h 暴露两个函数// 从一个已加载的模块生成 ModuleInfo ModuleInfo createModuleInfo (const VST3::Hosting::Module module, bool includeDiscardableClasses); // 把 ModuleInfo 以 JSON 形式写入输出流 void outputJson (const ModuleInfo info, std::ostream output);典型用法对应 ReadMe 示例auto moduleInfo ModuleInfoLib::createModuleInfo (module, false); ModuleInfoLib::outputJson (moduleInfo, std::cout);5.3 createModuleInfo 的实现逻辑从 moduleinfocreator.cpp 源码可以还原出完整生成流程模块名取module.getName()并去掉最后一个.之后的扩展名如MyPlugin.vst3→MyPlugin。工厂信息从module.getFactory().info()拷贝 vendor、url、email、flags 四项。类列表的条件生成只有当工厂的classesDiscardable()为 false或其为 true 且includeDiscardableClasses参数为 true 时才枚举factory.classInfos()生成ClassInfo。也就是说对于类可丢弃的模块默认传 false不导出类列表——这正是includeDiscardableClasses参数的语义头文件注释if true adds the current available classes to the module info。快照关联调用VST3::Hosting::Module::getSnapshots (module.getPath())取得模块目录下的快照图片按uid即 CID与类匹配快照路径若以模块路径为前缀会被裁剪成相对路径写入 JSON。类字段映射依次填充cidci.ID().toString()、category、name、vendor、version、sdkVersion、subCategories、cardinality、classFlags。5.4 outputJson 与 JSON5 输出outputJson内部使用一个JSON5Writer辅助类同样位于 moduleinfocreator.cpp进行美化输出缩进 2 空格、键后带:输出结构严格与解析器期望的 schema 对称{ Name: MyPlugin, Version: 1.0.0, Factory Info: { Vendor: MyCompany, URL: https://example.com, E-Mail: devexample.com, Flags: { Unicode: true, Classes Discardable: false, Component Non Discardable: false } }, Classes: [ { CID: 01234567-89ab-cdef-0123-456789abcdef, Category: Audio Effect, Name: My Effect, Vendor: MyCompany, Version: 1.0.0, SDKVersion: 3.7.12, Sub Categories: [Fx, Stereo], Class Flags: 0, Cardinality: 2147483647, Snapshots: [ { Scale Factor: 1.0, Path: snapshot.png } ] } ] }需要注意outputJson生成的是键名带空格的 JSON5 风格文件如Factory Info、Class Flags这与解析器接受的键名严格一致读写两端对称闭合。六、工程集成与使用建议6.1 完整接入清单把解析 生成能力同时纳入自有工程的完整清单为解析端moduleinfoparser.cpp、moduleinfoparser.h、moduleinfo.h、json.h、jsoncxx.h生成端moduleinfocreator.cpp、moduleinfocreator.h、moduleinfo.hsdk_hosting库 平台module_*.cpp/.mm编译要求C17std::optional、std::string_view、std::variant头文件搜索路径VST SDK 根目录6.2 在 JUCE 生态中的位置本仓库JUCE将 VST3 SDK 完整内嵌于 modules/juce_audio_processors_headless/format_types/VST3_SDK 目录作为juce_audio_processors_headless模块的 VST3 宿主/加载实现基础。sdk_hosting的VST3::Hosting::Module正是 JUCE 的 VST3 插件扫描与宿主功能所依赖的模块加载层ModuleInfoLib 则在此之上提供元数据的 JSON 序列化/反序列化能力可用于插件管理器导出清单、安装器生成或校验 moduleinfo、以及宿主持久化插件信息时的 CID 兼容迁移记录。6.3 实践建议解析时永远传错误流即使不关心错误详情也建议传入std::cerr或自定义日志流便于定位畸形文件的行列位置。写入与读取保持键名一致手写 JSON 时必须使用带空格的规范键名Factory Info、Class Flags、Sub Categories、Scale Factor、E-Mail等否则会被严格校验拒绝。区分parseJson与parseCompatibilityJson只需 CID 迁移信息时用后者需要完整模块清单时用前者两者共享同一严格校验内核。注意includeDiscardableClasses对声明Classes Discardable的模块若希望清单包含当前可用的类列表请传true。七、小结ModuleInfoLib 是 VST3 SDK 中处理moduleinfo.json的官方轻量级库解析端提供绝不抛异常、失败返回空 optional的容错 API 与严格的字段校验创建端基于sdk_hosting的模块加载能力一条调用即可从.vst3模块生成结构化清单并输出为 JSON5 格式。掌握其数据模型ModuleInfo/FactoryInfo/ClassInfo/Compatibility、JSON 键名规范与两个核心 API即可在宿主、安装器或插件管理工具中可靠地读写 VST3 模块元数据。提示ReadMe 中提到 VST3 SDK 还包含moduleinfotool命令行工具可以从命令行完成模块 → moduleinfo.json的转换就当前仓库快照而言该工具的可执行源码未包含在内但完全可以通过上文介绍的createModuleInfooutputJson两个 API 在自有代码中实现等价能力。【免费下载链接】JUCEJUCE is an open-source cross-platform C application framework for desktop and mobile applications, including VST, VST3, AU, AUv3, LV2 and AAX audio plug-ins.项目地址: https://gitcode.com/GitHub_Trending/ju/JUCE创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考