# Libcanberra

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, available in the Official repositories. It contains the library and a GTK+ module.

You have to choose a backend to play sounds:

- ALSA backend is included in libcanberra package
- GStreamer backend can be installed with package libcanberra-gstreamer, available in the Official repositories.
- PulseAudio backend can be installed with package libcanberra-pulse, available in the Official repositories.

Also, you have 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, available in the Official repositories.
- Alternatively, you can install ubuntu-soundsAUR, available in the Arch User Repository.

## Configuration

By default, the GTK+ module is loaded automatically, when a GTK+ application launched. You can overwrite default settings in 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 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

    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-introspectionAUR

    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

Category:

- Development