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