Skip to main content

Migrating to v1.0

The path from v0.11.x to v1.0.0 brought about a small set of breaking changes that were necessary for the stabilization of the Elementary core API. Here we enumerate each breaking change and provide suggestions for updating your code.

Distinct Renderer Packages​

Before v1.0, Elementary shipped only an @elemaudio/core and @elemaudio/core-lite package, each of which provided the supported renderers in their exports. This was convenient initially, but became an issue which yielded package bloat, increased complexity when trying to update one renderer in isolation, and encouraged coupling.

As of v1.0 each renderer is available in its own package, as detailed in the Packages section on the sidebar.

// Old:
import {el, ElementaryPluginRenderer} from '@elemaudio/core';

// New:
import {el} from '@elemaudio/core';
import PluginRenderer from '@elemaudio/plugin-renderer';

// Or:
import {el} from '@elemaudio/core';
import {default as core} from '@elemaudio/plugin-renderer';

You'll notice as well that the @elemaudio/web-renderer and @elemaudio/offline-renderer packages no longer export singleton renderer instances, they now export class constructors, allowing multiple instances running in parallel. This pattern is one we aim to gradually adopt in the Node.js renderer and Plugin renderer in future updates.

// Old:
import {ElementaryWebAudioRenderer as core} from '@elemaudio/core';

core.initialize(...);
core.render(...);

// New:
import WebRenderer from '@elemaudio/web-renderer';

let core = new WebRenderer();

core.initialize(...);
core.render(...);

Explicit trailing arguments​

As part of the move to support strong TypeScript definitions on the core library functions, the following nodes were changed to now explicitly require all trailing arguments in their invocations.

  • el.sample
  • el.seq
  • el.seq2
  • el.phasor

In each of these cases, the last argument is for reset behavior. If you still don't need reset behavior, you can simply place a constant value 0 in the argument array.

// Old:
el.phasor(440);
el.seq({seq: [1, 2, 3]}, el.train(1));

// New:
el.phasor(440, 0);
el.seq({seq: [1, 2, 3]}, el.train(1), 0);

Removed the explicit memo API​

Before v1.0, memoization for composite nodes required an explicit wrapper. This API has been removed as it is no longer needed; memoization for composite nodes now happens automatically. See Understanding Memoization for details.

Removed the sugar API​

Similar to the above change, the "sugar" API of v0.11.x has been removed in favor of a more clear and consistent API. In almost all cases, the sugar API was only relevant for composite nodes in the first place. Now that the composite node API and memoization have changed, this API is much less helpful. See Understanding Memoization for more details.

Removed el.freeverb​

In an effort to consolidate the core library around a better standard for the library API, el.freeverb has been removed. The original library code is available here on GitHub and you're invited to use it freely in your own applications. When using this algorithm you're strongly encouraged to think about keys and memoization and how you can standardize the Freeverb API within the context of your own app.