Sound Plugin for Unofficial MapTool-1.3.b89 Plugin Mod

[Lord.Ashes]

This is a Sound Plugin for the Unofficial MapTool-1.3.b89.Plugin_Support.R3 Mod of MapTool.

The post for the Unofficial MapTool-1.3.b89.Plugin_Support.R3 Mod can be found here...http://forums.rptools.net/viewtopic.php?f=8&t=24539

The Sound Plugin can be downloaded from here...https://www.mediafire.com/folder/as6mnq3b730iu/Sound.

Disclaimer: This is a Sound Plugin for an unofficial release of MapTools. Please do not post question about this Plugin or MapTool Mod to the Core MapTool team. Post your questions in this thread instead.

As per the Unofficial MapTool-1.3.b89.Plugin_Support.R3 thread, these plugins are intended to add optional functionality which does not impact the use of a Campaign file regardless if the plugin is or is not installed. This means that if a Campaign files is used to provide Sound requests, the exact same Campaign file will also work with clients that do not have the Sound plugin installed (as long as they are also using the Unofficial MapTool-1.3.b89.Plugin_Support.R3 version of MapTool).

//
// ----------------------------------------------------
// Sound Plugin for MapTool-1.3.b89.Plugin_Support.R3
// ----------------------------------------------------
//
// Version: 1.0
//
// Programmed By: Lord Ashes
//
// Source Code Files: Sound.Java, SoundHandler.Java
// Compiled Files: Sound.Class, SoundHandler.Class, SoundHandler$1.Class, SoundHandler$AudioProcessor.Class
//
// Comments:
//
// This plugin consists of two plugins: Sound and SoundHandler.
// The Sound plugin parses Macro Function and processes local functions (such as getAudioChannel, setAudioChannel, getAudioRepository, getAudioRepository, etc).
// Any requests that are to be processed by all applicable clients are processed by writing an audio cue to the MessagePanel for SoundHandler.
// The SoundHandler plugin implement the MessagePanelHandler function which check MessagePanel messages for audio cues. When an audio cue is found, it processes
// the cue and removes the audio cue from the MessagePanel. If the Ear Plugs option is turned on, audio is not processed but the audio cues are left in the
// MessagePanel so that clients have an indication that a audio request was made but not processed due to the Ear Plugs option.
// Both Sound and SoundHandler need to be installed in order for this plugin to work.
//


Installation:

Unzip the Sound Plugin file into the Plugins directory in your MapTool directory. If there isn't a "plugins" directory present, create it.
The Source Code sub-directory can be deleted it is not required for the plugin to work. It is provided so that the Sound plugin can be modified, if desired.

Macro Functions:

All macro functions are executed using the pluginExecute(), pluginExecuteWithWarning(), pluginThread() or pluginThreadWithWarning() macro functions which are
added in unofficial MapTool-1.3.b89.Plugin_Support.R3

Typically pluginExecute() and pluginExecuteWithWarning() can be used for these Sound function because the plugin handles threading on it own and thus the actual
processing of audio is non-blocking regardless of which set of macro functions (pluginExecute() or pluginThread()) is used.

The syntax, using pluginExecute() as an example, for all Sound plugin functions is:

pluginExecute("Sound","function","parameters")

Where "function" is one of the below functions and "parameters" is a comma separated list of parameters (where applicable).
The below function list uses an abbreviated notation. For example:

setAudioRepository(RepositoryLocation)

Actually means:

pluginExecute("Sound","setAudioRepository","RepositoryLocation")

The Sound plugin supports the following functions:

getAudioRepository() = Used to get the last saved Audio Repository location.
setAudioRepository(Location) = Used to set the location of the Audio Repository. Typically set once on Campaign Load.
getAudioChannel() = Used to get the currently selected audio channel.
setAudioChannel(Channel) = Used to set the currently selected audio channel. Can be set as part of an requestAudio() call.
getAudioRepetitions() = Used to get the number of repetitions for future audio requests.
setAudioRepetitions(Reps) = Used to set the number of repetitions for future audio requests. Can be set as part of an requestAudio() call.
getEarPlugs() = Used to get the status of the Ear Plugs for the current channel.
setEarPlugs(State) = Used to set the status of the Ear Plugs for the current channel. Ear Plugs prevent audio request for the channel from being played.
getLock()* = Used to get the current channel's lock status.
setLock(State)* = Used to set the current channel's lock status. Usabled by GM only. Locked channels can only be used by the GM.
getLimit()* = Used to get the number of usable audio channels.
setLimit(Count)* = Used to set the number of usable audio channels. Usabled by GM only.
requestAudio(RequestFile)* = Used to make a distributed audio request. Parameters not provided used the last set values for those parameters.
requestAudio(RequestFile,Repetitions)*
requestAudio(RequestFile,Repetitions,Channel)*
requestAudio(RequestFile,Repetitions,Channel,AudioRepository)*
requestStop(Channel)* = Used to stop currently playing audio on a channel
cacheAudio(RequestFile)* = Caches an audio file to the local cache so that playing it is faster and does not require access to the audio repository.

Function marked with a * are distributed function which will request the effect on all applicable clients. Function that are not marked with a * are local functions which perform the indicated task only locally. It should be noted that settings such as those changed by setAudioRepetitions are marked as local function because they change only the local value of setting. Once the requestAudio() function is used, the value of these settings is pushed along with the requested audio to the clients but the client's local values will not be changed - hence why these function are listed as local.

Applicable Clients:

The Sound plugin does most processing through the use of Audio Cues in the MessagePanel. This is how the Sound plugin distributes requests to all applicable clients. The SoundHanlder portion of the Sound plugin intercepts these Audio Cues and triggers the actual processing of the request. This means that the normal MapTool Message Panel rules apply. For example, if the result of a Sound plugin macro function is sent to the GM only then only the GM will receive the sound request. If the result is sent only to one player then the sound request will only be sent to that player.

Notes On Channels:

Unlike my previous MapTool modification that added sound by modifying MapTool itself, the Sound plugin does not really use a limited amount of software channels. Each request spawns its own thread but there is no limit on the number of threads that can be spawned. However, all requests are still associated with a channel number. These channel numbers are use when performing other Sound plugin related functions such as Ear Plugs, Locking audio channels, and stopping audio channels.

The setLimit function, only usable by a GM, sets the number of available channels. The setLock function, usabled by GM only, can be used to Lock certain channels for GM use only. This then allows players to set their Ear Plugs appropriately. For example, the GM may use the setLimit(2) function to allows 2 audio channels to be used. She then uses the setLock() to lock the first channel but not the second channel. This means that only the GM can use the first channel while everyone (players and GM) can use the second channel. Now players who want to get GM invoked sound effects but not the player induced ones can set Ear Plugs to 0 for channel 1 (the GM channel) and set Ear Plugs to 1 for channel 2 (the player channel). Note that Ear Plugs are channel specific settings thus you need to setAudioChannel() before setEarPlugs(). In order to avoid all sounds one would need to setEarPlugs for each available channel (but it would probably be faster to just remove the plugin).

Audio Cues When Ear Plugs Are On:

When Ear Plugs are off, audio request are played and nothing is written to the MessagePanel. However when Ear Plugs are on, any audio requests are written to the Message Panel as audio cues indicating the channel, request and repetitions that were requested. In this way, a player who does not want to use the audio feature can still obtain information about the various sounds that the GM and/or players are invoking...sort of like closed captioning. Hwever, keep in mind that the audio cue will just indicate the requested file to play. For example, if the audio file is called Hello.was then the audio cue will indciate "Hello" but the actual contents of the Hello.wav file may be more than just Hello.

Compatibility:

This Sound plugin requires Unofficial MapTool-1.3.b89.Plugin_Support.R3 version of MapTool. It is not compatible with Unofficial MapTool-1.3.b89.Plugin_Support.R2 or Unofficial MapTool-1.3.b89.Plugin_Support.R1.

Audio Repository:

This Sound Plugin does not come with Audio Repository functionality. The provision of such an Audio Repository is beyond the scope of the plugin. Previously this core code of the Sound plugin has been tested with XAMPP web server (a free web server) and also DropBox. Almost any source that allows the download/streaming of audio files using a internet URL should be usable as a Audio Repository source. However, please note that the resource (i.e. audio file) URL needs to be consistent each it is used. If the URL names changes each time the resource is accessed then this source can not be used as a Sound Plugin Audio Repository because the Sound Plugin needs predictable URLs.

Sound Plugin Intention:

The intention of all plugins made using the Plugin Support version of MapTool is that these plugins are optional and are not needed to partake in using a Campaign file that uses them. This Sound plugin is no different. As such the Campaign designer should take care to ensure that none of the sounds are vital to the campaign. For example, don't provide a clue that there is someone in the abandonded house with the players by playing a sound file that contains the sound effects of footsteps because any players who do not have the Sound Plugin installed will not hear this. Similarly don't provide the quest information in a sound file because players that don't have the Sound Plugin installed will not hear it. Remember that the audio cues will only appear when the Sound Plugin is installed but a player has Ear Plugs on...it will not appear if the player does not have the Sound Plugin installed.

One way around this is to build macro function which trip corresponding Sound Plugin function and also provide the same information to the Message Panel. Basically create audio cues which are not dependent on the Sound Plugin so that if a client does not have the Sound Plugin installed, he/she still gets the Message Panel information.

How It Works (You Don't Need To Read This Section To Use The Plugin):

The Sound class portion of the Sound Plugin provides a number of functions which can be called using the pluginExecute() family of macro function (provided in the Plugin Support unofficial version of MapTools). Local functions are resolved by this class which usually results in the setting and/or creation of a local file to hold the changed setting. Since each Sound Plugin request is a different thread, communication between different requests is difficult. One method of handling this communication is for previous threads to write their messages (e.g. settings) to a file which future threads can read. This is what Sound.Class does. Any request that need to be distributed to all applicable clients are not handled by the Sound class. Instead the Sound class inserts an audio cue into the Message Panel. Since the contents of the Message Panel is sent to all applicable clients, the corresponding audio cue will be sent out to all applicable clients in the exact same manner.

For those interested in seeing the audio cues, the SoundHandler classes files can be removed from the plugins directory. In such a case the Sound class will place the audio cues into the Message Panel but there will be not SoundHandler to process them which will mean that the audio cues will remain in the Message Panel distributed to all applicable clients.

When the SoundHandler class is present, it implements a MessagePanelHandler which checks each MessagePanel message to see if it contains any audio cues. If so, the audio cue is processed (most commonly resulting in some audio playing) and removed from the MessagePanel so the users do not actually see the corresponding audio cue. In the case of Ear Plugs the audio cue is slightly reformated and then pushed back to the MessagePanel to intentionally display the audio cue instead of processing the audio request. Both Sound and SoundHandler could be combined into a single Java file which would have still resulted in multiple (but less) Class files. However, the plugin was separated into two parts so that the source code would be easier to follow.

Edits: 1. Post (text) reformatting changes