Audio Support

Determining device audio support.

UJML provides several different ways to determine the device context for playing sounds. See Audio Elements.

Determining if the device can play sounds

Some devices do not support the x-sound element, meaning that they cannot play sounds. The _isSupported() function may be called with &_X_SOUND; device information entity to determine if a device supports the x-sound element. See _isSupported() function, Feature Support Information Entities.

Determining supported file types

Different devices support different sound file types. See Audio Elements. The _isSupported() function may be called with one of the file type feature support entities to determine if it supports that sound file type. See _isSupported() function, Feature Support Information Entities. You can determine a device's preferred sound file type by calling the _getStringProperty() function with the &_PROPERTY_STRING_PREFERRED_SOUND_EXTENSION; device information entity. See _getStringProperty() function, String Device Information Entities.

Use the _sound_url() function to append the file extension for the device's preferred file format to a file name. See _sound_url() function. For example calling '_sound_url("http://myserver/app/startupsound")' on a device where the preferred file extension is '.mp3' will return 'http://myserver/app/startupsound.mp3'.

Example

The following example shows how to load a variable with the URL of an audio file. It is part of the events.ujml sample.

Copy Code

mSoundURL = _sound_url("snd/sound");

The following example shows how to load the resource for a particular sound file format and, if it is not available, makes another attempt using a fallback sound file format. It is part of the events.ujml sample.

Copy Code

<state var="sLoadSounds">
    <transition value="true">
        <resources>
            <resource>
                <url><eval>mSoundURL</eval></url>
                <event name="onResourceAvailable">
                    <script>
                        showMessage(_strcat("onResourceAvailable: ", mSoundURL));
                        mSoundLoaded = true;
                    </script>
                </event>
                <event name="onResourceError">
                    <variables>
                        <var name="preferredFormat" type="string"/>
                    </variables>
                    <script>
                        showMessage(_strcat("onResourceError: ", mSoundURL));

                        preferredFormat =
                            _getStringProperty(&_PROPERTY_STRING_PREFERRED_SOUND_EXTENSION;);

                        // Try for a fallback URL?
                        if (!mSoundFallback)
                        {
                            // See if there is a fallback we can do.
                            if (!_streq(preferredFormat, "mid"))
                            {
                                // Try .mid
                                if (_isSupported(&_SOUND_TYPE_MID;))
                                {
                                    mSoundURL = "snd/sound.mid";
                                    mSoundFallback = true;
                                    _clear_state(sLoadSounds);
                                    sLoadSounds = true;
                                }
                            }
                            else if (!_streq(preferredFormat, "wav"))
                            {
                                // Try .wav
                                if (_isSupported(&_SOUND_TYPE_WAV;))
                                {
                                    mSoundURL = "snd/sound.wav";
                                    mSoundFallback = true;
                                    _clear_state(sLoadSounds);
                                    sLoadSounds = true;
                                }
                            }
                            // Are we still not doing a fallback?
                            if (!mSoundFallback)
                            {
                                sLoadSounds = false;
                            }
                        }
                        else
                        {
                            sLoadSounds = false;
                        }
                    </script>
                </event>
            </resource>
        </resources>
    </transition>
</state>