addon/services/audio.js:20

AudioService

A Service that provides methods for interacting with the various Audio classes and the Web Audio API's AudioContext. This can be thought of as the "entrypoint" to using ember-audio. An application using ember-audio should use this service for all interactions with the Web Audio API.

Ember.Something.extend({
  audio: Ember.inject.service(),

  loadSound() {
    return this.get('audio').load('some.mp3').asSound('some-sound');
  }
});

Property Summary

Public Properties
public
audioContext: AudioContext

An AudioContext instance from the Web Audio API. NOT available in all browsers. Not available in any version of IE (except EDGE) as of April 2016.
Private Properties
private
_beatTracks: Map

This acts as a register for BeatTrack instances. BeatTrack instances are placed in the register by name, and can be called via audioService.getBeatTrack('name')
private
_fonts: Map

This acts as a register for soundfonts. A font is just a Map of Note objects which is placed in this register by name, and can be played like: audioService.getFont('some-font').play('Ab1');
private
_samplers: Map

This acts as a register for Sampler instances. Sampler instances are placed in the register by name, and can be called via audioService.getSampler('name')
private
_sounds: Map

This acts as a register for Sound instances. Sound instances are placed in the register by name, and can be called via audioService.getSound('name')
private
_tracks: Map

This acts as a register for Track instances. Track instances are placed in this register by name, and can be called via audioService.getTrack('name')

Method Summary

Public Methods
public
createNoteArray(json): Array | Note

Creates an array of Note objects from a json object containing notes and frequency values.
public
createOscillator(opts): Oscillator

Creates an Oscillator instance.
public
createWhiteNoise(opts): Sound

Creates a Sound instance with it's audioBuffer filled with one sample's worth of white noise.
public
getBeatTrack(name): BeatTrack

Gets a BeatTrack instance by name from the _beatTracks register.
public
getFont(name): Object

Gets a soundfont Map by name from the _fonts register and allows it to be played via the returned POJO containing a method called play.
public
getSampler(name): Sampler

Gets a Sampler instance by name from the _samplers register
public
getSound(name): Sound

Gets a Sound instance by name from the _sounds register
public
getTrack(name): Track

Gets a Track instance by name from the _tracks register
public
load(src): Object

Acts as a proxy method, returns a POJO with methods that return the _load and _loadFont methods so that in the end. See example.
public
pauseAll( )

Gets all Track instances and calls Sound/pause:method on each. Only works for tracks because only Track instances are pause-able.
public
removeFromRegister(type, name)

Given a sound's name and type, removes the sound from it's register.
public
stopAll(type='tracks')

Gets all instances of requested type and calls Sound/stop:method on each.
Private Methods
private
_createNoteObjectsForFont(audioData, instrumentName): Array

Takes an array of arrays, each inner array acting as a key-value pair in the form [noteName, audioData]. Each inner array is transformed into a Note and the outer array is returned. This method also sets each note on it's corresponding instrument Map instance by name. Each note is playable as seen in the example.
private
_createSoundFor(type, props): Sound | Track | BeatTrack

Creates an Audio Class instance (which is based on which "type" is specified), and passes "props" to the new instance.
private
_createSoundsArray(name, srcArray): Promise | Array

Accepts an array of URLs to audio files and creates a Sound instance for each.
private
_extractDecodedKeyValuePairs(notes): Array

Takes an array of base64 encoded strings (notes) and returns an array of arrays like [[name, audio], [name, audio]]
private
_getRegisterFor(type): Map

Gets a register by it's type.
private
_load(name, src, type): Promise | Sound | Track | BeatTrack

Loads and decodes an audio file, creating a Sound, Track, or BeatTrack instance (as determined by the "type" parameter) and places the instance into it's corresponding register.
private
_loadBeatTrack(name, srcArray): Promise | BeatTrack

Creates a BeatTrack instance from an array of URLs.
private
_loadFont(instrumentName, src): Promise | Array

The notes are sorted the way that they would appear on a piano. In the example, you can see how the note Ab1 from the font-name soundfont would be played:

Public Properties

An AudioContext instance from the Web Audio API. NOT available in all browsers. Not available in any version of IE (except EDGE) as of April 2016.

Private Properties

addon/services/audio.js:102

private _beatTracks: Map

This acts as a register for BeatTrack instances. BeatTrack instances are placed in the register by name, and can be called via audioService.getBeatTrack('name')

addon/services/audio.js:81

private _fonts: Map

This acts as a register for soundfonts. A font is just a Map of Note objects which is placed in this register by name, and can be played like: audioService.getFont('some-font').play('Ab1');

addon/services/audio.js:71

private _samplers: Map

This acts as a register for Sampler instances. Sampler instances are placed in the register by name, and can be called via audioService.getSampler('name')

addon/services/audio.js:61

private _sounds: Map

This acts as a register for Sound instances. Sound instances are placed in the register by name, and can be called via audioService.getSound('name')

addon/services/audio.js:92

private _tracks: Map

This acts as a register for Track instances. Track instances are placed in this register by name, and can be called via audioService.getTrack('name')

Public Methods

addon/services/audio.js:244

public createNoteArray(json): Array | Note

Creates an array of Note objects from a json object containing notes and frequency values.

Parameters:

Name Type Attribute Description
json Object | Null

Optionally provided json object. If not provided, the object returned from utils/frequencyMap is used.

Return:

addon/services/audio.js:295

public createOscillator(opts): Oscillator

Creates an Oscillator instance.

Parameters:

Name Type Attribute Description
opts Object

An object passed into the Oscillator instance.

Return:

Oscillator

The created Oscillator instance.
addon/services/audio.js:271

public createWhiteNoise(opts): Sound

Creates a Sound instance with it's audioBuffer filled with one sample's worth of white noise.

Parameters:

Name Type Attribute Description
opts Object

An object passed into the Sound instance.

Return:

Sound

The created white noise Sound instance.
addon/services/audio.js:310

public getBeatTrack(name): BeatTrack

Gets a BeatTrack instance by name from the _beatTracks register.

Parameters:

Name Type Attribute Description
name String

The name of the BeatTrack instance that should be retrieved from the _beatTracks register.

Return:

BeatTrack

Returns the BeatTrack instance that matches the provided name.
addon/services/audio.js:355

public getFont(name): Object

Gets a soundfont Map by name from the _fonts register and allows it to be played via the returned POJO containing a method called play.

Parameters:

Name Type Attribute Description
name String

The name of the Map that should be retrieved from the _fonts register.

Return:

Object

Returns a POJO that has a play method which allows a note from the requested font to be played.

Example:

audio.getFont('some-font').play('Ab1');
addon/services/audio.js:375

public getSampler(name): Sampler

Gets a Sampler instance by name from the _samplers register

Parameters:

Name Type Attribute Description
name String

The name of the sampler that should be retrieved from the _samplers register.

Return:

Sampler

returns the Sampler instance that matches the provided name.
addon/services/audio.js:325

public getSound(name): Sound

Gets a Sound instance by name from the _sounds register

Parameters:

Name Type Attribute Description
name String

The name of the sound that should be retrieved from the _sounds register.

Return:

Sound

returns the Sound instance that matches the provided name.
addon/services/audio.js:340

public getTrack(name): Track

Gets a Track instance by name from the _tracks register

Parameters:

Name Type Attribute Description
name String

The name of the Track instance that should be retrieved from the _tracks register.

Return:

Track

Returns the Track instance that matches the provided name.

Acts as a proxy method, returns a POJO with methods that return the _load and _loadFont methods so that in the end. See example.

Parameters:

Name Type Attribute Description
src String | Array

The URL location of an audio file. Will be used by "fetch" to get the audio file. Can be a local or a relative URL. An array of URLs is required if a beatTrack is being loaded via .asBeatTrack or .asSampler.

Return:

Object

returns a POJO that contains a few methods that curry "src" "type" and "name" over to Audio/_load:method and Audio/_loadFont:method and allow you to specify what type of Sound you'd like created.

Example:

audio.load('some-url.wav').asSound('some-sound');
audio.load('some-url.mp3').asTrack('some-track');
audio.load(['some-url.mp3']).asSampler('some-sampler');
audio.load(['some-url.mp3']).asBeatTrack('some-beat-track');
audio.load('some-url.js').asFont('some-font');
addon/services/audio.js:406

public pauseAll( )

Gets all Track instances and calls Sound/pause:method on each. Only works for tracks because only Track instances are pause-able.

addon/services/audio.js:420

public removeFromRegister(type, name)

Given a sound's name and type, removes the sound from it's register.

Parameters:

Name Type Attribute Description
type String

The type of sound that should be removed. Can be 'sound', 'track', 'font', 'beatTrack', or 'sampler'.
name String

The name of the sound that should be removed.
addon/services/audio.js:390

public stopAll(type='tracks')

Gets all instances of requested type and calls Sound/stop:method on each.

Parameters:

Name Type Attribute Description
type='tracks' String

The type of the register that you wish to stop all instances of. Can be 'tracks', or 'sounds'.

Private Methods

addon/services/audio.js:671

private _createNoteObjectsForFont(audioData, instrumentName): Array

Takes an array of arrays, each inner array acting as a key-value pair in the form [noteName, audioData]. Each inner array is transformed into a Note and the outer array is returned. This method also sets each note on it's corresponding instrument Map instance by name. Each note is playable as seen in the example.

Parameters:

Name Type Attribute Description
audioData Array

Array of arrays, each inner array like [noteName, audioData].
instrumentName String

Name of the instrument each note belongs to. This is the name that will be used to identify the instrument on the fonts register.

Return:

Array

Returns an Array of Notes

Example:

audioService.getFont('font-name').play('Ab5');
addon/services/audio.js:459

private _createSoundFor(type, props): Sound | Track | BeatTrack

Creates an Audio Class instance (which is based on which "type" is specified), and passes "props" to the new instance.

Parameters:

Name Type Attribute Description
type String

The type of Audio Class to be created.
props Object

POJO to pass to the new instance

Return:

addon/services/audio.js:612

private _createSoundsArray(name, srcArray): Promise | Array

Accepts an array of URLs to audio files and creates a Sound instance for each.

Parameters:

Name Type Attribute Description
name String

The base-name of the sound. If one were loading up multiple kick drum samples, this might be 'kick'.
srcArray Array

An array of strings. Each item being a URL to an audio file that should be loaded and turned into a Sound instance.

Return:

Promise | Array

A promise that resolves to an array of Sound objects.
addon/services/audio.js:635

private _extractDecodedKeyValuePairs(notes): Array

Takes an array of base64 encoded strings (notes) and returns an array of arrays like [[name, audio], [name, audio]]

Parameters:

Name Type Attribute Description
notes Array

Array of base64 encoded strings.

Return:

Array

Returns an Array of arrays. Each inner array has two values, [noteName, decodedAudio].
addon/services/audio.js:436

private _getRegisterFor(type): Map

Gets a register by it's type.

Parameters:

Name Type Attribute Description
type String

Which register to return.

Return:

Map
addon/services/audio.js:487

private _load(name, src, type): Promise | Sound | Track | BeatTrack

Loads and decodes an audio file, creating a Sound, Track, or BeatTrack instance (as determined by the "type" parameter) and places the instance into it's corresponding register.

Parameters:

Name Type Attribute Description
name String

The name that the created instance should be registered as.
src String

The URI location of an audio file. Will be used by "fetch" to get the audio file. Can be a local or a relative URL
type String

Determines the type of object that should be created, as well as which register the instance should be placed in. Can be 'sound', 'track', or 'beatTrack'.

Return:

Promise | Sound | Track | BeatTrack

Returns a promise which resolves to an instance of a Sound, Track, or BeatTrack
addon/services/audio.js:589

private _loadBeatTrack(name, srcArray): Promise | BeatTrack

Creates a BeatTrack instance from an array of URLs.

Parameters:

Name Type Attribute Description
name String

The name that this BeatTrack instance will be registered as on the _beatTracks register.
srcArray Array

An array of strings that specify URLs to load as Sounds.

Return:

Promise | BeatTrack

A promise that resolves to a BeatTrack instance.
addon/services/audio.js:530

private _loadFont(instrumentName, src): Promise | Array

  1. Creates a Font instance and places it in the fonts register.
  2. Loads a soundfont file and decodes all the notes.
  3. Creates a Note instance for each note.
  4. Places each note on the font, using the note's identifier as key.
  5. Returns a promise that resolves to an array of properly sorted Note object instances.

The notes are sorted the way that they would appear on a piano. In the example, you can see how the note Ab1 from the font-name soundfont would be played:

Parameters:

Name Type Attribute Description
instrumentName String

The name that you will refer to this sound font by.
src String

The URI location of a soundfont file. Will be used by "fetch" to get the soundfont file. Can be a local or a relative URL.

Return:

Promise | Array

Returns a promise that resolves when the sound font has been successfully decoded. The promise resolves to an array of sorted note names.

Example:

audio.getFont('font-name').play('Ab1');