Syrinscape Sounds

Overview

The Syrsincape Sounds extension for Fantasy Grounds Unity allows users to trigger sound playback in Syrinscape from within the Fantasy Grounds VTT.  This extension was developed by mattekure (discord mattekure#8651) and distributed through Team Twohy.  The product was originally sold on DMsGuild, and then transitioned to now be sold on the Fantasy Grounds Forge.  

https://forge.fantasygrounds.com/shop/items/117/view 

The Syrinscape Sounds extension is ruleset neutral and should work in all CoreRPG based rulesets.  A Syrinscape account is required to use this extension.  This extension will work with any sounds purchased through Syrinscape, and at any subscription level.  To get the full benefit of Syrinscape and this extension I recommend  getting the SuperSyrin subscription.  Details on Syrinscape accounts and offerings can be found on their website.

https://syrinscape.com/ 

Syrinscape Player Options

This extension will work with all current Syrinscape Player options. Details about each Syrinscape player can be found on their website.

Online Players

Web Player (Recommended) - An online web based player requiring no client install.  Easiest to use for both Game Masters and Players.  Players do not require an account to hear sounds triggered by the GM. With a SuperSyrin subscription, pushing sounds to players is simple.

Online Player - An online client player that must be installed on both the GM and Players devices.  Both GM and Players require at least a free syrinscape account.  With a SuperSyrin subscription, pushing sounds to players is simple.

Offline (Genre) Players

Fantasy Player - An offline client player that must be installed on the GMs device containing primarily Fantasy genre sounds.  The GM must pre-download all of the soundsets which will be used.  The Fantasy player has no built-in capability to send audio to players.  For information on directing audio to players, see Sharing Audio with Players.

Sci-Fi Player - An offline client player that must be installed on the GMs device containing primarily Sci-fi genre sounds.  The GM must pre-download all of the soundsets which will be used.  The Fantasy player has no built-in capability to send audio to players.  For information on directing audio to players, see Sharing Audio with Players.

Tutorial videos

Youtube Playlist: https://www.youtube.com/watch?v=7m6B4-kmJWE&list=PLcdYC2zo9JB8dy1nNj8jWMgtP5kkUPFV-

Optional Chat Triggers Module

This extension supports the use of Chat Triggers to automate sound playback, but it does not come with any sound triggers defined.  GMs are free to build their own chat triggers, but for convenience, I have released an optional chat triggers module which contains around 800 pre-built chat triggers.  The triggers are primarily defined for the D&D 5E ruleset, but may work in others.  In order to guarantee access to all of the sounds in the Chat Triggers module, a SuperSyrin subscription is recommended.

https://forge.fantasygrounds.com/shop/items/118/view 

Support

As this is a complicated programmed feature, if you are having any issues, Please come to our Discord and tag @mattekure so he can help you...
Discord server - http://discord.gg/rob2e 

Installation, Updating and Enabling

This extension was originally sold on DMsGuild and has since been migrated to the Fantasy Grounds Forge.  Although the extension is no longer for sale on DMsGuild, all updates are published to both DMsGuild and the Forge, so no repurchase is necessary.

Installation and Updating

Forge

Once the extension has been purchased on the Forge, it will be installed when an update is run.  Open Fantasy Grounds Unity, and select "Check for Updates".  Updates will automatically be downloaded whenever the "Check for Updates" button is pushed.  See Enable Extension below.

Screenshot_2.jpg

DMsGuild

Installation files for this extension can be found in your DMsGuild library.

https://www.dmsguild.com/my_library.php 

Search for "Syrinscape" and download the extension and module.

Screenshot_1.jpg

After downloading the extension and instruction module, they must be copied to the Fantasy Grounds data directory into the relative directories.  The FG Data directory can be accessed by selecting the Folder icon on the launch page.

Screenshot_3.jpg

Copy the extension and instruction module to the appropriate directories.  Make sure to check for any old or duplicate copies as sometimes DMsGuild will change the naming of the files.

Screenshot_4.jpg

Restart Fantasy Grounds

Enable Extension

After the extension and module has been installed, you must enable the extension for your campaign.  On the FG Load Campaign screen, select your campaign, select the Syrinscape Sounds FGU entry on the extensions list, then load the campaign

Screenshot_5.jpg


Updating Sound Links

There are two methods available to produce your SoundLinks module.  The online website and Offline application.

Online Syrin2FG Website

https://mattekure.com/Syrin2FG/

The Syrin2FG website can be directly accessed using the above link.  For convenience, it can also be opened by using the Update SoundLinks button from within FG.  Clicking this button will open the same website linked above.  Follow the instructions on the website to generate and download your custom Syrinscape SoundLinks module.

Screenshot_6.jpg

Offline Syrin2FG converter

For convenience, I have created an offline utility application to convert the Syrinscape CSV file into a Fantasy Grounds Sound Links module.  The offline converter is considerably faster than using the online converter listed above and does not rely on the speed of your internet connection.  The utility application can be downloaded at the link below.

https://github.com/mattekure/SyrinCSV2FG/releases 

Instructions
  1. Open the application
  2. Click the Download Syrinscape CSV button
  3. Click Browse and select the downloaded CSV file
  4. Click Convert
  5. Copy the generated file to your Fantasy Grounds modules folder.
Security Concerns

For some unknown reason, a small number of Anti-Virus applications (including windows defender) falsely flag this utility as infected or malicious.  This is due to how python packages the code within the executable. If the file is flagged, you may have to add an exception for it in your Anti-Virus application. The full source code for the application is available for review at the link above.  If you have any security concerns over use of this utility, I encourage you to use the online converter above.

Syrinscape Web / Online Player Setup

In order to trigger sounds in the Syrinscape Web or Online players, the GMs Authentication token must be registered in Fantasy Grounds.  This process generally only needs to be done once unless the Authentication token changes.

Obtain your Authentication Token

Visit the Syrinscape Control Panel and make sure you are logged in to the website.

https://syrinscape.com/online/cp/

Under "Your Game" select the Copy to copy the token.

image.png

Register Token in Fantasy Grounds

In a campaign with the Syrinscape extension loaded, open the Syrinscape window, and select Register Authentication Token.

image.png

Paste the copied token into the window using Ctrl+V and select Store Authentication Token

image.png

Syrinscape Genre (Fantasy, Sci-fi) player setup

To use the Syrinscape Fantasy or Sci-fi players, you must set the Player Type option to Genre.  

image.png

When using the Fantasy or Sci-Fi players, you must pre-download all of the sounds you intend to use.  Sounds that have not been downloaded to the player will not trigger playback when selected in Fantasy Grounds.  Instructions for use of the Genre clients can be found on the Syrinscape Website.

Syrinscape Sound Terminology

Syrinscape uses several different terms to refer to sound element types.  For full information see the Syrinscape Web Page and the Syrinscape YouTube channel.  

Mood

A Mood is a dynamically created looping sound.  It is created by combining a variety of Music, Sound Effect and One-Shot elements.  Moods are dynamic in that playback is varied, and non-repetitive.  Only a single Mood can be played at a time.  If another mood is selected, the currently playing mood will fade out as the new mood is faded in.

Music

A Music element is generally a looping soundtrack containing one ore more Samples of music.    Music elements can be played concurrently with any currently running Mood or sound.  For example, if you have a Tavern mood playing, you can add a lute music element to play along with it.  Music elements may have many different Samples, which can vary in many ways.  

Sound Effect

A Sound Effect element is generally a looping set of sounds made of one or more Samples representing a specific type of effect.  Sound Effects can be played concurrently with any currently running Mood or sound.  For example, if you have a Barghest Battle mood playing, you could also play a Rain sound effect alongside.

One-Shot

A One-shot element is a non-looping sound made of one or more Samples.  One-shots can be played concurrently with any currently running Mood or sound.  One-shots are used to represent any single instance of a sound such as a fireball exploding, or a sword hitting.  A One-shot can be made of many different Samples, so you could have 10 or more different variations of a fireball exploding.

Sample

A Sample is the lowest level sound element in Syrinscape. Each sample represents a single, discrete sound recording.   Samples are not accessible within the Fantasy Grounds interface.  Each Music, Sound Effect, and One-Shot element is made of multiple samples which can be randomized on playback.

UI Overview

Sound Records Window

image.png

 

  1. Register Authentication Token button:  For setting up the Web/Online player connection.
  2. Update Soundlinks button:  To open the Syrin2FG website to update soundlinks.
  3. Chat Triggers button: Opens the Chat triggers window to create and edit chat triggers.
  4. Volume Control: To open the volume control for use with the Web/Online players.
  5. Soundboards: To open the soundboards window to create and edit soundboards.
  6. Sounds List: This is the list of sounds available for playback.  Click on the link to the left to open a sound record.
  7. Search: Enter words to search for sounds
  8. Filters: You can filter the list of sounds by Product, Sound set, and type.

Sound Record

Sound records are not editable.

image.png

  1. Sound Name
  2. Sound Product or Pack
  3. Soundset
  4. Sound Type
  5. Play Button (draggable).  Click this to initiate playback of the sound.  This button can be dragged to create a link that immediately plays the sound when clicked.
  6. Stop Button (draggable).  Click to stop playback of the sound.  This button can be dragged to create a link that immediately plays the sound when clicked.

Options Menu

After enabling the extension in your Fantasy Grounds Campaign, several options will become available in the Options window.

image.png

Autoload Module?

Option Values: Yes | No

Default Value: Yes

When this option is set to Yes, the extension will attempt to automatically load the Sound Links module when the campaign is started.  

Include speaker in trigger check?

Option Values: Yes | No

Default Value: No

When this option is set to Yes, the extension will include the name of the speaker When performing a chat trigger check.  This can be useful for setting up unique triggers for individual players.  For example, setting up a unique sound for when Bob the Barbarian attacks with a war hammer, vs when an Orc attacks with a war hammer.

Player Type

Option Values: Online | Genre

Default Value: Online

This should be set to Online if using the Web or Syrinscape Online players.  It should be set to Genre if using the Fantasy or Sci-fi players.

Trigger on hidden/GM Only messages

Option Values: Yes | No

Default Value: No

When this option is set to Yes, the Chat triggers will attempt to match against messages that are hidden from the players.  This allows GM rolls to be kept hidden, while allowing triggers to occur on hits/misses, etc.  In order to trigger on an initiative TURN notification, this must be set to Yes.

Finding Sounds

Sounds can be found by using a combination of text search and filters.

image.png

#1 Group:  The group dropdown selection is the broadest filter available.  There is one special group which contains 3 sound records that are not generated by Syrinscape.  The Stop All buttons can be found in the Syrinscape Sounds group.

image.png

#2 Text Search: Type in text here to search for sounds.

#3 Filters: The Sound Set and Type filters are the most commonly used.  Use the Type filter to select One-shots, Moods, or other element types.

Linking Sounds

Sound record and Sound Play/Stop links can be added to any Formatted text field, maps and to the shortcut bar.  

image.png

image.png

Play / Stop buttons can also be drag/dropped to create a link. When these links are created, they will contain the name Play or Stop after the name of the sound.  When these links are clicked, the sound will immediately begin Playback/Stop.  No window will be opened.

image.png

Playing / Stopping Sounds

Playing  Sounds

 

Sound records can be triggered to begin playback in a number of ways.

image.png

Stopping Sounds

Sounds can be stopped individually or globally.  Each sound record has both a Play and a Stop button.  Pressing the Stop button will stop playback of that individual sound without affecting other sounds currently playing.  The Stop button may also be dragged and linked in the same way that the Play button can.

image.png

Stopping All Sounds

image.png

Note: Syrinscape does not instantly stop all playback, instead it fades the sounds away, so there may be some small delay for the actual sounds to stop.

Chat Triggers

Chat Triggers allow the DM to automate playing back sounds based on text that appears in the Chat Window.  To add, edit or view chat triggers, click on the "Chat Triggers" button at the top of the Syrinscape window.

image.png

Chat Trigger Record

A Chat Trigger record consists of 4 fields.

image.png

1. Name: The name of the Chat trigger

2. Sound Record: You can link the sound record to play when this trigger fires by dragging the sound link here.  Only 1 sound record can be tied to each chat trigger.  Do not drag the Play Button link.

image.png

3. ADV?: This button instructs the extension to use advanced LUA pattern matching (Regular Expressions) rather than simple text matching.  For more information on this advanced topic, please see Lua Pattern Matching for Chat Triggers

4. Trigger Text: This is the text that will be included in the pattern match.  For simple text matches, this text must appear in the chat message exactly as it is entered here.  The text may occur anywhere in the message, at the beginning, middle or end.  You can add additional triggers by clicking the + to the right of the trigger text.

Chat Trigger Options

See Options Menu

By default, Chat Triggers do not include the name of the Speaker when checking for a match.  If you wish to include the speakers name, you can turn on the option to include it.  This allows you to set up custom triggers for individual Players or NPCs by forcing the trigger to include their specific names in the matching text.

By default, Chat Triggers do not check messages that are hidden from the Players or GM Only.  If you wish to check these messages, enable the option.  If you wish to trigger a sound on the [TURN] messages, the Trigger on Hidden/GM Only Messages option must be set to Yes.

Lua Pattern Matching for Chat Triggers

Lua Patterns are a unique form of Regular Expressions which allow for very powerful pattern matching.  Lua patterns are slightly different than typical Regular Expressions, so be careful when entering them.  For more information on Lua patterns see: https://www.lua.org/pil/20.2.html

Lua patterns use special character classes and magic characters to enable more powerful pattern searching. 

Character Classes

The following table shows the special character classes.

. all characters
%a letters
%c control characters
%d digits
%l lower case letters
%p punctuation characters
%s space characters
%u upper case letters
%w alphanumeric characters
%x hexadecimal digits
%z the character with representation 0
Magic Characters

Some characters, called magic characters, have special meanings when used in a pattern. The magic characters are

    ( ) . % + - * ? [ ^ $

The following table shows the commonly used magic character modifiers.

+ 1 or more repetitions
* 0 or more repetitions
- also 0 or more repetitions
? optional (0 or 1 occurrence)

Volume Control (Online Player Only)

When using the Syrinscape Web or Online player, you can control the global volumes and global one-shot volume from within Fantasy Grounds.  The Volume button is located on the Syrinscape window.

image.png

Volume for each may be controlled either by selecting an absolute number from 0%-150% or by 5% increments up/down.

image.png

Soundboards

Soundboards add a quick and easy way to prepare sounds for playback.  Each soundboard can link up to 18 sounds. The Soundboards window can be accessed from the Syrinscape Window.

image.png

When Unlocked for editing, a sound board will show 18 record links.  Sounds may be added to the soundboard by dragging the record link to the soundboard.

image.png

When the Soundboard is complete and locked, it will no longer display the sounds. The window will change to show 18 numbered buttons instead.  When each button is pressed, the linked sound will immediately begin playback.  When the mouse is hovered over a sound button, the popup text will show the name of the sound record linked at that location.

image.png

 

Debugging Chat Command

A chat command has been added which turns on/off debugging for this extension.

Command:

/syrindebug [on|off]

When enabled in the chat, additional information about each sound played and each sound trigger activated will be displayed in the chat.

image.png

Sharing Audio with Players

Fantasy Grounds and this extension do not directly handle or manipulate the actual transmission of sound in any way.  This extension works entirely by sending messages to the Syrinscape players to induce them to initiate playback.  As such, the handling of audio is outside of the scope of this extension.  However, several options are available and covered below.

SuperSyrin Subscribers

The best and easiest way to share audio with players requires a SuperSyrin subscription to Syrinscape.  With this subscription, the DM has 2 options.

Web Player

The new Syrinscape Web Player allows the DM to share a URL with players and have any triggered audio playback through the website.  This solution requires no client install for the players, and they do not have to have a Syrinscape account.  The URL to the web player can also be used in OBS as a browser source to capture audio for streaming if desired. More information regarding the Web Player can be found here:

https://syrinscape.com/web-player/

Syrinscape Online Player

The Syrinscape Online player is a downloaded client which is installed on the DM and Players devices.  There are versions for Windows, Mac and Linux.  When using the Online player, each player and the DM must have at least a free a syrinscape account, and must authenticate with the player using that account.  The DM can create a "game" on the syrinscape website and invite players to join it.  While joined, any sounds will be played back on the members devices.  More information regarding the Syrinscape Online Player can be found here:

https://syrinscape.com/online/ 

Genre Players (Fantasy & Sci-Fi)

The Syrinscape Fantasy and Sci-Fi players are intended for offline use and as such have no inherit capabilities for sharing audio.  It is possible however, to redirect the audio to players using several different methods.  See Redirection Audio below.

Redirecting Audio

Discord

Many gaming groups use Discord to transmit audio/video.  For users who want to direct syrisncape audio output to a discord chat, you can try the Discord Audio Pipe.

https://github.com/QiCuiHub/discord-audio-pipe

How to Install Discord Audio Pipe:

https://youtu.be/CAofRXOHksw 

Voicemeeter / Virtual Audio Cables

Many solutions for routing audio in Windows rely on the use of Voicemeeter and Virtual Audio Cables.  These software packages are available on the VB Audio website.

https://vb-audio.com/


Changelog