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