| Previous | Index | Next |
This document is offered 'as is'. There may still be formatting mistakes or non-coherent sections or comments. Please report any such elements to the editor of the document.
Copyright (c) Music Technology Group (MTG), Universitat Pompeu Fabra (UPF).
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant sections being this 'Introduction', with the Front-Cover Texts being the one herein included, and with no Back-Cover Texts. A copy of the license is available at http://www.fsf.org/licenses/fdl.txt.
CLAM is a Free Software framework licensed under GNU-GPL that allows to fully develop multiplatform audio applications in C++ using advanced processing algorithms. It is not limited to the processing part of your application; it can help you providing multiplatform solutions for most problems that an audio application should face:
CLAM is able to do complex audio processing involving:
And last but not least, it comprises a big repository of already done algorithms concerning areas such as:
CLAM stands for C++ Library for Audio and Music and in Catalan means something like 'a continuous sound produced by a large number of people as to show approval or disapproval of a given event'. It is the best name we could find after long discussions and it is certainly much better than its original name (MTG-Classes).
CLAM was formerly developed as an internal project on the Music Technology Group at UPF named MTG-Classes. The aim of the project was to create a foundation of C++ classes to be used by all the research projects at the MTG. Literally (from the first written draft) the goal was:
'To offer a complete, flexible and platform independent Sound Analysis/Synthesis C++ platform to meet current and future needs of all MTG projects.'The three main axes of these goals were defined as:
These initial objectives have slightly changed since then mainly to accommodate to the fact that the library is no longer seen as an internal tool for the MTG but as a library that is made public under the GNU-GPL in the course of the Agnula IST European Project.
CLAM code is standard ISO/ANSI C++. It uses multiplatform libraries to abstract platform dependant issues. Non portable code and even library dependant code is very localized and isolated. This makes it easier to port CLAM to whatever platform.
Currently, the following platforms are supported:
| Linux | gcc 2.95 | Fully supported |
| gcc 3.X | Fully supported | |
| Windows | VisualC++ 6 (SP5) | Supported until release 0.6.1, not currently supported any longer |
| VisualC++ 7.1 | Fully Suported | |
| MacOSX | gcc 3.X | Fully Supported |
Reports on CLAM ports to any other platform will be appreciated.
Althought CLAM goes toward a visual environment, currently, this "visual builder" (quoting R.E. Johnson) is in beta stage and CLAM functionalities are only accessible by doing your own programs. Thus, a good level in object oriented C++ programming experience is needed, although we have tried our best to keep interfaces as simple as possible.
Of course, CLAM is a framework for audio and music processing so some knowledge in those areas (as well as some DSP basis) is also recommended.
The CLAM framework is built on top of some architectural basic elements that are used as building blocks and should therefore be mastered. Most of this document is about them but, just to have a first impression, these are the basic principles used in CLAM:
A CLAM based system can be viewed as a set of Processing objects deployed as an interconnected network. Each Processing can retrieve ProcessingData tokens and modify them acording to some algorithm.
Programmers can keep control over the ProcessingData flow between Processing or they can delegate this task to one of the many automated FlowControl schedulers.
A set of Processings can be arranged to form a new processing. Thus you can use that new processing to abstract what the full bunch of Processings does and then scale up to a more complex system. Processings can be arranged on compile-time (ProcessingComposites), or dinamically on run-time (Networks).
Figure 1: CLAM Network
Networks allow to build a CLAM system without no C++ knowledge, using only the graphical interface. They can be also used to build up rapid prototypes of a later optimized system. The prototyping environment is still some how limited.
The Processing classes are the main building blocks of the CLAM framework. All processing in the CLAM must be performed inside a Processing class.
Interaction between Processings follows a very bounded but flexible interface. This way, CLAM can manage Processing in a very general way and it boosts the reusability of Processings between different CLAM systems.
All the Processing configuration process is done by giving it a configuration object before the Processing object is on the running state. While the Processing is running, the processing algoritm will be executed every time the Do() method is called at the processing execution rate.
While the Processings is running receive and emits two kinds of output:
When no automated FlowControl is involved, you can also overload the Do() method to pass as parameters the ProcessingData that would be otherwise accessible from the ports. This way of implementing Processing is now deprecated but still used.
The following figure illustrates all the different components of a Processing class.
Figure 2: Processing Object Representation
Both, Configurations and ProcessingData, are implemented as DynamicTypes (often DT for short). DynamicTypes are an abstraction that allows to have objects with not all attributes instantiated. DynamicType are implemented using preprocessor macros that will expand each attribute declaration in accessors and instanciation interface among other useful methods.
One of the most used features in dynamic types is that they provide some kind of introspection, and thus CLAM can provide some useful functionalities in a general way on every new DynamicType you will define. Examples of those free functionalities that you get by defining some class as DT are XML serialization, generic atribute visit, automatic interface generation...
You can see section chapter VI for more information on DynamicTypes use.
(See section 35, chapter XX, chapter IX for XML support)
The CLAM Visualization Module fullfills two different developers needs. The first one is to inspect graphically CLAM objects as a debugging aid. The other one is to build a complete GUI based application that can be used in interaction with the Processing part of a CLAM system.
CLAM-VM has been designed in a very decoupled way so that it can be fully removed harmlessly from a CLAM system. It provides some general services that are toolkit independent such as thread safe data caching, model-view comunication and sincronization...
That CLAM-VM infrastructure can be used with any toolkit such as Qt, Fltk... In fact, it provides already done widgets, the toolkit dependant part. They are mostly implemented using FLTK and OpenGL but next releases will provide more support on Qt.
(See chapter XIV)
CLAM provides integrated and platform independent support for system dependant tasks. For example:
Although the structure of this document is a bit complex, hopefully by the time you get here you will be able to understand why the index has been set that way.
Basically, there are three parts to this document:
Part 1. User Documentation: Is the information any user of the CLAM framework should be aware of.
Part 2. Developer Documentation: Includes all the necessary information for more advanced users/developers.
Part 3. CLAM Sample Applications: In this part, we explain the most important sample applications included with CLAM.
Part 4. Migration: Is just a brief summary of the differences between the different releases (for already introduced and advanced users).
So, this document is intended to work as a more or less progressive introduction to CLAM. Start reading the first page and stop whenever you think details are becoming overwhelming. Of course for some particular users some sections may be 'skipable' and some may even prefer to start by reading about the sample applications just to get a grasp of what the framework is able to offer.
Going into a bit more details of the different parts, each of them includes the following topics.
Part 1 starts off with some information any CLAM user will need the first time he/she tries to use the framework: in the 'Deploying CLAM in your System' chapter you will be guided on how to configure CLAM in your system; and in the 'CLAM Build System Documentation'chapter you will be introduced to the features and functionalities of the rather particular build system that is used in CLAM. In the next chapter you will find a 'Usage Tutorial' (chapter IV) that introduces the basic functionality of the CLAM framework, furthermore in this same section we include a listing of other relevant examples that are kept in the repository. All following chapters focus on the different functionalities of the framework from a user's point of view (you will find chapters on Dynamic Types, Processing classes, Processing Data classes, XML Support, Audio I/O, MIDI I/O, The Application classes, and the Visualization Module (GUI)).
Part 2's first chapter, XIII. CLAM Coding conventions, gives some hints on coding recommendations and conventions for developers. The next chapters (Dynamic Types, Processing Data classes and XML) give an inside view on how to develop using the internal features of these CLAM's building blocks.
Part 3 includes an explanation of the following applications: SMSTools, SALTO, Spectral Delay and Rappid. The last chapter in this part explains how to use CLAM to develop LADSPA plug-ins. After you have read the introduction and have managed to compile CLAM, you may wish to go directly to these examples, before getting deeper into the library.
Part 4 gives a summary of the differences between this release and previous ones. You can skip this if you are not already familiar with the CLAM framework. Note: this part explains main differences between three latest releases, all the previous ones, though, have only been internal to MTG.
There are different sources of CLAM related information. All of them, though, are linked and updated at CLAM's website at www.iua.upf.es/mtg/clam .
| Previous | Index | Next |