The Applet

Controlling the Applet through API

CONCEPTS

With the API extension of WebSynth Audio, the WSAudio applet exposes public methods that you may call from external programs. This feature lets you create your own visual interface to the WSAudio engine, directly on the web page.

You may choose to monitor/control the WSAudio engine state through another Java applet of yours, or through JavaScript code.

The following additional parameters of the applet becomes useful only if you're planning to use the API extension.

AUTOSTART

When using the API extension, you will tipically want to start/stop the applet engine by yourself. This parameter will instruct
the engine not to start any stream at startup, even in presence of the STREAM param. You may later call the startPlaying method to
start the engine.

SYNTAX: <PARAM NAME=AUTOSTART VALUE=false>

JSMETHOD

This parameter can be used when you need callbacks to your JavaScript code from the audio engine to receive events.
As you will see later, you have methods to schedule time notifications from the audio engine.
You may specify any combination of the available events and associate them a function name. These funcions will have to be
reachable by the applet in the JavaScript sense. Typically these functions will be globally declared in the html page containing
the applet.

SYNTAX: <PARAM NAME=JSMETHOD VALUE="eventname=funcname eventname=funcname ...>

eventname may assume the following values:

appletstart - the specified function will be called after the applet "start" method has completed succesfully. This give you
a safe opportunity to get the applet instance (document.applets["name"]) only when it is actually valid.

appletstop - the specified function will be called after the applet "stop" method has completed succesfully. This give you
a safe opportunity to track the validity of the applet instance.

audiotime - this event, together with the addEvent method of the applet, constitutes the synchronization framework for
JavaScript. The specified function will be called on every scheduled time event. The function will have to be declared
with one parameter that will hold a String information of the event.

audioend - the specified function will be called when the audio engine has finished playing. This may happen becase
the end of file has been reached, or because you explicitly issued a "stopPlaying" on the applet.

PUBLIC METHODS

The public methods available, can be called both by another Applet or by JavaScript code.

CALLING THROUGH JAVASCRIPT

In JavaScript you will use the following code:

<HTML> <SCRIPT> var wsaudio=null; function wsTime(msg) { if (wsaudio!=null) { ... } } function wsEnd() { if (wsaudio!=null) { ... } } function wsStart() { wsaudio=document.applets["WSAudio"]; ... } function wsStop() { wsaudio=null; ... } function myFunction() { if (wsaudio!=null) { wsaudio.addEvent(50,"msg1"); wsaudio.addEvent(100,"msg2"); wsaudio.addEvent(150,"msg3"); wsaudio.addEvent(200,"msg4"); wsaudio.startPlaying("/sounds/streams/file.wsa"); } } </SCRIPT> <BODY> <APPLET ARCHIVE=wsaudio.jar CODEBASE=/applets CODE=com.sonicle.wsaudio.WSAudio NAME="WSAudio" MAYSCRIPT WIDTH=2 HEIGHT=2> <PARAM NAME=JSMETHOD VALUE="appletstart=wsStart appletstop=wsStop audioend=wsEnd audiotime=wsTime"> </APPLET> <FORM> <INPUT TYPE=Button VALUE="Click!" NAME="actionButton" onClick=myFunction()> </FORM> </BODY> </HTML>....

The wsaudio instance is set only when the applet notifies that it is ready to run.
This will prevent JavaScript errors referencing an invalid applet.

CALLING THROUGH JAVA APPLETS

The following technical description shows how to control WSAudio through another Java applet, and requires some knowledge of the Java programming language.
NOTE: to compile successfully the following examples you will need to have a copy of the WSAudio package on your machine, and make it visible to the Java VM through the CLASSPATH environment variable (set CLASSPATH = C:\alu\classes;%CLASSPATH%).

The WSAudio applet, may be used as a normal component ignoring the fact that it extends applet.
When using it through API we won't need its Applet features.
To create it you could simply do:

import java.applet.*; import com.sonicle.wsaudio.*;

public class Player extends Applet {

... WSAudio wsaudio=new WSAudio(); ... }

From now on, we can use wsaudio to call its API methods.
You will usually register yourself as a listener to the engine, to monitor its current state and update your visual objects.
For example:

import java.applet.*; import com.sonicle.wsaudio.*;

public class Player extends Applet implements WSAudioListener {

... WSAudio wsaudio=new WSAudio(); wsaudio.setListener(this); ... //implementation of the WSAudioListener interface ... ... }

WSAudioListener INTERFACE DESCRIPTION

public void streamOpening()

This function is called by the engine before trying to open the stream, for example after you call
startPlaying().

public void connectionRefused()

You receive this call if the stream cannot be opened because the host refused the connection.

public void streamOpened();

Once the stream host has been contacted, you receive this call. Now the engine will start parsing
the content.

public void invalidStream()

If the content is not valid, you receive this call.

public void sectionSelected(int section)

If the content is valid, the engine tries to select the preferred section, or the first one available if problems
araise during repositioning on the file. You receive this event once the engine has selected the section.

public void streamStarted()

After the section is selected, the engine begins to read actual audio data. The AudioPlayer is not started
until the buffering time has elapsed.

public void audioStarted()

The AudioPlayer has been actually started.

public void streamStopped()

The stream has been stopped.

public void streamRepositioning()

The engine is trying to reposition the stream. To do this, the current connection is closed, and a new one is
created for repositioning. During this time, the server may refuse the connection.

public void timeEvent(String message)

For each scheduled time event (see addEvent), once the specified 10th of audio seconds has passed, the engine
calls timeEvent on the listener with the requested message.

public void positionChanged(long position)

The engine calls this method while playing, to notify the stream position as listened by the user.

public void appletStarted()

Once the browser starts the applet, you get notified by this call. This may be used if you decide to control
the engine as a separate applet sharing the same HTML page.

public void appletStopped()

Once the browser stops the applet, you get notified by this call. This may be used if you decide to control
the engine as a separate applet sharing the same HTML page.

public void buffering()
This function is called by the engine when the connetion becomes slow, and not enough encoded data are available.

METHODS DESCRIPTION

void startPlaying()

Start playing the stream specified in the STREAM param, if any, or the last played one through startPlaying(url).

void startPlaying(String StreamURL)

Start playing the file located at the specified URL. StreamURLcan be any valid Java URL. The referenced file must be a WSAudio supported file. This will override the STREAM param of the applet, if any.

void stopPlaying()

Stop playing the stream, if any. This method will stop all of the WSAudio threads currently running (downloading, decoding and playing).

void setPaused(boolean b)

Pause (b=true) or restart (b=false) playing the current stream.
When paused, the applet will stop returning audio data to the audio engine, while continuing download and decode of the stream until buffer space is available.
When restarted, the applet will continue returning audio data beginning at the point it was paused.

String getStreamURL()

Returns the String URL representation of the currently playing WSAudio file, if any.

long getPlayLength()

Returns the total length of the current stream in number of samples.
This maybe 0 initially, if the engine has not read the header (status=STATUS_UNKNOWN, see below).

long getPlayPosition()

Returns the number of samples that had already been played.

long getPlayFrequency()

The nearest frequency to the desired one is returned, depending on the JVM capablities.
The desired one may be the one determined by the content, or the one specified through setFrequency.
Note: JVMs previous to the 1.2 will always scale to 8KHz, because of VM limitations. The Java2 VM will
match the actual desired frequency.

int getPlayChannels()

Returns the actual playing channels.
Note: JVMs previous to the 1.2 will always scale to 1 channel, because of VM limitations. The Java2 VM will
match the actual channels of the content.

void setPreferredSection(int s)

The new WSA files are multi content files. They encode both 14.4 and 28.8 sections, and new ones will be
addeded in the future. With this method you tell the audio engine which of the sections you whish to play
(0=14.4, 1=28.8) before starting the stream.
This content selection requires repositioning on the file through HTTP byte ranges. If this fails, the first section
available on the file will be played.
For older SA or MA files, the selected section will always be 0.

long getPreferredSection(int s)

Returns the last desired section number.

String getSectionDescription(int s)

Returns a description of the content of the specified section number. This is valid after the sectionSelected event
has been received by the listener.

int getSectionsCount()

Returns the number of sections contained in the stream file. This is valid after the sectionSelected event
has been received by the listener.

String getTitle()

Returns the title contained in the stream file, if any.

boolean isAudioStarted()

Returns true if the AudioPlayer has been started. This may be false if still in wait state or if the header has not been
read yet.

booleain isRealized()

Returns true if WSAudio has already determined the type of decoder to be used, and created its instance.
The decoder is normally created once the section has been selected (sectionSelected event).

restartPlayingAt(double pos)

Requests for repositioning. The position must be a value in the range 0.0-1.0 where 0.0 is the start of the stream, and
1.0 is the end.

int getStatus()

Returns the current status of the applet, as one of the following WSAudio public constants:

WSAudio.STATUS_UNKNOWN
The applet is in an unknown state. This may be in two cases:
- the applet has been just instantiated and is not playing anything, yet.
- the donwloading thread has not read the header of the audio file, yet (no length or frequency information available).

WSAudio.STATUS_BUFFERING
The applet is not receiving enough data to be decoded and the audio engine has already played the last available samples. This can happen when the connection is too slow.

WSAudio.STATUS_PLAYING
The applet is happily playing audio data.

WSAudio.STATUS_PAUSED
The applet has been paused calling the setPaused(true)method. Note that the applet never decides to pause by himself.

WSAudio.STATUS_EOF
The applet has finished downloading, decoding and playing the stream.

WSAudio.STATUS_REFUSED
The server hosting the audio files refused connection for some reason.

long getFrequency()

Returns the frequency of the output audio data in Hz. This method will return valid data only after the startPlayingmethod has been invoked.
This rapresents the resampling frequency regardless of actual output frequency of the AudioPlayer.

void setFrequency(long hz)

Sets the resampleing frequency of the audio data in Hz. If non zero, output frequency will be forced at the specified value. If zero, output frequency
will be the one of the selected content.
NOTE: this method must be called before calling the startPlayingmethod, or it will have no effect on the current stream.

long getBufferingTime()

Returns the initial buffering time.

void setBufferingTime(long ms)

Sets the initial buffering time in milliseconds, that is the time the applet will wait before actually producing audio. When calling the startPlaying method, the applet will start downloading and decoding the stream, but will wait the specified amount of milliseconds before starting the audio engine. This can help slow connection or very slow machines.

double getVolume()

Returns the current output volume (0.0-1.0). Default is 1.0.

void setVolume(double v)

Sets the output volume (0.0-1.0).

void setListener(WSAudioListener l)

Sets the listener for WSAudio events.

void addEvent(long decsecs,String msg)

When sinchronizing Java/JavaScript code to the audio engine, you will schedule time events through this method.
Specify tenth of seconds since the beginning of audio and the String message to be delivered.
The String message will be passed to the time event function. It is up to you to give meaning to this message.
You will need to specify the JavaScript function with the JSMETHOD parameter for the event to be delivered
to JavaScript.

void addRequestLine(String str)

If your system implements security schemes, you may find that the applet is not sending correct keys to the web server enabling communication. These keys are usually HTTP request lines containing encrypted strings. You may use this function to add these request lines to the applet.

void clearRequestLines()

It may happen that the request keys used for a previous stream become invalid. You may clear any previous request line and add new ones with this method.

PLAYER EXAMPLE SOURCE CODE

The Player.java source code is a true example for a simple WebSynth Player.
You may use this source code freely.