Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →
@elemaudio/plugin-renderer
Advanced tools
@elemaudio/plugin-renderer - npm Package Compare versions
Comparing version 1.0.13 to 1.0.14
| { | ||
| "name": "@elemaudio/plugin-renderer", | ||
| "version": "1.0.13", | ||
| "version": "1.0.14", | ||
| "type": "module", | ||
@@ -40,3 +40,3 @@ "description": "Official package for rendering Elementary Audio applications in the Plugin Dev Kit", | ||
| }, | ||
| "gitHead": "0a2a77fcd36fdc641d32944b37d1d77b67daba03" | ||
| "gitHead": "1c88229e9f1a67b2cd911a5b231d227e3ecfb48e" | ||
| } |
167
README.md
@@ -5,7 +5,7 @@ # @elemaudio/plugin-renderer | ||
| Applications using this renderer must be run from within the Elementary Plugin Dev Kit, which | ||
| is a native audio plugin in VST3 and AU formats, **currently only supported on MacOS 10.11+**. | ||
| Applications using this renderer must be run from within the Elementary Plugin Dev Kit, a separate | ||
| audio plugin distributed with the npm package in VST3/AU formats, and supported only on the following platforms: | ||
| This package will be used alongside `@elemaudio/core`. Please see the full | ||
| documentation at [https://www.elementary.audio/docs](https://www.elementary.audio/docs) | ||
| * macOS 10.11+ | ||
| * Windows 10+ | ||
@@ -30,4 +30,3 @@ ## Installation | ||
| Finally, the audio plugin will look at `https://127.0.0.1:3000` to load your application, so you'll need to spin | ||
| up your server before proceeding. You may also direct the plugin harness to load your app from a different URL if you need, | ||
| such as for testing from a deployed server instance. For a quick example, try `create-react-app` out of the box. See the note below | ||
| up your server before proceeding. For a quick example, try `create-react-app` out of the box. See the note below | ||
| on provisioning a dev certificate for serving your app over https. | ||
@@ -112,3 +111,3 @@ | ||
| ```js | ||
| core.dispatch('setParameterValue', parameterName, newValue); | ||
| core.dispatch('setParameterValue', {name: parameterName, value: newValue}); | ||
| ``` | ||
@@ -125,5 +124,13 @@ | ||
| #### resize | ||
| ```js | ||
| core.dispatch('resize', {width: 500, height: 500}); | ||
| ``` | ||
| Sends a request to the underlying plugin host to update the window size holding the plugin editor. | ||
| ## Events | ||
| The `NodeRenderer` singleton instance is an event emitter with an API matching that of the [Node.js Event Emitter](https://nodejs.org/api/events.html#class-eventemitter) | ||
| The `PluginRenderer` singleton instance is an event emitter with an API matching that of the [Node.js Event Emitter](https://nodejs.org/api/events.html#class-eventemitter) | ||
| class. | ||
@@ -134,42 +141,5 @@ | ||
| ## Virtual File System | ||
| ### `'parameterValueChange'` | ||
| Unlike the [Web Renderer](./web-renderer.md) and the [Offline Renderer](./offline-renderer.md), the Elementary runtime in the | ||
| Plugin Renderer does have access to your file system. Therefore when you try to reference sample files during your render step, such as | ||
| with `el.sample({path: '/real/path/on/disk.wav'}, el.train(1), 1)`, Elementary will attempt to find and load that file from your | ||
| file system. | ||
| Currently, only wav files are supported for this file loading mechanism. | ||
| :::info | ||
| In a near future update, the PluginRenderer will move to using a virtual file system like the Web and Offline renderers. | ||
| At that time, loading directly from disk during `render()` will be deprecated. | ||
| ::: | ||
| ## MIDI | ||
| The PluginRenderer does not include MIDI support itself. | ||
| ## Dev SSL Certificate | ||
| One thing to note, in order for the Plugin Dev Kit to load from 127.0.0.1, we need to equip the dev | ||
| server with a valid SSL certificate to serve over https. There are various ways of doing this depending | ||
| on which framework you're using. For example, `create-react-app` can be invoked with an `HTTPS=true` environment | ||
| variable, and a custom SSL certificate using `SSL_CRT_FILE` and `SSL_KEY_FILE`. | ||
| ```bash | ||
| $ BROWSER=false HTTPS=true SSL_CRT_FILE=./localhost-cert.pem SSL_KEY_FILE=./localhost-key.pem npm start | ||
| ``` | ||
| To generate a valid, custom SSL certificate, we recommend [mkcert](https://github.com/FiloSottile/mkcert) configured | ||
| against a local certificate authority. | ||
| ## Specialization | ||
| There are a few features of the `PluginRenderer` that are unique to the audio | ||
| plugin context. | ||
| ### Event: `'parameterValueChange'` | ||
| The `parameterValueChange` event fires any time one of the eight macro parameter values changes | ||
| The `parameterValueChange` event fires any time one of your parameter values changes | ||
| inside the DAW itself. The associated event object passed to your callback will specify the ID of the | ||
@@ -183,3 +153,3 @@ parameter whose value has changed, and the new value given. The new value given will be a number on | ||
| core.on('parameterValueChange', function(e) { | ||
| console.log(e.paramId); // e.g. "/macro/1" | ||
| console.log(e.paramId); // e.g. "feedback" | ||
| console.log(e.value); // e.g. 0.193149 | ||
@@ -189,3 +159,3 @@ }); | ||
| ### Event: `'loadState'` | ||
| ### `'loadState'` | ||
@@ -208,3 +178,3 @@ The loadState event fires any time the plugin host (e.g. the DAW) is attempting to assign new state | ||
| ### Event: `'playhead'` | ||
| ### `'playhead'` | ||
@@ -236,12 +206,78 @@ The playhead event fires regularly to relay information about the host transport. | ||
| ## Virtual File System | ||
| ### Window Size | ||
| Unlike the [Web Renderer](./web-renderer.md) and the [Offline Renderer](./offline-renderer.md), the Elementary runtime in the | ||
| Plugin Renderer does have access to your file system. Therefore when you try to reference sample files during your render step, such as | ||
| with `el.sample({path: '/real/path/on/disk.wav'}, el.train(1), 1)`, Elementary will attempt to find and load that file from your | ||
| file system. | ||
| You can configure what size the plugin window takes by serving a static configuration file | ||
| from your dev server at `https://127.0.0.1:3000/elementary.config.json`. This file must match | ||
| the example JSON specification below. | ||
| Currently, only wav files are supported for this file loading mechanism. | ||
| :::info | ||
| In a near future update, the PluginRenderer will move to using a virtual file system like the Web and Offline renderers. | ||
| At that time, loading directly from disk during `render()` will be deprecated. | ||
| ::: | ||
| ## MIDI | ||
| The PluginRenderer does not include MIDI support itself. | ||
| ## Dev SSL Certificate | ||
| One thing to note, in order for the Plugin Dev Kit to load from 127.0.0.1, we need to equip the dev | ||
| server with a valid SSL certificate to serve over https. There are various ways of doing this depending | ||
| on which framework you're using. For example, `create-react-app` can be invoked with an `HTTPS=true` environment | ||
| variable, and a custom SSL certificate using `SSL_CRT_FILE` and `SSL_KEY_FILE`. | ||
| ```bash | ||
| $ BROWSER=false HTTPS=true SSL_CRT_FILE=./localhost-cert.pem SSL_KEY_FILE=./localhost-key.pem npm start | ||
| ``` | ||
| To generate a valid, custom SSL certificate, we recommend [mkcert](https://github.com/FiloSottile/mkcert) configured | ||
| against a local certificate authority. | ||
| ## Configuration | ||
| When the Plugin Dev Kit loads inside its host, it will first try to reach `https://127.0.0.1:3000/elementary.config.json` | ||
| to retrieve a static JSON payload with configuration settings. An example configuration file is below. | ||
| ```json | ||
| { | ||
| "displayName": "BigDelay", | ||
| "company": "My Company", | ||
| "bundleId": "com.mycompany.bigdelay", | ||
| "version": "1.0.0", | ||
| "manufacturerCode": "MyCo", | ||
| "pluginCode": "BgDe", | ||
| "numInputChannels": 2, | ||
| "numOutputChannels": 2, | ||
| "window": { | ||
| "width": 753, | ||
| "height": 373, | ||
| "showToolbar": false | ||
| }, | ||
| "parameters": [ | ||
| { "paramId": "mix", "name": "Mix", "min": 0.0, "max": 1.0, "defaultValue": 1.0 }, | ||
| { "paramId": "size", "name": "Size", "min": 0.0, "max": 1.0, "defaultValue": 0.5 }, | ||
| { "paramId": "lowCut", "name": "Lo-Cut", "min": 0.0, "max": 1.0, "defaultValue": 0.0 }, | ||
| { "paramId": "highCut", "name": "Hi-Cut", "min": 0.0, "max": 1.0, "defaultValue": 1.0 } | ||
| ] | ||
| } | ||
| ``` | ||
| ### Parameters | ||
| Note in the above example file: the `parameters` property is an array which can be populated with | ||
| as many parameters as you need. You must specify a `paramId`, `name`, `min`, `max` and `defaultValue` property | ||
| for each given parameter in the list. | ||
| ### Window Size & Toolbar | ||
| By default, the Elementary Plugin Dev Kit will display a small pink toolbar with a window resizing handle. | ||
| You can disable this toolbar by setting `showToolbar` false within the `window` property as in the example above. | ||
| Window size and the available range for resizing can be configured using the following settings. | ||
| ```json | ||
| { | ||
| "window": { | ||
| "width": 565, | ||
@@ -252,5 +288,3 @@ "height": 280, | ||
| "minWidth": 565, | ||
| "minHeight": 280, | ||
| "resizable": true, | ||
| "preserveAspectRatio": true | ||
| "minHeight": 280 | ||
| } | ||
@@ -260,2 +294,14 @@ } | ||
| ## Remote Configuration | ||
| Finally, you can configure the Elementary Plugin Dev Kit to point to a URL _other_ than `localhost:3000` by providing | ||
| a separate configuration file at `~/.ElementaryDevKitRemoteConfig.json`. This file may be used to provide a single `url` | ||
| property directing the plugin where to connect to load your resources. Example: | ||
| ```json | ||
| { | ||
| "url": "https://bigdelay.mycompany.com/static/" | ||
| } | ||
| ``` | ||
| ## Limitations | ||
@@ -265,6 +311,3 @@ | ||
| * It's currently MacOS only, 10.11+. | ||
| * It's branded the "Elementary Dev Kit" and will show up in your DAW that way | ||
| * It only exposes 8 parameters (which you can wire into your app, see below) | ||
| * It will only load your code from `https://127.0.0.1:3000` | ||
| * MacOS 10.11+ and Windows 10+ | ||
| * Only effect plugins are properly supported (MIDI information is not yet propagated) | ||
@@ -274,4 +317,4 @@ | ||
| In a near future update, we will formalize the process for shipping a production version of your plugin after building with the | ||
| Plugin Dev Kit. That process will remove the above limitations. | ||
| Plugin Dev Kit. | ||
| ::: | ||
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
New alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Fixed alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Improved metrics
- Total package byte prevSize
- increased by0.14%
13505638
- Number of lines in readme file
- increased by16.23%
308
No dependency changes