1GSound
2======
3
4What is it?
5-----------
6
7GSound is a small library for playing system sounds. It's designed to be
8used via GObject Introspection, and is a thin wrapper around the [libcanberra](http://0pointer.de/lennart/projects/libcanberra/) C library.
9
10Homepage: https://wiki.gnome.org/Projects/GSound
11
12Documentation: https://developer.gnome.org/gsound/stable
13
14Source: https://git.gnome.org/browse/gsound
15
16Bugs: https://bugzilla.gnome.org/enter_bug.cgi?product=gsound
17
18##Usage via GObject Introspection.
19
20As GSound is based on libcanberra it shares a similar API. To use it,
21you first create and initialise a GSound context. You then pass the
22context a list of (attribute, value) pairs instructing it what to play,
23like so in Python:
24
25```Python
26from gi.repository import GSound
27
28try:
29    ctx = GSound.Context()
30    ctx.init()
31    ctx.play_simple({ GSound.ATTR_EVENT_ID : "phone-incoming-call" })
32except:
33    # Handle errors
34    pass
35```
36
37or the equivalent in JavaScript (using GJS)
38
39```JavaScript
40const GSound = imports.gi.GSound;
41
42let ctx = new GSound.Context();
43
44try {
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
53The list of supported attributes can be found in
54[gsound-attr.h](https://developer.gnome.org/gsound/stable/gsound-GSound-Attributes.html),
55and can be used via the `GSound.ATTR_*` string constants if the target
56language supports this.
57
58Playing Sounds
59--------------
60
61There are two very similar play commands, `GSound.Context.play_simple()`
62and the corresponding `play_full()`.
63
64The "full" version is an asynchronous function following the GIO model.
65It takes a callback argument which will be called when the sound has
66finished playing. As with other GIO async functions, you should call
67`GSound.Context.play_finish()` within the callback in order to receive
68any exceptions which might have occurred during playback; note that
69cancelling playback will result in a `Gio.IOError.CANCELLED` exception
70(or something similar).
71
72On the other hand, `play_simple()` does not give you any feedback when
73the sound finishes. However, it will still report any errors which
74occurred before the sound was submitted to the server (with
75`play_full()`, these are reported in the callback).
76
77It's important to note that both versions are non-blocking and will
78return control to your application immediately, without waiting for the
79sound to finish playing (or even start, really).
80
81Usage in Vala
82-------------
83
84GSound can be used in Vala via the included VAPI file. The API is
85slightly different from other introspected languages. Since Vala supports
86varargs, these are used to pass attribute-value pairs rather than
87`GHashTable`s. One neat feature as that since `play_full()` is a proper
88async function, it can be used with `yield` like so:
89
90```Vala
91public 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
102instead.)
103
104Usage in C
105-----------
106
107As a C library, GSound can of course be used from C and C++. If your project
108is already using  GObject libraries then you'll find the style fits right in.
109Like Vala, the C API uses varargs to pass attributes to the backend, for
110example (error checking omitted for brevity):
111
112```C
113GSoundContext *ctx = gsound_context_new(NULL, NULL);
114
115gsound_context_play_simple(ctx, NULL, NULL;
116                           GSOUND_ATTR_EVENT_ID, "phone-incoming-call",
117                           NULL);
118```
119
120License
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
133Prerequisites
134-------------
135
136Building GSound from git requires a fairly modern Gnome development
137environment; so far it's only been tested on Fedora 20. At a minimum,
138you'll need headers for GObject (at least 2.36.0) and libcanberra, as well
139as the needed machinery to generate GObject introspection data and the Vala
140VAPI.
141
142Differences from libcanberra
143----------------------------
144
145GSound wraps the libcanberra API very closely, with the following
146differences:
147
1481) 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
1542) 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
1583) 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
1614) `GCancellable`s are used for cancelling sounds in progress, again for
162   consistency with GIO.
163
1645) 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.
167