Accessing a Plug-in’s Elements

Plug-ins can be controlled by JavaScript (and Java) if they were developed with support for LiveConnect. Although it is possible to provide public variables in a plug-in, most plug-ins provide methods that you can use in JavaScript. The general JavaScript syntax for invoking a plug-in’s methods is:

document.embedName.methodName(arguments)
document.embeds[index].methodName(arguments)

JavaScript and LiveAudio

LiveAudio is LiveConnect-enabled. Generally speaking, LiveAudio provides two sets of JavaScript methods that enable you to interact with a LiveAudio instance via JavaScript:

• Methods to control a loaded LiveAudio plug-in instance. These functions return Boolean values, but the returned value is rarely ever referred to.
• Methods that indicate the current state of a loaded LiveAudio plug-in instance.

Let’s take a look at the JavaScript methods that control a LiveAudio plug-in instance.

play(loop, 'URL_of_sound')

loop is a Boolean value or an integer. If set to true, the specified sound file is played repeatedly in an infinite loop. If set to false, the sound plays once and stops at the end of the track. If you specify an integer as the first argument for this method, LiveAudio plays the sound the specified number of times.

URL_of_sound is the URL of the desired sound file.

This method plays a specified number of times.

stop()

Stops the current sound playing.

pause()

Pauses and unpauses the current sound playing. Invoking this method when the sound is paused causes it to continue playing from where it was paused.

start_time(seconds)

seconds is an integer specifying the number of seconds from the beginning where the sound should start playing. Use this method if you do not want the sound to start playing from the beginning. start_time() does not actually start playing a sound but rather specifies where it should start when it starts.

end_time(seconds)

seconds is an integer specifying the number of seconds from the end where the sound should stop playing. Use this method if you do not want the sound to stop playing at the natural end of the sound track.

setvol(percent)

percent is an integer from 0 to 100, specifying the desired volume (0 is silent, 100 is the loudest).

This method sets the current volume of a LiveAudio instance, whether or not it is currently playing.

fade_to(to_percent)

to_percent is an integer specifying the final volume to which the sound fades. Use this method to fade from the current volume to the specified one.

fade_from_to(from_percent, to_percent)

from_percent is an integer specifying the initial volume where the fade starts. to_percent is an integer specifying the final volume to which the sound fades. Use this method to fade from a specified volume to another specified volume (both provided as arguments).

start_at_beginning()

Use this method to override a start_time(). That is, if you used the start_time() to specify where the sound should start playing, this method cancels that. It is equivalent to start_time(0).

stop_at_end()

Similarly, this method overrides an end_time(), and is equivalent to end_time(0).

There are also JavaScript methods that indicate the current state of a LiveAudio plug-in instance. Except for GetVolume(), which returns an integer, these methods return Boolean values.

IsReady()

This method returns true if the plug-in instance has completed loading, and false otherwise.

IsPlaying()

This method returns true if the sound is currently playing, and false otherwise.

IsPaused()

This method returns true if the sound is currently paused, and false otherwise.

GetVolume()

This method returns the current volume as a percentage. The returned value is an integer.

Note that all values are Java-equivalent data types. That is, a method that returns an integer actually returns an int. These data types are wrapped to JavaScript types, as explained earlier in the chapter.

Since you already know how to use the preceding methods, check out Example 31-5 to see how you can use them to create a useful JavaScript application.