Directory Layout

Sounds and themes are looked for in a set of directories. By default, applications should look in $XDG_DATA_DIRS/sounds. Applications may further add their own sound directories to this list, and users may extend or change the list (in application/desktop specific ways). In each of these directories themes are stored as subdirectories. A theme can be spread across several base directories by having subdirectories of the same name. This way users can extend and override system themes.

In order to have a place for third party applications to install their sounds there should always exist a theme called "freedesktop". The data for the freedesktop theme is available for download at: sound theme specification page. Implementations are required to look in the "freedesktop" theme if a sound was not found in the current theme.

Each theme is stored as subdirectories of the base directories. The internal name of the theme is the name of the subdirectory, although the user-visible name as specified by the theme may be different. Hence, theme names are case sensitive, and are limited to ASCII characters. Theme names may also not contain comma or space.

In at least one of the theme directories there must be a file called index.theme that describes the theme. The first index.theme found while searching the base directories in order is used. This file describes the general attributes of the theme.

In the theme directory are also a set of subdirectories containing sound files. The subdirectories are allowed to be several levels deep, e.g. the subdirectory "stereo/alerts" in the theme "freedesktop" would end up at $basedir/freedesktop/stereo/alerts.

The sounds files must be one of the types: WAV/PCM 8-48kHz, 8/16 bits or OGG/Vorbis I. The extension must be ".wav", or ".oga" respectively (in lower case). It is not recommended to use ".ogg" extension, but it is also supported for legacy reasons.

Besides the sound files, there may be an additional file with extra sound data for each file. It should have the same basename as the sound file, with the extension ".sound". e.g. if the sound file is called "system-shutdown.wav" the corresponding file would be named "system-shutdown.sound".

Finally, a pseudo file format ".disabled" is used for disabling sounds in a theme that inherits from another theme. If the sound lookup algorithms detects a file with the suffix ".disabled" it shall immediately terminate the lookup logic and consider the sound not available. All files with ".disabled" suffix should be of length zero.

To save disk space Vorbis I encoded sound files are recommended.

The sound samples must be normalized with a suitable average replay level, in order to be properly mixed down. For more informations, please read Replay Gain Calculation from and check that your volume level is reasonable.

Sounds for different output profiles (i.e. for Stereo, Surround 4.1, Surround 5.1 and so on) may be part of a theme. All implementations are required to fallback to the "stereo" output profile as last resort.