Audio Elements

Audio elements are UJML tags that define the audio objects played by a UJML application.

Audio objects are digital audio files that your UJML application can play on a supported device. You can determine if the device supports sounds by calling the _isSupported() function with the &_X_SOUND; device information entity to determine if a device supports the x-sound element. See Audio Support, _isSupported() function, Feature Support Information Entities, x-sound.

The play element is a UJML tag that declares one or more sounds to play when the containing state transition activates. See State Transitions, play. On supported devices, the sounds will play until the sound is complete or the state transitions out. The sounds only play once when the state transition becomes active. They will not replay unless the state transitions out and becomes active again. Within the play event, you reference the URL of your sound file using an x-sound element containing a url element. See x-sound, url.

File types

Different devices support different audio file types. You can determine available and preferred file types at run time. See Determining Device Context, Audio Support.

The easiest way to support multiple devices is to supply the same sound in different file formats. You can then call the _sound_url() function to append the file extension for the device's preferred file format to the file name. See _sound_url() function. For example calling '_sound_url("http://myserver/app/beep")' on a device where the preferred file extension is '.wav' will return 'http://myserver/app/beep.wav'.

Audio events

The onSoundStarted and onSoundFinished events will fire when the sounds start playing and finish playing. See Handling Events, onSoundStarted, onSoundFinished.

Note: There is no way to discover which audio object caused the event to fire.

Example

The following example shows how to play a sound file referred to by a variable value. It is part of the lunarlander.ujml sample.

Copy Code

<play>
    <x-sound>
        <url><eval>mEngineSoundURL</eval></url>
    </x-sound>
</play>

The following example shows how to handle an onSoundStarted event by showing a message. It is part of the events.ujml sample.

Copy Code

<event name="onSoundStarted">
    <script>
        showMessage("onSoundStarted");
    </script>
</event>

The following example shows how to handle an onSoundFinished event by showing a message. It is part of the events.ujml sample.

Copy Code

<event name="onSoundFinished">
    <script>
        showMessage("onSoundFinished");
    </script>
</event>