path: root/spec/sound-theme-spec.xml

<?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>