AboutAudio

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 )
3. Put your song into the folder data/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:

   data/music/ingame_07.ogg
data/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:

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

   data/music/ingame_13/sub/song-1.ogg
data/music/ingame_13/sub/song-2.ogg
data/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 data/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:

3. widelands/sound/animals/BUILDING/ or

4. widelands/tribes/TRIBE/workers/WORKER/ or

5. widelands/tribes/TRIBE/bobs/BOB/

6. In the [[global] section, register every sound effect you will be using with the directive "soundfx=NAME"

7. In the work program, use the command "playFX NAME" to play the effect
8. 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)