wyvern.common.net
Interface RemoteAudio

All Known Subinterfaces:

Commandable, Monster, Player

All Known Implementing Classes:

AbstractCommandable, MonsterImpl, PlayerImpl

public interface RemoteAudio

Remote interface for starting, stopping, or modifying an audio track on a client.

Some definitions:

• "Audio" refers to music, alerts, and sounds.

• A "Music" is a sound that's considered the "background music". Only one background track can be playing at a time. You can adjust the gain (volume), stop it, or start another track. The background music is dependent on the player's state: which map they're in, whether they're in combat, or whether something interesting just happened, such as dying or solving a quest.

  Music is generally not time-sequenced: players in the same map may not be hearing the same music, or may be hearing it playing at completely different points in the soundtrack.

• An "Alert" is a simple sound, used for notifications, such as message beeps, or a bell when your character has run low on health or some other vital stat.

  Alerts are very simple: once one is started, it can't be stopped or modified, and the client will play it until it's finished. The client does not send a notification back to the server when it has finished playing an Alert.

  You can specify optional parameters to an Alert when you play it, but once it's sent to the client, you can no longer modify them for that alert sound. Multiple alerts can be playing at the same time on the client, and alerts are usually only heard by one player.

• A "Sound" refers to a physical sound effect, produced by something inside the game. Sounds have a location, and can be heard differently by different players in the same map.

  Unlike Music and Alerts, Sounds each have a unique ID sent to the client so that they can be stopped or modified (e.g. changing the volume). This is because if a player leaves a room where a sound is playing, the server needs to shut it off immediately for that player. The client must send a notification back when it has finished playing a Sound, because the server needs to be able to stop listening for the player to move towards or away from the sound.

Our use of the terms "Music", "Alert" and "Sound" depends on their usage, not on their file format. A Sound could anything audible, from a sampled sound of a door closing to a midi file of a harp playing. Similarly, Music and Alerts can be in any audio format supported by the game clients.

When you issue a request to play an audio track of any kind, the client will check if it's missing the file, or has an outdated version. If so, it sends a request to the server to begin downloading the file. Each client implementation can decide what it wants to do at that point. Usually it will skip the track if it doesn't have it at all, and play the outdated version if it has one. If it skips the track, it will still send a notification back to the server if it was a Music or Sound track.

Version:

1.0, Jul 22, 2003

Author:

Steve Yegge

Field Summary

static double	DEFAULT_ALERT_GAIN Volume level for Alerts.
static int	DEFAULT_ALERT_REPEAT_DELAY Alerts have no repeat delay by default, since they don't repeat.
static int	DEFAULT_ALERT_REPEATS Alerts just play once, by default.
static double	DEFAULT_GAIN Default gain of 0.5 means "not louder or softer than the file would normally play on the user's computer." 0.0 is silent, 1.0 is max volume.
static int	DEFAULT_REPEAT_DELAY Default amount of time to wait between repeats on soundtracks, if not specified by the owner.
static int	DEFAULT_REPEATS Default number of repeats to perform, if not otherwise specified, for map background music

Method Summary

void	pauseSound(java.lang.String id) Pauses a particular sound.
void	playAlert(java.lang.String path) Plays the specified sound file on the client, one repeat, no delay, and the default gain.
void	playAlert(java.lang.String path, int repeats, int repeatDelay, double gain) Plays the specified alert with custom parameters.
void	playDefaultMusic() The player has switched maps, so figure out the default background music to be playing, and plays it.
void	playPriorityMusic(java.lang.String path) Sets the background music track to the specified file, with the default gain/volume.
void	playPriorityMusic(java.lang.String path, int repeats, int repeatDelay, double gain) Plays the specified music with custom parameters.
void	playSound(java.lang.String path, java.lang.String id) Plays a sound effect on the client with the default gain.
void	playSound(java.lang.String path, java.lang.String id, int repeats, int repeatDelay, double gain) Plays the specified sound effect with custom parameters.
void	resumeSound(java.lang.String id) Resumes a particular sound.
void	setMusicGain(double gain) Sets the volume of the background music.
void	setSoundGain(java.lang.String id, double gain) Sets the volume of a particular sound playing on the client.
void	stopAllSounds() Stops all of the currently playing sounds on the client.
void	stopMusic() Stops the background music completely.
void	stopSound(java.lang.String id) Stops the specified sound effect.

Field Detail

DEFAULT_REPEAT_DELAY

public static final int DEFAULT_REPEAT_DELAY

Default amount of time to wait between repeats on soundtracks, if not specified by the owner. Milliseconds.

See Also:

Constant Field Values

DEFAULT_REPEATS

public static final int DEFAULT_REPEATS

Default number of repeats to perform, if not otherwise specified, for map background music. -1 means loop continuously, separated by DEFAULT_REPEAT_DELAY. 0 means don't repeat, 1 means play +1 repeats, 2 means play +2 repeats, etc. A value of 5 means the track plays a total of 6 times.

See Also:

Constant Field Values

DEFAULT_GAIN

public static final double DEFAULT_GAIN

Default gain of 0.5 means "not louder or softer than the file would normally play on the user's computer." 0.0 is silent, 1.0 is max volume.

See Also:

Constant Field Values

DEFAULT_ALERT_REPEATS

public static final int DEFAULT_ALERT_REPEATS

Alerts just play once, by default.

See Also:

Constant Field Values

DEFAULT_ALERT_REPEAT_DELAY

public static final int DEFAULT_ALERT_REPEAT_DELAY

Alerts have no repeat delay by default, since they don't repeat.

See Also:

Constant Field Values

DEFAULT_ALERT_GAIN

public static final double DEFAULT_ALERT_GAIN

Volume level for Alerts.

See Also:

Constant Field Values

Method Detail

playAlert

public void playAlert(java.lang.String path)

Plays the specified sound file on the client, one repeat, no delay, and the default gain.

Can't be stopped, so use with care.

Parameters:

path - the relative path to the sound file

playAlert

public void playAlert(java.lang.String path,
                      int repeats,
                      int repeatDelay,
                      double gain)

Plays the specified alert with custom parameters. Can't be stopped, so use with care.

Parameters are file path, number of repeats, delay between repeats, and gain (volume). The alert won't play if the path is null or not found on the server. All other params are adjusted to be within the valid range for the parameter, if necessary.

Parameters:

path - the relative path to the sound file.

repeats - number of times the client should repeat the piece before stopping (and for music and sound, sending the notification back to the server). 0 means don't repeat; just play and stop.

repeatDelay - number of milliseconds to pause between repeats, if we're repeating.

gain - the volume for this track, from 0.0 to 1.0

playDefaultMusic

public void playDefaultMusic()

The player has switched maps, so figure out the default background music to be playing, and plays it.

playPriorityMusic

public void playPriorityMusic(java.lang.String path)

Sets the background music track to the specified file, with the default gain/volume. Always defaults to zero repeats in this version. If you want repeats or looping, call the overloaded version that lets you specify other parameters.

Client sends an "#endmusic" directive back to the server when it's finished playing all the repeats.

When this playMusic() is called, the specified music overrides the current background music. The player is considered to be playing the soundtrack in "priority" mode, meaning that switching maps or combat states won't revert it back to the normal map or combat music.

Parameters:

path - the relative path to the sound file, including extension. Can be any supported sound format (midi, ogg, others.) Nothing will be played if the path is null, or the file isn't found on the server.

playPriorityMusic

public void playPriorityMusic(java.lang.String path,
                              int repeats,
                              int repeatDelay,
                              double gain)

Plays the specified music with custom parameters.

Parameters:

path - the relative path to the sound file. Can be any supported sound format.

repeats - number of times the client should repeat the piece before stopping and sending a notification back to the server. A value of 0 means don't repeat; just play the track once. A value of -1 means repeat indefinitely.

repeatDelay - number of milliseconds to pause between repeats, if we're repeating. Negative values are interpreted as zero (no delay).

gain - the volume for this track, from 0.0 to 1.0. Values outside the range are clipped to 0.0 or 1.0.

stopMusic

public void stopMusic()

Stops the background music completely. Client does not send a notification back to the server.

setMusicGain

public void setMusicGain(double gain)

Sets the volume of the background music.

Parameters:

gain - the new background music gain, from 0.0 to 1.0

playSound

public void playSound(java.lang.String path,
                      java.lang.String id)

Plays a sound effect on the client with the default gain. Plays the sound exactly once, with no delay.

Client sends a "#endsound id" directive back to the server when the sound finishes playing, unless it was interrupted with stopSound() or stopAllSounds().

Parameters:

path - relative path to the sound file, in any supported format, including midi.

id - the unique ID of this sound. It has to be unique, so you can't use (for example) the hashcode of the path to the file, since more than one of the same sound may be playing at once. Usually you pass the hashcode of the object that emitted the sound.

playSound

public void playSound(java.lang.String path,
                      java.lang.String id,
                      int repeats,
                      int repeatDelay,
                      double gain)

Plays the specified sound effect with custom parameters. Client sends a "#endsound id" directive back to the server when the sound finishes playing, unless it was interrupted with stopSound() or stopAllSounds().

Parameters:

path - the relative path to the sound file, in any supported format, including midi.

id - the unique ID of this sound. It has to be unique, so you can't use (for example) the hashcode of the path to the file, since more than one of the same sound may be playing at once. Usually you pass the hashcode of the object that emitted the sound.

repeats - number of times the client should repeat the piece before stopping and sending a notification back to the server. A value of 0 means don't repeat; just play the track once. A value of -1 means repeat indefinitely, until explicitly stopped.

repeatDelay - number of milliseconds to pause between repeats, if we're repeating. Negative values are interpreted as zero (no delay).

gain - the volume for this track, from 0.0 to 1.0. Values outside the range are clipped to 0.0 or 1.0.

stopSound

public void stopSound(java.lang.String id)

Stops the specified sound effect.

Parameters:

id - the unique ID of the sound effect. The client will not send an "#endsound" back to the server.

stopAllSounds

public void stopAllSounds()

Stops all of the currently playing sounds on the client. Does not stop the background music or any currently-playing alerts. No notifications are sent back from theclient.

setSoundGain

public void setSoundGain(java.lang.String id,
                         double gain)

Sets the volume of a particular sound playing on the client.

Parameters:

gain - the new background music gain, from 0.0 to 1.0

id - the unique track ID for the sound to modify

pauseSound

public void pauseSound(java.lang.String id)

Pauses a particular sound. The sound will stop playing on the client, and resume when we call resumeSound() with this track id. If the sound is stopped with stop() after pausing it, then it cannot be resumed, and will ignore the resumeSound() request.

Parameters:

id - the unique track id of the sound to resume

resumeSound

public void resumeSound(java.lang.String id)

Resumes a particular sound. The sound will resume on the client, unless it was stopped after it was paused.

Parameters:

id - the unique track id of the sound to resume