Skip to content

API Reference

Jump to bottom
Jakub Fiala edited this page Oct 1, 2018 · 12 revisions

r-audio exports a number of React Components falling into the following categories:

  • Base components: set up context and basic Web Audio functionality. The only public base component is RAudioContext.
  • Graph components: used to compose graphs. They do not provide any Web Audio functionality by themselves.
  • Audio nodes: wrappers for Web Audio nodes

Component classes listed as (private) are not exported, but may be adding props to the descendant classes which are useful to document.

Index

Base components

RAudioContext

Initialises an AudioContext and encapsulates one audio graph.

Props:

  • debug: enables debug mode. In debug mode, all contained RComponents will render debug HTML.
  • onInit: a function which is called when the AudioContext is initialised. The context is passed to it as the first argument. Useful for inspecting the context/decoding audio on demand.

RComponent (private)

Base class for all components requiring an AudioContext. If a RComponent is placed outside an RAudioContext, a ReferenceError is thrown.

RAudioNode (private)

Inherits from RComponent and manages the lifecycle, connections and updates to an audio node.

Props:

  • connectToParam: specifies a parameter of the destination node which the current node should connect to. If not specified, the node connects to the destination's input.
  • connectFromChannel: specifies the channel of the node's output signal which should connect to the destination.
  • connectToChannel: specifies the input channel of the destination which the node should connect to.
  • transitionTime: if specified, updates to params will be executed as a ramp over the specified time (in seconds). Use an object to specify different times for different params, like so:
<RBiquadFilter frequency={220} gain={1.1} transitionTime={ { frequency: 0.5, gain: 0.3 } } />
  • transitionCurve: sets the curve used for ramps an be set either to linear or exponential. Use an object to specify different curves for different params.
  • disconnected: a boolean attribute determining whether the node should connect to its destination or not.

RConnectableNode (private)

Inherits from RAudioNode. Represents any RAudioNode that can be connected to. Handles disconnection from parent nodes in a pipeline.

RScheduledSource (private)

Inherits from RAudioNode. Components which wrap nodes inheriting from the AudioScheduledSourceNode class in Web Audio inherit from RScheduledSource.

Props:

  • start: time when playback should be scheduled (in seconds). If not specified, playback will not start.
  • stop: time when playback end should be scheduled (in seconds). If not specified, playback will either stop automatically (in case of a non-looped buffer source node) or will not stop until the node is removed, or a new stop time specified (in case of an oscillator, or a constant source node).

Graph components

RPipeline

Connects its children in a series, i.e. for a list of children [A,B,C] the connections will be A -> B -> C.

Mechanism diagram

pipeline

Inbound branches

In a RPipeline, if a non-connectable node appears between two other nodes, an inbound branch must be created. Consider the following graph configuration:

<RPipeline>
    <ROscillator start={0} frequency={440} />
    <RBiquadFilter frequency={5000} />
    <ROscillator
        start={0}
        frequency={2}
        connectToParam="gain" />
    <RGain gain={0.5} />
</RPipeline>

The pipeline is resolved from the end, so RGain will be connected to the nearest preceding connectable node – RBiquadFilter. The second oscillator will constitute an in- bound branch and connect to the gain parameter of RGain. The resulting graph is depicted below:

pipeline

RSplit

Connects its children in parallel, i.e. the input will be connected to each child, and each child will be connected to the destination.

RCycle

Connects every child to the child itself, as well as the destination.

RSplitChannels

A composite component which connects children in parallel (like RSplit), and distributes the input signal channels to individual children.

Props:

  • channelCount: maximum number of channels to distribute

Composition of RSplitChannels

channels

RExtensible

An "abstract" component which can be subclassed to create custom reusable r-audio components (subgraphs). The reason for its existence is the fact that r-audio can only work with components which are subclassing RComponent.

The subgraph is declared by overriding the renderGraph method. Under the hood, it's essentially just a pipeline which renders custom content instead of its children.

Props:

The props can be set arbitrarily and mapped onto various props within the subgraph.

Using RExtensible

First, you need to create a subclass of RExtensible and override the renderGraph method, returning your subgraph.

class DelayLine extends RExtensible {
  renderGraph() {
    return (
      <RCycle>
        <RPipeline>
          <RGain gain={this.props.gain}/>
          <RDelay delayTime={this.props.delayTime}/>
        </RPipeline>
      </RCycle>
    );
  }
}

You can then use the custom component in a r-audio graph, passing custom props as desired:

render() {
  return (
    <RAudioContext>
      <RPipeline>
        <DelayLine gain={0.7} delayTime={0.3} />
      </RPipeline>
    </RAudioContext>
  );
}

Audio Nodes

These components correspond to non-deprecated AudioNodes in Web Audio. Unless specified otherwise, their props are inherited from ancestor classes + identical to properties of the Web Audio objects.

RAnalyser

extends RConnectableNode

Corresponds to Web Audio AnalyserNode.

Props:

  • as specified in Web Audio

Children

If the child is a function, it will be called every time the component is rendered. The first argument will be a proxy object with the following methods:

  • getFloatFrequencyData
  • getByteFrequencyData
  • getFloatTimeDomainData
  • getByteTimeDomainData

RAudioWorklet

extends RConnectableNode

Corresponds to Web Audio AudioWorkletNode.

Props:

  • worklet (String): the name of an instantiated AudioWorklet module.
  • any custom AudioParams specified by the worklet

RBiquadFilter

extends RConnectableNode

Corresponds to Web Audio AnalyserNode.

Props:

  • as specified in Web Audio

Children

If the child is a function, it will be called every time the component is rendered. The first argument will be a proxy object with the following methods:

  • getFrequencyResponse

RBufferSource

extends RScheduledSource

Corresponds to Web Audio BufferSourceNode.

Props:

  • as specified in Web Audio

RChannelMerger

extends RConnectableNode

Corresponds to Web Audio ChannelMerger. Note: if multiple nodes connect to RChannelMerger, each incoming connection is connected to a different channel

Props:

  • as specified in Web Audio

RChannelSplitter

extends RConnectableNode

Corresponds to Web Audio ChannelSplitter. Note: if RChannelSplitter connects to multiple nodes, each outgoing connection is connected from a different channel

Props:

  • as specified in Web Audio

RConstantSource

extends RScheduledSource

Corresponds to Web Audio ConstantSourceNode.

Props:

  • as specified in Web Audio

RConvolver

extends RConnectableNode

Corresponds to Web Audio ConvolverNode.

Props:

  • as specified in Web Audio

RDelay

extends RConnectableNode

Corresponds to Web Audio DelayNode.

Props:

  • as specified in Web Audio

RDynamicsCompressor

extends RConnectableNode

Corresponds to Web Audio DynamicsCompressorNode.

Props:

  • as specified in Web Audio

RGain

extends RConnectableNode

Corresponds to Web Audio GainNode.

Props:

  • as specified in Web Audio

RIIRFilter

extends RConnectableNode

Corresponds to Web Audio IIRFilterNode.

Props:

  • as specified in Web Audio

Children

If the child is a function, it will be called every time the component is rendered. The first argument will be a proxy object with the following methods:

  • getFrequencyResponse

RMediaElementSource

extends RAudioNode

Corresponds to Web Audio MediaElementSourceNode.

Props:

  • element: a HTMLMediaElement used to construct the node

RMediaStreamSource

extends RAudioNode

Corresponds to Web Audio MediaStreamSourceNode.

Props:

  • stream: a MediaStream used to construct the node

ROscillator

extends RScheduledSource

Corresponds to Web Audio OscillatorNode.

Props:

  • as specified in Web Audio

RStereoPanner

extends RConnectableNode

Corresponds to Web Audio StereoPannerNode.

Props:

  • as specified in Web Audio

RPanner

extends RConnectableNode

Corresponds to Web Audio PannerNode.

Props:

  • as specified in Web Audio

RWaveShaper

extends RConnectableNode

Corresponds to Web Audio WaveShaperNode.

Props:

  • as specified in Web Audio
Clone this wiki locally