1. Introduction 1.1. Project/Component Working Name: libcanberra 1.2. Name of Document Author/Supplier: Author: Jerry Tan Sponsor: 1.3. Date of This Document: 18/08/2008 1.4. Name of Major Document Customer(s)/Consumer(s): 1.4.1. The PAC or CPT you expect to review your project: Solaris PAC 1.4.2. The ARC(s) you expect to review your project: LSARC 1.4.3. The Director/VP who is "Sponsoring" this project: Robert O'Dea 1.4.4. The name of your business unit: Software - OPG 1.5. Email Aliases: 1.5.1. Responsible Manager: leo.binchy@sun.com 1.5.2. Responsible Engineer: jerry.tan@sun.com 1.5.3. Interest List: jds-dev@sun.com 2. Project Summary 2.1. Project Description: libcanberra is a desktop event sound library. 3. Business Summary Sound effects are an important part of the usability of modern desktops. In the past, GNOME events have been managed by ESD, and managed by libgnome. The GNOME community has long been interested in deprecating the usage of both ESD and libgnome, so this library is intended to be the replacement. The previous solution had a number of problems: a minimal set of defined sound events, no support for theming, and poor integration into applications. libcanberra has been introduced to resolve these problems. 4. Technical Description: 4.1. Details: Similar to the XDG Icon Naming Specification and the XDG Icon Theme Specification, the FreeDesktop.org community has been working to unify event sounds on desktop, so they have created the XDG Sound Theme Specification and the XDG Sound Name Specification. The intent is that these two new specifications will be established as the future standard for sound event theming for free desktops. The libcanberra library is a very small and lean implementation of these specifications. It is also very powerful and provides a more rich set of interfaces. Along with libcanberra, this case will also integrate the xdg-sound-theme module. The xdg-sound-theme module only contains audio media files which are installed to the /usr/share/sounds/freedesktop directory. These are the default sound event sounds. An event sound is triggered via libcanberra by calling the ca_context_play() function on a previously created ca_context object. The ca_context_play() takes a list of key-value pairs that describe the event sound to generate as closely as possible. The most important property is CA_PROP_EVENT_ID which defines the XDG sound name for the sound to play. Here is a code sample: ca_context *c = NULL; /* Create a context for the event sounds for your application */ ca_context_create(&c); /* Set a few application-global properties */ ca_context_change_props(c, CA_PROP_APPLICATION_NAME, "An example", CA_PROP_APPLICATION_ID, "org.freedesktop.libcanberra.Test", CA_PROP_APPLICATION_ICON_NAME, "libcanberra-test", NULL); /* ... */ /* Trigger an event sound */ ca_context_play(c, 0, CA_PROP_EVENT_ID, "button-pressed", /* The XDG sound name */ CA_PROP_MEDIA_NAME, "The user pressed the button foobar", CA_PROP_EVENT_MOUSE_X, "555", CA_PROP_EVENT_MOUSE_Y, "666", CA_PROP_WINDOW_NAME, "Foobar Dialog", CA_PROP_WINDOW_ICON_NAME, "libcanberra-test-foobar-dialog", CA_PROP_WINDOW_X11_DISPLAY, ":0", CA_PROP_WINDOW_X11_XID, "4711", NULL); /* ... */ ca_context_destroy(&c); The canberra-gtk-play program is intended to be used by programs which want to play sound events. For example, the autostart desktop file /usr/share/gnome/autostart/libcanberra-login-sound.desktop uses canberra-gtk-play to play the login sound. To simplify libcanberra usage from a GTK+ program, GTK+ bindings are provided by the libcanberra-gtk library. The libcanberra GTK+ module library is used so that sounds associated with GTK+ widget events are played. In other words, by making sure that all GTK+ based programs load this module, they will automatically support sound event theming according to the FreeDesktop specifications. libcanberra supports ogg-vorbis for default system sounds since ogg-vorbis is a good free, compressed standard for desktop audio. 4.2. Interfaces: Exported Interfaces Interface Classification Comments --------------- -------------- --------------------- SUNWlibcanberra Uncommitted the package SUNWlibcanberra-devel Uncommitted the dev package /usr/bin/canberra-gtk-play Volatile tool to play event sounds /usr/lib/libcanberra-gtk.so.0.0.0 Volatile libcanberra library /usr/lib/libcanberra.so.0.0.0 Volatile libcanberra-gtk library /usr/lib/gtk-2.0/modules/ Volatile libcanberra GTK+ libcanberra-gtk-module.so module /usr/lib/libcanberra/ Volatile Plugin directory /usr/lib/pkgconfig/libcanberra-gtk.pc Volatile libcanberra /usr/lib/pkgconfig/libcanberra.pc Volatile pkg-config files /usr/include/canberra-gtk.h Volatile libcanberra-gtk header file /usr/include/canberra.h Volatile libcanberra header file /usr/share/gnome/autostart Volatile login sound /libcanberra-login-sound.desktop /usr/share/gnome/shutdown Volatile logout sound /libcanberra-logout-sound.sh /usr/share/sounds Uncommitted XDG Sound Theme installation directory. /usr/share/sounds/freedesktop Volatile Default sound theme. Imported Interfaces Interface Classification Comments --------- -------------- -------- OGG/Vorbis Volatile LSARC/2008/510 GTK+ Committed LSARC/2008/510 SATA (Sun Audio) Committed PSARC/2001/226 4.3. Doc Impact: Man page is needed. 4.4. Packaging & Delivery: SUNWlibcanberra - the package for libcanberra SUNWlibcanberra-devel - the dev package for libcanberra 4.5. Dependencies: 4.6. L10N Impact: The Desktop team is working with the G11N to evaluate and provide I18N/L10N support 4.7 Security Impact: None. 5. Reference Documents: http://0pointer.de/blog/projects/sixfold-announcement.html http://0pointer.de/public/sound-theme-spec.html http://0pointer.de/public/sound-naming-spec.html