SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场vcv-rack-plugin

vcv-rack-plugin

编程与开发

查看项目

更新于 10-16 03:52

技能介绍

用途

该技能用于帮助开发者构建 VCV Rack v2 插件。VCV Rack 是开源的 Eurorack 模块化合成器模拟器，插件是 C++ 共享库（.dylib/.so/.dll），由 Rack 在运行时加载。一个插件是若干模块的集合，每个模块包含引擎（Module）与界面（ModuleWidget）两半，两者始终配对并通过 createModel<>() 注册。

主要能力

  • 项目脚手架：可通过 vcp（vc-plugins-cli）执行 vcp --create-plugin，或使用 Rack SDK 的 $RACK_DIR/helper.py createplugin MyPlugin，或手动创建文件。
  • plugin.json 清单：包含 slug、name、version、license、brand、author、authorEmail、modules 等字段。slug 发布后不可更改；版本主号需与 Rack 主号一致（Rack 2 对应 2.x.x）。
  • Module 与 ModuleWidget 编写：Module 子类化 rack::Module，保存状态与 DSP 逻辑，process() 每个音频采样调用一次；ModuleWidget 子类化 rack::ModuleWidget，为面板布局旋钮、端口、灯与显示器。
  • DSP 实现：process() 中使用 args.sampleTime 处理时间相关数学，音频信号为 +/-5V，CV 为 0-10V 单极或 +/-5V 双极，音高为 1V/oct，C4 基准为 dsp::FREQ_C4（261.6256 Hz）；所有输出需做 NaN/Inf 防护；process() 中不允许分配、加锁或阻塞式 I/O。提供逐采样与块处理（FFT、神经网络、卷积）两种常见模式。
  • Widget 构建：使用居中布局辅助函数 addParam/createParamCentered、addInput/createInputCentered、addOutput/createOutputCentered、addLight/createLightCentered 等。SDK 提供 60 多个内置组件（旋钮、端口、开关、按钮、滑块、螺丝、灯），常用如 RoundBlackKnob、RoundLargeBlackKnob、RoundSmallBlackKnob、RoundBlackSnapKnob、Trimpot、Davies1900hLargeBlackKnob、PJ301MPort、ThemedPJ301MPort、CKSS、CKSSThree、LEDButton、ScrewSilver/ScrewBlack、ThemedScrew。
  • 面板 SVG 设计：在 Inkscape 中设计，单位为 mm，高度 128.5 mm，宽度为 5.08 mm（1 HP）的倍数，文字需转换为路径（Path > Object to Path）；可用带颜色圆圈的 components 图层进行自动生成：红 #ff0000 = Param、绿 #00ff00 = Input、蓝 #0000ff = Output、品红 #ff00ff = Light。
  • 状态序列化：参数自动保存，自定义状态通过 dataToJson() / dataFromJson() 序列化。
  • 异步加载：文件 I/O 与重量级 DSP 初始化不得阻塞音频线程，需使用 std::thread 配合 std::atomic 标志的模式处理。
  • 复音：最多支持 16 通道，按通道将状态组织进结构体，通过 getPolyVoltage(c)、setVoltage(out, c)、setChannels() 处理。
  • 扩展器：相邻模块间使用双缓冲扩展器消息进行线程安全通信，通过 rightExpander.producerMessage / consumerMessage 实现。
  • 构建与发布：make 编译、make dist 打包为 .vcvplugin、make install 安装到 Rack 用户目录；本地构建使用 RACK_DIR=./dep/Rack-SDK 前缀；跨平台编译可使用 rack-plugin-toolchain 与 Docker（docker run --rm -v $(pwd):/plugin rack-plugin-toolchain:19 make plugin-build PLUGIN_DIR=/plugin）；GitHub Actions 可为 lin-x64、win-x64、mac-x64、mac-arm64 四个目标构建并在打标签时发布；标签需与 plugin.json 中的版本一致。
  • DSP 架构分层：将 Rack 胶水代码与纯 DSP 分离，DSP 类不应包含 rack.hpp；Module 作为薄封装负责电压域读写与归一化转换。
  • 优先使用 SDK 工具函数：clamp、rescale、math::normalize/interpolateLinear/interpolateLog、dsp::quadraticBipolar/cubic/exponentialBipolar、dsp::amplitudeToDb/dbToAmplitude、dsp::FREQ_C4/FREQ_A4、dsp::exp2_taylor5、dsp::approxSin/approxCos、dsp::SchmittTrigger/PulseGenerator/Timer、dsp::BiquadFilter/RCFilter/SlewLimiter/ExponentialFilter、dsp::minBlep，以及 string::f/toLowerCase/trim/truncate 等，避免重复实现。

使用方式

技能提供参考文件以获取更深入细节：references/manifest-reference.md（plugin.json 完整 schema）、references/module-template.md（完整可复制的模块模板）、references/dsp-patterns.md（振荡器、滤波器、包络、触发器等 DSP 手册）、references/panel-design.md（Inkscape SVG 面板创建、组件放置、深色主题）、references/component-library.md（60 多个内置 UI 组件目录）、references/ci-cd.md（多平台构建的 GitHub Actions 工作流）、references/rack-sdk-api.md（engine、dsp、app、widget 命名空间的关键 SDK API）、references/testing.md（DSP 单元测试：测试框架、mock 策略、覆盖率、性能基准）。

适用场景

适用于为 VCV Rack v2 开发插件的 C++ 开发者，尤其是需要搭建工程结构、实现音频 DSP、设计面板界面、处理复音与模块间通信、配置跨平台构建与发布流程的场景。

限制与注意事项

  • 路径中不能包含空格，Makefile 构建系统无法处理。
  • SVG 中的文字必须是路径，Rack 渲染器不支持字体。
  • 不要跨帧存储字体/图像引用，OpenGL 上下文可能被销毁，应每帧通过 APP->window->loadFont() 加载。
  • 不要硬编码采样率，使用 args.sampleTime。
  • 不要在 process() 中分配内存（禁止 new/malloc、STL 容器增长）。
  • 不要在 process() 中阻塞（禁止文件 I/O、互斥锁、网络）。
  • 不要硬削波输出，让下游模块处理饱和。
  • 不要自行编写 clamp/rescale，使用 SDK 中的 clamp() 与 rescale()。
  • slug 一经发布不可更改，它是永久标识符。
  • 若插件未出现在 Rack 中，检查 Rack 用户目录下的 log.txt。

以上内容依据所提供的技能资料整理，未提供的收费、价格、平台或效果信息暂未提供。