libkanberra 1.0

   Copyright 2022-2025 Pablo Barciela <scow (at) riseup (dot) net>
   Copyright 2008-2012 Lennart Poettering <mzyvopnaoreen (at) 0pointer (dot) de>

License

   This program is free software; you can redistribute it and/or modify it
   under the terms of the GNU Lesser General Public License as published
   by the Free Software Foundation, either version 2.1 of the License, or
   (at your option) any later version.

   This program is distributed in the hope that it will be useful, but
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser
   General Public License for more details.

Overview

   libkanberra is an implementation of the XDG Sound Theme and Name
   Specifications, for generating event sounds on free desktops, such as
   CAFE. It comes with several backends (ALSA, PulseAudio,
   OSS, GStreamer) and is designed to be portable. It consists
   of the following parts:
    1. libkanberra: the main library
    2. libkanberra-ctk: some glue code to make it easier to use
       libkanberra from Ctk+ applications
    3. libkanberra-ctk-module: a Ctk+ module that uses libkanberra-ctk to
       trigger input feedback event sounds

Current Status

   libkanberra is mostly feature complete. For now however it includes
   backends only for ALSA, PulseAudio, OSS and GStreamer.

   libkanberra has been declared a blessed CAFE dependency.

   The OSS driver is incomplete: only sound files that are in a format
   natively understood by the sound card are supported. If the sample
   type, channel map or sampling rate of the sound file are not supported
   by the sound card no automatic conversion will take place and the file
   will not be played. Also note that the OSS backend is most likely
   incompatible with OSS4, due to subtle incompatibilities between OSS4
   and the OSS 3.x.

   It is recommended to always take the "shortest" path from libkanberra
   to the audio device. I.e. don't use the GStreamer plugin if libkanberra
   supports the final output target natively. Besides being more
   resource-friendly and less error-prone, some advanced functionality
   might get lost with each layer you add to your stack. For example:
   while you could use libkanberra's Gstreamer backend to output to a
   PulseAudio server this will not be able to make use of sample cacheing
   or will be able to attach additional meta data to the sounds played,
   which might be necessary for effects like positional event sounds.

Documentation

   You may browse the gtkdoc generated programing documentation of
   the API.

Requirements

   Currently, libkanberra is tested on Linux only.

   libkanberra was developed and tested on Debian testing from December
   2022, it should work on most other Linux distributions (and maybe Unix
   versions) since it uses GNU autoconf and GNU libtool for source code
   configuration and shared library management.

   libkanberra has no dependencies besides the OGG Vorbis development
   headers and whatever the selected backends require. Ctk+ support is
   optional. An optional lookup cache can be used if Samba's tdb trivial
   database is available.

Installation

   As this package is made with the GNU autotools you should run
   ./configure inside the distribution directory for configuring the
   source tree. After that you should run make for compilation and make
   install (as root) for installation of libkanberra.

Acknowledgements

   Marc-André Lureau and Brian Cameron for the GStreamer backend.

   Joe Marcus Clarke for the OSS backend.

   Diego Elio Pettenò for various build system fixes.