Currently Online

Latest Posts

Changes in AboutAudio

Editor Comment

sound for immovables


Revision Differences of Revision 11

[TOC] ¶

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

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

## Music ¶

Music files could be found in the folder `data/music` and are played in different parts of widelands. The name of the sound files reflect when they are played ('xx' stand for a two digit number): ¶

View | Filename(s) ¶
------ | --------------- ¶
Intro (First splashscreen) | intro_xx.ogg ¶
Menu | menu_xx.ogg ¶
During game | ingame_xx.ogg ¶

Files with same name, like `ingame_` but different numbers are played randomly. ¶

### 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 [File format](#file-format)) ¶
3. Put your song into the folder `widelatands/music` ¶
4. Name your song `menu_XX.ogg` or `ingame_XX.ogg`. Where 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. ¶
Example file names: ¶

wi`delandsta/music/ingame_07.ogg`
wi`delandsta/music/ingame_16.ogg
`

5. Widelands will pick up your song the next time you start it ¶

### 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 ¶
Examples: ¶

wi`delandsta/music/ingame_12/myCD_song1.ogg`
wi`delandsta/music/ingame_12/myCD_song2.ogg`
wi`delatands/music/ingame_12/myCD_song3.ogg`

wi`delandsta/music/ingame_13/sub/song-1.ogg`
wi`delandsta/music/ingame_13/sub/song-2.ogg`
wi`delatands/music/ingame_13/sub/dir/song-n.ogg`

3. Widelands will pick up your song the next time you start it ¶

## Sound effects ¶

All sound effects are placed in the folder `widelatands/sound/`. You will find several subfolders which contains sound effects for specific things. ¶
Sound effects are joined with different types of objects: ¶

Object | Sound ¶
---------| -------- ¶
Buildings | Turning sail of a windmill ; An ax get sharpend in a ax workshop ¶
Workers | Lumberjack fells a tree; Farmer carves wheat ¶
Immovables | Trees have birds singing or crickets chirping; Grass have frogs croaking, Sound to animals ¶

__IMPORTAND NOTE:__ Sound effects are defined in script files. Those files should be edited with simple text editors. Please do not edit them with word or an office suite. ¶

### Conditions for sound effect playback ¶

Having every effect play every time is not funny anymore when you have 50 buildings/workers playing a sound every 5 seconds. Therefor you will not hear your sound effect every time you expect it to be played! ¶

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 ¶

### Effects synchronized to Immovables ¶

Effects for immovables are defined in the corresponding `init.lua` file. One can find them in the folders beneath `data/world/immovables/`. Here is an example of `data/world/immovables/grass1/init.lua`: ¶

~~~~ ¶
animations = { ¶
idle = { ¶
pictures = path.list_files(dirname .. "idle.png"), ¶
hotspot = { 10, 20 }, ¶
sound_effect = { ¶
directory = "sound/animals", ¶
name = "frog1", ¶
}, ¶
}, ¶
} ¶
~~~~ ¶

The usage should be clear: ¶

Line | Meaning ¶
------- | ---------- ¶
`sound_effect = {` | adds the predefined table "sound_effect" ¶
`directory = "sound/animals",` | is the path to the folder where the soundfile is stored ¶
`name = "frog1",` | is the filename of the sond ¶
`},` | closes the table "sound_effect" ¶



### Effects synchronized to buildings

~~~~ ¶
programs = { ¶
work = { ¶
-- TRANSLATORS: Completed/Skipped/Did not start rearing cattle because ... ¶
descname = _"rearing cattle", ¶
actions = { ¶
"sleep=15000", ¶
"return=skipped unless economy needs barbarians_ox", ¶
"consume=wheat water", ¶
"playFX=sound/farm ox 192", ¶
"animate=working 15000", -- Animation of feeding the cattle ¶
"recruit=barbarians_ox" ¶
} ¶
}, ¶
}, ¶
~~~~

### Effects synchronized to workers ¶

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

* widelands/sound/animals/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) ¶