addon/classes/connection.js:17

Connection

This class represents a single connection in a Sound instance's connections array. It is mostly just a wrapper around an AudioNode instance. It defines some standards for how to handle the behaviors of different AudioNode types. Most connections create their corresponding AudioNode immediately, but some AudioNodes are "throw-away" and have to be created each time a Sound instance is played.

Most properties in this class just define how to go about getting/creating an AudioNode instance and setting it on this class' node property. Some define how to set properties on the AudioNode instance after it has been created.

Property Summary

Public Properties
public
createCommand: String

If source is specified, this method will be called on the object that was retrieved from source. The value returned from this method is set on the node property.
public
createdOnPlay: Boolean

If this is true, the AudioNode will be created every time the consuming Sound instance is played.
public
exponentialRampToValuesAtTime: Ember.MutableArray

Items in this array are set at play-time on the node via an exponential ramp that ends at the specified time.
public
linearRampToValuesAtTime: Ember.MutableArray

Items in this array are set at play-time on the node via a linear ramp that ends at the specified time.
public
name: String

The name of the connection. This is the name that can be used to get an AudioNode instance via the getNodeFrom method, or a Connection instance via the getConnection method.
public
node: AudioNode

This is the main attraction here in connection-land. All the other properties in the Connection class exist to create or mutate this property. Houses an AudioNode instance that will be used by an instance of the Sound class.
public
onPlaySetAttrsOnNode: Ember.MutableArray

An array of POJOs that specify properties that need to be set on a node when any of the play methods are called. For instance, an AudioBufferSourceNode must be created at play time, because they can only be played once and then they are immediately thrown away.
public
path: String

If an AudioNode instance already exists and is accessible to the Sound instance, the path to the node can be placed here. If this value is specified, all options except name become useless. If node is specified, it will override this option and the AudioNode supplied to node will be used.
public
setValuesAtTime: Ember.MutableArray

Items in this array are set at play-time on the node via an exponential ramp that ends at the specified time.
public
source: String

If createCommand is specified, the object at this location (relative to the Sound instance) will be used as the "source" of the createCommand.
public
startingValues: Ember.MutableArray

Items in this array are set immediately at play-time on the node.

Method Summary

Public Methods
public
onPlaySet( )

Allows an AudioNode's values to be set at a specific time relative to the moment that it is played, every time it is played.
public
onPlaySet( )

Convenience method that uses onPlaySet twice to set an initial value, and a ramped value in succession.
Private Methods
private
_initArrays( )

If any of the array types are null on init, set them to an Ember.MutableArray

Public Properties

addon/classes/connection.js:86

public createCommand: String

If source is specified, this method will be called on the object that was retrieved from source. The value returned from this method is set on the node property.

Example:

// results in the node property being created like:
// this.get('audioContext').createGain();
{
  source: 'audioContext'
  createCommand: 'createGain'
}

If this is true, the AudioNode will be created every time the consuming Sound instance is played.

addon/classes/connection.js:147

public exponentialRampToValuesAtTime: Ember.MutableArray

Items in this array are set at play-time on the node via an exponential ramp that ends at the specified time.

A convenience setter method called onPlaySet exists for this array and should be used unless it does not allow enough freedom for your use-case.

Example:

// at play time: connection.node.gain.exponentialRampToValueAtTime(0.1, 1)
{
  key: 'gain',
  value: 0.1,
  endTime: 1
}
// the same thing can be accomplished like:
connection.onPlaySet('gain').to(0.1).endingAt(1)
addon/classes/connection.js:173

public linearRampToValuesAtTime: Ember.MutableArray

Items in this array are set at play-time on the node via a linear ramp that ends at the specified time.

A convenience setter method called onPlaySet exists for this array and should be used unless it does not allow enough freedom for your use-case.

Example:

// at play time: connection.node.gain.linearRampToValueAtTime(0.1, 1)
{
  key: 'gain',
  value: 0.1,
  endTime: 1
}
// the same thing can be accomplished like:
connection.onPlaySet('gain').to(0.1).endingAt(1, 'linear')

The name of the connection. This is the name that can be used to get an AudioNode instance via the getNodeFrom method, or a Connection instance via the getConnection method.

This is the main attraction here in connection-land. All the other properties in the Connection class exist to create or mutate this property. Houses an AudioNode instance that will be used by an instance of the Sound class.

If this property is set directly, all of the other properties on this class (except name) are rendered useless.

An array of POJOs that specify properties that need to be set on a node when any of the play methods are called. For instance, an AudioBufferSourceNode must be created at play time, because they can only be played once and then they are immediately thrown away.

Valid keys are:

attrNameOnNode {string} Determines which property on the node should be set to the value. This can be a nested accessor (ie. 'gain.value').

relativePath {string} Determines where on this (the Sound instance) to get the value. This can be a nested accessor (ie. 'gainNode.gain.value').

value {mixed} The direct value to set. If used along with relativePath, this will act as a default value and the value at relativePath will take precedence.

Example:

// Causes gainNode.gain.value = soundInstance.get('gainValue') || 1;
// to be called at play-time

{
  name: 'gainNode',
  onPlaySetAttrsOnNode: [
    {
      attrNameOnNode: 'gain.value',
      relativePath: 'gainValue',
      value: 1
    }
  ]
}

If an AudioNode instance already exists and is accessible to the Sound instance, the path to the node can be placed here. If this value is specified, all options except name become useless. If node is specified, it will override this option and the AudioNode supplied to node will be used.

Example:

// Uses the Audio Node instance from:
// soundInstance.get('audioContext.destination')
{
  name: 'destination',
  path: 'audioContext.destination'
}

Items in this array are set at play-time on the node via an exponential ramp that ends at the specified time.

A convenience setter method called onPlaySet exists for this array and should be used unless it does not allow enough freedom for your use-case.

Example:

// at play time: connection.node.gain.setValueAtTime(0.1, 1)
{
  key: 'gain',
  value: 0.1,
  startTime: 1
}
// the same thing can be accomplished like:
connection.onPlaySet('gain').to(0.1).at(1)

If createCommand is specified, the object at this location (relative to the Sound instance) will be used as the "source" of the createCommand.

Example:

// Creates the AudioNode by calling:
// this.get('audioContext')[createCommand]();
{
  source: 'audioContext'
  createCommand: createGain
}

Items in this array are set immediately at play-time on the node.

A convenience setter method called onPlaySet exists for this array and should be used unless it does not allow enough freedom for your use-case.

Example:

// at play time: connection.node.gain.setValueAtTime(0.1, audioContext.currentTime)
{
  key: 'gain',
  value: 0.1
}
// the same thing can be accomplished like:
connection.onPlaySet('gain').to(0.1)

Public Methods

addon/classes/connection.js:275

public onPlaySet( )

Allows an AudioNode's values to be set at a specific time relative to the moment that it is played, every time it is played.

Especially useful for creating/shaping an "envelope" (think "ADSR").

Example:

// results in an oscillator that starts at 150Hz and quickly drops
// down to 0.01Hz each time it's played
const kick = audio.createOscillator({ name: 'kick' });
const osc = kick.getConnection('audioSource');

osc.onPlaySet('frequency').to(150).at(0);
osc.onPlaySet('frequency').to(0.01).at(0.1);
addon/classes/connection.js:328

public onPlaySet( )

Convenience method that uses onPlaySet twice to set an initial value, and a ramped value in succession.

Especially useful for creating/shaping an "envelope" (think "ADSR").

Example:

// results in an oscillator that starts at 150Hz and quickly drops
// down to 0.01Hz each time it's played
const kick = audio.createOscillator({ name: 'kick' });
const osc = kick.getConnection('audioSource');

osc.onPlayRamp('frequency').from(150).to(0.01).in(0.1);

Private Methods

addon/classes/connection.js:365

private _initArrays( )

If any of the array types are null on init, set them to an Ember.MutableArray