Elementary Audio

https://www.elementary.audio/docs
Admin
Elementary Audio is a high-performance framework for real-time audio synthesis and processing,...
Tokens:26,472
Snippets:211
Trust Score:7.4
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install @elemaudio/web-renderer

Source: https://www.elementary.audio/docs/packages/web-renderer

Installs the @elemaudio/web-renderer package using npm. This is the first step to using the library in your web project.

```bash
npm install --save @elemaudio/web-renderer
```

--------------------------------

### Install @elemaudio/core

Source: https://www.elementary.audio/docs/packages/core

Installs the core Elementary Audio package using npm. This is the first step to using the library in your project.

```bash
npm install --save @elemaudio/core
```

--------------------------------

### Initializing MIDI and Audio Engine

Source: https://www.elementary.audio/docs/tutorials/web-midi

This asynchronous function initializes the MIDI and audio engine components. It's designed to be called upon user interaction, such as clicking a 'Get Started' button. Initialization ensures that the necessary audio and MIDI functionalities are ready to be used.

```javascript
async function getStarted() {
  await midi.initialize(displayControllers);
  await engine.initialize();
  ui.getStarted();
}
```

--------------------------------

### Initialize and Render Basic Audio Graph with Elementary

Source: https://www.elementary.audio/docs/in_depth

This snippet demonstrates the basic setup for an Elementary Audio application. It initializes the core renderer, defines a simple audio graph using `el.cycle` and `el.mul`, and then renders it. This serves as a foundational example for creating sound with Elementary.

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

core.on('load', function(e) {
  let x = el.cycle(440);
  let y = el.cycle(220);
  let z = el.mul(x, y);

  core.render(z, z);
});

core.initialize();
```

--------------------------------

### C++ Example Usage

Source: https://www.elementary.audio/docs/guides/Native_Integrations

A C++ example demonstrating the integration of the Elementary Audio runtime with an embedded JavaScript engine (Quickjs).

```APIDOC
## C++ Example Usage

### Description
This example shows a basic C++ program that initializes the `elem::Runtime`, sets up communication with an embedded JavaScript engine (Quickjs), evaluates JavaScript code, and processes audio blocks.

### Code Example:

```cpp
#include <Runtime.h>
#include <quickjs.h>
#include <quickjs_utils.h>

int main(int argc, char** argv) {
    // 1. Create the Runtime instance
    elem::Runtime<float> runtime(44100.0, 512);

    // 2. Set up a message passing interface (using Quickjs)
    auto ctx = choc::javascript::createQuickJSContext();

    // Register a native interop method to receive instructions from JavaScript
    ctx.registerFunction("__postInstructions__", [&](choc::javascript::ArgumentList args) {
        // Assuming instructions are JSON-stringified before calling this native method
        runtime.applyInstructions(elem::js::parseJSON(args[0]->toString()));
        return choc::value::Value(); // Return value is not used in this example
    });

    // 3. Evaluate JavaScript containing Elementary frontend code
    // Replace 'inputFileContents' with actual JavaScript code or file content
    auto rv = ctx.evaluate("// Your JavaScript code here...");

    // 4. Process audio data on the main thread
    // Replace inputBufferData, numInputChannels, outputBufferData, numOutputChannels, blockSize with actual values
    // Ensure inputBufferData and outputBufferData are allocated and have correct dimensions.
    const float* inputBufferData[1]; // Example: 1 input channel
    const float* outputBufferData[1]; // Example: 1 output channel
    size_t numInputChannels = 1;
    size_t numOutputChannels = 1;
    size_t blockSize = 512;

    runtime.process(
        inputBufferData,
        numInputChannels,
        outputBufferData as float**, // Cast needed if outputBufferData is float*
        numOutputChannels,
        blockSize,
        nullptr // userData
    );

    return 0;
}
```

**Note:** This example is based on the command-line tool found in the Elementary Audio GitHub repository.
```

--------------------------------

### Basic Offline Rendering Example

Source: https://www.elementary.audio/docs/packages/offline-renderer

Demonstrates how to initialize the OfflineRenderer, configure its settings, define input and output buffers, and process audio using a simple cycle node. This example shows the core workflow for offline audio processing.

```javascript
import {el} from '@elemaudio/core';
import OfflineRenderer from '@elemaudio/offline-renderer';

(async function main() {
  let core = new OfflineRenderer();

  await core.initialize({
    numInputChannels: 0,
    numOutputChannels: 1,
    sampleRate: 44100,
  });

  let inps = [];
  let outs = [new Float32Array(44100 * 10)]; 

  core.render(el.cycle(440));

  core.process(inps, outs);
})();
```

--------------------------------

### Basic Web Audio Rendering Example

Source: https://www.elementary.audio/docs/packages/web-renderer

Demonstrates how to initialize the WebRenderer with an AudioContext, connect it to the audio destination, and render a simple audio graph using Elementary core functions. It shows the typical workflow for audio processing in the browser.

```javascript
import {el} from '@elemaudio/core';
import WebRenderer from '@elemaudio/web-renderer';

const ctx = new AudioContext();
const core = new WebRenderer();

(async function main() {
  let node = await core.initialize(ctx, {
    numberOfInputs: 0,
    numberOfOutputs: 1,
    outputChannelCount: [2],
  });

  node.connect(ctx.destination);

  let stats = await core.render(el.cycle(440), el.cycle(441));
  console.log(stats);
})();
```

--------------------------------

### C++ Example: Elementary Runtime Integration with JavaScript

Source: https://www.elementary.audio/docs/guides/Native_Integrations

Demonstrates a C++ program that initializes the Elementary `Runtime`, sets up a JavaScript context with QuickJS, registers a native interop function for receiving instructions from JavaScript, evaluates JavaScript code, and processes audio blocks. It highlights the core steps for integrating native audio processing with a JavaScript frontend.

```cpp
#include <Runtime.h>
 

int main(int argc, char** argv) {
    elem::Runtime<float> runtime(44100.0, 512);
 
    auto ctx = choc::javascript::createQuickJSContext();
 
    ctx.registerFunction("__postInstructions__", [&](choc::javascript::ArgumentList args) {
        // Imagining here that we've JSON-stringified the instructions before calling into
        // this native interop method, so we must parse the instruction set from JSON before applying.
        runtime.applyInstructions(elem::js::parseJSON(args[0]->toString()));
        return choc::value::Value();
    });
 
    // Now that we have the message passing set up, we can evaluate our JavaScript containing the
    // Elementary frontend code
    auto rv = ctx.evaluate(inputFileContents);
 
    // And finally we can process some audio data
    runtime.process(
        inputBufferData,
        numInputChannels,
        outputBufferData,
        numOutputChannels,
        blockSize,
        nullptr, // userData
    );
 
    return 0;
}
```

--------------------------------

### Install @elemaudio/offline-renderer

Source: https://www.elementary.audio/docs/packages/offline-renderer

Install the offline-renderer package using npm. This is a necessary step before using the package in your project.

```bash
npm install --save @elemaudio/offline-renderer
```

--------------------------------

### Example Voice State - JavaScript

Source: https://www.elementary.audio/docs/guides/Understanding_Keys

Illustrates a possible state of the 'voices' array after processing a 'noteOn' MIDI event. This shows how gate and frequency parameters are updated for a specific voice.

```javascript
[
  {gate: 1.0, freq: 110},
  {gate: 0.0, freq: 440},
];
```

--------------------------------

### el.mm1p Filter Example

Source: https://www.elementary.audio/docs/reference/mm1p

Demonstrates how to use the el.mm1p filter in a pipeline. It includes setting a cutoff frequency with el.prewarp and routing an input signal.

```javascript
let out = el.mm1p({}, el.prewarp(800), el.in({channel: 0}));
```

--------------------------------

### el.select Usage Examples (Elementary)

Source: https://www.elementary.audio/docs/reference/select

Demonstrates the usage of the el.select function with different gate signal scenarios. It shows how to achieve direct signal selection and smooth transitions through interpolation.

```elementary
el.select(1, a, b); // Equivalent to `a`
el.select(0, a, b); // Equivalent to `b`
el.select(el.train(1), a, b); // Constantly switching between `a` and `b`
el.select(el.sm(el.train(1)), a, b); // Constantly fading between `a` and `b`
```

--------------------------------

### Dynamically Updating Virtual File System in Elementary Audio

Source: https://www.elementary.audio/docs/packages/web-renderer

Shows how to update the virtual file system after initialization using `updateVirtualFileSystem`. This example fetches an MP3 file, decodes it using the Web Audio API, and adds it to the virtual file system.

```typescript
let res = await fetch('https://ia800407.us.archive.org/9/items/999WavFiles/10.mp3');
let sampleBuffer = await ctx.decodeAudioData(await res.arrayBuffer());

core.updateVirtualFileSystem({
  '/some/new/arbitrary/fileName.wav': [
    sampleBuffer.getChannelData(0),
    sampleBuffer.getChannelData(1),
  ]
});

// In this example, after performing the update, we can now `render()` a new graph which references
// our new file data.
core.render(...el.mc.sample({path: '/some/new/arbitrary/fileName.wav', channels: 2}, el.train(1)))
```

--------------------------------

### Implement Feedback Loop with el.tapIn and el.tapOut

Source: https://www.elementary.audio/docs/reference/tapIn

Demonstrates how to use el.tapIn to create a feedback loop by connecting to a tapOut node named 'a'. This example wires an input signal, multiplies it by 0.5, adds the tapped-in signal, and then renders the result. Proper gain control is recommended to prevent instability.

```javascript
core.render(
  el.tapOut({name: 'a'},
    el.mul(
      0.5,
      el.add(
        el.in({channel: 0}),
        el.tapIn({name: 'a'})
      ),
    ),
  )
);
```

--------------------------------

### Basic el.metro Usage with train

Source: https://www.elementary.audio/docs/reference/metro

Demonstrates starting with a pulse train at 5Hz and then introducing another train at 10Hz. This example highlights unsynchronized trains due to setTimeout.

```javascript
core.on('load', function(e) {
  core.render(el.train(5));
 
  setTimeout(function() {
    core.render(el.or(el.train(10), el.train(5)));
  }, 1233);
});
```

--------------------------------

### el.sparseq Example Usage

Source: https://www.elementary.audio/docs/reference/sparseq

Demonstrates how to use el.sparseq to create a sparse sequence of values triggered by a pulse train. The sequence values and their timing are defined in the 'seq' property.

```javascript
el.sample(
  {path: '/path/to/kick.wav'},
  el.sparseq({seq: [
    { value: 1, tickTime: 0 },
    { value: 0, tickTime: 100 },
    { value: 1, tickTime: 10000 },
    { value: 0, tickTime: 10100 },
  ]}, el.train(500), 0),
  1,
)
```

--------------------------------

### Sequencing Samples with el.sample and sparseq2

Source: https://www.elementary.audio/docs/reference/sampleseq

This example demonstrates sequencing sample playback using el.sample and sparseq2. It creates a sequence of triggers and applies them to a sample. This method works well for consistent forward time but can break if the time signal jumps.

```javascript
let seq = el.sparseq2({
  seq: [
    { time: 0.0, value: 1 },
    { time: 0.5, value: 0 },
    { time: 1.0, value: 1 },
    { time: 1.5, value: 0 },
  ]
}, el.div(el.time(), el.sr()));

let sequencedSample = el.sample({path}, seq, 1);
```

--------------------------------

### Simple Feedback Loop using el.tapOut and el.tapIn

Source: https://www.elementary.audio/docs/reference/tapOut

This example demonstrates a basic feedback loop using el.tapOut to send a signal and el.tapIn to receive it. A multiplier is used to control the feedback gain. The inherent delay is determined by the engine's block size.

```javascript
let input = el.in({channel: 0});
let output = el.add(
  // Propagate the input signal and insert a tap out
  el.tapOut({name: 'a'}, input),
  // Feed the tap back in here with a 0.5 gain in the loop
  el.mul(
    0.5,
    el.tapIn({name: 'a'})
  ),
);

core.render(output);
```

--------------------------------

### Creating Signal-Driven Phasor Frequencies

Source: https://www.elementary.audio/docs/guides/Making_Sound

This section explores dynamic frequency control for the `el.phasor` operator by using other Elementary operators. Examples include slowly ramping frequency and sweeping between two frequencies.

```javascript
// Maybe slowly ramping up to 440Hz?
let tone = sineTone(el.phasor(el.mul(440, el.phasor(1))));

// Or maybe slowly ramping from 200Hz up to 640Hz?
let tone = sineTone(el.phasor(el.add(200, el.mul(440, el.phasor(1)))));

// Or maybe quickly ramping between 200Hz up to 640Hz?
let tone = sineTone(el.phasor(el.add(200, el.mul(440, el.phasor(20)))));
```

--------------------------------

### Mounting a Node Ref in the Graph

Source: https://www.elementary.audio/docs/guides/Using_Refs

Shows how to integrate a node, created via a ref, into the running audio graph using `core.render`. This example renders a low-pass filter using the previously defined cutoff ref.

```javascript
// A very simple graph running a lowpass filter over the input signal
core.render(el.lowpass(cutoff, 1.0, el.in({channel: 0})));
```

--------------------------------

### Get MIDI Input Device Names

Source: https://www.elementary.audio/docs/tutorials/web-midi

A private helper method to retrieve an array of names for all currently connected MIDI input devices using WEBMIDI.js.

```javascript
#getInputNames() {
  return WebMidi.inputs.map((input) => input.name);
}
```

--------------------------------

### Create and Add Audio Buffer Resource (C++)

Source: https://www.elementary.audio/docs/guides/Native_Integrations

Example demonstrating how to create a custom `AudioBufferResource` and add it to the runtime's shared resource map. This is useful for providing custom audio data to nodes.

```C++
auto resource = std::make_unique<elem::AudioBufferResource>(audioChannelData, numChannels, numSamples);
auto result = runtime->addSharedResource(name, std::move(resource));
```

--------------------------------

### Virtual File System: Dynamic Update

Source: https://www.elementary.audio/docs/packages/offline-renderer

Dynamically updates the virtual file system after the core has been initialized. This allows new sample data to be loaded at runtime using `updateVirtualFileSystem`. The example shows initialization, processing, updating the file system, and then rendering a new graph that uses the updated data.

```typescript
await core.initialize({
  numInputChannels: 0,
  numOutputChannels: 1,
});

let inps = [];
let outs = [new Float32Array(44100 * 10)]; // 10 seconds of output data

// Render our processing graph
core.render(el.cycle(440));

// Pushing samples through the graph. After this call, the buffer in `outs` will
// have the desired output data which can then be saved to file if you like.
core.process(inps, outs);

// Perhaps now we have some new sample data that needs to be loaded, maybe in response
// to an HTTP request (though admittedly it might be both easier and better to just make
// a new OfflineRenderer if you're doing something like HTTP request handling!)
core.updateVirtualFileSystem({
  '/some/new/arbitrary/fileName.wav': myNewSampleData,
});

// In this example, after performing the update, we can now `render()` a new graph which references
// our new file data.
core.render(el.sample({path: '/some/new/arbitrary/fileName.wav'}, el.train(1)))

// Process again; this will overwrite what's already in `out`
core.process(inps, outs);
```

--------------------------------

### el.meter Usage Example with Event Handling

Source: https://www.elementary.audio/docs/reference/meter

Demonstrates how to use the el.meter node to analyze audio signals and handle the emitted meter events. The 'name' property is used to differentiate between meters, and the event's 'source' property reflects this name.

```javascript
core.render(
  el.meter({name: 'left'}, el.cycle(440)),
  el.meter({name: 'right'}, el.cycle(441))
);

core.on('meter', function(e) {
  if (e.source === 'left') {
    handleLeftPeakValue(e.max);
  }
  if (e.source === 'right') {
    handleRightPeakValue(e.max);
  }
});
```

--------------------------------

### Sequencing Samples with el.sampleseq

Source: https://www.elementary.audio/docs/reference/sampleseq

This example shows how to use el.sampleseq to sequence sample playback. It merges the sequencing logic into a single node, allowing it to correctly handle time jumps by repositioning the playhead within the sample buffer. It requires a sequence, sample path, duration, and a time input.

```javascript
let sequencedSample = el.sampleseq({
  seq: [
    { time: 0.0, value: 1 },
    { time: 0.5, value: 0 },
    { time: 1.0, value: 1 },
    { time: 1.5, value: 0 },
  ],
  path,
  duration: 4,
}, el.div(el.time(), el.sr()));
```

--------------------------------

### Garbage Collection Coordination (JavaScript)

Source: https://www.elementary.audio/docs/guides/Native_Integrations

Example demonstrating how to coordinate garbage collection between a native C++ `gc()` call and a JavaScript `prune()` call on the renderer. This ensures the renderer and runtime remain in sync after memory cleanup.

```JavaScript
class OfflineRenderer {
  // ... omitted

  gc() {
    let pruned = this._native.gc();
    this._renderer.prune(pruned);
    return pruned;
  }

  // ... omitted
}
```

--------------------------------

### Compress Drum Bus with el.skcompress

Source: https://www.elementary.audio/docs/reference/skcompress

This example demonstrates how to compress a drum bus using the el.skcompress function. The drum bus signal is used for both the sidechain and the input signal to be compressed, achieving standard compressor behavior. Key parameters include attack time (10ms), release time (100ms), threshold (-48dB), ratio (4:1), and knee width (10dB).

```javascript
let drumBus = el.add(kick, hat, snare, cymbals);

// Compress the drumBus directly by passing it both as the sidechain
// signal and as the signal to filter
let out = el.skcompress(10, 100, -48, 4, 10, drumBus, drumBus);
```

--------------------------------

### Dynamically Update Audio Graph Based on UI Input

Source: https://www.elementary.audio/docs/in_depth

This example shows how to dynamically update an Elementary Audio graph in response to user input, such as a slider change. It illustrates mapping a UI value to audio parameters (like amplitude modulation frequency) and re-rendering the graph with `core.render()`. This highlights Elementary's ability to handle real-time changes.

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

// A hypothetical event listener for input from a slider on the UI
mySlider.on('change', function(e) {
  // Let's assume that the event object here roughly matches the event object of an HTML Range input,
  // and that the slider value ranges from [0, 1]
  let newSliderValue = parseFloat(e.target.value);

  // Now maybe we want that [0, 1] range to map from [10, 1000] to represent our
  // amplitude modulation frequency.
  let x = el.cycle(440);
  let y = el.cycle(el.const({key: 'ampModFreq', value: 10 + newSliderValue * 9990}));
  let z = el.mul(x, y);

  core.render(z, z);
});

core.initialize();
```

--------------------------------

### Importing and Instantiating Audio/MIDI Components

Source: https://www.elementary.audio/docs/tutorials/web-midi

This code snippet imports necessary modules for UI, audio engine, MIDI handling, and synthesis. It then instantiates the Emittery, Engine, Midi, and Synth classes to set up the core components of the application. The Midi implementation is passed the noteEmitter for communication.

```javascript
import Emittery from "emittery";

import "./style.css";
import * as ui from "./ui";
import { Engine } from "./audio/engine";
import { Midi } from "./midi";
import { Synth, computeFrequency } from "./audio/synth";

const noteEmitter = new Emittery();
const engine = new Engine();
const midi = new Midi(noteEmitter);
const synth = new Synth();
```

--------------------------------

### Initialize Web Audio Engine

Source: https://www.elementary.audio/docs/tutorials/web-midi

Sets up the Web Audio context and the WebRenderer. The audio context is initially suspended and resumed upon user interaction. The WebRenderer is configured for zero inputs and a mono output, then connected to the audio context's destination.

```javascript
import WebRenderer from "@elemaudio/web-renderer";

export class Engine {
  context;
  core;

  constructor() {
    this.core = new WebRenderer();
    this.context = new AudioContext();
    this.context.suspend();
  }

  async initialize() {
    // Start the audio context
    this.context.resume();

    // Initialize web renderer
    const node = await this.core.initialize(this.context, {
      numberOfInputs: 0,
      numberOfOutputs: 1,
      outputChannelCount: [1],
    });

    // Connect web renderer to audio context
    node.connect(this.context.destination);
  }
}
```

--------------------------------

### Initializing Elementary Audio with Virtual File System

Source: https://www.elementary.audio/docs/packages/web-renderer

Initializes the Elementary Audio core processor with options, including a virtual file system mapping string paths to audio data. This is essential for web environments lacking direct file system access.

```typescript
let node = await core.initialize(ctx, {
  numberOfInputs: 0,
  numberOfOutputs: 1,
  outputChannelCount: [2],
  processorOptions: {
    // Maps from String -> Array<Float32Array> | Float32Array
    virtualFileSystem: {
      '/your/virtual/file.wav': (new Float32Array(512)).map(() => Math.random() - 0.5),
    }
  }
});
```

--------------------------------

### Get Shared Resource Map Keys

Source: https://www.elementary.audio/docs/guides/Native_Integrations

Returns an iterator through the names of the entries in the shared resource map.

```APIDOC
## getSharedResourceMapKeys

### Description
Returns an iterator through the names of the entries in the shared resource map. This method intentionally does not provide access to the values in the map.

### Method
`SharedResourceMap::KeyViewType getSharedResourceMapKeys();`

### Parameters
None

### Request Example
```cpp
for (const auto& key : runtime->getSharedResourceMapKeys()) {
    // Process each shared resource name
    std::cout << key << std::endl;
}
```

### Response
#### Success Response (SharedResourceMap::KeyViewType)
- Returns an iterator providing access to the names (keys) of the shared resources.

### Response Example
```json
{
  "example": "[\"audioBuffer1\", \"audioBuffer2\"]"
}
```
```

--------------------------------

### Enable Web MIDI and Handle Device Connections

Source: https://www.elementary.audio/docs/tutorials/web-midi

Asynchronously enables Web MIDI, displays available controllers, and sets up listeners for device connection and disconnection events. Requires a secure context (localhost or https).

```javascript
async initialize(displayControllers) {
  try {
    await WebMidi.enable();
    displayControllers(this.#getInputNames(), this.selectedInput?.name);

    WebMidi.addListener("connected", () => {
      displayControllers(this.#getInputNames(), this.selectedInput?.name);
    });

    WebMidi.addListener("disconnected", () => {
      displayControllers(this.#getInputNames(), this.selectedInput?.name);
    });
  } catch (err) {
    console.error("WebMidi could not be initialized:", err);
  }
}
```

--------------------------------

### Initialize Generic Renderer

Source: https://www.elementary.audio/docs/packages/core

Demonstrates how to instantiate the generic `Renderer` class, which requires a callback function to handle instruction batches sent to the audio runtime.

```javascript
const core = new Renderer((instructionBatch) => {
  // Send the instruction batch to your `elem::Runtime<FloatType>` instance, wherever that may be!
  // Perhaps this is a websocket send step, or perhaps calling a FFI interface in your JavaScript runtime,
  // or even just saving to file to perform snapshot regression testing like with Jest.
});
```

--------------------------------

### WebRenderer Constructor

Source: https://www.elementary.audio/docs/packages/web-renderer

Initializes a new instance of the WebRenderer. Multiple instances can be created and managed independently.

```APIDOC
## Constructor WebRenderer

### Description
Initializes a new instance of the WebRenderer. Multiple instances can be created and managed independently.

### Method
```
new WebRenderer()
```

### Parameters
None

### Request Example
```javascript
import WebRenderer from '@elemaudio/web-renderer';
let core = new WebRenderer();
```

### Response
Returns a new WebRenderer instance.
```

--------------------------------

### Synchronized el.metro Usage with interval

Source: https://www.elementary.audio/docs/reference/metro

Shows synchronized metronome signals using el.metro with specified intervals. This example illustrates how el.metro ensures consistent synchronized rising edges.

```javascript
core.on('load', function(e) {
  core.render(el.metro({interval: 200}));
 
  setTimeout(function() {
    core.render(el.or(el.metro({interval: 400}), el.metro({interval: 200})));
  }, 1233);
});
```

--------------------------------

### Basic Synthesizer with MIDI Input - JavaScript

Source: https://www.elementary.audio/docs/guides/Understanding_Keys

Demonstrates a simple synthesizer that responds to MIDI events. It sets up a 'load' event handler to listen for 'midi' events, updates voice parameters, and renders the audio graph using core.render. It requires the 'el' and 'core' objects from the Elementary Audio library.

```javascript
let voices = [
  {gate: 0.0, freq: 440},
  {gate: 0.0, freq: 440},
];

function synth(vs) {
  return el.add(vs.map(function(v) {
    return el.mul(v.gate, el.cycle(v.freq));
  }));
}

core.on('load', function() {
  core.on('midi', function(e) {
    let vs = updateVoices(voices, e);

    core.render(synth(vs), synth(vs));
  });
});
```

--------------------------------

### Get Shared Resource Map Keys (C++)

Source: https://www.elementary.audio/docs/guides/Native_Integrations

Returns an iterator through the names (keys) of the entries in the shared resource map. This method intentionally does not provide access to the resource values themselves.

```C++
SharedResourceMap::KeyViewType getSharedResourceMapKeys();
```

--------------------------------

### Initialize Midi Class with WEBMIDI.js

Source: https://www.elementary.audio/docs/tutorials/web-midi

Sets up the Midi class constructor, accepting an event emitter and initializing the selected input to null. This is the foundational structure for MIDI control.

```javascript
import { WebMidi } from "webmidi";

export class Midi {
  noteEmitter;
  selectedInput;

  constructor(noteEmitter) {
    this.noteEmitter = noteEmitter;
    this.selectedInput = null;
  }

  // Class methods...
}
```

--------------------------------

### listVirtualFileSystem

Source: https://www.elementary.audio/docs/packages/web-renderer

Lists the names of all entries currently in the virtual file system.

```APIDOC
## listVirtualFileSystem

### Description
Lists the names of all entries currently in the virtual file system.

### Method
```javascript
core.listVirtualFileSystem(): Promise<Array<string>>;
```

### Parameters
None

### Request Example
```javascript
let entries = await core.listVirtualFileSystem();
console.log('VFS entries:', entries);
```

### Response
#### Success Response (200)
- **Array<string>** - An array of strings, where each string is the name of an entry in the virtual file system.
```

--------------------------------

### Using el.const for Constant Values

Source: https://www.elementary.audio/docs/guides/Making_Sound

Illustrates how to use `el.const` to represent constant values within Elementary Audio, which can be more efficient than calculating them at audio rate. This example shows `el.const({value: 2})`.

```javascript
el.const({value: 2})
```

--------------------------------

### el.sample: Basic and Rate-Controlled Sample Playback

Source: https://www.elementary.audio/docs/reference/sample

Demonstrates loading a sample with el.sample, showing default playback, half-speed playback, and continuous pitch modulation using el.add and el.cycle.

```javascript
el.sample({path: 'kick.wav'}, el.train(1), 1);   // Equivalent to the default playback
el.sample({path: 'kick.wav'}, el.train(1), 0.5); // Half speed playback
el.sample({path: 'kick.wav'}, el.train(1), el.add(1, el.cycle(1))); // Continuous pitch modulation
```

--------------------------------

### Basic Signal Creation in Elementary Audio

Source: https://www.elementary.audio/docs/guides/Understanding_Keys

Demonstrates the creation of two distinct audio signals using `el.cycle` with different frequency values. In Elementary, these are treated as mathematically different functions.

```javascript
let x = el.cycle(440);
let y = el.cycle(441);
```

--------------------------------

### Signal Creation with Keys for Efficient Updates

Source: https://www.elementary.audio/docs/guides/Understanding_Keys

Illustrates using the `key` property on `el.const` nodes to uniquely identify signals that differ only by a property change. This allows Elementary to recognize minimal updates and transition smoothly.

```javascript
let x = el.cycle(el.const({key: 'test', value: 440}));
let y = el.cycle(el.const({key: 'test', value: 441}));

core.render(x);
core.render(y);
```

--------------------------------

### elem::Runtime Constructor

Source: https://www.elementary.audio/docs/guides/Native_Integrations

Initializes the Elementary `Runtime` with the specified sample rate and block size. This sets up the core audio processing environment.

```cpp
Runtime(double sampleRate, int blockSize);
```

--------------------------------

### Instantiate WebRenderer

Source: https://www.elementary.audio/docs/packages/web-renderer

Creates a new instance of the WebRenderer. Multiple instances can be created and managed independently within a Web Audio application.

```javascript
let core = new WebRenderer();
```

--------------------------------

### core.initialize with Virtual File System

Source: https://www.elementary.audio/docs/packages/offline-renderer

Initializes the Elementary Audio core processor, optionally loading data into the virtual file system at initialization.

```APIDOC
## initialize /websites/elementary_audio

### Description
Initializes the Elementary Audio core processor. The `virtualFileSystem` property can be used to load sample data at initialization time.

### Method
Promise<void>

### Endpoint
N/A (Initialization parameter)

### Parameters
#### Request Body
- **virtualFileSystem** (object) - Optional - An object where keys are virtual file paths and values are the file content (e.g., Float32Array for audio samples).

### Request Example
```javascript
await core.initialize(ctx, {
  numInputChannels: 0,
  numOutputChannels: 2,
  virtualFileSystem: {
    '/your/virtual/file.wav': (new Float32Array(512)).map(() => Math.random() - 0.5),
  }
});
```

### Response
#### Success Response (void)
Initialization is successful.

#### Response Example
None
```

--------------------------------

### Using el.snapshot to capture and log signal values

Source: https://www.elementary.audio/docs/reference/snapshot

This example demonstrates how to use el.snapshot to capture the value of a signal on a pulse train's rising edge. It then logs the captured event data to the console. The 'ss' name is used to identify the source of the snapshot event.

```javascript
core.render(el.snapshot({name: "ss"}, el.train(1), el.cycle(20)));

core.on('snapshot', function(e) {
  console.log(e); // { source: "ss", data: 0.1394131 }
});
```

--------------------------------

### CMake Integration

Source: https://www.elementary.audio/docs/guides/Native_Integrations

Steps to add Elementary Audio as a git submodule and link it in your CMakeLists.txt.

```APIDOC
## CMake Integration

### Description
Add Elementary Audio to your project using git submodules and CMake.

### Steps

1. **Add submodule:**
   ```bash
   git submodule add https://github.com/elemaudio/elementary.git elementary
   ```

2. **Update `CMakeLists.txt`:**
   ```cmake
   # Add the runtime subdirectory
   add_subdirectory(elementary/runtime)

   # Make sure you link your target against the runtime
   target_link_libraries(${TARGET_NAME} PRIVATE runtime)
   ```
```

--------------------------------

### Initializing Virtual File System in Playground API

Source: https://www.elementary.audio/docs/playground_api

Demonstrates how to implement the `getVirtualFileSystem` function to populate the Playground's virtual file system with audio data fetched from a URL. This function is called only during initialization.

```javascript
async getVirtualFileSystem(decodeAudioData) {
  let res = await fetch('https://ia800407.us.archive.org/9/items/999WavFiles/10.mp3');
  let sampleBuffer = await decodeAudioData(await res.arrayBuffer());
 
  return {
    'ten:0': sampleBuffer.getChannelData(0),
    'ten:1': sampleBuffer.getChannelData(1),
  };
}
```

--------------------------------

### initialize

Source: https://www.elementary.audio/docs/packages/web-renderer

Initializes the Elementary runtime within a given AudioContext, creating an AudioWorkletNode for the runtime.

```APIDOC
## initialize

### Description
Initializes the Elementary runtime within a given AudioContext, creating an AudioWorkletNode for the runtime. Subsequent operations are forwarded to this AudioWorkletNode. Supports `processorOptions` for virtual file system initialization.

### Method
```javascript
core.initialize(ctx: AudioContext, options: AudioWorkletNodeOptions) : Promise<WebAudioNode>
```

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **ctx** (AudioContext) - The AudioContext to initialize the runtime in.
- **options** (AudioWorkletNodeOptions) - Options for configuring the AudioWorkletNode, including `processorOptions`.

### Request Example
```javascript
import WebRenderer from '@elemaudio/web-renderer';

const ctx = new AudioContext();
const core = new WebRenderer();

let node = await core.initialize(ctx, {
  numberOfInputs: 0,
  numberOfOutputs: 1,
  outputChannelCount: [2],
});

node.connect(ctx.destination);
```

### Response
#### Success Response (200)
- **WebAudioNode** - A promise that resolves to the underlying AudioWorkletNode.
```

--------------------------------

### Synth Voice Example - Elementary Audio

Source: https://www.elementary.audio/docs/motivation

A JavaScript helper function that applies an ADSR envelope to a pair of detuned saw waves for a synth voice. It uses Elementary's audio primitives like `el.adsr`, `el.mul`, `el.add`, and `el.blepsaw`. The function takes a `voice` object containing frequency and gate references as input.

```javascript
// A small helper function for assigning an ADSR envelope applied to a
// pair of detuned saws to a given synth voice.
function synthVoice(voice) {
  let env = el.adsr(4.0, 1.0, 0.4, 2.0, voice.gateRef);
 
  return el.mul(
    env,
    el.add(
      el.blepsaw(el.sm(voice.freqRef)),
      el.blepsaw(el.sm(el.mul(voice.detuneMultiplier, voice.freqRef))),
    ),
  );
}

```

--------------------------------

### Referencing Virtual Files in Elementary Audio Graphs

Source: https://www.elementary.audio/docs/packages/web-renderer

Demonstrates how to use audio nodes like `el.sample` within an Elementary Audio graph by referencing paths defined in the virtual file system.

```typescript
core.render(el.sample({path: '/your/virtual/path.wav'}, el.train(1)))
```

--------------------------------

### Import WebRenderer

Source: https://www.elementary.audio/docs/packages/web-renderer

Imports the WebRenderer class from the @elemaudio/web-renderer package. This import is necessary to create an instance of the renderer.

```javascript
import WebRenderer from '@elemaudio/web-renderer';
```

--------------------------------

### Import Core Components

Source: https://www.elementary.audio/docs/packages/core

Imports essential functions and types from the @elemaudio/core package for audio node composition and manipulation.

```javascript
import {
  el,
  createNode,
  isNode,
  resolve,
  Renderer,
} from '@elemaudio/core';
```

--------------------------------

### Modulate Filter Cutoff with setInterval (JavaScript Thread)

Source: https://www.elementary.audio/docs/guides/Sample_Accurate_Rendering

This JavaScript code snippet demonstrates modulating a lowpass filter's cutoff frequency using setInterval on the main thread. The LFO value is computed every 12ms. Changes are applied at the start of the next audio block, which may introduce latency. Dependencies: Elementary core, el module.

```javascript
core.on('load', function() {
  setInterval(function() {
    let time = Date.now();
    let cutoff = 800 * (1 + Math.sin(2.0 * Math.PI * Date.now() / 10000));
    core.render(
      el.lowpass(el.const({key: 'cut', value: cutoff}), 1.414, el.input({channel: 0})),
    );
  }, 12);
});
```

--------------------------------

### Rendering Distinct Signals in Elementary Audio

Source: https://www.elementary.audio/docs/guides/Understanding_Keys

Shows how rendering two signals created with different constant values without keys results in a new graph and smooth transition. This highlights the need for keys to identify similar signals with property changes.

```javascript
let x = el.cycle(440);
let y = el.cycle(441);

core.render(x);
core.render(y);
```

--------------------------------

### CMakeLists.txt Configuration for Elementary Runtime

Source: https://www.elementary.audio/docs/guides/Native_Integrations

Configures CMake to add the Elementary runtime subdirectory and link it against your target executable. This ensures the native audio engine is correctly integrated into your build.

```cmake
# Add the runtime subdirectory
add_subdirectory(elementary/runtime)
 
# Make sure you link your target against the runtime
target_link_libraries(${TARGET_NAME} PRIVATE runtime)
```

--------------------------------

### updateVirtualFileSystem

Source: https://www.elementary.audio/docs/packages/web-renderer

Adds new buffers to the virtual file system.

```APIDOC
## updateVirtualFileSystem

### Description
Adds new buffers to the virtual file system after initialization. Overwriting existing entries is not supported; this method is for adding new entries only.

### Method
```javascript
core.updateVirtualFileSystem(Object<string, Array<Float32Array> | Float32Array>): Promise<bool>;
```

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **Object<string, Array<Float32Array> | Float32Array>** - An object where keys are entry names and values are Float32Array buffers or arrays of Float32Array buffers.

### Request Example
```javascript
let buffer = new Float32Array([0, 1, 0, -1]);
let success = await core.updateVirtualFileSystem({ '/mybuffer': buffer });
console.log('Buffer added:', success);
```

### Response
#### Success Response (200)
- **bool** - A boolean indicating whether the buffer was successfully added.
```

--------------------------------

### Play a Synth Note

Source: https://www.elementary.audio/docs/tutorials/web-midi

Handles incoming MIDI note events to play a new voice. It generates a unique key for the voice, computes its frequency, updates the voices array (limiting to 8 polyphonic voices), and returns the resulting audio graph.

```javascript
import { el } from "@elemaudio/core";

// Assume synthVoice, synth, and computeFrequency are defined elsewhere

playNote(midiNote) {
  const key = `v${midiNote}`;
  const freq = computeFrequency(midiNote);

  // Add note to voices after removing previous instances.
  this.voices = this.voices
    .filter((voice) => voice.key !== key)
    .concat({ gate: 1, freq, key })
    .slice(-8);

  return synth(this.voices);
}
```

--------------------------------

### C++ Runtime API

Source: https://www.elementary.audio/docs/guides/Native_Integrations

Documentation for the `elem::Runtime<FloatType>` class and its methods.

```APIDOC
## C++ Runtime API

### Description
Interact with the Elementary Audio native engine through the `elem::Runtime<FloatType>` class. This class manages the audio processing graph and communication with JavaScript.

### Class: `elem::Runtime<FloatType>`

#### Constructor

**Description:** Creates an instance of the `Runtime` with the specified sample rate and block size.

**Signature:**
```cpp
Runtime(double sampleRate, int blockSize);
```

#### `applyInstructions`

**Description:** Applies graph rendering instructions received from the JavaScript environment. You may need to implement custom serialization/deserialization if not using JSON.

**Signature:**
```cpp
void applyInstructions(js::Array const& batch);
```

**Note:** A utility function `elem::js::parseJSON(std::string const& serialized)` is provided for JSON parsing.

#### `process`

**Description:** Executes the internal audio processing callback for a given number of samples. The `userData` pointer can be used to pass custom data to audio processing nodes.

**Signature:**
```cpp
void process(
    const FloatType** inputChannelData,
    size_t numInputChannels,
    FloatType** outputChannelData,
    size_t numOutputChannels,
    size_t numSamples,
    void* userData = nullptr
);
```

**Important:** `inputChannelData` and `outputChannelData` must not point to the same memory location.

#### `processQueuedEvents`

**Description:** Processes events generated by the audio graph, such as analysis node outputs (meters, FFTs, etc.) or errors. Call this periodically to handle these events.

**Signature:**
```cpp
void processQueuedEvents(std::function<void(std::string const&, js::Value)> evtCallback);
```

#### `reset`

**Description:** Resets the internal state of all nodes within the audio graph, including buffers and sample readers.
```

--------------------------------

### Render Audio Graph

Source: https://www.elementary.audio/docs/packages/core

Illustrates how to use the `render` method of the `Renderer` instance to process audio graph descriptions, such as sine wave generators.

```javascript
core.render(el.cycle(440), el.cycle(441));
```

--------------------------------

### Compose Basic Audio Graph with Elementary Core

Source: https://www.elementary.audio/docs/in_depth

Demonstrates composing a simple audio graph using functions from the @elemaudio/core package. It shows creating sine wave nodes and modulating their amplitudes.

```javascript
import {el} from '@elemaudio/core';

let x = el.cycle(440);
let y = el.cycle(220);
let z = el.mul(x, y);
```

--------------------------------

### elem::Runtime::applyInstructions Method

Source: https://www.elementary.audio/docs/guides/Native_Integrations

Applies graph rendering instructions to the runtime. This method takes an array of instructions, potentially serialized from JavaScript, and updates the audio processing graph. A utility function `elem::js::parseJSON` is available for JSON deserialization.

```cpp
void applyInstructions(js::Array const& batch);
```

--------------------------------

### Render with Transition Options

Source: https://www.elementary.audio/docs/packages/core

Shows how to use `renderWithOptions` to control fade times for root nodes during graph transitions, specifying fade-in and fade-out durations.

```javascript
await renderer.renderWithOptions({ rootFadeInMs: 4, rootFadeOutMs: 4 }, ...graphNodes);
```

--------------------------------

### Create a Single Synth Voice

Source: https://www.elementary.audio/docs/tutorials/web-midi

Generates an ElemNode representing a single synthesizer voice. It uses an el.blepsaw oscillator and a gate to control sound output. Keys are assigned for optimization.

```javascript
import { el } from "@elemaudio/core";

function synthVoice(voice) {
  return el.mul(
    el.const({ key: `${voice.key}:gate`, value: voice.gate }),
    el.blepsaw(el.const({ key: `${voice.key}:freq`, value: voice.freq })),
  );
}
```

--------------------------------

### Instantiate OfflineRenderer

Source: https://www.elementary.audio/docs/packages/offline-renderer

Demonstrates how to create a new instance of the OfflineRenderer. No arguments are needed for the constructor, allowing for multiple independent renderers.

```javascript
let core = new OfflineRenderer();
```

--------------------------------

### FFT Analysis and Event Handling in Elementary Audio

Source: https://www.elementary.audio/docs/reference/fft

Demonstrates how to use el.fft for Fast Fourier Transform analysis and how to listen for 'fft' events emitted by it. The 'fft' event provides source identification and the FFT data (real and imaginary parts).

```javascript
core.render(el.fft({size: 1024, name: "myfft"}, el.blepsaw(20)));

core.on('fft', function(e) {
  console.log(e); // { source: "myfft", data: { real: [...], imag: [...] } }
});
```

--------------------------------

### Initialize WebRenderer with AudioContext

Source: https://www.elementary.audio/docs/packages/web-renderer

Initializes the Elementary runtime within a given AudioContext. This method creates an AudioWorkletNode for the runtime and returns a promise resolving to the node, which can be connected to the Web Audio graph's destination.

```javascript
let node = await core.initialize(ctx, {
  numberOfInputs: 0,
  numberOfOutputs: 1,
  outputChannelCount: [2],
});

node.connect(ctx.destination);
```

--------------------------------

### OfflineRenderer Constructor and Initialization

Source: https://www.elementary.audio/docs/packages/offline-renderer

Instantiate and initialize the OfflineRenderer with specific audio processing parameters.

```APIDOC
## OfflineRenderer Constructor

### Description
Initializes a new instance of the OfflineRenderer. Multiple instances can be created and used independently.

### Method
`new OfflineRenderer()`

### Parameters
None

### Constructor Example
```javascript
let core = new OfflineRenderer();
```

## core.initialize

### Description
Initializes the Elementary offline runtime, preparing it for rendering. Unlike the web renderer, the runtime is ready immediately after this promise resolves.

### Method
`core.initialize(options: Object): Promise<void>`

### Parameters
#### Request Body
- **numInputChannels** (number) - Optional - Default: 0. The number of input channels.
- **numOutputChannels** (number) - Optional - Default: 2. The number of output channels.
- **sampleRate** (number) - Optional - Default: 44100. The sample rate for audio processing.
- **blockSize** (number) - Optional - Default: 512. The block size for processing.
- **virtualFileSystem** (Object<string, Array<number>|Float32Array>) - Optional - Default: {}. A map of file names to their data for the virtual file system.

### Request Example
```json
{
  "numInputChannels": 0,
  "numOutputChannels": 1,
  "sampleRate": 44100
}
```

### Response
#### Success Response (200)
Void, but the promise resolves when initialization is complete.
```
Tokens:
Raw