Debian Codegraph @

README

raw
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.