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

from gi.repository import GSound

ctx = GSound.Context()

try:
    ctx.init();
    ctx.play_simple({ 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
}

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. It is guaranteed that the callback will be run exactly once.

Note that calling gsound_context_play_full() with a NULL callback is not equivalent to calling gsound_context_play_simple(). When calling play_simple(), errors which occur before the sound is passed to the sound server are reported immediately, whereas with play_full() these are reported in the callback. If you pass a NULL callback to gsound_context_play_full() you will not be able to receive these errors, so it is strongly recommended to avoid doing this and use gsound_context_play_simple() in the case when you don't need to be notified when the sound 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.

For the list of attributes supported by GSound, see GSound Attributes.

Caching

If supported by the sound server, frequently-used sounds may be cached. This may be useful, for example, for sound effects in a game. To cache a sound, either call gsound_context_cache(), or pass the special GSOUND_ATTR_CANBERRA_CACHE_CONTROL attribute to one of the play() functions.

For example, in the startup code for a game you might include something like the following (error checking omitted):

1
2
3
4
5

GSoundContext *ctx = gsound_context_new (NULL, NULL);
gsound_context_cache(ctx, NULL,
                     GSOUND_ATTR_MEDIA_FILENAME,
                     "/path/to/player-spaceship-fire-laser.ogg",
                     NULL);

There are three caching modes available, "permanent", "volatile" and "never". The default mode when calling gsound_context_cache() is "permanent", and the default mode for gsound_context_play_simple() and play_full() is "never".

See the documentation for GSOUND_ATTR_CANBERRA_CACHE_CONTROL for more details.

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.

This function is intented to be used by language bindings.

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.

This function is intented to be used by language bindings.

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().

This function is intented to be used by language bindings.

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.

This function is intented to be used by language bindings.

enum GSoundError