DOE Sound Extension

From Fantasy Grounds Wiki
Revision as of 22:25, 18 January 2017 by Dulux-oz (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

The DOE: Sound Extension brings sound to Fantasy Grounds in the form of Sound Links. Sound Links can be manually selected and triggered by the GM or they can be automatically triggered when certain events occur via the DOE: Sound Autosound feature and/or the Chatsound feature.

Sound Links are accessed via the DOE: Sound Sound Board and GM-created MiniBoards, lists of Sound Links able to be manipulated almost the same as any other Fantasy Grounds list of links.

Most of the other DOE Extensions incorporate the inclusion of Sound Links seamlessly and Sound Links can also be used in Story and Notes Entries via the use of MiniBoards which can be linked via the Link Paragraph Type. MiniBoards can even be placed on Maps and Images as Map Pins. Basically, almost anywhere where you can use a Link in Fantasy Grounds you can use a MiniBoard.

GM's can share MiniBoards with Players and can also create Chatsound Triggers which will automatically play Sounds whenever a give sequence of characters is sent from one computer to another to appear in the Fantasy Ground's Chatbox.

SmiteWorks and Community Developers can incorporate extra Autosound Triggers into Rulesets and Extension with only a few lines of code, without having to worry about whether the DOE: Sound Extension will be loaded or not: if the Extension is not loaded the Autosound Triggers will simply be ignored by default in all existing Rulesets and Extensions.

Version

1.0 - Initial Creation
2.0 - FGv3.2 Compatibility update, added Chatsounds and MiniBoards
3.0 - FGv3.2.2 Compatibility update, improved ChatSound String-Recognition

Dependencies

This Extension is dependent upon the following Rulesets:

  • CoreRPG v3.2.2+

This Extension is dependent upon the following Extensions:

  • DOE: Base v2.3

Ruleset Compatibility

This Extension has been tested and works with the following Rulesets:

  • CoreRPG Ruleset v3.2.2+
  • 3.5E D&D Ruleset
  • 4E D&D Ruleset
  • 5E D&D Ruleset
  • Barbarians Of Lemuria Ruleset
  • 6E Call Of Cthulhu Ruleset
  • 7E Call Of Cthulhu Ruleset
  • Castles And Crusades Ruleset
  • Fate Core Ruleset
  • MoreCore Ruleset
  • Numenera Ruleset
  • Pathfinder Ruleset
  • SavageWorlds Ruleset

This Extension has been tested and works with the following Rulesets, but requires compatible Graphics. Please contact the Author if you would like to help by providing suitable Graphics:

  • 13th Age Ruleset v3+
  • d20 Modern Ruleset

This Extension is not required by the following Rulesets, as this functionality is already built-in:

  • DOR: Core Ruleset
  • DOR: Alternity Ruleset
  • DOR: Dragon Warriors Ruleset
  • DOR: Übergame Ruleset

This Extension will not work with any other Ruleset. Other CoreRPG-Child Rulesets may be able to use this Extension, but the Extension will need to be tested first. Please contact the Author if you would like this Extension to be tested with an unlisted CoreRPG-Child Ruleset.

Extension Compatibilities

This Extension has been tested and works with the following Extensions:

  • DOE: Alignment Graph Extension
  • DOE: Campaign Style Graph Extension
  • DOE: Locations Extension
  • DOE: OLE Extension
  • DOE: Organisations Extension
  • DOE: Weather Extension
  • 1890s Era (CoC)
  • 5E - Language Fonts (FR) - Wizards
  • 5E - Language Fonts - Wizards
  • Blank Skills (Fate)
  • D&D Player's Handbook Desktop Decal Extension
  • Dark Ages (CoC)
  • Present Era (CoC)
  • Theme - Dungeon
  • Theme - Wood

This Extension has been tested and works with the following Extensions, but requires compatible Graphics. Please contact the Author if you would like to help by providing suitable Graphics:

  • 5E D&D Theme - Wizards

This Extension has not been tested with any other Extension, but should work with any Extension compatible with the CoreRPG Ruleset v3.2+ and any child Rulesets.

Supersedes

The following Extensions are superseded by this Extension and are no longer required:

  • None

Known Bugs

This Extension has the following known bugs:

  • None

Sound Links cannot be exported to Modules as stand-alone links or as attachments to other, non-DOE records as this breaks the linkages and the Sound Links will not work. No error message is displayed when this happens (indeed, no error has occurred within Fantasy Grounds itself, just in the linkages). However, MiniBoards, Autosounds and Chatsounds and their accompanying Sound Links, plus Sound Links on DOE records (such as on DOE: Location, DOE: Weather and DOE: Organisation records) can all be Exported successfully.

Usage

The DOE: Sound System

Getting Fantasy Grounds to play sounds is a complex problem. Fantasy Grounds does not include a sound engine, nor does it include a method of getting any resulting sounds over the Internet from the Host computer to the Clients. To solve this problem the DOE: Sound Extension provides a "system"; a way to connect Fantasy Grounds to a 3rd party sound engine and then either connect that 3rd party sound engine to a 3rd party Voice over IP (VoIP) application or, provided a given Player is also using the 3rd party sound engine, to trigger the Player's 3rd party sound system to play the sound locally.

The DOE: Sound Extension acts as an interface between Fantasy Grounds and Syrinscape, a free sound engine designed specifically for use with Role-Playing Games. Syrinscape comes with two free Sound Packs and additional Sound Packs can be obtained via a monthly subscription or purchased separately. Syrinscape is (in the the opinion of this Extension's Author) the best sound application for Role-Playing Games available.

Opeational Models

The DOE: Sound System has two possible models of operation: with or without a VoIP application. Using the DOE: Sound Extension with a VoIP application means that only one person needs to have Syrinscape and the appropriate Sound Packs installed; using the DOE: Sound Extension without a VoIP application means that each person who wants to hear sound needs to have Syrinscape and the appropriate Sound Packs installed on their computer. Both models of operation can be used at the same time, with those who have Syrinscape installed playing sounds locally and those who don't hearing sounds as they are sent of the VoIP application.

So, which model is the "best"? Well, that depends upon a number of different factors, including cost, complexity of set-up, network bandwidth, etc. The Pros and Cons of each model is given below:

Non-VoIP Model Pros

  • Simpler Set-up: Install Syrinscape, install the appropriate Sound Packs, turn on Sounds in the Fantasy Grounds Options, and away you go.
  • Less Bandwidth Used: Instead of sending audio across the Internet from one person (the Sound Host) to everyone else (the Sound Clients), only Sound Triggers are sent across the Internet (Sound Triggers are very small).
  • More Control: Each person has full control over the volume of the sounds produced by their own copy of Syrinscape, including being able to turn off sound completely.

Non-VoIP Model Cons

  • Greater Cost: Each person who wants to hear sound needs to install their own copy of Syrinscape and the appropriate Sound Packs. This will probably mean each person will need their own Syrinscape subscription (or purchase their own Sound Packs).

VoIP Model Pros

  • Lesser Cost: Only the person acting as the Sound Host needs to have Syrinscape and the appropriate Sound Packs installed. The Sound Host can be, but does not have to be, the Fantasy Grounds Host (the GM).

VoIP Model Cons

  • More Complex Set-up: The Sound Host is required to not only install Syrinscape and the appropriate Sound Packs, but also setup the VoIP application to transmit not only his own voice but also the sounds produced by Syrinscape. The Sound Clients also need to set up the VoIP application to transmit their voice as well.
  • More Bandwidth Used: In this operational model it is actual audio which is being sent across the Internet from the Sound Host to the Sound Clients, thus using up quite a bit of Internet Bandwidth.
  • Less Control: Depending upon the VoIP application used and the way the VoIP application is set up, individuals may not be able to independently control the Syrinscape sound volumes or even turn them off if desired.

Setting Up The Sound System Without VoIP

To use the DOE: Sound Extension without using a VoIP application each person who wants to hear sounds needs to install their own copy of Syrinscape and the appropriate Sound Packs on the same computer that Fantasy Grounds is installed on. The only other thing that needs to be done is turn on Sound from the Fantasy Grounds Options window. The Sound Option is turned off by default so that no errors are caused if Syrinscape is not installed.

Setting Up The Sound System With VoIP

To set up the Sound System with VoIP and provide sounds over the Internet the TeamSpeak VoIP application is used, along with a Virtual Audio Cable (AB-Cable) to connect Syrinscape to TeamSpeak.

So the complete Sound System with VoIP look like this:

  • Fantasy Ground (via the DOE: Sound Extension) => Syrinscape => VB-Cable => TeamSpeak

All this may appear to be complicated, but the DOE: Sound Extension makes things as easy as possible with full instructions on how to put the Sound System with VoIP together and also how to run the Sound System during your games.

The first thing that needs to be done to set up the Sound System with VoIP is to following the instructions on the Linking TeamSpeak & Syrinscape Wiki Page. Repeating all of that information here is redundant. especially as you only have to setup the link between TeamSpeak and Syrinscape once. Note that only the Sound Host (the person running Syrinscape, who DOES NOT have to be the Fantasy Grounds Host (the GM)) needs to set up Syrinscape and Teamspeak.

Once Syrinscape, TeamSpeak and VB-Cable are installed and linked together the DOE: Sound Extension can be used to create and run Sound Links, Autosounds and Chatsounds from Fantasy Grounds to Syrinscape; the rest of this Manual describes how to do this.

Running The System Sound (with or without VoIP)

Syrinscape needs to be running on the same computer as Fantasy Grounds and should be started first (but this is not required).

If using the DOE: Sound Extension with VoIP then as was mentioned on the Linking TeamSpeak & Syrinscape Wiki Page Syrinscape needs to be started AFTER the Windows Default Playback Device has been set to VB-Cable. If you forget to do this then Syrinscape will need to be restarted with the Windows Default Playback Device set to VB-Cable.

Creating Sound Links

Sound Links, MiniBoards, Autosounds and Chatsounds can only be created by the GM, even if the GM is not acting as the Sound Host.

Sound Links cannot be created directly on the DOE: Sound Sound Board, but are created via the DOE: Sound Sound Setup page. Simply create a Sound Record with whatever name you like, then enter in an appropriate Sound String.

Sound Strings can be typed manually into the Sound String Entrybox, but it is far easier and less prone to mistakes for Syrinscape to produce the Sound Strings for us and then we can copy and paste the Sound Strings into the entrybox.

From the Syrinscape application window:

  1. Click on the Settings Button in the bottom-left corner of the Syrinscape application window.
  2. Click on the Enable Button for 3rd Party App Integration on the Settings Window.
  3. Click on the OK Button on the 3rd Party App Integration Window.

Each Sound Button on the Syrinscape application window now has a small "+" Widget. Clicking on a "+" Widget generates a Sound String for that sound and places it on the Window's Clipboard. If we now put the mouse-cursor in the Sound String Entrybox of our new Sound Record and press CTRL-V we will paste the Sound String from the Window's Clipboard into the record.

Next, click on the green Create Sound Button to the below-right of the Sound String Entrybox to actually create the Sound Link. The Sound Link will be displayed on the Sound Record and will also be placed on the DOE: Sound Sound Board.

It's also generally a good idea to note down in Notes section any relevant information about the sound, such as which Syrinscape Sound Pack the sound uses.

Astute users of Syrinscape will have realised by now that any sound or group of sounds that Syrnscape can produce can be made into a Sound Link and controlled by Fantasy Grounds by this method.

Finally, remember to Lock the Sound Record so that you don't accidentally overwrite the new Sound Link.

When you have finished creating Sound Records remember to exit 3rd Party App Integration Mode in Syrinscape by clicking on the Settings Button and choosing Cancel for 3rd Party App Integration.

Using Sound Links

Sound Links can be activated by clicking on the appropriate Sound Link Icon, a purple box with a white treble clef in it. All Sound Links will be displayed on the DOE: Sound Sound Board so that you can have all of your Sound Links in one place. Now you rarely if ever need to swap back and forth between Fantasy Grounds and Syrinscape as you can control Syrinscape from the DOE: Sound Sound Board.

Sound Links can also be dragged from the DOE: Sound Sound Board to any MiniBoard. MiniBoards are exactly that: Mini Sound Boards. MiniBoards can be organised into Categories, linked into any place in Fantasy Grounds that will accept a regular link, including as Pin Links on Images and Maps and as Link Formatted Paragraph Types in Story and Note Entries, and even shared with Players.

Sound Links can also be linked directly to Maps and Images, Story and Note entries, etc, without using a MiniBoard. However, the resulting Sound Links will not be Exportable and WILL NOT WORK when re-imported. It is highly recommended that you only place Sound Links via a linked MiniBoard. Sound Link Icons will revert back to the standard Fantasy Ground Link Icon if linked incorrectly, indicating that they will be broken if Exported.

Most of the other DOE Extensions can also accept Sound Links and have special Sound Link Tabs on their various records. Now you can have the sounds of a tavern directly accessible on you Tavern Building Record from the DOE: Locations Extension, or the sounds of a thunderstorm on a DOE: Weather stormy Weather Record, for example. Such Sound Links used with DOE Extensions retain their Sound Link Icons, and thus do not need to be linked via a MiniBoard.

Sound Links and Sound Records can be deleted and edited, but any such changes will have no effect on any Sound Links on MiniBoards or on Sound Links dragged from the DOE: Sound Sound Board, because when a Sound Link is dragged from the DOE: Sound Sound Board a copy of the Sound Link is made when the Sound Link is dropped onto the parent object.

What Happens If Syrinscape Isn't Loaded, Or A Sound Does Not Exist In Syrinscape

If Syrinscape is not installed on the same computer you are running Fantasy Grounds on when you click on a Sound Link then a Window's Error and Error Window will be produced. Although these can be safely ignored and have no effect on Fantasy Grounds (the sound just won't play) it is best to prevent them from occurring in the first place by turning off Sound in the Fantasy Ground Options Window.

Note that Sound Triggers are sent to the Fantasy Ground Client computers (the Players) even if the Fantasy Ground Host computer (the GM) has turned Sounds off. This allows a Player to act as the Sound Host and frees up the GM's computer for other tasks (if using the With VoIP operational model).

If Syrinscape is not loaded when you click on a Sound Link (and you have Sound turn on in the Fantasy Grounds Option window) then Windows will load Syrinscape and the sound will eventually play. How much delay there is depends upon how long it takes Syrinscape to load, so it's best to load Syrinscape before loading Fantasy Grounds.

If the particular Syrinscape Sound Pack hasn't been installed on the computer then Syrinscape can't play that sound, but no other adverse effect will occur.

Creating Autosounds

The DOE: Sound Extension has the ability to play sounds automatically, triggered when certain events occur in Fantasy Grounds. These are known as Autosounds. Now you can have Fantasy Grounds play an Autosound whenever an attack roll is made, or when a damage roll is made, or when a host of other events occur.

Autosounds are just regular Sound Records with a Trigger attached. Autosounds can be created completely manually, but it is best to semi-automate the process as this makes the GM's job easier.

Because each Fantasy Ground Ruleset can have different triggering events, the first step in setting up Autosounds is to let the DOE: Sound Extension "learn" what events occur within your campaign. As you play your campaign the DOE: Sound Extension listens for events and records them on the Autosounds Tab as Autosound Records.

After a session or two of gaming within a particular campaign most events that could occur have, so the next step is to open each Autosound Record and assign an appropriate Sound String to it. This is done in exactly the same way as for a Sound Record. It is also probably a good idea to change the Autosound Record's Name to something more reader-friendly, because by default the Autosound Record's Name is the same as its Trigger, and while Triggers are reasonably easy to interpret that are not as reader-friendly as they could be.

Don't change the Autosound's Trigger value because this will cause the link between the Autosound and the relevant event to break. Leave it alone!

Remember to click on the green Create Sound Button to actually create the Autosound.

Note that Autosounds do not appear on the DOE: Sound Sound Board. If you'd like to be able to manually play an Autosound you will need to create a separate Sound Record.

Finally, remember to Lock the Autosound Record so that you don't accidentally overwrite the new Autosound and remember to reset Syrinscape out of 3rd Party App Integration Mode.

What happens if you don't assign a Sound String to an Autosound Record? Nothing - the DOE: Sound Extension will simply ignore any Autosound without a Sound String.

Note that you can delete Autosound Records as normal, but a new Autosound Record (minus any Sound String) will be created automatically by the DOE: Sound Extension the next time the triggering event occurs.

Creating Chatsounds

In addition to Autosounds the DOE: Sound Extension has the ability to play sounds triggered from a given sequence of characters that occur in the Fantasy Grounds' Chat Box. These are known as Chatsounds. This provides a GM-determined way of having sounds play automatically.

Chatsounds are similar to Autosounds. Chatsounds are created manually by the GM in a way similar to creating SoundLinks; in fact, Chatsounds are a type of SoundLink with a chat trigger attached.

The first step in creating a Chatsound is determining the character sequence that you want to use as a trigger. Chatsound Triggers can have up to three parts, allowing for those triggers that may have varying components to them (eg "Parry: X -> Miss!" where X is any number: the first part of the Trigger would be "Parry:" and the second part would be "Miss!"). The rules for multi-part Triggers are:

  • The second and third part of a Trigger are optional.
  • If the third part of a Trigger is used then the second part must also be used. You cannot have a first and third part to the Trigger and a "blank" second part.
  • If the second and/or third part of a Trigger are used then the second part MUST occur in the Chat Box after the first part, and the third part MUST occur after the second part.

Once you have determined your Trigger the next step is to assign it (in its various parts) and an appropriate Sound String to a Chatsound Record. This is done in exactly the same way as for a Sound Record. It is also probably a good idea to give the Chatsound a meaningful, easy to read name.

Remember to click on the green Create Sound Button to actually create the Chatsound.

Note that like Autosounds, Chatsounds do not appear on the DOE: Sound Sound Board.

Finally, remember to Lock the Chatsound Record so that you don't accidentally overwrite the new Chatsound and remember to reset Syrinscape out of 3rd Party App Integration Mode.

Note that you need to be specific about the Chatsound trigger, otherwise the Chatsound may be heard at inappropriate times.

Also note that only Chat Messages which actually travel across the Internet are detected by the DOE: Sound's Chatsound function; messages that appear in the Chatbox without traveling across the Internet will NOT trigger a Chatsound (this is a limitation of the Fantasy Grounds engine, not a design decision of the DOE: Sound Extension).

Extension Details

General Information

All Controls and Entryfields should be self-explanatory. Notes are provided for those that may not be.

All Fields will be Hidden when Empty.

All Text Entryfields are multi-line.

The Notes Field is a FormattedText.

All Sound Links are eligible to be used as Pin Locations on Maps as well as Links in all CoreRPG sub-systems, but this is NOT recommended; use one or more Sound Links on a MiniBoard instead. MiniBoards should be able to be used in all CoreRPG-Child Ruleset sub-systems, but this is not guaranteed.

Accessing The DOE: Sound System

The DOE: Sound System is accessed from the Menubar/Sidebar by clicking on the Large Sound Button located with the other Large Buttons. Note that this Button may be different from the one shown in some Rulesets. Also note that the Button may not show up by default; in which case activate it from the Library Button/System.

This opens the Sound Board, which consists of a list of Sound Links. Also accessible via the Tabs along the right-hand side are the Sound Records, the MiniBoards, the Autosound Records and the Chatsound Records, each consisting of a List of the appropriate Records. In addition, there is the standard Filter Box along the bottom.

Sound Board

The Sound Board contains a List of Sound Links, along with a List Edit Button.

Each Entry in the List consists of a Name, a Sound Link Icon and, when the List is in Edit Mode, a Delete Item Button.

Sound Links are placed on this list automatically when they are created in Sound Records.

Setup (Sound Records)

The Setup Page contains a List of Sound Records, along with a List Edit Button.

Each Entry in the List consists of a Name, a Shortcut Icon and, when the List is in Edit Mode, a Delete Item Button.

Sound Records are use to record information about a given sound, including the sound's Sound String.

Type or copy (CTRL-V) the appropriate Sound String from Syrinscape into the Sound String Entrybox.

Click on the green Create Sound Button to actually create the Sound Link for this Sound Record.

MiniBoard

The MiniBoard Page contains a List of MiniBoards, along with a List Edit Button.

MiniBoards are use to list groups of Sound Links to be linked to other Fantasy Grounds records. They consist of a Name, a List of Sound Links and a Notes page.

Drag and Drop Sound Links from the DOE: Sound Sound Board to the MiniBoard to add Sound Links to the MiniBoard.

Autosound

The Autosound Page contains a List of Autosound Records, along with a List Edit Button.

Each Entry in the List consists of a Name, a Shortcut Icon and, when the List is in Edit Mode, a Delete Item Button.

Autosound Records are use to record information about a given Autosound, including the Autosound's Sound String and Trigger.

Unless manually entering Autosounds and their Triggers it is STRONGLY recommended that the Trigger Entrybox be left alone!

Type or copy (CTRL-V) the appropriate Sound String from Syrinscape into the Sound String Entrybox.

Click on the green Create Sound Button to actually create the Autosound for this Autosound Record.

Chatsound

The Chatsound Page contains a List of Chatsound Records, along with a List Edit Button.

Each Entry in the List consists of a Name, a Shortcut Icon and, when the List is in Edit Mode, a Delete Item Button.

Chatsound Records are use to record information about a given Chatsound, including the Chatsound's Sound String and Trigger (in up to three parts).

Type the appropriate character sequence into the Trigger Entrybox.

Type or copy (CTRL-V) the appropriate Sound String from Syrinscape into the Sound String Entrybox.

Click on the green Create Sound Button to actually create the Chatsound for this Chatsound Record.

Options

The DOE: Sound Extension adds an Option to the Options System: Turn Sound On or Off.

Useful Links

This Extension

Other Extensions By Dulux-Oz

Copyright Information

This Software is Copyright Peregrine I.T. Pty Ltd © 2004-2017 except where explicitly stated otherwise.

'Purple Die Over Australia' is Copyright Peregrine I.T. Pty Ltd © 2004-2017.

'Fantasy Grounds' is a trademark of SmiteWorks USA, LLC.

'Fantasy Grounds' is Copyright © 2004-2017 SmiteWorks USA LLC.

Copyright to other material within this Manual/Extension may be held by other Individuals and/or Entities. Nothing in or from this Manual/Extension in printed, electronic and/or any other form may be used, copied, transmitted or otherwise manipulated in ANY way without the explicit written consent of Matthew James BLACK or, where applicable, any and all other Copyright holders.

License Agreement

Please see the Extension Module (available from this Extension's Forum Page) for full Licensing details.

Donations

If you like this Extension and find it useful, you may like to consider making a Donation to the Author so that this Extension and similar Software can continue to be maintained and developed.

Donations can be made via PayPal to:

Thankyou.

Developer Notes

The following Notes are provided to enable other Developers to write Rulesets and Extensions which will be compatible with this one.

The Author is happy to assist fellow Developers to get their Ruleset and/or Extension working with this Extension - please contact the Author via the Fantasy Grounds Forums.

Extension Properties

This Extension includes the following Properties Tags:

<exclusiongroup>DOESound</exclusiongroup>
<loadorder>50</loadorder>

Creating Autosound Triggers

Autosounds trigger off OOB Messages: in particular, OOB Message Types. Thus it is relatively trivial to increase the number and range of Autosounds by including special "Sound" OOB Message in Rulesets and Extensions. The beauty of this is that if the below instructions are followed Fantasy Grounds will safely ignore any such OOB Messages and they will only be acted upon by the DOE: Sound Extension - meaning that you can include them in your Ruleset or Extension without worrying about whether the end-user-GM is using the DOE: Sound Extension or not!

To get an Autosound to play at the appropriate time simply have your code send an OOB Message with a unique "Type" (eg Comm.deliverChatMessage({"autosoundtriggertype1"})) at the correct time and the DOE: Sound Extension takes care of the rest. It is literally that simply!

Now because of an error Comm Message that the CoreRPG Ruleset sends out when an unknown OOB Message is received, any Sound OOB Messages need to be registered first. This is done by:</p>

OOBManager.registerOOBMsgHandler("autosoundtriggertype1",fpDummy);

This also requires a dummy function (fpDummy()) which looks like this:

function fpDummy()

    return;

end

The same dummy function can be used for all Sound OOB Message registrations. We only need to register the Sound OOB Messages to "trick" Fantasy Grounds into letting the Sound OOB Message go through without error.

So, imagine having Fantasy Grounds play the Fire Spell Sound from Syrinscape automatically whenever a fire-based spell is cast - simply have Fantasy Grounds determine when such a spell is used and then send an OOB Message with its type set to an appropriate value - and the DOE Sound Extension will play it for you automatically!

Return to the Extensions Page.