Wikitude SDK API Reference

API Docs for: 8.5.0
Show:

Sound Class

Extends ARchitectObject
Module: AR

An instance of this class represents a sound file, specified by a URI.

An instance of Sound traverses through various states during its lifetime, which are defined in AR.CONST.STATE. At each point in time, a Sound instance has exactly one of the following states:

  • INITIALIZED
  • LOADING
  • LOADED
  • PLAYING
  • PAUSED
  • ERROR

The typical state transitions during the lifecycle of a Sound instance is as follows:

  • Creation of the object with new AR.Sound(...) -> INITIALIZE
  • sound.load() -> LOADING
  • Loading finished -> LOADED
  • Start playing -> PLAYING
  • Pause playing -> PAUSED
  • Resume playing -> PLAYING
  • Playing finished -> LOADED
  • Call sound.destroy() -> Object destroyed

On important state changes, a trigger (onLoaded(), onFinishedPlaying(), onError()) will be called by the system. A developer can react on these events by providing custom logic to these triggers. In case no custom logic is applied to a trigger, the trigger will not fire. The triggers can be passed on creation time, or added later.

In case no preloading should be performed, a Sound file can also be played right after it has been initialized. The Sound file will then be streamed and not stored on the device. Keep in mind that this might cause a delay in playing the file, as it has to be loaded first. Please note that the state will not change to either LOADING, LOADED, PLAYING or PAUSED, it will remain in INITIALIZED state as it is streamed onto the phone. Still, the triggers will fire.

Example:
var sound = new AR.Sound("http://www.myuri.com/sound.mp3", {
  onLoaded : function(){sound.play();},
  onError : function(){
    // alert the user that the sound file could not be loaded
    },
});
sound.onFinishedPlaying = function(){alert("Playing finished");};
sound.load();

Note that reloading the content is not possible - calling sound.load() while the sound file is in a state different from INITIALIZED does not have any effect.

Executing sound.play() while the file is in a state different from LOADED, PAUSED or INITIALIZED will have no effect.

When a Sound file in LOADED state is no longer needed, it is essential to call destroy() to clean up ressources on the device.

When a Sound file has been paused, there are two ways to resume playing: Calling resume() will continue playing at the time the file was paused. Calling play() will start playing the file from the very beginning. If a Sound file is initialized, and resume() is called, it will have the same effect as play(1).

The ERROR state indicates that a problem was detected either while loading or playing the file.

Constructor

Sound

(
  • uri
  • options
)

Parameters:

  • uri String

    The uri to the audio file.

  • options Object optional

    Setup-Parameters to customize additional object properties.

    Accepted options-properties are

Methods

destroy

()

Inherited from ARchitectObject

Destroys the object.

load

()

Initiate the loading process of the sound file. The loaded file will be stored on the device for immediate playing (and thus will use system ressources). It is good practice to destroy (sound.destroy()) the sound files when they are no longer needed (for example in context.onExit()).

pause

()

Pauses playing this sound file. To resume from the time the file was paused, call resume(). If play() is called on a paused file, the play will start from the very beginning.

play

(
  • loopTimes
)

Plays the sound file.

Parameters:

  • loopTimes (defaults to 1) Number optional

    Defines how often the sound file should be played in a row. A negative value indicates an infinite looping.

resume

()

Allows a paused sound file to resume playing from the time the file was paused. In any other cases, resume() has the same effect as calling play(1).

stop

()

Stops playing this sound file. If play() was called multiple times on the same file, stop() will stop every running playback of this file. onFinishedPlaying() will not be triggered after stop() has been called.

Properties

destroyed

Boolean

Inherited from ARchitectObject

Indicates if the object has already been destroyed.

state

Number

The state the Sound object is currently in. The property is read-only and will be modified by the system. Custom modifications will result in an exception. Valid values are defined in AR.CONST.STATE

Events

onError

The trigger will fire when the Sound file changed its state to ERROR.

The trigger is null by default, and will thus result in no action executed when the trigger fires. A developer can add custom functionality by assigning a custom function to onError.

onFinishedPlaying

The trigger will fire when the Sound file changed its state from PLAYING to either LOADED or INITIALIZED.

The trigger is null by default, and will thus result in no action executed when the trigger fires. A developer can add custom functionality by assigning a custom function to onFinishedPlaying.

onLoaded

The trigger will fire when the Sound file changed its state from LOADING to LOADED.

The trigger is null by default, and will thus result in no action executed when the trigger fires. A developer can add custom functionality by assigning a custom function to onLoaded.