diff options
Diffstat (limited to 'sound-theme/sound-theme-spec.xml')
-rw-r--r-- | sound-theme/sound-theme-spec.xml | 756 |
1 files changed, 756 insertions, 0 deletions
diff --git a/sound-theme/sound-theme-spec.xml b/sound-theme/sound-theme-spec.xml new file mode 100644 index 0000000..5aa1d4f --- /dev/null +++ b/sound-theme/sound-theme-spec.xml @@ -0,0 +1,756 @@ +<?xml version="1.0"?> +<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" +"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ +]> +<article id="index"> + <articleinfo> + <title>Sound Theme Specification</title> + <releaseinfo>Post-0.5 Snapshot</releaseinfo> + <date>Post 2008</date> + <authorgroup> + <author> + <firstname>Marc-Andre</firstname> + <surname>Lureau</surname> + <authorblurb><para>Sound Theme Specification</para></authorblurb> + <affiliation> + <address> + <email>marcandre.lureau@gmail.com</email> + </address> + </affiliation> + </author> + <author> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <authorblurb><para>PulseAudio Project</para></authorblurb> + <affiliation> + <address> + <email>lennart@poettering.net</email> + </address> + </affiliation> + </author> + <author> + <firstname>Patryk</firstname> + <surname>Zawadzki</surname> + <authorblurb><para>Initial Sound Theme Specification draft proposal</para></authorblurb> + <affiliation> + <address> + <email>patrys@pld-linux.org</email> + </address> + </affiliation> + </author> + <author> + <firstname>Alexander</firstname> + <surname>Larsson</surname> + <authorblurb><para>Icon Theme Specification author</para></authorblurb> + <affiliation> + <address> + <email>alexl@redhat.com</email> + </address> + </affiliation> + </author> + <author> + <firstname>Frans</firstname> + <surname>Englich</surname> + <authorblurb><para>Icon Theme Specification author</para></authorblurb> + <affiliation> + <address> + <email>frans.englich@telia.com</email> + </address> + </affiliation> + </author> + </authorgroup> + </articleinfo> + + <sect1 id="overview"> + <title>Overview</title> + <para> + A sound theme is a set of event sounds that share a common feel, + or instrument set. The user can then select the sound theme that + they want to use, and all applications use sounds from the theme. + </para> + <para> + 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 a sound filename. + </para> + </sect1> + + <sect1 id="definitions"> + <title>Definitions</title> + <variablelist> + <varlistentry> + <term>Sound Theme</term> + <listitem> + <para> + 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. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Sound file</term> + <listitem> + <para> + The mandatory supported sound file formats are WAV/PCM + 8-48kHz, 8/16bits, and OGG/Vorbis I. WAV at 48kHz/Stereo is + the recommended uncompressed format, and OGG/Vorbis I is the + recommended compressed format. The sample must be + normalized, in order to be mixed down nicely with a suitable + average replay level. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Base Directory</term> + <listitem> + <para> + Sounds and themes are searched for in a set of directories, + called base directories. The themes are stored in + subdirectories of the base directories. + </para> + </listitem> + </varlistentry> + </variablelist> + </sect1> + + <sect1 id="directory_layout"> + <title>Directory Layout</title> + <para> + 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. + </para> + <para> + 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: <ulink url="http://www.freedesktop.org/software/sound-theme/"><citetitle>freedesktop.org + sound theme specification page</citetitle></ulink>. + Implementations are required to look in the "freedesktop" theme if + a sound was not found in the current theme. + </para> + <para> + 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. + </para> + <para> + 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. + </para> + <para> + 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. + </para> + <para> + 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. + </para> + <para> + 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". + </para> + <para> + 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. + </para> + <para> + To save disk space Vorbis I encoded sound files are recommended. + </para> + <para> + The sound samples must be normalized with a suitable average + replay level, in order to be properly mixed down. For more + informations, please read + <ulink url="http://replaygain.hydrogenaudio.org/calculating_rg.html"><citetitle>Replay + Gain Calculation from hydrogenaudio.org</citetitle></ulink> and + check that your volume level is reasonable. + </para> + <para> + 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. + </para> + </sect1> + + <sect1 id="file_formats"> + <title>File Formats</title> + <para> + 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 an encoding field. Instead, they + must always be stored in UTF-8 encoding. + </para> + <para> + The index.theme file must start with a section called + <citetitle>Sound Theme</citetitle>, with contents according to + table 1 below. All lists are comma-separated. + <table> + <title>Standard Keys</title> + <tgroup cols="4"> + <thead> + <row> + <entry>Key</entry> + <entry>Description</entry> + <entry>Value Type</entry> + <entry>Required</entry> + </row> + </thead> + <tbody> + <row> + <entry>Name</entry> + <entry> + Short name of the sound theme, used in e.g. lists when + selecting themes. + </entry> + <entry>localestring</entry> + <entry>YES</entry> + </row> + <row> + <entry>Comment</entry> + <entry> + Longer string describing the theme + </entry> + <entry>localestring</entry> + <entry>YES</entry> + </row> + <row> + <entry>Inherits</entry> + <entry> + <para> + 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). + </para> + <para> + 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. + </para> + </entry> + <entry>strings</entry> + <entry>NO</entry> + </row> + <row> + <entry>Directories</entry> + <entry> + List of subdirectories for this theme. For every + subdirectory there must be a section in the index.theme + file describing that directory. + </entry> + <entry>strings</entry> + <entry>YES</entry> + </row> + <row> + <entry>Hidden</entry> + <entry> + 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. + </entry> + <entry>boolean</entry> + <entry>NO</entry> + </row> + <row> + <entry>Example</entry> + <entry> + The name of a sound that should be used as an example of + how this theme sounds like. + </entry> + <entry>string</entry> + <entry>NO</entry> + </row> + </tbody> + </tgroup> + </table> + </para> + <para> + 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. + <table> + <title>Per-Directory Keys</title> + <tgroup cols="4"> + <thead> + <row> + <entry>Key</entry> + <entry>Description</entry> + <entry>Value Type</entry> + <entry>Required</entry> + <entry>Type</entry> + </row> + </thead> + <tbody> + <row> + <entry>Context</entry> + <entry> + The context the sound is normally used in. This + is in detail discussed in <xref linkend="context"/>. + </entry> + <entry>string</entry> + <entry>NO</entry> + </row> + <row> + <entry>OutputProfile</entry> + <entry> + Define the output profile for which the sounds are made + for. It can be "stereo" or "5.1", or any other output configuration. + </entry> + <entry>string</entry> + <entry>NO</entry> + </row> + </tbody> + </tgroup> + </table> + </para> + <para> + 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". + </para> + <para> + The optional file filename.sound contains a group "Sound + Data", with the content listed in table 3. + <table> + <title>Sound Data Keys</title> + <tgroup cols="4"> + <thead> + <row> + <entry>Key</entry> + <entry>Description</entry> + <entry>Value Type</entry> + <entry>Required</entry> + </row> + </thead> + <tbody> + <row> + <entry>DisplayName</entry> + <entry> + A translated UTF8 string that can be displayed instead + of the sound by a user interface. + </entry> + <entry>localestring</entry> + <entry>NO</entry> + </row> + </tbody> + </tgroup> + </table> + </para> + <para> + Extensions to filename.sound are allowed, but the + keys must be begin with "X-" to avoid collisions with future + standardized extensions to this format. + </para> + + <sect2 id="context"> + <title>Context</title> + + <para>The <systemitem>context</systemitem> 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. + </para> + + <para>These are the available contexts:</para> + <itemizedlist> + + <listitem> + <formalpara> + <title>Alert</title> + <para>Sounds to alert the user of an action or event + which may have a major impact on the system or their + current use, such as + <action>dialog-error</action>.</para> + </formalpara> + </listitem> + + <listitem> + <formalpara> + <title>Notification</title> + <para>Sounds to notify the user that the system, or their + current use has changed state in some way, e.g. new email + arriving, new non-critical updates available...</para> + </formalpara> + </listitem> + + <listitem> + <formalpara> + <title>Support</title> + <para>Sounds that give the user feedback on their + actions. Sounds on window opening/closing for + example.</para> + </formalpara> + </listitem> + + <listitem> + <formalpara> + <title>Game</title> + <para>Sounds used for games.</para> + </formalpara> + </listitem> + + </itemizedlist> + + </sect2> + </sect1> + + <sect1 id="sound_lookup"> + <title>Sound Lookup</title> + <para> + The sound lookup mechanism has two global settings, the list of + base directories and the internal name of the current theme. Given + these we specify how to look up sound file from the sound + name. + </para> + <para> + 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). A last fallback is unthemed sound. As soon as there is + a sound that matches in a theme, the search is stopped. + </para> + <para> + To support localized sounds we first lookup the sound in the + LC_MESSAGES locale setting of the program. If that fails, the + locale string is truncated at the "@" if it includes it and it is + tried again. Then, the locale string is truncated at the "_" if it + includes it and it is tried again. Then it is looked for a sound + in the "C" locale. Finally non-localized sound files are searched. + </para> + <para> + If a sound name is not found, it is truncated at the last "-" and + it is tried again. This is done again until no further "-" are + present in the name string. This is useful to define common sounds + for similar events. i.e. instead of defining two seperate sounds + for "new-message-im" and "new-message-email" it might make sense + to define just "new-message" instead. + </para> + <para> + The lookup is done first in the requested output profile, followed + by a lookup in "stereo" on failure and then without any output + profile. + </para> + <para> + The lookup algorithm should check for ".disabled" files first, + followed by ".oga" (then ".ogg", although this might be removed + later) and finally for ".wav". + </para> + <para> + Configuration programs that allow limited user manipulation of the + selected sound theme (i.e. for disabling or replacing certain + sounds), should create a dynamicly created theme "__custom" that + inherits from the selected theme and store it in the + "~/.local/share/sounds/__custom" directory. Its index.theme should + list a single directory ".". The sounds defined in that theme + should not be attached to any output profile and should not be + localized. The overwritten sounds should thus be stored directly + below the aforementioned directory. + </para> + <para> + The exact algorithm (in pseudocode) for looking up a sound in a + theme is: + + <programlisting> +FindSound(sound, locale, outputprofile, theme) { + filename = LookupSound (sound, locale, outputprofile, theme) + if filename != none + return filename + + if theme has parents + for parent in theme.parents { + filename = LookupSound (sound, locale, outputprofile, parent) + if filename != none + return filename + } + + return none +} + </programlisting> + + With the following helper functions: + + <programlisting> +LookupSound (requestedname, requestedlocale, requestedoutputprofile, requestedtheme) { + for theme in (requestedtheme, + "freedesktop", + "") { + for profile in (requestedoutputprofile, "stereo", "") { + for each subdir in $(theme subdir list) { + if DirectoryMatchesOutputProfile(subdir, profile) { + for each directory in $(basename list) { + for each name in (requestedname, + truncatesuffix(requestedname, "-"), + truncatesuffix(truncatesuffix(requestedname, "-"), "-"), + truncatesuffix(truncatesuffix(truncatesuffix(requestedname, "-"), "-"), "-"), + ...) { + for each locale in (requestedlocale, + truncatesuffix(requestedlocale, "@"), + truncatesuffix(requestedlocale, "_"), + "C", + "") { + for extension in ("disabled", "oga", "ogg", "wav") { + filename = directory/theme/subdir/locale/name.extension + if exist filename + return filename + } + } + } + } + } + } + } + } + + return none +} + +DirectoryMatchesOutputProfile(subdir, profile) { + read OutputProfile from subdir + if OutputProfile == profile + return true + return false +} +</programlisting> + + </para> + </sect1> + + <sect1 id="example"> + <title>Example</title> + <para> + Here is an example index.theme file: + <programlisting> +[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 5.1 + +[stereo] +OutputProfile=stereo + +[5.1] +OutputProfile=5.1 +</programlisting> + +The corresponding directory tree in the /usr/share/sounds +directory could look like this: + +<programlisting> +birch/index.theme +birch/stereo/evolution-urgent-message.oga +birch/stereo/evolution-urgent-message.wav +birch/stereo/fr/evolution-urgent-message.oga +birch/stereo/evolution-urgent-message.sound +birch/5.1/evolution-urgent-message.oga +</programlisting> + +Where birch/stereo/evolution-urgent-message.sound contains: + +<programlisting> +[Sound Data] +DisplayName=Evolution urgent message +DisplayName[fr]=Message urgent dans Evolution +</programlisting> + + </para> + <para> + In this example a lookup of "evolution-urgent-message", with a 5.1 + system preference and no localization, would get the + "birch/5.1/evolution-urgent-message.oga" sound file. + </para> + + </sect1> + + <sect1 id="install_sounds"> + <title>Installing Application Sounds</title> + <para> + If you're an application author and you want to install sounds + so that they can be used by your application, you should + at least install the sound file in the "freedesktop" theme. This means + installing a stereo WAV file in + $XDG_DATA_DIRS/sounds/freedesktop/stereo/. + </para> + <para> + Optionally you can install sounds in different formats and + languages. For example, installing a localized OGG/Vorbis 5.1 game + sound in $prefix/share/sounds/freedesktop/5.1/fr. + </para> + <para> + You might even want to install sounds that match other well + known themes so your application will fit in with some specific + desktop environment. + </para> + <para> + 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. + </para> + <para> + After installing/updating a sound in a theme directory, make sure + to update the mtime of the theme directory itself (i.e. touch + $XDG_DATA_DIRS/sounds/freedesktop or similar), so that caches can + be kept up-to-date. + </para> + </sect1> + + <sect1 id="implementation_notes"> + <title>Implementation Notes</title> + <para> + 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. + </para> + <para> + 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 theme 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 may + change the mtime of the the toplevel theme directory (such as + $XDG_DATA_DIRS/sounds/freedesktop) where it changed the theme to + make sure that the new sounds will eventually get used. + </para> + </sect1> + + <sect1 id="background"> + <title>Background</title> + <para> + The sound theme specification is heavily based on the "Icon Theme + Specification" by Alexander Larsson and Frans Englich. + </para> + </sect1> + + <appendix id="changes"> + <title>Change history</title> + <formalpara> + <title>Version 0.5, 2 September 2008, Marc-Andre Lureau</title> + <para> + <itemizedlist> + <listitem> + <para> + Deprecate usage of ".ogg" extension in favor of ".oga" + (according + to <ulink url="http://wiki.xiph.org/index.php/MIME_Types_and_File_Extensions"><citetitle>MIME + Types and File Extensions from xiph.org</citetitle></ulink>) + </para> + </listitem> + </itemizedlist> + </para> + </formalpara> + <formalpara> + <title>Version 0.4, 29 July 2008, Lennart Poettering</title> + <para> + <itemizedlist> + <listitem> + <para> + Document that every time a theme is updated to changed the directory needs to be touched. + </para> + </listitem> + </itemizedlist> + </para> + </formalpara> + <formalpara> + <title>Version 0.3, 25 July 2008, Lennart Poettering</title> + <para> + <itemizedlist> + <listitem> + <para> + Reordered lookup algorithm, to allow easy overwriting of sounds from inherited themes. + </para> + </listitem> + <listitem> + <para> + Document "__custom" theme. + </para> + </listitem> + <listitem> + <para> + Document ".disabled" sound files. + </para> + </listitem> + <listitem> + <para> + Other fixes + </para> + </listitem> + </itemizedlist> + </para> + </formalpara> + <formalpara> + <title>Version 0.2, 4 June 2008, Marc-Andre Lureau and Lennart Poettering</title> + <para> + <itemizedlist> + <listitem> + <para> + Updated the Lookup algorithm. + </para> + </listitem> + <listitem> + <para> + Remove Length and Locale from directory property. + </para> + </listitem> + <listitem> + <para> + Use OutputProfile instead of SoundSystem. + </para> + </listitem> + <listitem> + <para> + Add ReplayGain note. + </para> + </listitem> + </itemizedlist> + </para> + </formalpara> + <formalpara> + <title>Version 0.1, 11 February 2008, Marc-Andre Lureau</title> + <para> + <itemizedlist> + <listitem> + <para> + Initial draft. + </para> + </listitem> + </itemizedlist> + </para> + </formalpara> + </appendix> +</article> |