Latest Posts

Changes in AboutAudio

Editor Comment

added missing spaces around words in section "Internationalized sound effects"


Revision Differences of Revision 4

## 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 SoundEffects. 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. ¶