                                  SOUNDSENSE
                    A sound-engine tool for Dwarf Fortress

Author: Petr Prokop

You can find me on the official Dwarf Fortress forums as 'zwei'
Contact via PM: http://www.bay12forums.com/smf/index.php?action=profile;u=16734
You can also reach me on email: zwei2stein@gmail.com

Version: Release 27 Build 129
Last Updated: 02.04.2011
For DF version:	0.31.18
Requirements: Java 1.6 runtime (Works on any OS with java support... in theory)

Homepage: http://df.zweistein.cz/soundsense/
Forum thread: http://www.bay12forums.com/smf/index.php?topic=60287.0

Notable contributors in aplhabetical order:

> Rainseeker
> Tokkius
> Thundercraft
> Tyrspawn

Description
===========
SoundSense is an unofficial (3rd party) sound-engine tool for the Dwarf Fortress roguelike.
It plays various sound effects, voices and music based on what entries appear in the 
gamelog.txt.

Basically, game events are detected and this triggers certain sounds and soundtracks. For 
example, specific combat events will trigger certain sound effects like the clanging of 
swords and the impact of arrows. Likewise, a change from Winter to Spring will change the 
background music.

Although it has only been tested on Windows and Linux, SoundSense should (in theory) run 
on any OS with java support. Startup scripts are included for Windows and Linux.

See this post for help on getting it to run on Mac OS X: 
http://www.bay12forums.com/smf/index.php?topic=60287.msg1552676#msg1552676

(Note: Feedback on using SoundSense with Mac OS X is appreciated. It has not be tested 
enough yet to warrant official support.)


Downloads
=========
Requires java 1.6 runtime:
http://java.sun.com/javase/downloads/index.jsp

Remember to add the official sound pack (separate download) after installation!
The latest Soundpack.zip, as well as a few unofficial sound packs, can be found here: 
http://df.zweistein.cz/soundsense/


Installation
============
Installing and configuring software can be intimidating if you are not an IT nerd. And this
is no exception with SoundSense. But bear with me and it can actually be pretty easy.

Non-scary instructions:

 * Install the java runtime
 * Download and extract SoundSense (It does not matter where.)
 * Download soundpack.zip and extract the "packs" folder to SoundSense directory
 * Run soundsense.cmd or soundsense.exe

First, you need to have the java runtime installed. It can be downloaded from the java 
homepage. To determine if your computer already has the correct installation of java, go 
to the Start button, left click "Run..." from the bottom of the menu, type in "cmd" in the 
dialog that opens, and press the [OK] button. A dark windows pops up and you will be at a 
command prompt. Type in "java -version" and press [Enter].

A few lines starting with [java version "1.6.0_14"] or something similar should apear. If 
that case is the case, you are good to go. But if you see [java version "1.5.x_xx" or an 
earlier version (lower number), you will need to download and install the latest java.

If something similar to ['java' is not recognized as an internal or external command] 
appears, either java has not been installed yet or it was not installed correctly. If 
your case is the latter, it may be possible to work around the problem by editing the 
soundSense.cmd (in your SoundSense directory). Open it with Notepad and find line line 
starting with "java -Dja..." and replace the "java" part with the full path for your java 
installation. For example: "C:\Program Files\Java\jdk1.6.0_20\bin\java.exe"

That was the hard part.

Now, where to install it? SoundSense expects to be in a sub-directory that is inside your 
Dwarf Fortress directory. So, for example, if you have Dwarf Fortress in F:/df_31_18_win/,
you should unpack the contents of SoundSense zip to F:/df_31_18_win/soundsense/. By 
default, you want to make sure that the .cmd file you use to launch SoundSense is inside a 
sub-directory of (i.e., below) the DF folder where gamelog.txt is located.

If you want to install to a different location, you need to edit configuration.xml and 
edit the <gamelog path="../gamelog.txt"/> line. Replace "../gamelog.txt" with the path to 
where Dwarf Fortress is located. For example: "F:/df_31_18_win/gamelog.txt"

SoundSense is now all set up and ready to run. But you still need the actual sounds and 
music that it will play. So download soundpack.zip and unzip the "packs" directory and all 
the contents inside that to the SoundSense directory.

You can start SoundSense by launching (double left-clicking) either soundSense.cmd or 
soundSenseExe.cmd. (Using the latter should give you clearer error messages regarding a 
bad java installation.) If you like, you can create a shortcut to soundSense.cmd, rename 
it "SoundSense" and move it to your desktop for easy access.

Finally, remember that SoundSense needs to run in the background. Ideally, you should 
start SoundSense BEFORE you start Dwarf Fortress.


Known Issues
============

* Moments of Silence

Occationally, the music in SoundSense will stop for a short period (10, 20, or 30 seconds) 
before resuming. This is not a bug - it is intentional. This was done to let ears rest a 
bit between tracks. (Research shows that ears which get a rest have time to recover and 
are less likely to be damaged.) Also, a few tracks have a silent start and, at low volume, 
may take a minute or longer to become audible. If in doubt, you can see what is currently 
playing in GUI under the volume slider. During periods of silence, this will typically 
show "10s silence" or similar.

* Game Loads and the Music is Random

When a game is loaded, SoundSense picks a random seasonal music track to play. This is not 
a bug - it is intentional. There is no way for SoundSense to detect what season it is when 
a game is loaded, so a random soundtrack is chosen. But when the season next changes, it 
will choose the correct soundtrack.

* Adventure Mode - A Bit Lacking

Adventure Mode kind of works. The battle sounds function quite well because they are 
mostly the same as those in Fortress Mode. But SoundSense is still a bit lacking in other 
adventure sounds. The problem is that Adventure Mode does not log many other usefull 
events. For example, encountering a megabeast or a quest mob is resolved in chat, leaving 
no message in the game log to trigger SoundSense.

Improvements in how DF handles logging could benfit both SoundSense and DF as a whole. 
Such suggestions have already been posted in the official Dwarf Fortress forums: 
http://www.bay12forums.com/smf/index.php?topic=64834.0

* Event Detection: Better Late Than Never ?

In some cases, by the time SoundSense detects conditions to trigger an alert, it may be 
too late to react to the situation. For example, a "Tantrum Spiral" might already be over 
before the player can be alerted.

Part of this is a balance between detecting too many false positives and ignoring events 
until it is too late to do anything. For example, a soldier might lose a pet and report 
feeling like blowing off some steam... but instead of throwing a tantrum they calm down.

Another problem is FPS sensitivity. A specific sequence of events may trigger certain 
alert sounds in a high FPS situation, but it might not trigger with low FPS. The sequence 
of events might "time out". Also, pausing the game could cause similar problems.

* Compatible With DF Mods - Should Work, But NO PROMISES

SoundSense was mainly designed for "vanilla" (unmodified) Dwarf Fortress. It should work 
fine with most mods. However, I can not guarantee compatibility. Some mods, especially 
"major" or "full conversions", may create unusual behavior and involve dangerous events 
that SoundSense was not designed to detect.

Another words, SoundSense may lack sounds for certain mod-specific events. (E.g.; you 
should NOT expect SoundSense to include gunshot sounds for mods that add guns! But you CAN 
modify SoundSense yourself to do this.) Conversely, some events that work normally in 
vanilla DF may trigger so frequently with a mod as to be very annoying.

* Any Other Issues? Post Feedback

There is a thread at the official Dwarf Fortress forums. Feel free to post any issues, 
suggestions, and contributions there:
http://www.bay12forums.com/smf/index.php?topic=60287.0

When providing feedback about your experience with SoundSense, please specify which mods 
(if any) you are using. If SoundSense seems to behave weirdly only for you, it just might 
be from using certain mods.


Customization
=============

You can insert additional sounds and music into SoundSense by adding entries to an .xml 
configuration file. logPattern="regexp" is a regular expression which, if matched, will 
cause a random soundFile from a list to be played. (Details on how java uses regular 
expressions: http://java.sun.com/j2se/1.4.2/docs/api/java/util/regex/Pattern.html )

Sound element attributes:

 * logPattern - regular expression matching log line (see link above)
 * channel - string; Specifies a channel on which sound is played. Sounds played on a 
channel can be looped or stopped prematurely.
 * loop - string; Specifying "start" will start looping a sound on a channel until an 
expression with "stop" is triggered or until a different loop sound is played on the same 
channel. (If a non-looped sound is triggered on the same channel, this loop will resume 
when the non-looped is done playing.)
 * concurency - number; The number of concurrent (i.e., simultaneous) sounds allowed to be 
played besides this sound. If SoundSense is currently playing more than this, the sound is 
ignored. The default is unlimited.
 * timeout - number; This initiates a time out during which this particular sound is 
prevented from playing again. This is measured in milliseconds and the default is 0.
 * delay - number; Adds a delay before the sound is played. This is measured in 
milliseconds and the default is 0.
 * haltOnMatch - boolean; If this is set to True and more than one equivalent logPattern 
exists, SoundSense will only process the first logPattern expression. If it is False, it 
will continue to process matching (e.g., identical) logPatterns. The default is True.
 * speech - boolean; If this is set to True, SoundSense will echo the gamelog text line 
(containing the logPattern) with a speech synthesizer instead of playing a sound. The 
default is False.

SoundFile element attributes:

 * fileName - the path to and name of the sound/music file
 * weight - number; This controls the likelihood of a sound being chosen. Default is 100.
 * volumeAdjustment - number; This can be used to adjust the volume of the sample. The 
value can range from -40 to +6 decibles and the default is 0.

SoundSense supports these audio formats for soundFiles:

 * mp3   (SoundSense can normalize the sound volume with this format)
 * ogg   (works, but SoundSense can not normalize the sound volume)
 * wav   (See note below. SoundSense only supports "Windows PCM" encoded .wav files)
 * aiff
 * au

Note: Not all .wav files are supported...

SoundSense supports .wav encoded in the "Windows PCM" format. However, some files with the 
.wav extention are actually encoded in some other proprietary format. A sound format 
conversion utility (such as FormatFactory) could be used to fix them.

Some Tips:

* Control of Randomness - Each logPattern expression can contain several soundFile 
elements. When it is triggered, one of them is randomly chosen to play. You can control 
the probability of each sound being chosen by adding the weight="number" attribute.

* Simultaneous Sounds - By default, only one sound will play for a given logPattern, even 
if there are several expression using identical logPatterns. (Only the first expression is 
processed.) But you can allow more than one sound to be played for same pattern by giving 
the first one the haltOnMatch="false" attribute. They will all start at same time (unless 
one or more of them also has a delay). An example is in Seasons.

* Sequential Sounds - Two (or more) sounds can be played sequentially (one after the 
other) for the same logPattern by using the haltOnMatch="false" tip above and including a 
delay attribute for one of them with a delay that surpasses the length of the other.

Helpful files:

 * packSkeletons.zip ( http://df.zweistein.cz/soundsense/packSkeletons.zip ) - This 
contains .xml files for all known gamelog lines currently without sounds. You can use this 
as a starting point to expand SoundSense.
 * missingMessages.cmd - Run this program to parse your gamelog.txt file and output all 
lines your sound packs will not recognize.
 * logging.properties - Edit this file to enable more debug messages from SoundSense. Set 
".level = ALL" to view a very verbose output.

Sources of sound & music:

The following are some sites of interest, should you want additional sounds/music.
(Websites with free, creative commons, public domain, and/or GNU GPL licensed audio):

http://soundbible.com/
http://www.freesound.org/searchText.php
http://www.musopen.org/
http://opengameart.org/browse/audio
http://www.incompetech.com/m/c/royalty-free/
http://ccmixter.org
http://free-loops.com/
http://www.pdsounds.org/
http://commons.wikimedia.org/wiki/Category:Sound
http://www.archive.org/details/opensource_audio
http://publicdomainaudiovideo.blogspot.com/


Disclaimer
==========
SoundSense has been tested and I can not imagine a situation where it could cause harm. 
However, to be on the safe side: SoundSense is provided 'as is,' without warranty of any 
kind, either express or implied. You assume total responsibility for the use of the 
Software as it is entirely at your own risk.


Acknowledgment
==============
The SoundSense program itself was written (and is maintained) by Petr Prokop. But a lot of 
talented people produced, recorded and edited the music and sound that went into this 
project. They deserve our acknowledgment and appreciation, too. If you enjoy SoundSense 
and are curious to see who these people are or how many different sources we used, then 
check out ATTRIBUTION.TXT in the Soundpack.zip package for a full credits list. 

