@elemaudio/plugin-renderer - npm Package Compare versions

Comparing version 1.0.1 to 1.0.2

package.json

 {
   "name": "@elemaudio/plugin-renderer",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "type": "module",
@@ -37,3 +37,3 @@ "description": "Official package for rendering Elementary Audio applications in the Plugin Dev Kit",
   },
-  "gitHead": "cad6ad54b75658d18e20b3cb18878e7e4a2044dd"
+  "gitHead": "ed7cd35997c91d8bf7a255f0d75e623c0138d967"
 }

README.md

@@ -85,2 +85,38 @@ # @elemaudio/plugin-renderer
 
+### dispatch
+
+```js
+core.dispatch(eventName: string, payload);
+```
+
+The `dispatch` method on the `PluginRenderer` interface is unique to Elementary's Audio Plugin runtime, and can be used
+for communicating with the underlying audio processor within the DAW. There are two supported event types that can be
+dispatched to the audio processor: `saveState`, and `setParameterValue`.
+
+#### saveState
+
+```js
+core.dispatch('saveState', JSON.stringify(myAppState));
+```
+
+See the `loadState` event description below for more information; this mechanism can be used to inform the underlying
+processor of any state that should be persisted by the audio plugin host (e.g. the DAW). This is necessary for behaviors
+like saving and loading DAW project files. The payload here should be a string, and will be relayed back to your application
+by the host via the loadState event at appropriate times.
+
+#### setParameterValue
+
+```js
+core.dispatch('setParameterValue', parameterName, newValue);
+```
+
+The `setParameterValue` event can be dispatched to the underlying audio plugin to ask the plugin host to update a
+given parameter value. This is necessary for, say, capturing automation data in the host DAW's timeline as the user drags
+a knob in your user interface.
+
+Note: You should be careful here to ensure that your application state always reflects the values that the host knows
+for your parameters. Therefore you should think of `setParameterValue` as an opportunity for the host to perform the update,
+after which a `parameterValueChange` event will fire to inform you that the host has received your request and performed
+the update.
+
 ## Events
@@ -131,25 +167,36 @@
 
-### Event: `'/macro/\*'`
+### Event: `'parameterValueChange'`
 
-The `/macro/\*` event fires any time one of the eight macro parameter values changes
-inside the DAW itself. These events will be enumerated by the index of the parameter changed. That is,
-when the first parameter is changed the event name will be `'/macro/0'`, when the second parameter is
-changed, the event name will be `'/macro/1'`, etc.
+The `parameterValueChange` event fires any time one of the eight macro parameter values changes
+inside the DAW itself. The associated event object passed to your callback will specify the ID of the
+parameter whose value has changed, and the new value given. The new value given will be a number on
+the range [0, 1].
 
-The argument given to any subscribed callbacks will simply be the new parameter value
-as a number on the range [0, 1].
+Example:
 
+```js
+core.on('parameterValueChange', function(e) {
+  console.log(e.paramId); // e.g. "/macro/1"
+  console.log(e.value); // e.g. 0.193149
+});
+```
+
+### Event: `'loadState'`
+
+The loadState event fires any time the plugin host (e.g. the DAW) is attempting to assign new state
+to the plugin. This could be, for example, upon loading a saved project file: the DAW will open the
+plugin in its default state, and then send the loadState event with the relevant state for the saved
+project.
+
+The event object contains a single `value` property, which is a string carrying any information you may
+have requested to be saved using the `core.dispatch('saveState')` mechanism.
+
 Example:
 
 ```js
-core.on('/macro/5', function(v) {
-  setCutoffFrequency(20 + v * 18000);
+core.on('loadState', function(e) {
+  console.log(JSON.parse(e.value));
 });
 ```
 
-:::info
-Note: currently these 8 parameter values cannot be written from JavaScript. This will
-be addressed in a forthcoming update.
-:::
-
 ### Event: `'playhead'`
@@ -156,0 +203,0 @@

New alerts

Native code

Supply chain risk

Contains native code (e.g., compiled binaries or shared libraries). Including native code can obscure malicious behavior.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

20370906

increased by75746.7%

Number of package files

19

increased by216.67%

Number of lines in readme file

264

increased by21.66%

Worsened metrics

Number of medium supply chain risk alerts

2

increased byInfinity%

No dependency changes