| 1 |
GSound |
| 2 |
====== |
| 3 |
|
| 4 |
What is it? |
| 5 |
----------- |
| 6 |
|
| 7 |
GSound is a small library for playing system sounds. It's designed to be |
| 8 |
used via GObject Introspection, and is a thin wrapper around the [libcanberra](http://0pointer.de/lennart/projects/libcanberra/) C library. |
| 9 |
|
| 10 |
Homepage: https://wiki.gnome.org/Projects/GSound |
| 11 |
|
| 12 |
Documentation: https://developer.gnome.org/gsound/stable |
| 13 |
|
| 14 |
Source: https://git.gnome.org/browse/gsound |
| 15 |
|
| 16 |
Bugs: https://bugzilla.gnome.org/enter_bug.cgi?product=gsound |
| 17 |
|
| 18 |
##Usage via GObject Introspection. |
| 19 |
|
| 20 |
As GSound is based on libcanberra it shares a similar API. To use it, |
| 21 |
you first create and initialise a GSound context. You then pass the |
| 22 |
context a list of (attribute, value) pairs instructing it what to play, |
| 23 |
like so in Python: |
| 24 |
|
| 25 |
```Python |
| 26 |
from gi.repository import GSound |
| 27 |
|
| 28 |
try: |
| 29 |
ctx = GSound.Context() |
| 30 |
ctx.init() |
| 31 |
ctx.play_simple({ GSound.ATTR_EVENT_ID : "phone-incoming-call" }) |
| 32 |
except: |
| 33 |
# Handle errors |
| 34 |
pass |
| 35 |
``` |
| 36 |
|
| 37 |
or the equivalent in JavaScript (using GJS) |
| 38 |
|
| 39 |
```JavaScript |
| 40 |
const GSound = imports.gi.GSound; |
| 41 |
|
| 42 |
let ctx = new GSound.Context(); |
| 43 |
|
| 44 |
try { |
| 45 |
ctx.init(); |
| 46 |
// For some reason I can't seem to use the attribute defines in GJS |
| 47 |
ctx.play_simple({ "event.id" : "phone-incoming-call" }, null); |
| 48 |
} catch (e) { |
| 49 |
// handle error |
| 50 |
} |
| 51 |
``` |
| 52 |
|
| 53 |
The list of supported attributes can be found in |
| 54 |
[gsound-attr.h](https://developer.gnome.org/gsound/stable/gsound-GSound-Attributes.html), |
| 55 |
and can be used via the `GSound.ATTR_*` string constants if the target |
| 56 |
language supports this. |
| 57 |
|
| 58 |
Playing Sounds |
| 59 |
-------------- |
| 60 |
|
| 61 |
There are two very similar play commands, `GSound.Context.play_simple()` |
| 62 |
and the corresponding `play_full()`. |
| 63 |
|
| 64 |
The "full" version is an asynchronous function following the GIO model. |
| 65 |
It takes a callback argument which will be called when the sound has |
| 66 |
finished playing. As with other GIO async functions, you should call |
| 67 |
`GSound.Context.play_finish()` within the callback in order to receive |
| 68 |
any exceptions which might have occurred during playback; note that |
| 69 |
cancelling playback will result in a `Gio.IOError.CANCELLED` exception |
| 70 |
(or something similar). |
| 71 |
|
| 72 |
On the other hand, `play_simple()` does not give you any feedback when |
| 73 |
the sound finishes. However, it will still report any errors which |
| 74 |
occurred before the sound was submitted to the server (with |
| 75 |
`play_full()`, these are reported in the callback). |
| 76 |
|
| 77 |
It's important to note that both versions are non-blocking and will |
| 78 |
return control to your application immediately, without waiting for the |
| 79 |
sound to finish playing (or even start, really). |
| 80 |
|
| 81 |
Usage in Vala |
| 82 |
------------- |
| 83 |
|
| 84 |
GSound can be used in Vala via the included VAPI file. The API is |
| 85 |
slightly different from other introspected languages. Since Vala supports |
| 86 |
varargs, these are used to pass attribute-value pairs rather than |
| 87 |
`GHashTable`s. One neat feature as that since `play_full()` is a proper |
| 88 |
async function, it can be used with `yield` like so: |
| 89 |
|
| 90 |
```Vala |
| 91 |
public async void play(string filename, |
| 92 |
GLib.Cancellable? cancellable) throws GLib.Error |
| 93 |
{ |
| 94 |
var ctx = new GSound.Context(); |
| 95 |
ctx.init(); |
| 96 |
yield ctx.play_full(cancellable, |
| 97 |
GSound.Attributes.MEDIA_FILENAME, filename); |
| 98 |
} |
| 99 |
``` |
| 100 |
|
| 101 |
(Note that libcanberra comes with it's own VAPI file, which you could use |
| 102 |
instead.) |
| 103 |
|
| 104 |
Usage in C |
| 105 |
----------- |
| 106 |
|
| 107 |
As a C library, GSound can of course be used from C and C++. If your project |
| 108 |
is already using GObject libraries then you'll find the style fits right in. |
| 109 |
Like Vala, the C API uses varargs to pass attributes to the backend, for |
| 110 |
example (error checking omitted for brevity): |
| 111 |
|
| 112 |
```C |
| 113 |
GSoundContext *ctx = gsound_context_new(NULL, NULL); |
| 114 |
|
| 115 |
gsound_context_play_simple(ctx, NULL, NULL; |
| 116 |
GSOUND_ATTR_EVENT_ID, "phone-incoming-call", |
| 117 |
NULL); |
| 118 |
``` |
| 119 |
|
| 120 |
License |
| 121 |
------- |
| 122 |
|
| 123 |
> This program is free software; you can redistribute it and/or modify it |
| 124 |
> under the terms of the GNU Lesser General Public License as published |
| 125 |
> by the Free Software Foundation, either version 2.1 of the License, or |
| 126 |
> (at your option) any later version. |
| 127 |
|
| 128 |
> This program is distributed in the hope that it will be useful, but |
| 129 |
> WITHOUT ANY WARRANTY; without even the implied warranty of |
| 130 |
> MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser |
| 131 |
> General Public License for more details. |
| 132 |
|
| 133 |
Prerequisites |
| 134 |
------------- |
| 135 |
|
| 136 |
Building GSound from git requires a fairly modern Gnome development |
| 137 |
environment; so far it's only been tested on Fedora 20. At a minimum, |
| 138 |
you'll need headers for GObject (at least 2.36.0) and libcanberra, as well |
| 139 |
as the needed machinery to generate GObject introspection data and the Vala |
| 140 |
VAPI. |
| 141 |
|
| 142 |
Differences from libcanberra |
| 143 |
---------------------------- |
| 144 |
|
| 145 |
GSound wraps the libcanberra API very closely, with the following |
| 146 |
differences: |
| 147 |
|
| 148 |
1) Attribute/value pairs are passed using `GHashTable`s instead of |
| 149 |
`ca_proplists`. This is because most GI consumers have automatic conversion |
| 150 |
from native associative array types (e.g. Python's `dict`) to `GHashTable`. |
| 151 |
The Vala and C APIs instead use varargs, as libcanberra does in those |
| 152 |
languages. |
| 153 |
|
| 154 |
2) Errors are reported using `GError`s rather than using integer return values. |
| 155 |
Most GI consumers map `GError`s to native exceptions, and they work mostly like |
| 156 |
exceptions in Vala too. |
| 157 |
|
| 158 |
3) Callbacks use the standard GIO async pattern (i.e. call a `finish()` function |
| 159 |
on a `GAsyncResult` that's handed to a callback you supply). |
| 160 |
|
| 161 |
4) `GCancellable`s are used for cancelling sounds in progress, again for |
| 162 |
consistency with GIO. |
| 163 |
|
| 164 |
5) What libcanberra calls "properties" are called "attributes" in GSound to |
| 165 |
avoid confusing them with GObject properties. The actual strings (e.g. |
| 166 |
"media.filename") are the same, however. |