Version 0.1 February 11 2008 Marc-Andre Lureau

marc-andre.lureau@nokia.com

A sound theme is a set of sounds that share a common feel, or instrument set. The user can then select the sound theme that they want to use, and all apps use sounds from the theme. The initial user of sounds themes is the desktop notification service. But it can have other uses. From a programmer perspective a sound theme is just a mapping. Given a set of directories to look for sounds in and a theme name it maps from sound name to an sound filename. Sound Theme A sound theme is a named set of sounds. It is used to map from a sound name. Themes may inherit from other themes as a way to extend them. Sound file The supported sound file formats are WAV/PCM 48kHz, 16bits, and OGG/Vorbis. WAV is the recommended uncompressed format, and OGG/Vorbis is for compressed. Support for OGGs is optional. Base Directory Sounds and themes are searched for in a set of directories, called base directories. The themes are stored in subdirectories of the base directories. Sounds and themes are looked for in a set of directories. By default, apps 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: http://www.freedesktop.org/software/sound-theme/. 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. (FIXME) The sounds files must be one of the types: WAV/PCM 48kHz, 16 bits or OGG/Vorbis. The extension must be ".wav", or ".ogg" respectively (lower case). The support for OGG files is optional. Implementations that do not support OGGs should just ignore any ".ogg" files. In addition to this 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-log-out.wav" the corresponding file would be named "system-log-out.sound". Both the sound theme description file and the sound data files are ini-style text files, as described in the desktop file specification. They don't have any encoding field. Instead, they must always be stored in UTF-8 encoding. The index.theme file must start with a section called Sound Theme, with contents according to table 1 below. All lists are comma-separated. Key Description Value Type Required Name short name of the sound theme, used in e.g. lists when selecting themes. localestring YES Comment longer string describing the theme localestring YES Inherits The name of the theme that this theme inherits from. If a sound name is not found in the current theme, it is searched for in the inherited theme (and recursively in all the inherited themes). If no theme is specified implementations are required to add the "freedesktop" theme to the inheritance tree. An implementation may optionally add other default themes in between the last specified theme and the freedesktop theme. strings NO Directories list of subdirectories for this theme. For every subdirectory there must be a section in the index.theme file describing that directory. strings YES Hidden Whether to hide the theme in a theme selection user interface. This is used for things such as fallback-themes that are not supposed to be visible to the user. boolean NO Example The name of a sound that should be used as an example of how this theme sounds like. string NO Each directory specified in the Directory key has a corresponding section with the same name as the directory. The contents of this section is listed in table 2 below. Key Description Value Type Required Type Context The context the sound is normally used in. This is in detail discussed in . string NO SoundSystem Define the sound system for which the sounds are made for. It can be "stereo" or "5.1", or whatever system suits the configuration in which they are recorded. string NO Length Nominal length in seconds of the sounds in this directory. (FIXME) integer NO Locale Locale name, if applicable. (FIXME: not usable since transaltions would have to update the index.. instead subdirectoy locale seems more efficient...) string NO In addition to these groups you may add extra groups to the index.theme file in order to extend it. These extensions must begin with "X-", and can be used to add desktop specific information to the theme file. Example group names would be "X-KDE Sound Theme" or "X-Gnome Sound Theme". The optional filename.sound file contains a group called "Sound Data", with the content listed in table 3. Key Description Value Type Required DisplayName A translated UTF8 string that can be displayed instead of the sound by a user interface. localestring NO Loop Indicates if the sound is appropriate in loop-mode playing. This can be useful for ringing tones, environment, instruments... boolean NO Extensions to the filename.sound file are allowed, but the keys must be begin with "X-" to avoid collisions with future standardized extensions to this format. The Context allows the designer to group sounds on a conceptual level. It doesn't act as a namespace in the file system, such that sounds can have identical names, but allows implementations to categorize and sort by it, for example. These are the available contexts: Sounds to alert the user of an action or event which may have a major imact on the system or their current use case, such as dialog-error. Sounds to notify the user that the system, or their current use case has changed state in some way, e.g. new email arriving, new non-critical update available... Sounds that give the user feedback on their actions. Sounds on window opening / closing for example. Sounds used for games. The sound lookup mechanism has two global settings, the list of base directories and the internal name of the current theme. Given these we need to specify how to look up sound file from the sound name. The lookup is done first in the current theme, and then recursively in each of the current theme's parents, and finally in the default theme called "freedesktop" (implementations may add more default themes before "freedesktop", but "freedesktop" must be last). As soon as there is a sound that matches in a theme, the search is stopped. The lookup inside a theme is done in three phases. First all the directories are scanned for an exact match, e.g. one where the locale of the sound match what was looked up. Then all the directories are scanned for any sound that matches the name. If that fails we finally fall back on unthemed sound. If we fail to find any sound at all it is up to the application to pick a good fallback, as the correct choice depends on the context. The exact algorithm (in pseudocode) for looking up a sound in a theme (if the implementation supports OGG) is: FindSound(sound, locale) { filename = FindSoundHelper(sound, locale, soundsystem, user selected theme); if filename != none return filename filename = FindSoundHelper(sound, locale, soundsystem, "freedesktop"); if filename != none return filename return LookupFallbackSound (sound) } FindSoundHelper(sound, locale, soundsystem, theme) { filename = LookupSound (sound, locale, soundsystem, theme) if filename != none return filename if theme has parents parents = theme.parents for parent in parents { filename = FindSoundHelper (sound, locale, soundsystem, parent) if filename != none return filename } return none } With the following helper functions: LookupSound (sound, locale, soundsystem, theme) { // lookup localized version for each subdir in $(theme subdir list) { for each directory in $(basename list) { for system in (soundsystem, "stereo") { if DirectoryMatchesSoundSystem(subdir, system) { for extension in ("wav", "ogg") { filename = directory/$(themename)/subdir/$locale/sound.extension if exist filename return filename } } } } } // lookup unlocalized version for each subdir in $(theme subdir list) { for each directory in $(basename list) { for system in (soundsystem, "stereo") { if DirectoryMatchesSoundSystem(subdir, system) { for extension in ("wav", "ogg") { filename = directory/$(themename)/subdir/sound.extension if exist filename return filename } } } } } return none } LookupFallbackSound (sound) { for each directory in $(basename list) { for extension in ("wav", "ogg") { if exists directory/sound.extension return directory/sound.extension } } return none } DirectoryMatchesSoundSystem(subdir, system) { read SoundSystem from subdir if SoundSystem == system return true return false } Here is an example index.theme file: [Sound Theme] Name=Birch Name[fr]=Bouleau Comment=Sound theme using wooden instruments Comment[fr]=Theme utilisant des instruments en bois Inherits=wood,default Directories=stereo/alert/fr notifications/long/5.1 [stereo/alert/fr] Context=Alert SoundSystem=stereo [notifications/long/5.1] Context=Notification SoundSystem=5.1 The corresponding directory tree in the /usr/share/sounds directory could look like this: birch/index.theme birch/stereo/alert/evolution-urgent-message.ogg birch/stereo/alert/evolution-urgent-message.wav birch/stereo/alert/fr/evolution-urgent-message.ogg birch/stereo/alert/evolution-urgent-message.sound birch/5.1/alert/evolution-urgent-message.ogg Where birch/stereo/alert/evolution-urgent-message.sound contains: [Sound Data] DisplayName=Evolution urgent message DisplayName[fr]=Message urgent dans Evolution Loop=yes In this example a lookup of "evolution-urgent-message", with a 5.1 system preference and no localization, would get the "birch/5.1/alert/evolution-urgent-message.ogg" sound file. So, you're an application author, and you want to install sounds so that they can be used by your application. Minimally you should install the sound file in the "freedesktop" theme. This means installing a stereo WAV file in $XDG_DATA_DIRS/sounds/freedesktop/stereo/$context. Optionally you can install sounds in different formats and language. For example, installing a localized OGG/Vorbis 5.1 game sound in $prefix/share/sounds/freedesktop/5.1/game/fr. You might even want to install sounds that matches other well known themes so your application will fit in with some specific desktop environment. It is recommended that the sounds installed in the freedesktop theme sound neutral, since it is a fallback theme that will be used in combination with some very different sounds from any origin. But if you don't have any neutral sound, please install whatever sound you have in the freedesktop theme so that all your application can at least produce some sounds in all themes. The algorithm as described in this document works by always looking up filenames in directories (a stat in unix terminology). A good implementation is expected to read the directories once, and do all lookups in memory using that information. This caching can make it impossible for users to add sounds without having to restart applications. In order to handle this, any implementation that does caching is required to look at the mtime of the toplevel sound directories when doing a cache lookup, unless it already did so less than 5 seconds ago. This means that any sound editor or theme installation program need only to change the mtime of the the toplevel directory where it changed the theme to make sure that the new sounds will eventually get used. The sound theme specification is heavily based on the "Icon Theme Specification" by Alexander Larsson and Frans Englich. Initial draft.