{"id":99,"date":"2023-09-23T16:33:06","date_gmt":"2023-09-23T23:33:06","guid":{"rendered":"https:\/\/rabiensoftware.com\/?p=99"},"modified":"2023-09-23T19:07:20","modified_gmt":"2023-09-24T02:07:20","slug":"creating-an-effect-plugin-with-gin","status":"publish","type":"post","link":"https:\/\/rabiensoftware.com\/index.php\/2023\/09\/23\/creating-an-effect-plugin-with-gin\/","title":{"rendered":"Creating an Effect plugin with Gin"},"content":{"rendered":"

Introduction<\/h3>\n

Creating a plugin with Gin & JUCE is a lot fast than with JUCE alone. A lot a boiler plate is handled for you, which lets you focus on getting your DSP working. This tutorial explains the code in the Gin example Effect<\/a> plugin which is a simple gain and pan plugin. A basic understanding of JUCE plugins is assumed. Start by forking and renaming the GinPlugin<\/a> repo. Edit the CMakeLists.txt<\/a> with you plugin name and ID and the build.sh<\/a> script with the name of your plugin. The repo is already setup to build a VST3, AU, LV2 plugin on Windows, macOS and Linux. Notarization on macOS is supported by adding your Apple developer account ID and signing keys as repository secrets.<\/p>\n

First Steps<\/h3>\n

Subclass your processor from gin::Processor<\/strong> instead of juce::AudioProcessor<\/strong> and your editor from gin::ProcessorEditor<\/strong> instead of juce::AudioProcessorEditor<\/strong>.<\/p>\n

The gin::ProcessorOptions\u00a0<\/strong>class allows you to specify options for your plugin. By default it is filled with sensible defaults based on various JUCE #defines. At the end of your constructor you also need to call init()<\/strong>. A minimal plugin should look like this:<\/p>\n

static<\/b><\/span> gin::ProcessorOptions getOpts<\/span>()\r\n{\r\n  \u00a0 <\/span>gin::ProcessorOptions opts;\r\n    \/\/ Fill in your custom options here\r\n  \u00a0 <\/span>return<\/b><\/span> opts;\r\n}\r\n\r\nEffectAudioProcessor::<\/span>EffectAudioProcessor<\/span>()<\/span>\r\n  \u00a0 <\/span>: gin::Processor (false<\/b><\/span>, getOpts())\r\n{\r\n    \/\/ call init and the end of your constructor\r\n  \u00a0 <\/span>init();\r\n}<\/pre>\n
Gin automatically handles loading and saving state, loading presets etc, all that is requires of your processor is to create the parameters and implement the processBlock<\/strong> function.<\/p>\n
Adding Parameters<\/h3>\n
Gin supports internal parameters and external parameters. Internal parameters are not visible to the host, and should be used for things that have no need to be automated. They are also useful for ranges that might change in size, like number of filter types. External parameters are exposed to the host and can be optionally automatable or not.<\/p>\n
For the vol & pan effect we will add 4 parameters, 2 internal (pan law & polarity invert) and 2 external (vol & pan)<\/p>\n
 \u00a0  <\/span>levelParam\u00a0 <\/span>= addExtParam (\"level\"<\/span>,\u00a0 <\/span>\"Level\"<\/span>,\u00a0 <\/span>{}, \"dB\"<\/span>, {-100.0f<\/span>, 5.0f<\/span>, 0.0f<\/span>, 5.0f<\/span>}, 0.0f<\/span>, 0.05f<\/span>);\r\n\u00a0 \u00a0 <\/span>panParam\u00a0 \u00a0 <\/span>= addExtParam (\"pan\"<\/span>,\u00a0 \u00a0 <\/span>\"Pan\"<\/span>,\u00a0 \u00a0 <\/span>{}, {}, \u00a0 <\/span>{-1.0f<\/span>, \u00a0 <\/span>1.0f<\/span>, 0.0f<\/span>, 1.0<\/span>},\u00a0 <\/span>0.0f<\/span>, 0.05f<\/span>,\u00a0 <\/span>panTextFunction);\r\n\u00a0 \u00a0 <\/span>modeParam \u00a0 <\/span>= addIntParam (\"mode\"<\/span>, \u00a0 <\/span>\"Mode\"<\/span>, \u00a0 <\/span>{}, {}, \u00a0 <\/span>{ 0.0f<\/span>, \u00a0 <\/span>1.0f<\/span>, 0.0f<\/span>, 1.0<\/span>},\u00a0 <\/span>0.0f<\/span>, 0.0f<\/span>, \u00a0 <\/span>modeTextFunction);\r\n\u00a0 \u00a0 <\/span>invertParam = addIntParam (\"invert\"<\/span>, \"Invert\"<\/span>, {}, {}, \u00a0 <\/span>{ 0.0f<\/span>, \u00a0 <\/span>1.0f<\/span>, 0.0f<\/span>, 1.0<\/span>},\u00a0 <\/span>0.0f<\/span>, 0.0f<\/span>, \u00a0 <\/span>onOffTextFunction);<\/pre>\n
For each parameter, provide and id, name, short name (optional), label (optional), range, default, smoothing time (optional) and value to text function (optional). A smoothing time prevents zipper noise when the user adjusts a parameter. Setting a smoothing time of 0 disables smoothing, leaving it up to your algorithm to provide smoothing itself.<\/p>\n
Gin parameters have up to 3 values associated with them. A value which is always between 0 and 1. A user value, which is displayed in the user interface and a processing value which is used by the processing algorithm. In some cases all these values may be in the 0 to 1 range, but for the level param they are all different. The user value is in dB and is in the range -100 db to +5 db and the processing value is the gain and is in the range 0 to ~3.1.<\/p>\n
To provide a processing value for a parameter, set the \u00a0gin::Parameter::conversionFunction<\/strong>.<\/p>\n
levelParam->conversionFunction = [] (float<\/b><\/span> in) { return<\/b><\/span> juce::Decibels::decibelsToGain (in); };<\/pre>\n
Text functions convert the user value into a string. If one isn’t provided a simple number with up to 3 decimal places is show. Text functions are used to convert mod and invert into strings and to add L, C or R to the pan value.<\/p>\n
static<\/b><\/span> juce::String modeTextFunction<\/span> (const<\/b><\/span> gin::Parameter&, float<\/b><\/span> v)\r\n{\r\n\u00a0 \u00a0 <\/span>if<\/b><\/span> ((int<\/b><\/span> (v)) == 0<\/span>)\r\n\u00a0 \u00a0 \u00a0 \u00a0 <\/span>return<\/b><\/span> \"Linear\"<\/span>;\r\n    return<\/b> \"3dB\"<\/span>;<\/span>\r\n}\r\n\r\nstatic<\/b><\/span> juce::String onOffTextFunction<\/span> (const<\/b><\/span> gin::Parameter&, float<\/b><\/span> v)\r\n{\r\n\u00a0 \u00a0 <\/span>if<\/b><\/span> (int<\/b><\/span> (v) == 0<\/span>)\r\n        return<\/b> \"On\"<\/span>;<\/span>\r\n    return<\/b> \"Off\"<\/span>;<\/span>\r\n}\r\n\r\nstatic<\/b><\/span> juce::String panTextFunction<\/span> (const<\/b><\/span> gin::Parameter&, float<\/b><\/span> v)\r\n{\r\n\u00a0 \u00a0 <\/span>if<\/b><\/span> (juce::String (v, 2<\/span>) == \"0.00\"<\/span>)\r\n\u00a0 \u00a0 \u00a0 \u00a0 <\/span>return<\/b><\/span> \"C\"<\/span>;\r\n\u00a0 \u00a0 <\/span>if<\/b><\/span> (v < 0<\/span>)\r\n\u00a0 \u00a0 \u00a0 \u00a0 <\/span>return<\/b><\/span> juce::String (-v, 2<\/span>) + \"L\"<\/span>;\r\n\u00a0 \u00a0 <\/span>return<\/b><\/span> juce::String (v, 2<\/span>) + \"R\"<\/span>;\r\n}<\/pre>\n
DSP Code<\/h3>\n
The heart of the processing block is this simple function that converts a pan and volume into a left and right gain with two different pan laws.<\/p>\n
\u00a0 \u00a0 <\/span>auto<\/b><\/span> getGains = [] (float<\/b><\/span> gain, float<\/b><\/span> pan, int<\/b><\/span> mode) -> std::pair<float<\/b><\/span>, float<\/b><\/span>>\r\n\u00a0 \u00a0 <\/span>{\r\n\u00a0 \u00a0 \u00a0 \u00a0 <\/span>if<\/b><\/span> (mode == 0<\/span>)\r\n\u00a0 \u00a0 \u00a0 \u00a0 <\/span>{\r\n\u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 <\/span>const<\/b><\/span> float<\/b><\/span> pv = pan * gain;\r\n  \u00a0 \u00a0 \u00a0   \u00a0 <\/span>return<\/b><\/span> { gain - pv, gain + pv };\r\n\u00a0 \u00a0 \u00a0 \u00a0 <\/span>}\r\n\u00a0 \u00a0 \u00a0 \u00a0 <\/span>else<\/b><\/span>\r\n\u00a0 \u00a0 \u00a0 \u00a0 <\/span>{\r\n\u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 <\/span>pan = (pan + 1.0f<\/span>) * 0.5f<\/span>;\r\n\r\n\u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 <\/span>return<\/b><\/span>\r\n\u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 <\/span>{\r\n\u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 <\/span>gain * std::sin ((1.0f<\/span> - pan) * juce::MathConstants<float<\/b><\/span>>::halfPi),\r\n\u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 <\/span>gain * std::sin (pan * juce::MathConstants<float<\/b><\/span>>::halfPi)\r\n\r\n\u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 <\/span>};\r\n\u00a0 \u00a0 \u00a0 \u00a0 <\/span>}\r\n\u00a0 \u00a0 <\/span>};<\/pre>\n
First we will get the parameters that won’t be smoothed and store them in variables. For the example, we will assume the user is ok with clicks if they change the pan law or polarity, but expect pan and volume to adjust without artifacts. Gin parameters can be accessed as ints or bools, which can save some casting.<\/p>\n
\u00a0 \u00a0 <\/span>const<\/b><\/span> auto<\/b><\/span> mode \u00a0 <\/span>= modeParam->getUserValueInt();\r\n\u00a0 \u00a0 <\/span>const<\/b><\/span> auto<\/b><\/span> inv\u00a0 \u00a0 <\/span>= invertParam->getUserValueBool() ? -1.0f<\/span> : 1.0f<\/span>;\r\n\r\n\u00a0 \u00a0 <\/span>const<\/b><\/span> auto<\/b><\/span> numSamps = buffer.getNumSamples();\r\n\u00a0 \u00a0 <\/span>auto<\/b><\/span> pos = 0<\/span>;<\/pre>\n
If no parameters are currently changing, this function can be applied to the entire block with the same input parameters, otherwise they need to change for each sample. First, we check if any parameters are changing and work sample by sample.<\/p>\n
\u00a0 \u00a0 <\/span>while<\/b><\/span> (isSmoothing() && pos < numSamps)\r\n\u00a0 \u00a0 <\/span>{\r\n\u00a0 \u00a0 \u00a0 \u00a0 <\/span>auto<\/b><\/span> gain = levelParam->getProcValue (1<\/span>);\r\n\u00a0 \u00a0 \u00a0 \u00a0 <\/span>auto<\/b><\/span> pan = panParam->getProcValue (1<\/span>);\r\n\r\n\u00a0 \u00a0 \u00a0 \u00a0 <\/span>auto<\/b><\/span> [left, right] = getGains (gain, pan, mode);\r\n\r\n\u00a0 \u00a0 \u00a0 \u00a0 <\/span>buffer.applyGain (0<\/span>, pos, 1<\/span>, left\u00a0 <\/span>* inv);\r\n\u00a0 \u00a0 \u00a0 \u00a0 <\/span>buffer.applyGain (1<\/span>, pos, 1<\/span>, right * inv);\r\n \u00a0 \u00a0 \u00a0 \u00a0<\/span>\r\n\u00a0 \u00a0 \u00a0 \u00a0 <\/span>pos++;\r\n\u00a0 \u00a0 <\/span>}<\/pre>\n
The function gin::Parameter::getProcValue(int stepSize)<\/strong> returns the next smoothed processing value for the parameter. The loop will continue until the parameters have reached their destination value or there is no more input to process. If there is still more input to process, it can be handled in a block for efficiency.<\/p>\n
\u00a0 \u00a0 <\/span>if<\/b><\/span> (pos < numSamps)\r\n\u00a0 \u00a0 <\/span>{\r\n\u00a0 \u00a0 \u00a0 \u00a0 <\/span>auto<\/b><\/span> todo = numSamps - pos; \u00a0 \u00a0  <\/span>\r\n\r\n\u00a0 \u00a0 \u00a0 \u00a0 <\/span>auto<\/b><\/span> gain = levelParam->getProcValue (todo);\r\n\u00a0 \u00a0 \u00a0 \u00a0 <\/span>auto<\/b><\/span> pan = panParam->getProcValue (todo);\r\n \u00a0 \u00a0 \u00a0 <\/span>\r\n\u00a0 \u00a0 \u00a0 \u00a0 <\/span>auto<\/b><\/span> [left, right] = getGains (gain, pan, mode); \u00a0  <\/span>\r\n\r\n\u00a0 \u00a0 \u00a0 \u00a0 <\/span>buffer.applyGain (0<\/span>, pos, todo, left\u00a0 <\/span>* inv);\r\n\u00a0 \u00a0 \u00a0 \u00a0 <\/span>buffer.applyGain (1<\/span>, pos, todo, right * inv);\r\n\u00a0 \u00a0 <\/span>}<\/pre>\n
Creating the Editor<\/h3>\n
If your plugin has UI (and it should), create it here. If you want your plugin to resize, wrap your editor in a gin::ScaledPluginEditor<\/strong>. Also create the plugin itself.<\/p>\n
bool<\/b><\/span> EffectAudioProcessor::<\/span>hasEditor() <\/span>const<\/b><\/span>\r\n{\r\n  \u00a0 <\/span><\/span>return<\/b> true<\/b>;<\/span>\r\n}\r\n\r\njuce::AudioProcessorEditor* EffectAudioProcessor<\/span>::createEditor<\/span>()\r\n{\r\n  \u00a0 <\/span>return<\/b><\/span> new<\/b><\/span> EffectAudioProcessorEditor (*this<\/b><\/span>);\r\n}\r\n\r\njuce::AudioProcessor* JUCE_CALLTYPE createPluginFilter<\/span>()\r\n{\r\n\u00a0 \u00a0 <\/span>return<\/b><\/span> new<\/b><\/span> EffectAudioProcessor();\r\n\r\n}<\/pre>\n
UI Code<\/h3>\n
Gin uses a grid layout for components. When creating the UI first specify the size of the grid, in this case 6 x 1. And then layout the controls on the grid.<\/p>\n
\u00a0 \u00a0 <\/span>setGridSize (6<\/span>, 1<\/span>);\r\n \u00a0 <\/span>\r\n\u00a0 \u00a0 <\/span>addControl (new<\/b><\/span> gin::Select (p.modeParam), 1<\/span>, 0<\/span>);\r\n\u00a0 \u00a0 <\/span>addControl (new<\/b><\/span> gin::Knob (p.levelParam), 2<\/span>, 0<\/span>);\r\n\u00a0 \u00a0 <\/span>addControl (new<\/b><\/span> gin::Knob (p.panParam, true<\/b><\/span>), 3<\/span>, 0<\/span>);\r\n\u00a0 \u00a0 <\/span>addControl (new<\/b><\/span> gin::Switch (p.invertParam), 4<\/span>, 0<\/span>);<\/pre>\n
Gin provides 3 basic controls. Select, based on a ComboBox. Knob, based on a rotary slider, and Switch, based on a toggle button. Add the to the UI with their grid position and Gin will handle updating them when their parameter changes and deleting them when the editor closes.<\/p>\n
The UI will look like this. Preset browser, preset load and save are all built in.<\/p>\n
<\/p>\n
Next Steps<\/h3>\n
If your plugin requires more state than just parameters, it can be saved in juce::ValueTree gin::Processor::state<\/strong>. Override the functions stateUpdated<\/strong> and updateState<\/strong> if you need to copy variables to \/ from the ValueTree.<\/p>\n
Create your own look and feel based on gin::CopperLookAndFeel\u00a0<\/strong>so that your plugins don’t look like my plugins.<\/p>\n
If the grid based layout is too restrictive, see the gin::Layout<\/strong> class to layout your components with json.<\/p>\n
If you have presets, add them to the plugin as binary resources. Then extract them in your constructor if the y don’t already exist.<\/p>\n
\u00a0 \u00a0 \u00a0 \u00a0 <\/span>auto<\/b><\/span> sz = 0<\/span>;\r\n\u00a0 \u00a0 \u00a0 \u00a0 <\/span>for<\/b><\/span> (auto<\/b><\/span> i = 0<\/span>; i < BinaryData<\/span>::namedResourceListSize<\/span>; i++)\r\n\u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 <\/span>if<\/b><\/span> (juce<\/span>::String<\/span> (BinaryData<\/span>::originalFilenames<\/span>[i]).endsWith<\/span> (\".xml\"<\/span>))\r\n\u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 <\/span>if<\/b><\/span> (auto<\/b><\/span> data = BinaryData<\/span>::getNamedResource<\/span> (BinaryData<\/span>::namedResourceList<\/span>[i], sz))\r\n\u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 <\/span>extractProgram<\/span> (BinaryData<\/span>::originalFilenames<\/span>[i], data, sz);<\/pre>\n
Conclusion<\/h3>\n
You now have a full featured plugin with almost no code at all.<\/p>\n","protected":false},"excerpt":{"rendered":"
Introduction Creating a plugin with Gin & JUCE is a lot fast than with JUCE alone. A lot a boiler plate is handled for you, which lets you focus on getting your DSP working. This tutorial explains the code in the Gin example Effect plugin which is a simple gain and pan plugin. A basic… 
 Read more<\/a><\/p>\n","protected":false},"author":1,"featured_media":100,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[8,6,7],"tags":[5,4,3],"class_list":["post-99","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-dsp","category-gin","category-programming","tag-dsp","tag-gin","tag-juce"],"_links":{"self":[{"href":"https:\/\/rabiensoftware.com\/index.php\/wp-json\/wp\/v2\/posts\/99","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/rabiensoftware.com\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/rabiensoftware.com\/index.php\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/rabiensoftware.com\/index.php\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/rabiensoftware.com\/index.php\/wp-json\/wp\/v2\/comments?post=99"}],"version-history":[{"count":1,"href":"https:\/\/rabiensoftware.com\/index.php\/wp-json\/wp\/v2\/posts\/99\/revisions"}],"predecessor-version":[{"id":101,"href":"https:\/\/rabiensoftware.com\/index.php\/wp-json\/wp\/v2\/posts\/99\/revisions\/101"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/rabiensoftware.com\/index.php\/wp-json\/wp\/v2\/media\/100"}],"wp:attachment":[{"href":"https:\/\/rabiensoftware.com\/index.php\/wp-json\/wp\/v2\/media?parent=99"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/rabiensoftware.com\/index.php\/wp-json\/wp\/v2\/categories?post=99"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/rabiensoftware.com\/index.php\/wp-json\/wp\/v2\/tags?post=99"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}