GSound

What is it?

GSound is a small library for playing system sounds. It's designed to be used via GObject Introspection, and is a thin wrapper around the libcanberra C library.

The reference documentation can be found at https://developer.gnome.org/gsound/stable

Usage via GObject Introspection

As GSound is based on libcanberra it shares a similar API. To use it, you first create and initialise a GSound context. You then pass the context a list of (attribute, value) pairs instructing it what to play, like so in Python:

   1 from gi.repository import GSound
   2 
   3 try:
   4     ctx = GSound.Context()
   5     ctx.init()
   6     ctx.play_simple({ GSound.ATTR_EVENT_ID : "phone-incoming-call" })
   7 except:
   8     # Handle errors
   9     pass

or the equivalent in JavaScript (using GJS)

const GSound = imports.gi.GSound;

let ctx = new GSound.Context();

try {
    ctx.init();
    // For some reason I can't seem to use the attribute defines in GJS
    ctx.play_simple({ "event.id" : "phone-incoming-call" }, null);
} catch (e) {
    // handle error
}

The list of supported attributes can be found in gsound-attr.h, and can be used via GSound.ATTR_* string constants if the target language supports this.

Playing Sounds

There are two very similar play commands, GSound.Context.play_simple() and the corresponding play_full().

The "full" version is an asynchronous function following the GIO model. It takes a callback argument which will be called when the sound has finished playing. As with other GIO async functions, you should call GSound.Context.play_finish() within the callback in order to receive any exceptions which might have occurred during playback; note that cancelling playback will result in a Gio.IOError.CANCELLED exception (or something similar).

On the other hand, play_simple() does not give you any feedback when the sound finishes. However, it will still report any errors which occurred before the sound was submitted to the server (with play_full(), these are reported in the callback).

It's important to note that both versions are non-blocking and will return control to your application immediately, without waiting for the sound to finish playing (or even start, really).

GSound can be used in Vala via the included VAPI file. The API is slightly different from other introspected languages. Since Vala supports varargs, these are used to pass attribute-value pairs rather than GHashTables. One neat feature as that since play_full() is a proper async function, it can be used with yield like so:

public async void play(string filename,
                       GLib.Cancellable? cancellable) throws GLib.Error
{
        var ctx = new GSound.Context();
        ctx.init();
        yield ctx.play_full(cancellable,
                            GSound.Attributes.MEDIA_FILENAME, filename);
}

(Note that libcanberra comes with it's own VAPI file, which you could use instead.)

Usage in C

As a C library, GSound can of course be used from C and C++. If your project is already using GObject libraries then you'll find the style fits right in. Like Vala, the C API uses varargs to pass attributes to the backend, for example (error checking omitted for brevity):

   1 GSoundContext *ctx = gsound_context_new(NULL, NULL);
   2 
   3 gsound_context_play_simple(ctx, NULL, NULL,
   4                            GSOUND_ATTR_EVENT_ID, "phone-incoming-call",
   5                            NULL);

Differences from libcanberra

GSound wraps the libcanberra API very closely, with the following differences:

Attribute/value pairs are passed using GHashTables instead of ca_proplists. This is because most GI consumers have automatic conversion from native associative array types (e.g. Python's dict) to GHashTable. The Vala and C APIs instead use varargs, as libcanberra does in those languages.
Errors are reported using GErrors rather than using integer return values. Most GI consumers map GErrors to native exceptions, and they work mostly like exceptions in Vala too.
Callbacks use the standard GIO async pattern (i.e. call a finish() function on a GAsyncResult that's handed to a callback you supply).
GCancellables are used for cancelling sounds in progress, again for consistency with GIO.
What libcanberra calls "properties" are called "attributes" in GSound to avoid confusing them with GObject properties. The actual strings (e.g. "media.filename") are the same, however.