Simple Examples

In C:

1
2
3
4
5
6
7
8
9
10
11
12
13

GSoundContext *ctx = NULL;
GCancellable *cancellable = g_cancellable_new();
GError *error = NULL;

ctx = gsound_context_new(cancellable, &error);
if (error) {
    // handle error
}

gsound_context_play_simple(ctx, cancellable, &error,
                           GSOUND_ATTR_EVENT_ID, "phone-incoming-call",
                           // other attributes...
                           NULL);

or, using Python via GObject Introspection:

1
2
3
4
5
6
7
8
9
10
11
12

from gi.repository import GSound, Gio

ctx = GSound.Context()
cancellable = Gio.Cancellable()

try:
    ctx.init(cancellable);
    ctx.play_simple(cancellable,
                   { GSound.ATTR_EVENT_ID : "phone-incoming-call" })
except:
    # Handle error
    pass

or using Vala:

1
2
3
4
5
6

try {
    var ctx = new GSound.Context();
    ctx.play_simple(null, GSound.Attribute.EVENT_ID, "phone-incoming-call");
} catch (Error e) {
    // handle error
}

Events

play_simple() versus play_full()

The above examples use the gsound_context_play_simple() method for playing sounds. This is a "fire and forget" method which returns immediately and does not block your program, and is suitable for most use cases.

If you need to find out when the sound finished (for example to repeat the sound) then you can use the gsound_context_play_full() version. This is an asynchronous method using the standard GIO async pattern, which will run the supplied GAsyncReadyCallback when the sound server has finished.

Passing Attributes

GSound supplies information to the sound server by means of attributes. Attributes can be set on the GSoundContext itself using gsound_context_set_attributes(), or supplied in a play() call. Attributes set on the context will automatically applied to any subsequent play() calls, unless overridden by that call.

In C and Vala, attributes are passed as NULL-terminated list of (attribute, value) pairs. When using GObject introspection, attributes are typically passed using a language-specific associated array, for example a dict in Python or an object in JavaScript.

GSOUND_ERROR

#define GSOUND_ERROR (gsound_error_quark())

gsound_error_quark ()

GQuark
gsound_error_quark (void);

gsound_context_new ()

GSoundContext *
gsound_context_new (GCancellable *cancellable,
                    GError **error);

Creates and initializes a new GSoundContext. If the an error occured during initialization, NULL is returned and error will be set appropriately.

gsound_context_open ()

gboolean
gsound_context_open (GSoundContext *context,
                     GError **error);

Attempts to open a connection to the backend sound driver. It is recommended that you set context attributes with gsound_context_set_attributes() before calling this function.

gsound_context_set_attributes ()

gboolean
gsound_context_set_attributes (GSoundContext *context,
                               GError **error,
                               ...);

Set attributes or change attributes on context . Subsequent calls to this function calling the same attributes will override the earlier values.

Note that GSound will set the GSOUND_ATTR_APPLICATION_NAME and GSOUND_ATTR_APPLICATION_ID for you if using GApplication, so you do not normally need to set these yourself.

gsound_context_set_attributesv ()

gboolean
gsound_context_set_attributesv (GSoundContext *context,
                                GHashTable *attrs,
                                GError **error);

Set attributes or change attributes on context . Subsequent calls to this function calling the same attributes will override the earlier values.

Note that GSound will set the GSOUND_ATTR_APPLICATION_NAME and GSOUND_ATTR_APPLICATION_ID for you if using GApplication, so you do not normally need to set these yourself.

gsound_context_set_driver ()

gboolean
gsound_context_set_driver (GSoundContext *context,
                           const char *driver,
                           GError **error);

Sets the libcanberra driver to driver , for example "pulse", "alsa" or "null". You normally do not need to set this yourself.

Note that this function may return TRUE even if the specified driver is not available: see the libcanberra documentation for details.

gsound_context_play_simple ()

gboolean
gsound_context_play_simple (GSoundContext *context,
                            GCancellable *cancellable,
                            GError **error,
                            ...);

The basic "fire-and-forget" play command. This function will not block, and just sends a request to the sound server before immediately returning.

If you need to know when a sound finishes playing then you should call gsound_context_play_full() instead.

You can cancel playback at any time by calling g_cancellable_cancel() on cancellable , if supplied.

gsound_context_play_simplev ()

gboolean
gsound_context_play_simplev (GSoundContext *context,
                             GHashTable *attrs,
                             GCancellable *cancellable,
                             GError **error);

The basic "fire-and-forget" play command. This function will not block, and just sends a request to the sound server before immediately returning.

If you need to know when a sound finishes playing then you should call gsound_context_play_full() instead.

You can cancel playback at any time by calling g_cancellable_cancel() on cancellable , if supplied.

gsound_context_play_full ()

void
gsound_context_play_full (GSoundContext *context,
                          GCancellable *cancellable,
                          GAsyncReadyCallback callback,
                          gpointer user_data,
                          ...);

Asynchronously request a sound to be played. When playback is finished (or if an error occurs) then callback will be called, following the normal GIO async pattern.

If playback is cancelled via cancellable , then callback will be called with G_IO_ERROR_CANCELLED.

If you do not need notification of when playback is complete, you should use gsound_context_play_simple().

gsound_context_play_fullv ()

void
gsound_context_play_fullv (GSoundContext *context,
                           GHashTable *attrs,
                           GCancellable *cancellable,
                           GAsyncReadyCallback callback,
                           gpointer user_data);

Asynchronously request a sound to be played. When playback is finished (or if an error occurs) then callback will be called, following the normal GIO async pattern.

If playback is cancelled via cancellable , then callback will be called with G_IO_ERROR_CANCELLED.

If you do not need notification of when playback is complete, you should use gsound_context_play_simple().

gsound_context_play_full_finish ()

gboolean
gsound_context_play_full_finish (GSoundContext *context,
                                 GAsyncResult *result,
                                 GError **error);

Finish an async operation started by gsound_context_play_full(). You must call this function in the callback to free memory and receive any errors which occurred.

gsound_context_cache ()

gboolean
gsound_context_cache (GSoundContext *context,
                      GError **error,
                      ...);

Requests that a sound be cached on the server. See caching.

gsound_context_cachev ()

gboolean
gsound_context_cachev (GSoundContext *context,
                       GHashTable *attrs,
                       GError **error);

Requests that a sound be cached on the server. See caching.

enum GSoundError