addon/classes/sound.js:18

Sound

Uses: Connectable Playable

The Sound class provides the core functionality for interacting with the Web Audio API's AudioContext, and is the base class for all other Audio types. It prepares an audio source, provides various methods for interacting with the audio source, creates AudioNodes from the connections array, sets up the necessary connections/routing between them, and provides some methods to play and Sound/stop:method the audio source.

Property Summary

Public Properties
public
audioBuffer: AudioBuffer

The AudioBuffer instance that provides audio data to the bufferSource connection.
public
audioContext: AudioContext

The parent AudioContext instance that all audio events are occurring within. It is useful for getting currentTime, as well as creating new AudioNodes.
public
connections: Ember.MutableArray
public
duration: Object

Computed property. Value is an object containing the duration of the audioBuffer in three formats. The three formats are raw, string, and pojo.
public
isPlaying: Boolean
public
name: String

When using the Audio-Service, The name that this Sound instance is registered as on it's parent register.
public
percentGain: Number

Computed property. Value is the amount of gain currently applied to the gain connection from the connections array, formatted as a percentage.
public
startOffset: Number

When a Sound instance is played, this value is passed to the AudioBufferSourceNode.start() offset param. Determines where (in seconds) the play will start, along the duration of the audio source.
Private Properties
private
_startedPlayingAt: Number

When a Sound instance plays, this is set to the audioContext.currentTime. It will always reflect the start time of the most recent Sound/_play:method.

Method Summary

Public Methods
public
changeGainTo(value): Object

Gets the gain connection and changes it's gain value to the value passed in. returns a pojo with the from method that value is curried to, allowing one to specify which type of value is being provided.
public
changePanTo(value)

Gets the panner connection and changes it's pan value to the value passed in.
public
getConnection(name): Connection
public
getNodeFrom(name): AudioNode
public
play( )
public
playAt(time)
public
playFor(seconds)
public
playIn(seconds)
public
playInAndStopAfter(playIn, stopAfter)
public
removeConnection(name)
public
seek(amount): Object

Gets the bufferSource and stops the audio, changes it's play position, and restarts the audio.
public
stop( )
public
stopAt(time)
public
stopIn(seconds)
public
update(key, value)
Protected Methods
protected
_initConnections( )
protected
wireConnections( ): Array | Connection
Private Methods
private
_createNode(connection): Connection
private
_play(time)
private
_setAttrsOnNode(connection): Connection
private
_stop(stopAt)
private
_watchConnectionChanges( )
private
_wireConnection(connection, idx, connections): Connection

Public Properties

The AudioBuffer instance that provides audio data to the bufferSource connection.

The parent AudioContext instance that all audio events are occurring within. It is useful for getting currentTime, as well as creating new AudioNodes.

This is the object that facilitates and ties together all aspects of the Web Audio API.

An array of Connection instances. Determines which AudioNode instances are connected to one-another and the order in which they are connected. Starts as null but set to an array on init via the {{#crossLink "Connectable/_initConnections:method"}}{{/crossLink}} method.

Computed property. Value is an object containing the duration of the audioBuffer in three formats. The three formats are raw, string, and pojo.

Duration of 6 minutes would be output as:

{
  raw: 360, // seconds
  string: '06:00',
  pojo: {
    minutes: 6,
    seconds: 0
  }
}
Whether an audio source is playing or not.

When using the Audio-Service, The name that this Sound instance is registered as on it's parent register.

addon/classes/sound.js:125

public percentGain: Number

Computed property. Value is the amount of gain currently applied to the gain connection from the connections array, formatted as a percentage.

addon/classes/sound.js:81

public startOffset: Number

When a Sound instance is played, this value is passed to the AudioBufferSourceNode.start() offset param. Determines where (in seconds) the play will start, along the duration of the audio source.

Private Properties

addon/classes/sound.js:70

private _startedPlayingAt: Number

When a Sound instance plays, this is set to the audioContext.currentTime. It will always reflect the start time of the most recent Sound/_play:method.

Public Methods

addon/classes/sound.js:150

public changeGainTo(value): Object

Gets the gain connection and changes it's gain value to the value passed in. returns a pojo with the from method that value is curried to, allowing one to specify which type of value is being provided.

Parameters:

Name Type Attribute Description
value Number

The value that the gain connection's gain.value should be set to. Can be a ratio, an inverseRatio or a percentage.

Return:

Object

Intermediary POJO containing the from method which will determine the type of value that gain.value is being set to and make the change accordingly.

Example:

// these all result in gainNode.gain.value === 0.9
soundInstance.changeGainTo(0.9).from('ratio');
soundInstance.changeGainTo(0.1).from('inverseRatio')
soundInstance.changeGainTo(90).from('percent');
addon/classes/sound.js:137

public changePanTo(value)

Gets the panner connection and changes it's pan value to the value passed in.

Parameters:

Name Type Attribute Description
value Number

The value, between -1 and 1 that the panner connection's pan.value should be set to.
addon/mixins/connectable.js:62

public getConnection(name): Connection

Inherited from Connectable
returns a connection from the connections array by it's name

Parameters:

Name Type Attribute Description
name String
The name of the AudioNode that should be returned.

Return:

Connection The requested Connection.
addon/mixins/connectable.js:43

public getNodeFrom(name): AudioNode

Inherited from Connectable
returns a connection's AudioNode from the connections array by the connection's name.

Parameters:

Name Type Attribute Description
name String
The name of the AudioNode that should be returned.

Return:

AudioNode The requested AudioNode.
Inherited from Playable
Plays the audio source immediately.
addon/mixins/playable.js:49

public playAt(time)

Inherited from Playable
Plays the audio source at the specified moment in time. A "moment in time" is measured in seconds from the moment that the {{#crossLink "AudioContext"}}{{/crossLink}} was instantiated. Functionally equivalent to {{#crossLink "Playable/_play:method"}}{{/crossLink}}.

Parameters:

Name Type Attribute Description
time Number
The moment in time (in seconds, relative to the {{#crossLink "AudioContext"}}AudioContext's{{/crossLink}} "beginning of time") when the audio source should be played.
addon/mixins/playable.js:80

public playFor(seconds)

Inherited from Playable
Starts playing the audio source immediately, but stops after specified seconds have elapsed.

Parameters:

Name Type Attribute Description
seconds Number
The amount of time after which the audio source is stopped.
addon/mixins/playable.js:67

public playIn(seconds)

Inherited from Playable
Plays the audio source in specified amount of seconds from "now".

Parameters:

Name Type Attribute Description
seconds Number
Number of seconds from "now" that the audio source should be played.
addon/mixins/playable.js:95

public playInAndStopAfter(playIn, stopAfter)

Inherited from Playable
Starts playing the audio source after playIn seconds have elapsed, then stops the audio source stopAfter seconds after it started playing.

Parameters:

Name Type Attribute Description
playIn Number
Number of seconds from "now" that the audio source should play.
stopAfter Number
Number of seconds from when the audio source started playing that the audio source should be stopped.
addon/mixins/connectable.js:76

public removeConnection(name)

Inherited from Connectable
Find's a connection in the connections array by it's name and removes it.

Parameters:

Name Type Attribute Description
name String
The name of the connection that should be removed.
addon/classes/sound.js:193

public seek(amount): Object

Gets the bufferSource and stops the audio, changes it's play position, and restarts the audio.

returns a pojo with the from method that value is curried to, allowing one to specify which type of value is being provided.

Parameters:

Name Type Attribute Description
amount Number

The new play position value.

Return:

Object

Intermediary POJO containing the from method which will determine the type of value that play position is being set to and make the change accordingly.

Example:

// for a Sound instance with a duration of 100 seconds, these will all
// move the play position to 90 seconds.
soundInstance.seek(0.9).from('ratio');
soundInstance.seek(0.1).from('inverseRatio')
soundInstance.seek(90).from('percent');
soundInstance.seek(90).from('seconds');
Inherited from Playable
Stops the audio source immediately.
addon/mixins/playable.js:136

public stopAt(time)

Inherited from Playable
Stops the audio source at the specified "moment in time" relative to the "beginning of time" according to the audioContext. Functionally equivalent to the _stop method.

Parameters:

Name Type Attribute Description
time Number
The time that the audio source should be stopped.
addon/mixins/playable.js:123

public stopIn(seconds)

Inherited from Playable
Stops the audio source after specified seconds have elapsed.

Parameters:

Name Type Attribute Description
seconds Number
Number of seconds from "now" that the audio source should be stopped.
addon/mixins/connectable.js:88

public update(key, value)

Inherited from Connectable
Updates an AudioNode's property in real time by setting the property on the connectable object (which affects the next play) and also sets it on it's corresponding connection.node (which affects the audio in real time). If a connection is pulling a property from a connectable object via onPlaySetAttrsOnNode[index].relativePath, this method will update that property directly on the Connection's node as well as on the connectable object. Important to note that this only works for properties that are set directly on a connectable object and then proxied/set on a node via onPlaySetAttrsOnNode.

Parameters:

Name Type Attribute Description
key String
The name/path to a property on an Oscillator instance that should be updated.
value String
The value that the property should be set to.

Example:

// With set
const osc = audioService.createOscillator({ frequency: 440 });
osc.play(); // playing at 440Hz
osc.set('frequency', 1000); // still playing at 440Hz
osc.stop();
osc.play(); // now playing at 1000Hz
// With update
const osc = audioService.createOscillator({ frequency: 440 });
osc.play(); // playing at 440Hz
osc.update('frequency', 1000); // playing at 1000Hz

Protected Methods

addon/mixins/connectable.js:139

protected _initConnections( )

Inherited from Connectable
Initializes default connections on Sound instantiation. Runs on('init').
addon/mixins/connectable.js:197

protected wireConnections( ): Array | Connection

Inherited from Connectable
Gets the array of Connection instances from the connections array and returns the same array, having created any AudioNode instances that needed to be created, and having connected the AudioNode instances to one another in the order in which they were present in the connections array.

Return:

Array | Connection Array of Connection instances collected from the connections array, created, connected, and ready to play.

Private Methods

addon/mixins/connectable.js:218

private _createNode(connection): Connection

Inherited from Connectable
Creates an AudioNode instance for a Connection instance and sets it on it's node property. Unless the Connection instance's createdOnPlay property is true, does nothing if the AudioNode instance has already been created. Also sets any properties from a connection's onPlaySetAttrsOnNode array on the node.

Parameters:

Name Type Attribute Description
connection Connection
A Connection instance that should have it's node created (if needed).

Return:

Connection The input Connection instance after having it's node created.
addon/mixins/playable.js:179

private _play(time)

Inherited from Playable
The underlying method that backs all of the play methods. Plays sound and sets isPlaying to true at specified time. Functionally equivalent to playAt.

Parameters:

Name Type Attribute Description
time Number
The moment in time (in seconds, relative to the {{#crossLink "AudioContext"}}AudioContext's{{/crossLink}} "beginning of time") when the audio source should be played.
addon/mixins/connectable.js:253

private _setAttrsOnNode(connection): Connection

Inherited from Connectable
Gets a Connection instance's onPlaySetAttrsOnNode and sets them on it's node.

Parameters:

Name Type Attribute Description
connection Connection
The Connection instance that needs it's node's attrs set.

Return:

Connection The input Connection instance after having it's nodes attrs set.
addon/mixins/playable.js:151

private _stop(stopAt)

Inherited from Playable
The underlying method that backs all of the stop methods. Stops sound and set isPlaying to false at specified time. Functionally equivalent to the stopAt method.

Parameters:

Name Type Attribute Description
stopAt Number
The moment in time (in seconds, relative to the {{#crossLink "AudioContext"}}AudioContext's{{/crossLink}} "beginning of time") when the audio source should be stopped.
addon/mixins/connectable.js:186

private _watchConnectionChanges( )

Inherited from Connectable
Observes the connections array and runs wireConnections each time it changes.
addon/mixins/connectable.js:300

private _wireConnection(connection, idx, connections): Connection

Inherited from Connectable
Meant to be passed to a Array.prototype.map function. Connects a Connection instance's node to the next Connection instance's node.

Parameters:

Name Type Attribute Description
connection Connection
The current Connection instance in the iteration.
idx Number
The index of the current iteration.
connections Array | Connection
The original array of connections.

Return:

Connection The input Connection instance after having it's node connected to the next Connection instance's node.