Jump to content
From ArchWiki

Related articles

- GTK
- Desktop notifications

Libcanberra is a simple abstract interface for playing event sounds. It implements the XDG Sound Theme and Naming Specifications for generating event sounds on free desktops, such as GNOME. Further description here

## Installation

Libcanberra can be installed with the package libcanberra. libcanberra no longer requires any backends for ALSA, pulseaudio or gstreamer, as they are now built in to the libcanberra package.

It is necessary to install a sound theme in order to hear any event sound:

- The default sound theme is 'freedesktop', which can be installed with the package sound-theme-freedesktop.
- Alternatively, search for "sound-theme" in the official repositories or the Arch User Repository.

## Configuration

By default, the GTK module is loaded automatically when a GTK application launched. You can overwrite the default settings in the user's GtkSettings file:

    $HOME/.gtkrc-2.0 and $XDG_CONFIG_HOME/gtk-3.0/settings.ini

    gtk-enable-event-sounds=true
    gtk-enable-input-feedback-sounds=true
    gtk-sound-theme-name=freedesktop

In GNOME, these settings are managed by gnome-settings-daemon, and the configuration is available in GSettings under the `org.gnome.desktop.sound` schema.

## systemd

To enable bootup, shutdown and reboot sounds using canberra, enable `canberra-system-bootup.service`.

## Usage in programming

You can write your own libcanberra sound events easily in many programming languages using GSound through GObject-Introspection, or you can simply use bash.

### Bash

- Dependency: libcanberra

    hello_world.sh

    #!/bin/bash
    canberra-gtk-play -i phone-incoming-call -d "hello world"

### C

- Dependency: libcanberra
- Build with: `gcc -o hello_world `pkg-config --cflags --libs glib-2.0 libcanberra` hello_world.c`

    hello_world.c

    #include <glib.h>
    #include <canberra.h>
    int main () {
    	ca_context * hello;
    	ca_context_create (&hello);
    	ca_context_play (hello, 0,
    		CA_PROP_EVENT_ID, "phone-incoming-call",
    		CA_PROP_EVENT_DESCRIPTION, "hello world",
    		NULL);
    	g_usleep (2000000);
    	return 0;
    }

- Dependency: gsound
- Build with: `gcc -o hello_world `pkg-config --cflags --libs glib-2.0 gsound` hello_world.c`

    hello_world.c

    #include <glib.h>
    #include <gsound.h>
    int main () {
    	GSoundContext *hello = gsound_context_new(NULL, NULL);
    	gsound_context_play_simple(hello, NULL, NULL,
    		GSOUND_ATTR_EVENT_ID, "phone-incoming-call",
    		GSOUND_ATTR_EVENT_DESCRIPTION, "hello world",
    		NULL);
    	g_usleep (2000000);
    	return 0;
    }

### Genie

- Dependency: libcanberra
- Makedependency: vala
- Build with: `valac --pkg libcanberra hello_world.gs`

    hello_world.gs

    uses
    	Canberra
    init
    	hello: Context
    	Context.create(out hello)
    	hello.play (0,
    		PROP_EVENT_ID, "phone-incoming-call",
    		PROP_EVENT_DESCRIPTION, "hello world")
    	Thread.usleep (2000000)

- Dependency: gsound
- Makedependency: vala
- Build with: `valac --pkg gsound hello_world.gs`

    hello_world.gs

    uses
    	GSound
    init
    	var hello = new GSound.Context
    	hello.init()
    	hello.play_simple(null,
    		GSound.Attribute.EVENT_ID, "phone-incoming-call",
    		GSound.Attribute.EVENT_DESCRIPTION, "hello world")
    	Thread.usleep (2000000)

### JavaScript

- Dependencies: gsound, gjs

    hello_world.js

    #!/usr/bin/gjs
    const GLib = imports.gi.GLib;
    const GSound = imports.gi.GSound;

    let hello = new GSound.Context();
    hello.init(null);
    hello.play_simple({ "event.id" : "phone-incoming-call",
                        "event.description" : "hello world" }, null);
    GLib.usleep (2000000);

### Lua

- Dependencies: gsound, lua-lgi-gitAUR

    hello_world.lua

    #!/usr/bin/lua
    lgi = require 'lgi'
    GLib = lgi.require('GLib')
    GSound = lgi.require('GSound')

    hello = GSound.Context()
    hello:play_simple({ [GSound.ATTR_EVENT_ID] = "phone-incoming-call",
                        [GSound.ATTR_EVENT_DESCRIPTION] = "hello world" })
    GLib.usleep (2000000)

### Perl

- Dependencies: gsound, perl-glib-object-introspection

    hello_world.pl

    #!/usr/bin/perl
    use Glib::Object::Introspection;
    Glib::Object::Introspection->setup (
    	basename => 'GSound',
    	version => '1.0',
    	package => 'GSound');
    my $hello = GSound::Context->new;
    $hello->play_simple({ "event.id" => "phone-incoming-call",
                          "event.description" => "hello world" });
    sleep (2);

### Python

- Dependencies: gsound, python-gobject

    hello_world.py

    #!/usr/bin/python
    import gi
    gi.require_version('GSound', '1.0')
    from gi.repository import GLib, GSound

    hello = GSound.Context()
    hello.init()
    hello.play_simple({GSound.ATTR_EVENT_ID: "phone-incoming-call",
                       GSound.ATTR_EVENT_DESCRIPTION: "hello world"})
    GLib.usleep(2000000)

### Ruby

- Dependencies: gsound, ruby-gir_ffiAUR

    hello_world.rb

    #!/usr/bin/ruby
    require 'gir_ffi'
    GirFFI.setup :GSound
    Hello = GSound::Context.new
    Hello.play_simple("event.id" => "phone-incoming-call",
                      "event.description" => "hello world")
    sleep (2)

### Vala

- Dependency: libcanberra
- Makedependency: vala
- Build with: `valac --pkg libcanberra hello_world.vala`

    hello_world.vala

    using Canberra;
    public class HelloWorld {
    	static void main () {
    	Context hello;
    	Context.create(out hello);
    	hello.play (0,
    		PROP_EVENT_ID, "phone-incoming-call",
    		PROP_EVENT_DESCRIPTION, "hello world");
    	Thread.usleep (2000000);
    	}
    }

- Dependency: gsound
- Makedependency: vala
- Build with: `valac --pkg gsound hello_world.vala`

    hello_world.vala

    using GSound;
    public class HelloWorld {
    	static void main () {
    	var hello = new GSound.Context();
    	hello.init();
            hello.play_simple(null,
    		GSound.Attribute.EVENT_ID, "phone-incoming-call",
    		GSound.Attribute.EVENT_DESCRIPTION, "hello world");
    	Thread.usleep (2000000);
    	}
    }

## See also

- Libcanberra Reference Manual
- GSound Reference Manual[dead link 2021-11-13 ⓘ]

Category:

- Development

Hidden category:

- Pages with dead links