Hello + sound event architecture

[Patryk Zawadzki]

Dnia 12-11-2006, nie o godzinie 17:44 +0100, Kevin Krammer napisał(a):
> On Sunday 12 November 2006 17:13, Patryk Zawadzki wrote:
> > Dnia 12-11-2006, nie o godzinie 16:54 +0100, Kevin Krammer napisał(a):
> > > On Sunday 12 November 2006 00:52, Patryk Zawadzki wrote:

> > > I'd say sound themes and notifications are orthogonal things. Sound is
> > > just one presentation form of a notification.
> >
> > This could be further expanded to cover all areas of notification but as
> > the galago-project provides us with a working notification-daemon for
> > desktop popups, I'd like to start with a generic sound event daemon and
> > then we can talk about a higher-level specification that internally uses
> > both of these.
> Well, and knotify already supports popups, dialogs, sounds and ...

Yes but there are some sounds (like "user clicks a menu activator") that
should not generate a popup not a dialog. That's why I think a direct
access DBUS namespace is required even if the notification daemon can
handle the sound by itself in most cases basing on the notification
type.

> Of course, assuming that a sound handler would be available, knotify could 
> delegate sound playing to it, however I think it is more likely that it just 
> continue handling the sounds itself.
> Given a sound theme specification it could play the same sounds solutions 
> composed of galago and a separate sound playing daemon would use.

That's why I want to get a specification done.

> > > Depending on the actual notification architecture, users might have
> > > explicit configuration for certain sounds, not just generic names.
> > Could you give an example?
> For example instead of having one "online" sound for all users in your IM's 
> contact list, having specific sounds for certain users or groups of users.

The app could allow the user to override the default sound in its own
interface. What if I want a specific icon for one of my IM buddies? Do
you expect the icon theme specification to address that? :)

> > My proposition would allow for more customization that is possible now.
> More customization than deciding if a sound should be played and which 
> paricular one for each single notification?

That should be enough on the framework level. The rest is up to the
application.

> > User could replace certain soundby providing her own versions in
> > her .sounds directory.
> IMHO sounds should be selectable from any path, requiring to copy a file into 
> a certain location will make the usuability folks show up on your doorsteps, 
> torches lit, rope ready and all that ;)

See above :)

> > She can also opt to temporarily mute all sound 
> > below a certain importance threshold for example to get a better movie
> > watching experience. Same could be offered by the notification daemon to
> > suppress the popups temporarily (and possibly offer a log to review
> > later).
> So, depending on the actual implementation, it would require two daemons to 
> know about the current situation instead of just the notification daemon?
> Wouldn't it be better to allow the notification daemon to temorarily alter the 
> notification representation?

As I already said, I'd like both the visual notification daemon and the
soundnotification daemon get combined into a single app. But sometimes
you just want a sound with no visual cues (like for button clicking
sounds or when user decides that he does not want to see a popup when
one of his IM buddies comes online).

> > > So such a D-Bus service would then be used by the nofitication daemon(s)
> > > when the event configuration indicates a representation including a
> > > sound?
> > Yes, it should be. But for a good start, letting applications themselves
> > delegate sound playback would be a huge step ahead.
> Hmm, sound like this would require the notification representation handling 
> inside the client instead of inside the daemon since the application would 
> need to know if it should play a sound and which one, and then call either 
> both notification APIs or just the one for the visible part.

No, the notification daemon can delegate the sound event to the sound
daemon (or handle it internally if it is a sound daemon itself) and let
the latter decide if the sound should be played or not.

> Just calling a single notification API like now sound a lot easier to me.

If you want both the visual popup and the sound, you should call only
the notification daemon and let it take care of the sound event.

> > > Well, I can see a definite value in a sound theme specification, however
> > > I'd rather have the notifcation daemons or, in the event of a shared
> > > implementation the notification daemon, do the sounds playing directly
> > > instead of further delegating it.
> > You can combine both into a single daemon that just implements two DBUS
> > namespaces.
> True. But in which use case would a client program want to play a notification 
> sound without doing a notification?

See the first comment for a common usecase. Applications like Nautilus
or GNOME Panel never use notification popups as the sounds are attached
to things like "an application is launched" or "current path is
changed".

> Or how would you synchronize the visual and accustical part if they are 
> separate method calls? In the worst case even to different daemons?

If you need both, you let notification daemon handle both (or pass one
to an external sound daemon if needed).

> > > I'd recommend concentrating on the sound theme specification. Just like
> > > the icon theme spec it will already be useful without a shared
> > > loading/caching/displaying/playing implementation.
> > This should be an easy thing to do given that the icon specification
> > works. I propose just rewording the icon spec to talk about sounds and
> > sound themes and removing the unneeded bits like "icon size"
> > subdirectories.
> Sounds good to me.

See attachment for a draft.

-- 
Patryk Zawadzki <patrys at pld-linux.org>
PLD Linux
-------------- next part --------------
Sound Theme Specification

Patryk Zawadzki
	<patrys at pld-linux.org>


Based on the Icon Theme Specification

Alexander Larsson
	<alexl at redhat.com>

Frans Englich
	<frans.englich at telia.com>


Version 0.1


Table of Contents

Overview
Definitions
Directory Layout
File Formats
    Context
Icon Lookup
Example
Installing Application Icons
Implementation Notes
Background
A. Change history


Overview

A sound theme is a set of sounds that share a common feel. The user can then select the sound theme that they want to use, and all apps use sounds from the theme.

>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 icon filename.


Definitions

	Sound Theme

	An sound theme is a named set of sounds. It is used to map from an soundname to a file. Themes may inherit from other themes as a way to extend them.

	Sound file

    A sound file is file that can be loaded and played. The supported sound file formats are WAV and OGG Vorbis. OGG is the recommended format due to its open license. WAV is supported due to backwards compability reasons, and it is not recommended that new themes use WAV files.

	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.


Directory Layout

Sounds and themes are looked for in a set of directories. By default, apps should look in $HOME/.sounds, in $XDG_DATA_DIRS/sounds and in /usr/share/sounds (in that order). 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 "waltz". The data for the waltz theme is available for download at: http://www.freedesktop.org/software/sound-theme/. Implementations are required to look in the "waltz" 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 sound files. Subdirectories are allowed and can be several levels deep, e.g. the subdirectory "apps" in the theme "waltz" would end up at $basedir/waltz/apps.

The sound files must be one of the types: OGG Vorbis or WAV, and the extension must be ".wav", or ".ogg" (lower case). 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 "login.ogg" the corresponding file would be named "login.sound".


File Formats

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.

Table 1. Standard Keys
Key			Description																	Value Type		Required
Name		short name of the icon 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.						strings			NO
			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
			"waltz" theme to the inheritance tree. An implementation may
			optionally add other default themes in between the last specified
			theme and the hicolor theme.
Directories	list of subdirectories for this theme. For every subdirectory there		 	strings			YES
			must be a section in the index.theme file describing that directory.
Hidden		Whether to hide the theme in a theme selection user interface. This		 	boolean			NO
			is used for things such as fallback-themes that are not supposed to
			be visible to the user.
Example		The name of a sound that should be used as an example of how this		 	string			NO
			theme sounds.

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 2. Per-Directory Keys
Key			Description															Value Type		Required
Context		The context the icon is normally used in. This is in detail			string			NO
			discussed in the section called “Context”.

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.

Table 3. Sound Data Keys
Key			Description															Value Type		Required
DisplayName	A translated UTF8 string that can be used instead of the sound		localestring	NO
			name when the sound is listen in e.g. a user interface.

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.

	Context

	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:

	* Actions. Sounds representing actions which the user initiates, such as Empty Trash.


Sound Lookup

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 a 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 "waltz" (implementations may add more default themes before "waltz", but "waltz" 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 two phases. First all the directories are scanned for any sound that matches the name. If that fails we fall back on unthemed sounds. 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 an sound in a theme is:

FindSound(sound) {
  filename = FindSoundHelper(icon, user selected theme);
  if filename != none
    return filename
  return LookupFallbackSound (sound)
}
FindSoundHelper(icon, theme) {
  filename = LookupSound (sound, theme)
  if filename != none
    return filename

  if theme has parents
    parents = theme.parents
  else if theme != waltz
    parents = [waltz]

  for parent in parents {
    filename = FindSoundHelper (sound, parent)
    if filename != none
      return filename
  }
  return none
}


With the following helper functions:

LookupSound (soundname, theme) {
  minimal_size = MAXINT
  for each subdir in $(theme subdir list) {
    for each directory in $(basename list) {
      for extension in ("ogg", "wav") {
        filename = directory/$(themename)/subdir/soundname.extension
        if exist filename
          return filename
      }
    }
  }
  return none
}

LookupFallbackSound (iconname) {
  for each directory in $(basename list) {
    for extension in ("ogg", "wav") {
      if exists directory/soundname.extension
        return directory/soundname.extension
    }
  }
  return none
}

In some cases you don't always want to fall back to a sound in an inherited theme. For instance, sometimes you look for a set of sounds, prefering any of them before using a sound from an inherited theme. To support such operations implementations can contain a function that finds the first of a list of sound names in the inheritance hierarchy. I.E. It would look something like this:

FindBestSound(soundList) {
  filename = FindBestSoundHelper(soundList, user selected theme);
  if filename != none
    return filename
  for sound in soundList {
    filename = LookupFallbackSound (icon)
    if filename != none
      return filename
  }
  return none;
}
FindBestSoundHelper(soundList, theme) {
  for sound in soundList {
    filename = LookupSound (sound, theme)
    if filename != none
      return filename
  }

  if theme has parents
    parents = theme.parents
  else if theme != waltz
    parents = [waltz]

  for parent in parents {
    filename = FindBestSoundHelper (soundList, parent)
    if filename != none
      return filename
  }
  return none
}


Installing Application Sounds

So, you're an application author, and want to install application sounds so that they work in the KDE and Gnome. Minimally you should install a sound in the waltz theme. This means installing an OGG file in $prefix/share/sounds/waltz/apps. Optionally you might want to install sounds with a feel 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 waltz theme sound neutral, since it is a fallback theme that will be used in combination with some very different sounding themes. But if you don't have any neutral sound, please install whatever sound you have in the waltz theme so that all applications get at least some sound in all themes.


Implementation Notes

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.


Background

The sound theme specification is based on the Icon Theme Specufication 0.11 by Alexander Larsson and Frans Englich.


A. Change history

Version 0.1, 12 November 2006, Patryk Zawadzki.

* Created initial draft.