About Audio

About Audio

Kinds of audio

There are two basic kinds auf audio in Widelands: music and sound effects. Music is split in three areas: the intro, which is played during the initial splash screen, music to be played in the full screen menus outside of a game and ingame music.

Sound effects are more varied: basically anything that is visible can produce an fx at any time:

• "non-player stuff", like animals and trees
• buildings in any of their phases: construction site, idle, different work programs
• workers of all kinds
• and of course the UI itself

Workers and buildings can produce sounds synchronized to either their appearance (i.e. to a certain frame of their "animation") or their status (i.e. their "work program").

To find out where we could use the most help, look at Sound Effects. If you are into longer pieces, just compose a little symphony or two and tell us

Adding your own music

A single piece

1. Decide whether your music is for the menus or should be played during the game
2. Write a song and encode it (see below for details on the file format)
3. Put your song into widelands/music
4. Name your song menu_XX.ogg or ingame_XX.ogg. XX stands for a number between 00 and 99 (use a leading zero, "ingame_1.ogg" is invalid). Each song must have a unique number. Songs with the same name and different numbers will be selected at random.
5. Widelands will pick up your song the next time you start it

Example:

 widelands/sound/ingame_07.ogg
 widelands/sound/ingame_16.ogg

Several pieces in a directory

You want to listen to your ogg collection in Widelands? You have written 150 songs and there are not enough numbers left? Just put your songs into a directory and follow those rules:

1. The toplevel directory must be named menu_XX or ingame_XX (this toplevel directory can also be a symbolic link!)
2. Subdirectories and songs can be named anything you like and can be nested as deep as you like
3. Widelands will pick up your song the next time you start it

Example:

 widelands/music/ingame_12/myCD_song1.ogg
 widelands/music/ingame_12/myCD_song2.ogg
 widelands/music/ingame_12/myCD_song3.ogg

 widelands/music/ingame_13/sub/song-1.ogg
 widelands/music/ingame_13/sub/song-2.ogg
 widelands/music/ingame_13/sub/dir/song-n.ogg

Adding your own sound effects

User interface

Audio for the UI is tightly integrated with the code. Please contact the developers for information.

Effects synchronized to work programs

1. Having more than one audio file for the same effect is encouraged!
2. Edit the file "conf" in the right directory:

• widelands/tribes/TRIBE/buildings/BUILDING/ or
• widelands/tribes/TRIBE/workers/WORKER/ or
• widelands/tribes/TRIBE/bobs/BOB/

3. In the [[global] section, register every sound effect you will be using with the directive "soundfx=NAME"
4. In the work program, use the command "playFX NAME" to play the effect
5. Put your audio file(s) in the same directory as the "conf" file. Name it NAME_XX.ogg where NAME is the same you used in "soundfx=". The naming conventions for music apply here, too, so you can use subdirectories.

Example:
The fisher should emit one of three effects on throwing his net, and one of three other effects when pulling it in again.

Files:
throw_fishnet_00.ogg, throw_fishnet_01.ogg, throw_fishnet_02.ogg
retrieve_fishnet_00.ogg, retrieve_fishnet_01.ogg, retrieve_fishnet_02.ogg

In the conf file (note lines 2 and 5 of the work program):
[[global]
soundfx=throw_fishnet
soundfx=retrieve_fishne

[[fish]
0=findspace size:any radius:7 resource:fish
1=walk coords
2=playFX throw_fishnet
3=mine fish 1
4=animation idle 3000
5=playFX retrieve_fishnet
6=createitem fish
7=return

In this special case, you might also have used sound synchronized to the animation in point 4. This should, however, only be done for animations that repeat over and over.

Effects synchronized to animations

This is similar in nature to effects synchronized to work programs, just the config file is different. This time, you have to edit the section for the animation you are aiming for. All other rules mentioned before apply here, too.

Use "sfx_name=NAME" to specifiy an effect name and "sfx_frame" for the frame number at which the effect should be triggered. Note that only the beginning is synchronized, you cannot depend on the effect ending at a certain time.

Be careful to have the same number of "sfx_name" as of "sfx_frame", otherwise you will hear ... something potentially quite funny

Example:
Assume that there are 50 frames in the animation and that you have the sound of someone chopping wood.
Files:

 wood_chop_00.ogg, wood_chop_01.ogg, wood_chop_02.ogg

In the conf file: [[global]
soundfx=wood_chop

# Cutting down a tree

[[harvesting]
pics=harvesting_??.png
sfx_frame=25
sfx_name=wood_chop
clrkey_r=0
clrkey_g=0
clrkey_b=255
hot_spot_x=5
hot_spot_y=13

Internationalized sound effects

Unlike music, sound effects can be recorded for several languages. For example, you could use this to change the lumberjack's warning call from "TIMBEEEEER!" to "BAUM FÄÄLLLLT!" for German players.

To use i18n-ed sound effects, just follow the usual naming scheme but append the locale to the filename/directory.
Examples:

  barbarians/workers/lumberjack/timber_00.ogg
  barbarians/workers/lumberjack/timber_01.ogg
  barbarians/workers/lumberjack/timber_02/
  barbarians/workers/lumberjack/timber_02/1.ogg
  barbarians/workers/lumberjack/timber_02/n.ogg

  barbarians/workers/lumberjack/timber_00.ogg.de_DE
  barbarians/workers/lumberjack/timber_01.ogg.de_DE
  barbarians/workers/lumberjack/timber_02.de_DE/
  barbarians/workers/lumberjack/timber_02.de_DE/1.ogg
  barbarians/workers/lumberjack/timber_02.de_DE/n.ogg

For any given effect:
If there is no localized file, the generic files (most probably in English) will be used. If there is at least one localized file, all the generic files will be ignored. (once again: this is determined per effect name, not per worker or anything else)

File format

All music and all sound effects in Widelands are encoded as Ogg.

Nominal and average bitrates typically range from 30 to 80 kbit/sec for sound effects, music should be encoded at or below about 150kbit/sec. Please use higher bitrates only if it is neccessary.

Sound effects should be recorded in mono (stereo effects are applied in-game), music may be mono or stereo.

Conditions for sound effect playback

(this is only a preview, the code is still under development)

You will not hear your sound effect every time you expect it to be played!

Having every effect play every time is not funny anymore when you have 50 buildings/workers playing a sound every 5 seconds Therefore, Widelands will implement a selection algorithm:

1. Any effect will be heard only once in a certain timespan (there are exceptions, e.g. for "start of battle")
2. If there are lots of effects that want to be played, less important ones will be played less often (no effect gets totally blocked, though)
3. Sound effects can register a priority that influences the decision in #2.