CSL HOWTO and FAQ

Jeff Tranter <tranter@pobox.com>

03 August, 2001

Introduction

CSL is the Common Sound Layer, a C-based API for sound programming. CSL is intended to address the problem of providing sound support in applications that works independently of the underlying sound drivers. It also hopes to become the common library for sound support under the KDE and Gnome projects.

It currently works on Linux systems using the OSS sound drivers and the aRts sound server (which runs on both KDE and Gnome desktop environments). The current features in the preview version 0.1.2 include:

sound driver abstraction, currently providing CSL/PCM API backends for OSS driver and aRts driver
working implementation of required aRts/MCOP communication in C
supports ARTS_SERVER/ARTS_COOKIE environment variables for aRts connections and authentification
supports OSS_DEVICE environment variable for OSS driver
utility programs:
- cslcat: outputs a sound stream in a given format
- testsine: generates a sine function in a given format
first stab at recording in the CSL::Adapter

CSL is being developed by Tim Janik and Stefan Westerfeld. This FAQ was written by Jeff Tranter.

Installation

Requirements

To build CSL you require:

a Linux system with OSS sound drivers
aRts sound server version 0.5.4 or later (optional, if you want aRts support)

Obtaining CSL

CSL is currently only provided in source format. You need to download the tar archive from http://www.arts-project.org/download/csl-0.1.2.tar.gz. Unless you are running a recent CVS version of KDE, you will need to obtain version 0.5.4 of aRts, available from: http://www.arts-project.org/download/arts-0.5.4.tar.gz.

Building and Installing

CSL follows the usual GNU build procedure, documented in the file INSTALL. Briefly, you need to run the commands:

%./configure
% make
% make install (as root)

If you are building from CVS then you can use the script autogen.sh to generate the configure script, make files, etc.

Testing

Here are some quick tests you can use to verify that CSL is working. From the top level CSL directory, run the command:

% ./tests/testsine | csl/cslcat

This should produce one second of a 440 Hertz sinewave tone.

The following command will read the random number generator device and send it to the sound driver via CSL, producing a white noise sound:

% cslcat < /dev/urandom

If you have any raw sound files, you can try playing one with the cslcat utility, for example:

% cslcat -r 44100 -w 8 -c 1 /usr/lib/games/koules/start.raw

The command locate '*.raw' can be used to find raw sound files on your system.

API Documentation

Documentation of the CSL API is currently being developed. The API documentation can be automatically generated from the source code using the doxygen tool. A configuration file Doxyfile has been supplied. An on-line version of the documentation should be available some time in the future.

Some example programs can be found in the examples directory. These are currently in development.

Contacting the Developers

If you want to contact the developers or other users of CSL to report a bug, ask a question, or offer to help contribute, send a message to the CSL mailing list described in the References section at the end of this document.

Frequently Asked Questions

Q. Where can I access the latest source code?

The code is in CVS hosted by freedesktop.org. There is currently no anonymous access. Contact the developers if you would like to get access to CVS.

Q. Are there Debian or RPM packages available?

Not yet. Feel free to volunteer :-)

How do I port applications to use CSL?

The best approach is to replace the sound API functions in your application with the relevant CSL functions. See the code examples and API documentation for ideas. In the future a wrapper application (csldsp) may be provided that will redirect calls to sound devices to CSL for supporting legacy applications.

How can I use CSL under KDE?

Yes, make sure you have installed version 0.5.4, or newer, of aRts.

How can I use CSL under Gnome?

Yes, install the Gnome version of aRts listed under References.

When I run CSL the aRts sound server reports: MCOP ObjectManager: can't find implementation for CSL::Adapter.

You forgot or incorrectly installed the aRts Adaptor for CSL. Make sure the build was successful, you did make install, and you have the required version of aRts.

CSL works with the aRts backend but the OSS backend fails.

If artsd is running then CSL cannot open the sound device. You can use the command artsshell suspendDoes CSL support multi-threaded programs? Yes. You need to initialize aRts using csl_driver_init_mutex(). See the example program cslmutex.

How can I have a CSL application use an aRts server on another host?

To have a CSL based application connect to a remotely running artsd process, artsd should be started with the -p option which enables network transparency and makes artsd listen on a specified port.

To circumvent cookie authentification, -u can be used. For example, to have artsd running on host A and stream sound to it from host B, the following commands can be issued (provided a working aRts and CSL installation is present on both systems):

A: % artsd -u -p 12345
B: % export ARTS_SERVER=A:12345
B: % mpg123 -s my-music.mp3 | cslcat

Note that starting artsd with the -u option completely disables authentification and can be a security risk on open networks.

Are mixer functions supported?

Not yet.

Are the ALSA sound drivers supported?

Not yet, but they should work with the ALSA OSS emulation.

References

aRts Project: http://www.arts-project.org
Conference paper on CSL: http://www.gtk.org/~timj/guadec-csl-2001
Doxygen home page: http://www.doxygen.org
Gnome aRts: http://www.arts-project.org/doc/gnome-arts-0.1.2.html

You can join the CSL mailing list by sending a message with the word subscribe as the message body to csl-request@space.twc.de. The mailing list is archived at http://www.mail-archive.com/csl@space.twc.de.

Jeff Tranter