Merge pull request #56 from open-audio-stack/feature/effect-instrument-categories

Derive plugin categories from VST3 SDK

Author: kmturley

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-audio-stack/core",
-  "version": "0.1.47",
+  "version": "0.1.48",
   "description": "Open-source audio plugin management software",
   "type": "module",
   "main": "./build/index.js",

package.json

@@ -1,19 +1,44 @@
+/**
+ * Plugin categories are derived from the official Steinberg VST3 Plug-in
+ * Type definitions (plugType) provided by the VST3 SDK.
+ *
+ * The VST3 SDK defines a large set of hierarchical category strings
+ * (e.g. "Fx|Dynamics", "Fx|EQ", "Instrument|Synth") which serve multiple
+ * purposes including host routing, UI grouping, and capability flags.
+ *
+ * This project intentionally normalizes and consolidates those categories
+ * into a smaller, format-agnostic set suitable for a plugin registry and
+ * tagging system. Not all VST3 plugType values map 1:1 to public categories.
+ *
+ * Authoritative source (VST3 SDK):
+ * https://steinbergmedia.github.io/vst3_doc/vstinterfaces/group__plugType.html
+ */
+
 export enum PluginCategoryEffect {
-  Chorus = 'chorus',
-  Compression = 'compression',
+  Delay = 'delay',
+  Distortion = 'distortion',
+  Dynamics = 'dynamics',
   Eq = 'eq',
   Filter = 'filter',
+  Modulation = 'modulation',
+  Pitch = 'pitch',
   Reverb = 'reverb',
+  Spatial = 'spatial',
+  Utility = 'utility',
 }
 
 export enum PluginCategoryInstrument {
-  Drums = 'drums',
+  Bass = 'bass',
+  Brass = 'brass',
+  Drum = 'drum',
+  Fx = 'fx',
   Guitar = 'guitar',
-  Keys = 'keys',
-  Orchestral = 'orchestral',
-  Samplers = 'samplers',
-  Synths = 'synths',
-  Vocals = 'vocals',
+  Piano = 'piano',
+  Sampler = 'sampler',
+  Strings = 'strings',
+  Synth = 'synth',
+  Voice = 'voice',
+  Woodwinds = 'woodwinds',
 }
 
 export interface PluginCategoryOption {
@@ -25,78 +50,132 @@ export interface PluginCategoryOption {
 
 export const pluginCategoryEffects: PluginCategoryOption[] = [
   {
-    description: 'Spatial movement and modulation.',
-    value: PluginCategoryEffect.Chorus,
-    name: 'Chorus/Phaser',
-    tags: ['Chorus', 'Phaser'],
+    name: 'Delay',
+    value: PluginCategoryEffect.Delay,
+    description: 'Echoes and rhythmic repeats.',
+    tags: ['Delay', 'Echo', 'Tape Delay', 'Ping Pong Delay', 'Multi-Tap Delay'],
+  },
+  {
+    name: 'Distortion',
+    value: PluginCategoryEffect.Distortion,
+    description: 'Add saturation, grit, or harmonic color.',
+    tags: ['Distortion', 'Saturation', 'Overdrive', 'Fuzz', 'Amp', 'Amplifier', 'Exciter', 'Waveshaper'],
   },
   {
-    description: 'Shape dynamics, grit and amplification.',
-    value: PluginCategoryEffect.Compression,
-    name: 'Compression/Distortion',
-    tags: ['Compression', 'Distortion', 'Amplifier', 'Amp'],
+    name: 'Dynamics',
+    value: PluginCategoryEffect.Dynamics,
+    description: 'Control dynamics and signal level.',
+    tags: ['Dynamics', 'Compressor', 'Limiter', 'Expander', 'Gate', 'Noise Gate'],
   },
   {
-    description: 'Balance frequencies and position sounds in the stereo field.',
+    name: 'EQ',
     value: PluginCategoryEffect.Eq,
-    name: 'EQ/Pan',
-    tags: ['EQ', 'Equalizer', 'Pan'],
+    description: 'Shape and balance frequency content.',
+    tags: ['EQ', 'Equalizer', 'Parametric EQ', 'Graphic EQ', 'Tone Control'],
   },
   {
-    description: 'Adjust tone and sculpt frequencies.',
-    value: PluginCategoryEffect.Filter,
     name: 'Filter',
-    tags: ['Filter'],
+    value: PluginCategoryEffect.Filter,
+    description: 'Sculpt sound using frequency filtering.',
+    tags: ['Filter', 'Lowpass', 'Highpass', 'Bandpass', 'Notch', 'Resonant', 'Auto Filter'],
+  },
+  {
+    name: 'Modulation',
+    value: PluginCategoryEffect.Modulation,
+    description: 'Create motion, width, and modulation.',
+    tags: ['Modulation', 'Chorus', 'Flanger', 'Phaser', 'Tremolo', 'Vibrato', 'Rotary', 'Ensemble'],
+  },
+  {
+    name: 'Pitch',
+    value: PluginCategoryEffect.Pitch,
+    description: 'Pitch shifting and harmonic processing.',
+    tags: ['Pitch', 'Pitch Shifter', 'Harmonizer', 'Vocoder', 'Octaver', 'Formant'],
   },
   {
-    description: 'Create depth with echoes, ambience, and space.',
+    name: 'Reverb',
     value: PluginCategoryEffect.Reverb,
-    name: 'Reverb/Delay',
-    tags: ['Reverb', 'Delay'],
+    description: 'Simulate space, depth, and ambience.',
+    tags: ['Reverb', 'Room', 'Hall', 'Plate', 'Spring', 'Convolution', 'Ambience'],
+  },
+  {
+    name: 'Spatial',
+    value: PluginCategoryEffect.Spatial,
+    description: 'Stereo positioning and spatial control.',
+    tags: ['Spatial', 'Stereo', 'Panner', 'Width', 'Imager', 'Mid/Side', 'Binaural'],
+  },
+  {
+    name: 'Utility',
+    value: PluginCategoryEffect.Utility,
+    description: 'Analysis, routing, and signal tools.',
+    tags: ['Utility', 'Gain', 'Trim', 'Analyzer', 'Meter', 'Phase', 'Mono', 'Polarity'],
   },
 ];
 
 export const pluginCategoryInstruments: PluginCategoryOption[] = [
   {
-    description: '',
-    value: PluginCategoryInstrument.Drums,
+    name: 'Bass',
+    value: PluginCategoryInstrument.Bass,
+    description: 'Bass instruments.',
+    tags: ['Bass'],
+  },
+  {
+    name: 'Brass',
+    value: PluginCategoryInstrument.Brass,
+    description: 'Brass instruments.',
+    tags: ['Brass'],
+  },
+  {
     name: 'Drums',
-    tags: ['Drums', 'Percussion'],
+    value: PluginCategoryInstrument.Drum,
+    description: 'Drum and percussion instruments.',
+    tags: ['Drums', 'Drum Kit', 'Percussion'],
+  },
+  {
+    name: 'FX Instrument',
+    value: PluginCategoryInstrument.Fx,
+    description: 'Sound-effect or experimental instruments.',
+    tags: ['FX', 'Sound Effects'],
   },
   {
-    description: '',
-    value: PluginCategoryInstrument.Guitar,
     name: 'Guitar',
-    tags: ['Guitar', 'String'],
+    value: PluginCategoryInstrument.Guitar,
+    description: 'Guitar instruments.',
+    tags: ['Guitar'],
+  },
+  {
+    name: 'Piano / Keys',
+    value: PluginCategoryInstrument.Piano,
+    description: 'Piano and keyboard instruments.',
+    tags: ['Piano', 'Keys', 'Keyboard'],
   },
   {
-    description: '',
-    value: PluginCategoryInstrument.Keys,
-    name: 'Keys',
-    tags: ['Keys', 'Piano'],
+    name: 'Sampler',
+    value: PluginCategoryInstrument.Sampler,
+    description: 'Sample-based instruments.',
+    tags: ['Sampler', 'Sample'],
   },
   {
-    description: '',
-    value: PluginCategoryInstrument.Orchestral,
-    name: 'Orchestral',
-    tags: ['Orchestral', 'Orchestra', 'Strings', 'Woodwind', 'Brass'],
+    name: 'Strings',
+    value: PluginCategoryInstrument.Strings,
+    description: 'String instruments.',
+    tags: ['Strings', 'String Ensemble'],
   },
   {
-    description: '',
-    value: PluginCategoryInstrument.Samplers,
-    name: 'Samplers',
-    tags: ['Samplers', 'Sampler', 'Sample'],
+    name: 'Synth',
+    value: PluginCategoryInstrument.Synth,
+    description: 'Sound synthesis instruments.',
+    tags: ['Synth', 'Synthesizer'],
   },
   {
-    description: '',
-    value: PluginCategoryInstrument.Synths,
-    name: 'Synths',
-    tags: ['Synths', 'Synth', 'Synthesizer'],
+    name: 'Voice',
+    value: PluginCategoryInstrument.Voice,
+    description: 'Vocal and choir instruments.',
+    tags: ['Voice', 'Vocal', 'Choir'],
   },
   {
-    description: '',
-    value: PluginCategoryInstrument.Vocals,
-    name: 'Vocals',
-    tags: ['Vocals'],
+    name: 'Woodwinds',
+    value: PluginCategoryInstrument.Woodwinds,
+    description: 'Woodwind instruments.',
+    tags: ['Woodwinds'],
   },
 ];

src/types/PluginCategory.ts

@@ -83,7 +83,7 @@ test('Get licenses', () => {
 
 test('Get plugin category effect', () => {
   const config: Config = new Config();
-  expect(config.pluginCategoryEffect(PluginCategoryEffect.Compression)).toEqual(pluginCategoryEffects[1]);
+  expect(config.pluginCategoryEffect(PluginCategoryEffect.Distortion)).toEqual(pluginCategoryEffects[1]);
 });
 
 test('Get plugin category effects', () => {
@@ -93,7 +93,7 @@ test('Get plugin category effects', () => {
 
 test('Get plugin category instrument', () => {
   const config: Config = new Config();
-  expect(config.pluginCategoryInstrument(PluginCategoryInstrument.Guitar)).toEqual(pluginCategoryInstruments[1]);
+  expect(config.pluginCategoryInstrument(PluginCategoryInstrument.Brass)).toEqual(pluginCategoryInstruments[1]);
 });
 
 test('Get plugin category instruments', () => {