API Docs for: v0.1.0
Show:

AudioPlayer Class

Extends Object

Grapefruit Audio API, provides an easy interface to use HTML5 Audio The GF Audio API was based on Howler.js

Constructor

AudioPlayer

(
  • manager
  • audio
  • [settings]
)

Parameters:

  • manager AudioManager

    AudioManager instance for this audio player

  • audio Object

    The preloaded audio file object

    • data ArrayBuffer | Audio

      The actual audio data

    • webAudio Boolean

      Whether the file is using webAudio or not

    • decoded Boolean

      Whether the data has been decoded yet or not

  • [settings] Object optional

    All the settings for this player instance

    • [autoplay=false] Boolean optional

      Whether to automatically start playing the audio file

    • [loop=false] Boolean optional

      Whether the audio should loop or not

    • [pos3d] Array optional

      The 3d position of the audio to play in the form [x, y, z]

    • [sprite] Object optional

      The audio sprite, if this audio clip has multiple sounds in it. This object is in the form { 'sound': [start, duration] }, and you can use them with .play('sound').

Methods

_activeNode

() AudioPlayer private

Get the first active audio node.

Returns:

AudioPlayer:

Audio node.

_clearEndTimer

(
  • timerId
)
private

Clear 'onend' timeout before it ends.

Parameters:

  • timerId Number

    timerId The ID of the sound to be cancelled.

_doFadeStep

() private

Performs a step in the fade transition

_drainPool

() private

If there are more than 5 inactive audio nodes in the pool, clear out the rest.

_inactiveNode

(
  • cb
)
private

Get the first inactive audio node. If there is none, create a new one and add it to the pool.

Parameters:

  • cb Function

    callback Function to call when the audio node is ready.

_load

() AudioPlayer private

Load the audio file for this player, this is called from the ctor there is no reason to call it manually.

Returns:

_nodeById

() AudioPlayer private

Get an audio node by ID.

Returns:

AudioPlayer:

Audio node.

_setupAudioNode

() Object private

Setup the gain node and panner for a Web Audio instance.

Returns:

Object:

The new audio node.

emit

(
  • type
  • data
)
Mixed chainable

Emits an event which will run all registered listeners for the event type

Parameters:

  • type String

    The event name to emit

  • data Mixed

    Any data you want passed along with the event

Returns:

Mixed:

Returns itself.

fade

(
  • from
  • to
  • len
  • [id]
  • [callback]
)
AudioPlayer chainable

Fade a currently playing sound between two volumes.

Parameters:

  • from Number

    The volume to fade from (0.0 to 1.0).

  • to Number

    The volume to fade to (0.0 to 1.0).

  • len Number

    Time in milliseconds to fade.

  • [id] String optional

    The play instance ID.

  • [callback] Function optional

    Fired when the fade is complete.

Returns:

AudioPlayer:

Returns itself.

getPosition

(
  • [id]
)
Number

Get the position of playback.

Parameters:

  • [id] String optional

    The play instance ID.

Returns:

Number:

getVolume

() Number

Returns the current volume of the player

Returns:

Number:

The current volume

loadSound

(
  • buffer
)
private

Finishes loading the Web Audio API sound and fires the loaded event

Parameters:

  • buffer Object

    The decoded buffer sound source.

mute

(
  • [id]
)
AudioPlayer chainable

Mute this sound.

Parameters:

  • [id] String optional

    The play instance ID.

Returns:

AudioPlayer:

Returns itself.

off

(
  • type
  • listener
)
Mixed chainable

Removes a listener function for an event type

Parameters:

  • type String

    The event name to emit

  • listener Function

    The function to remove

Returns:

Mixed:

Returns itself.

on

(
  • type
  • listener
)
Mixed chainable

Registers a listener function to be run on an event occurance

Parameters:

  • type String

    The event name to listen for

  • listener Function

    The function to execute when the event happens

Returns:

Mixed:

Returns itself.

once

(
  • type
  • listener
)
Mixed chainable

Registers a one-time callback for an event

Parameters:

  • type String

    The event name to listen for

  • listener Function

    the callback to call when the event occurs

Returns:

Mixed:

Returns itself.

pause

(
  • [id]
  • [timerId]
)
AudioPlayer chainable

Pause playback and save the current position.

Parameters:

  • [id] String optional

    The play instance ID.

  • [timerId] String optional

    Clear the correct timeout ID.

Returns:

AudioPlayer:

Returns itself.

play

(
  • [sprite]
  • [callback]
)
AudioPlayer chainable

Play a sound from the current time (0 by default).

Parameters:

  • [sprite] String optional

    Plays from the specified position in the sound sprite definition.

  • [callback] Function optional

    Returns the unique playback id for this sound instance.

Returns:

AudioPlayer:

Returns itself.

refreshBuffer

(
  • loop
  • [id]
)
private

Load the sound back into the buffer source.

Parameters:

  • loop Array

    Loop boolean, pos, and duration.

  • [id] String optional

    The play instance ID.

seek

(
  • pos
  • [id]
)
AudioPlayer chainable

Set the position of playback.

Parameters:

  • pos Number

    The position to move current playback to.

  • [id] String optional

    The play instance ID.

Returns:

AudioPlayer:

Returns itself.

setMuted

(
  • muted
  • [id]
)
AudioPlayer chainable

Set the muted state of this sound.

Parameters:

  • muted Boolean
  • [id] String optional

    The play instance ID.

Returns:

AudioPlayer:

Returns itself.

setPosition

(
  • x
  • y
  • z
  • [id]
)
AudioPlayer chainable

Set the 3D position of the audio source. The most common usage is to set the 'x' position to affect the left/right ear panning. Setting any value higher than 1.0 will begin to decrease the volume of the sound as it moves further away. NOTE: This only works with Web Audio API, HTML5 Audio playback will not be affected.

Parameters:

  • x Number

    The x-position of the playback from -1000.0 to 1000.0

  • y Number

    The y-position of the playback from -1000.0 to 1000.0

  • z Number

    The z-position of the playback from -1000.0 to 1000.0

  • [id] String optional

    The play instance ID.

Returns:

AudioPlayer:

Returns itself.

setVolume

(
  • vol
  • [id]
)
AudioPlayer chainable

Sets the current volume of the player

Parameters:

  • vol Number

    The current volume

  • [id] String optional

    The play instance ID.

Returns:

AudioPlayer:

Returns itself.

stop

(
  • [id]
  • [timerId]
)
AudioPlayer chainable

Stop playback and reset to start.

Parameters:

  • [id] String optional

    The play instance ID.

  • [timerId] String optional

    Clear the correct timeout ID.

Returns:

AudioPlayer:

Returns itself.

unmute

(
  • [id]
)
AudioPlayer chainable

Unmute this sound.

Parameters:

  • [id] String optional

    The play instance ID.

Returns:

AudioPlayer:

Returns itself.

Properties

_duration

Number private

The full duration of the file to play

_file

Object private

The preloaded audio file object

_loaded

Boolean private

Has this player data been loaded?

_nodes

Array private

The actual player nodes, these are either WebAudio Nodes or HTML5 Audio elements.

_onendTimer

Array private

Array of timeouts to track end events

_volum_manager

AudioManager private

The manager of the player

_volume

Number private

The current volume of the player

_webAudio

Boolean private

Does the browser support WebAudio API

autoplay

Boolean

Play the audio immediately after loading

Default: false

format

String

Override the format determined from the extension with this extension

Default: null

game

Game

The game instance this player belongs to

key

String

The cache key that uniquely identifies this piece of audio

loop

Boolean

Replay the audio immediately after finishing

Default: false

pos3d

Array

A 3D position where the audio should sound like it is coming from

Default: [0, 0, -0.5]

sprite

Object

A sound sprite that maps string keys to [start, duration] arrays. These can be used to put multiple sound bits in one file, and play them separately

Default: {}

src

String

The source of the audio, the actual URL to load up

volume

Number

The volume of the audio player

Default: 1

Events

end

Fired when audio finishes playing

Event Payload:

  • id String

    The id of the node that has finished playing

paused

Fired when audio is paused

Event Payload:

  • id String

    The id of the node that is paused

play

Fired when audio starts playing

Event Payload:

  • id String

    The id of the node that is used to play the audio

ready

Fired when the player is ready to play

Event Payload:

  • source String

    The source URL that will be used as the audio source