Dwarf Fortress Wiki - User contributions [en]

v0.31:Aquifer

2011-09-20T16:10:11Z

Vyznev: /* The modding method */ that regexp would hose your raws completely -- add backslashes to fix it, plus some general improvements

{{quality|Masterwork|15:52, 30 September 2010 (UTC)}}{{av}}
An '''aquifer''' is a subterranean layer of {{l|water|groundwater}}-bearing rock or {{l|soil}}. Attempts to mine through the layer will result in the mined-out squares immediately filling with {{l|water}}, effectively halting excavation at or below their level. This, in conjunction with the fact that they are often located in areas rich in {{l|loam}}, and {{l|sand}}, makes it difficult to find great quantities of {{l|stone}} in areas with aquifers, making for more challenging gameplay.

Aquifers can't be drained - the groundwater is limitless. {{l|stone detailing|Smoothed}} aquifer stone stops producing water. Aquifers located in {{l|water#Salt_Water|saltwater}} areas will produce salty water. Aquifers do not only produce water - if the incoming water is pressurized, an aquifer tile may instead absorb it. Just like with water production, this ability will not be disabled no matter how much water it absorbs.

== Where they are found ==

Aquifers are less likely to be found near and in mountains.{{verify}}

Layers which CAN contain aquifers:
*{{L|sandy clay loam}}
*{{L|silty clay loam}}
*{{L|loam}}
*{{L|sandy loam}}
*{{L|silt loam}}
*{{L|loamy sand}}
*{{L|silt}}
*{{L|sand (tan)|sand}}
*{{L|yellow sand}}
*{{L|white sand}}
*{{L|black sand}}
*{{L|red sand}}
*{{L|peat}}
*{{L|pelagic clay}}
*{{L|calcareous ooze}}
*{{L|siliceous ooze}}
*{{L|sandstone}}
*{{L|conglomerate}}
*{{L|puddingstone}}
Layers which CAN'T contain aquifers, despite their names suggesting otherwise:
*{{L|clay}}
*{{L|silty clay}}
*{{L|sandy clay}}
*{{L|clay loam}}
*{{L|siltstone}}
*{{L|mudstone}}

== What they do ==

Aquifers are tiles which produce water in their ''neighboring'' tiles -- north, south, east, west, and below. They do not produce water in diagonally adjacent tiles, or in the tile above them.

If you are digging an up/down staircase in the downward direction, and you hit an aquifer, the aquifer tile will be revealed as damp soil or stone, and the digging job will be un-designated for that tile.

If you are digging an up/down staircase in the ''upward'' direction, and you hit an aquifer from below, the aquifer tile will immediately start producing water in the stairwell.

== Dealing with aquifers ==

===Digging at a change in level===

Though an aquifer seems a daunting obstacle, it ''is'' possible to dig through it, given an ample supply of building material (rock or wood) and any unevenness in the depth of the aquifer. The basic facts:

* An aquifer layer will ''absorb'' an unlimited amount of water draining in from above.

* With an up/down stairway or channel designation, a dwarf can break through the floor of the cell ''beneath'' him. That means a dwarf can stand on top of an aquifer layer, dig an up/down stairway, and make it drain into the layer beneath it, if that layer is also an aquifer or has an open path to an aquifer layer nearby.

* A stairway may be swamped to dangerous levels with water draining in from the squares around it, but many stairways in a clump mean that the drainage to the next layer wins out.

* Constructing a wall, up/down stairway, or channel in an aquifer layer prevents any water from originating in that square. A wall prevents water from draining down into the next layer from any source, while the stairway or channel lets it come in from other squares and drain.

These points support the following method:

# Dig around at the level just above where you encountered the aquifer, placing up/down or down stairways according to your preferred city grid plan. Training up a few miners in this way will help later. Spot some points where the next level (as seen from down stairways) varies in wetness from one spot to another.
# For the following, pause the game after every square dug out and make sure the miners dig both layers at the same rate and redesignate when they cancel your plans automatically. Dig a 5x5 hollow square of up/down stairways at the change in level, going down as far as you can. The lower aquifer should accept water from the upper aquifer, allowing you to drain the upper aquifer (at least partway). Then gradually take on the area in the middle, building walls and/or staircases to fill in and stop the flow as you expand. Eventually you should get command over the source of flow, and can dig a hole in the center of the bottom-most layer surrounded by a 3x3 ring of impermeable rock.

* ''Caveat: sometimes only the top of the aquifer changes depth, but the bottom stays at the same level. In this case you will get nowhere. Sometimes the aquifer is two or more layers thick and it doesn't offset enough to let you all the way through - in this case, sometimes you can use the cave-in method to get through one layer, then use this method to get through the next. And sometimes you'll just find a hole right through when you investigate the change in level, because you're at a biome boundary and it's not aligned perfectly.

===The ore method===
On maps where the aquifer is not held in a layer of soil, but instead is held in a {{L|sedimentary layer}} such as sandstone, it may be possible to tunnel down through deposits of ore such as magnetite. For this to work you have to find a spot where there is coincidentally an ore deposit on each Z-level you need to dig through. This is only possible through tiresome trial and error, or through the use of a utility like reveal.exe. The trial and error method can be accomplished somewhat more easily by digging up/down stairs to reveal the layer underneath them without actually digging into the underlying layer. This method is more complicated with aquifers located in layers of {{L|conglomerate}}, as large clusters of {{L|puddingstone}} will support the aquifer and thus cannot be used to provide a path through it.

===The magma/obsidian method===
If you have access to a supply of magma, you can create your own obsidian caissons. By channeling into the aquifer layer and then filling these channels with magma, it is possible to create a wall of obsidian between your working area and the {{l|water}}-bearing rock or {{l|soil}}. However, changes to world generation with the last version have made this method more difficult than it once was, as it is now harder to find magma vents that extend above the aquifer level.

===The cave-in method===
If there are enough layers above the aquifer, then letting non aquifer rock fall into the aquifer layer gives an area of diggable rock. This requires at least 2 natural dry layers. If multiple aquifer layers are to be breached, things get more complicated. First {{l| channel}} out the area of aquifer that will be replaced. Then dig out all connecting floors and walls to the block that will fall (build a support to hold it until you are ready for collision). A {{l| burrow}} may be useful to assign unnecessary dwarves to a safe area. When everyone is clear, de-construct the support with a lever. (If you forgot to bring stone, then you may instead build a constructed floor to support it, designate it to be destroyed, and have a {{l|hospital}} standing ready in case the unlucky one survives.)

After the collapse, do not dig out the outer edge of the fallen rock.

This does not work with {{l| wood}} walls since they deconstruct on cave-in.

If you build many rings inside one another in your top drop layer, you can breach multi-level aquifers with as little as 2 natural layers of dry soil above it. Drop the rings from the outside to the inside using constructed arms to hold the center rings in place. Once a ring drops into the water below it, pump out the water in the center and dig down another layer. When that is complete, drop the next ring and continue the process until you are through. Since you start dropping rings from the outside it is necessary to know how many levels deep the aquifer is before you begin.<br>
Tutorial for more than one Aquifier can be found here: [[User:Rhenaya/HowtoDualAquifer]]

Some might regard this method as cheating, so use it at your own risk.

'''Note:''' There is a bug that may prevent this method from working, collapsed layers may turn into the aquifer layer type that was dug out at that level. So, for example: We have three layers, layer 1 has the caving in section, and is not an aquifer. Layer 2 is a dug out layer that is also not a aquifer. And Layer 3 which is dug out and is an aquifer. Now, the bug, say layer 1's cave-in section lands on layer 3's dug out area, sometimes layer 1's caved in section may change into layer 3's soil type. Making it an aquifer too. Thus making the cave-in method impossible for that area.

====Cave-In Example====

[[File:Aquifer-Plug.png|frame|none|Note: Side View]]

*Dig stairs down to the aquifer. Dig over the aquifer layer but under your "plug". You'll need a 5x5 landmass. (Slide 2)
*Channel out the area the plug will fall into. (Slide 3)
*Leave a single floor tile on top of the plug and dig out the outer layer of your plug. The plug should be a 3x3 landmass now. The single floor tile must keep the plug from falling. (Slide 3)
*Channel out the floor tile holding up the plug. (Slides 4 & 5)
*Construct floor tiles to reach the plug and dig through the middle to get under the aquifer. (Slide 6)

===The freezing method===

If you are playing in a freezing or very cold landscape, where it snows in winter and instantly freezes water on the map, you can dig out a 3x3 hole in the ground using {{l|channel}}s, and make it deeper and deeper until you reach the aquifer level. Once you reach the damp rock, tunnel into it with an up/down staircase - the incoming water will freeze after a few moments. The central square of the 3x3 hole should be tunnelable ice, so you can get to the rock beneath. If there are two aquifer levels, for example, you can just make a larger initial hole, and make a smaller one for the level after.

If your fortress is in a zone that gets warm, build walls around the inside of the hole to stop the water coming in once the ice melts.

<b>Note</b>: There is a bug that may prevent this from working, sometimes ice walls don't produce an ice floor tile above them, instead leaving it as "open space" which prevents the player from digging downwards.
Simplest method is to construct a wooden (or stone, if you have any) floor and then remove it. After the floor is removed, a natural ice floor will remain.
An alternative means that will work is to set the tile 1 z-level '''ABOVE''' your missing ice floor tile as a {{l|pond}}, and '''FILL IT'''. The first {{l|bucket}} of water that goes on it will create that missing ice floor tile the instant the water is dumped on it, and you will receive a cancellation message that the pond has gone away. Dezone the pond {{l|activity zone}}, and get back to work breaching that ice. Keep in mind that you will need an '''unfrozen water source''' to use to fill your bucket. Luckily you have an aquifer, so you can just dig into it somewhere underground.

===The pump method===

The pumping method uses multiple {{L|screw pump|pumps}} to keep an area dry long enough to smooth or {{l|wall}} off the edges, stopping the flow of water. It requires no special environment or resources, other than wood and dwarves (and patience). Most commonly, a moderately sized section of the aquifer layer is channeled out and several screw pumps are built facing it. Directly behind each of the screw pumps a few tiles are channeled out to receive and dispose of the pumped water. When the pumps are activated, they should pump water faster than the aquifer can produce it, allowing masons to smooth or build walls around your future staircase. You ''will'' get job cancellations during this process, as stray 2/7's of water interrupt the building process. Just unsuspend the construction when this happens, as long a dwarf manages to touch the wall before canceling, it will move incrementally toward completion and eventually finish. Depending on the availability of screw pumps and dwarves, you may need to wall off one corner or side at a time, then move the pumps and repeat. When drilling through more than one aquifer layer, be sure to leave yourself enough room to build additional layers of pumps and water disposal channels on lower levels.

Things to consider:
* Flowing water will cause parents to drop their infants, leading to job cancellations and occasionally [[fun]].
* Mechanical {{l|power}} may come in handy, but dwarf power works just fine and is much more portable.
* Channels can sometimes be used in place of walls, causing water produced by by the aquifer on one level to immediately fall and be consumed by the aquifer on the level below.
* This method may take a while.
* Aquifers do not create water in diagonal tiles, but do create water in hollow tiles directly below them. Therefore, you will want to dig two z-levels below the lowest aquifer layer before continuing with your fortress.

Two [http://www.bay12forums.com/smf/index.php?topic=79224.0 pump-based implementations] have been tested and found to meet dwarven standards of excellence. 

===The modding method===

By editing the the raws and removing the [AQUIFER] tag from all of the appropriate entries in inorganic_stone_layer.txt, inorganic_stone_mineral.txt, and inorganic_stone_soil.txt it is possible to remove all aquifers from the world. This can be done before creating a new world or after, if you find a particularly neat location ruined only by the presence of an aquifer. In order to modify an existing world, you must delete the [AQUIFER] tag from the raws in the savegame's folder.

On Linux:

cd df_linux/raw/objects/
sed -i 's/\[AQUIFER\]/(AQUIFER)/g' inorganic_stone_*.txt

and generate world. To edit an already generated world, run the <code>sed</code> command in the <tt>df_linux/data/save/''regionNN''/raw/objects</tt> folder instead. If you want to restore the tags later, you can do it with the command:

sed -i 's/(AQUIFER)/[AQUIFER]/g' inorganic_stone_*.txt

===Digging with help from below===

So say you sneak down below the aquifer through an ore vein or something, but you still want to punch a tunnel through a part of the aquifer that does ''not'' afford such luxury. With a typical double-layer aquifer (with an unsafe layer beneath it that fills from above) it is not easy to push through a stairwell where you'd like, even if you have access to the space beneath. Start by ensuring 24 building materials (wood or stone) are available close by on the layer above the top aquifer, and that a ''large'' space (at least 25x25 or so, preferably larger) is available on the top safe layer under the aquifer, four layers beneath the first. Dig or build an up-down stair at the same position on the upper and lower safe levels, and surround the top up-down stair with 8 down-stairs for better access. Have at least three legendary diggers and half a dozen moderately skilled masons close by and idle. It also helps to have a stairway or open space leading down from the lower level to relieve water buildup at the point you'll make the hole.

Start by digging an up/down stairway upward from the bottom safe stairway into the bottom (third) layer. Water will start pouring out into the bottom level. Designate the next two squares up (on the aquifer levels) as up-down stairs to link the two, and wait until the diggers get started on them. Then designate a 3x3x3 block around these as up-down stairs on the two aquifer levels and the unsafe level beneath. Once they're built very large amounts of water will be pouring down into the lower space. ''Warning:'' unlike in the previous version, diggers now make a habit of canceling designations that they feel they can't get to, such as if the lower level is too flooded for them to approach. Make sure all 27 up-down stairs are dug out ASAP. Then wall six squares on the top level (leaving two to be walled once the corners are filled in), and proceed downward from completed walls until you've walled squares on all three levels. After you finish, I'm not sure if it's technically necessary to construct up-down stairs in the space you dug out by designation in order to stop all water leakage.

===Going around===

If your embark site is covered by multiple biomes, there is a chance the aquifer is not present in every biome. In some maps this may be indicated by an outcropping of stone in a landscape otherwise composed of soil; in other maps the change in biome might be visible as a change in soil type or vegetation type or density. You might be able to dig down through a biome that doesn't have an aquifer, to a Z-level below the aquifer, and then (if you wish) tunnel beneath the aquifer to the previously inaccessible region.

Even if all the biomes of your site contain aquifers, they might not all be at the same Z-level. So you still might be able to dig down in one biome, reaching a Z-level beneath the aquifer in another biome.

== Benefits of aquifers ==
While annoying, aquifers can be useful for building a self-sufficient fortress, and for water-related {{l|megaprojects}}. Since an aquifer can absorb an infinite amount of water, it can function as a drain for anything above it. For instance, digging a pit in a lower Z level of an aquifer, then connecting it to a breached aquifer a level above through a channel dug a level above ''that'' will create a permanently flowing, compact, secure water/power source completely contained within the fortress.

Aquifers outside {{l|ocean}} biomes also contain fresh water. Since aquifers are almost always located close to the surface, freshwater aquifers can easily be turned into a source of infinite, secure, non-freezing drinking water for your dwarves, eliminating the need for a {{l|cistern}}. While both of these roles can also be filled by {{l|Caverns|cavern}} features, an aquifer allows you to get the same advantages without exposing yourself to potentially dangerous cavern creatures.

== External links ==

* [http://www.bay12forums.com/smf/index.php?topic=79224.15 QuantumMenace's two-slit method] for breaching aquifers of any depth - Illustrated guide

{{World}}

[[Category:World]]

Utility:SoundSense

2011-09-03T20:14:54Z

Vyznev: add some nicer formatting

=SoundSense=

Discussion: http://www.bay12forums.com/smf/index.php?topic=60287.0
Homepage: 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.

===On some Linux===

====Error on 'soundSense.sh' call: "/bin/sh^M : wrong interpret"====

File "soundSense.sh" has CR+LF characters at lines ending.
Convert these characters to a more suitable form, with a tool like "[http://en.wikipedia.org/wiki/Unix2dos dos2unix]":
dos2unix soundSense.sh
Shell script should then be run without previous error.

Also using sed you can try this:
# IN UNIX ENVIRONMENT: convert DOS newlines (CR/LF) to Unix format.
sed -i -e 's/\r$//' ./soundSense.sh
IF launching .sh file after that, says that something is wrong on the last line, when you try to launch sh. Just check, if "fi" is present there instead of "f" or smth like that.

====Error at playing any MP3 file: "javax.sound.sampled.UnsupportedAudioFileException: could not get audio input stream from input file: could not get audio input stream from input file"====

Your Java virtual machine failed at reading MP3 files as audio stream. This could fix by adding to JVM an extra plugin: [http://www.oracle.com/technetwork/java/javase/download-137625.html JMF MP3 Plugin].
Download plugin, and put *.jar files into your JVM "lib/ext/" directory.

====Error at playing any MP3 file: "javax.sound.sampled.LineUnavailableException: Audio Device Unavailable"====

Whereas your JVM succeeded in reading MP3 file as audio stream, it failed to access to an audio device. If your audio system uses [http://fr.wikipedia.org/wiki/Advanced_Linux_Sound_Architecture Alsa], you could install "aoss" utility, and "soundSense.sh" will call it. On Debian, package "alsa-oss" provides this utility.

====Goddammit I'm using pulseaudio and I still can't hear anything!====

Try to install osspd OR use padsp wrapper. While padsp wrapper wouldn't work everytime for me, osspd daemon worked just fine. (''[https://wiki.archlinux.org/index.php/Pulseaudio#OSS Archlinux Pulseaudio user]'')

===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.
* ''playbackThreshhold'' - number, 0-4, defines level of filter which is applied to this sound.

===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.
* ''randomBalance'' - boolean, if set to true will randomply distribute sound betweem stereo channels.
* ''balanceAdjustment'' - number, adjusts stereo channel, can range for -1 (full left) to 1 (full right).

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/

Utility:SoundSense

2011-09-03T20:09:32Z

Vyznev: more list item fixes

=SoundSense=

Discussion: http://www.bay12forums.com/smf/index.php?topic=60287.0
Homepage: 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.

===On some Linux===

====Error on 'soundSense.sh' call: "/bin/sh^M : wrong interpret"====

File "soundSense.sh" has CR+LF characters at lines ending.
Convert these characters to a more suitable form, with a tool like "[http://en.wikipedia.org/wiki/Unix2dos dos2unix]":
dos2unix soundSense.sh
Shell script should then be run without previous error.

Also using sed you can try this:
# IN UNIX ENVIRONMENT: convert DOS newlines (CR/LF) to Unix format.
sed -i -e 's/\r$//' ./soundSense.sh
IF launching .sh file after that, says that something is wrong on the last line, when you try to launch sh. Just check, if "fi" is present there instead of "f" or smth like that.

====Error at playing any MP3 file: "javax.sound.sampled.UnsupportedAudioFileException: could not get audio input stream from input file: could not get audio input stream from input file"====

Your Java virtual machine failed at reading MP3 files as audio stream. This could fix by adding to JVM an extra plugin: [http://www.oracle.com/technetwork/java/javase/download-137625.html JMF MP3 Plugin].
Download plugin, and put *.jar files into your JVM "lib/ext/" directory.

====Error at playing any MP3 file: "javax.sound.sampled.LineUnavailableException: Audio Device Unavailable"====

Whereas your JVM succeeded in reading MP3 file as audio stream, it failed to access to an audio device. If your audio system uses [http://fr.wikipedia.org/wiki/Advanced_Linux_Sound_Architecture Alsa], you could install "aoss" utility, and "soundSense.sh" will call it. On Debian, package "alsa-oss" provides this utility.

====Goddammit I'm using pulseaudio and I still can't hear anything!====

Try to install osspd OR use padsp wrapper. While padsp wrapper wouldn't work everytime for me, osspd daemon worked just fine. (''[https://wiki.archlinux.org/index.php/Pulseaudio#OSS Archlinux Pulseaudio user]'')

===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.
* playbackThreshhold - number, 0-4, defines level of filter which is applied to this sound.

===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.
* randomBalance - boolean, if set to true will randomply distribute sound betweem stereo channels.
* balanceAdjustment - number, adjusts stereo channel, can range for -1 (full left) to 1 (full right).

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/

Utility:SoundSense

2011-09-03T20:05:55Z

Vyznev: /* Some Tips: */ rm line breaks to fix bullet points

=SoundSense=

Discussion: http://www.bay12forums.com/smf/index.php?topic=60287.0
Homepage: 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.

===On some Linux===

====Error on 'soundSense.sh' call: "/bin/sh^M : wrong interpret"====

File "soundSense.sh" has CR+LF characters at lines ending.
Convert these characters to a more suitable form, with a tool like "[http://en.wikipedia.org/wiki/Unix2dos dos2unix]":
dos2unix soundSense.sh
Shell script should then be run without previous error.

Also using sed you can try this:
# IN UNIX ENVIRONMENT: convert DOS newlines (CR/LF) to Unix format.
sed -i -e 's/\r$//' ./soundSense.sh
IF launching .sh file after that, says that something is wrong on the last line, when you try to launch sh. Just check, if "fi" is present there instead of "f" or smth like that.

====Error at playing any MP3 file: "javax.sound.sampled.UnsupportedAudioFileException: could not get audio input stream from input file: could not get audio input stream from input file"====

Your Java virtual machine failed at reading MP3 files as audio stream. This could fix by adding to JVM an extra plugin: [http://www.oracle.com/technetwork/java/javase/download-137625.html JMF MP3 Plugin].
Download plugin, and put *.jar files into your JVM "lib/ext/" directory.

====Error at playing any MP3 file: "javax.sound.sampled.LineUnavailableException: Audio Device Unavailable"====

Whereas your JVM succeeded in reading MP3 file as audio stream, it failed to access to an audio device. If your audio system uses [http://fr.wikipedia.org/wiki/Advanced_Linux_Sound_Architecture Alsa], you could install "aoss" utility, and "soundSense.sh" will call it. On Debian, package "alsa-oss" provides this utility.

====Goddammit I'm using pulseaudio and I still can't hear anything!====

Try to install osspd OR use padsp wrapper. While padsp wrapper wouldn't work everytime for me, osspd daemon worked just fine. (''[https://wiki.archlinux.org/index.php/Pulseaudio#OSS Archlinux Pulseaudio user]'')

===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.
* playbackThreshhold - number, 0-4, defines level of filter which is applied to this sound.

===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.
* randomBalance - boolean, if set to true will randomply distribute sound betweem stereo channels.
* balanceAdjustment - number, adjusts stereo channel, can range for -1 (full left) to 1 (full right).

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/

Utility:SoundSense

2011-09-03T20:02:08Z

Vyznev: /* Error on 'soundSense.sh' call: "/bin/sh^M : wrong interpret" */ use \r in sed command to make it safe even if there are bare LFs

=SoundSense=

Discussion: http://www.bay12forums.com/smf/index.php?topic=60287.0
Homepage: 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.

===On some Linux===

====Error on 'soundSense.sh' call: "/bin/sh^M : wrong interpret"====

File "soundSense.sh" has CR+LF characters at lines ending.
Convert these characters to a more suitable form, with a tool like "[http://en.wikipedia.org/wiki/Unix2dos dos2unix]":
dos2unix soundSense.sh
Shell script should then be run without previous error.

Also using sed you can try this:
# IN UNIX ENVIRONMENT: convert DOS newlines (CR/LF) to Unix format.
sed -i -e 's/\r$//' ./soundSense.sh
IF launching .sh file after that, says that something is wrong on the last line, when you try to launch sh. Just check, if "fi" is present there instead of "f" or smth like that.

====Error at playing any MP3 file: "javax.sound.sampled.UnsupportedAudioFileException: could not get audio input stream from input file: could not get audio input stream from input file"====

Your Java virtual machine failed at reading MP3 files as audio stream. This could fix by adding to JVM an extra plugin: [http://www.oracle.com/technetwork/java/javase/download-137625.html JMF MP3 Plugin].
Download plugin, and put *.jar files into your JVM "lib/ext/" directory.

====Error at playing any MP3 file: "javax.sound.sampled.LineUnavailableException: Audio Device Unavailable"====

Whereas your JVM succeeded in reading MP3 file as audio stream, it failed to access to an audio device. If your audio system uses [http://fr.wikipedia.org/wiki/Advanced_Linux_Sound_Architecture Alsa], you could install "aoss" utility, and "soundSense.sh" will call it. On Debian, package "alsa-oss" provides this utility.

====Goddammit I'm using pulseaudio and I still can't hear anything!====

Try to install osspd OR use padsp wrapper. While padsp wrapper wouldn't work everytime for me, osspd daemon worked just fine. (''[https://wiki.archlinux.org/index.php/Pulseaudio#OSS Archlinux Pulseaudio user]'')

===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.
* playbackThreshhold - number, 0-4, defines level of filter which is applied to this sound.

===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.
* randomBalance - boolean, if set to true will randomply distribute sound betweem stereo channels.
* balanceAdjustment - number, adjusts stereo channel, can range for -1 (full left) to 1 (full right).

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/