..::CLAM::..C++ Lybrary for Audio and Music

CLAM MANUAL

I Introduction

  1 Disclaimer
  2 License of this document
  3 What is CLAM?
  4 What does 'CLAM' mean?
  5 Historical background
  6 Supported platforms
  7 Recommended previous skills
  8 Basic principles
    8.1 Processing architecture
    8.2 Processing classes
    8.3 Dynamic Types
    8.4 Visualization Module
    8.5 System utilities
  9 Structure of this document
  10 Where to find more information on CLAM

USER DOCUMENTATION

II Deploying CLAM in your system

  11 Roadmap
  12 Obtaining the CLAM sources
    12.1 GNU Tools distributed with MacOS X 10.2 Specific Issues
  13 Dependencies on third-party libraries
    13.1 External libraries on GNU/Linux
    13.2 External libraries on Microsoft Windows

III CLAM Build System Documentation

  14 Overview
  15 Setting up CLAM Build System
  16 USE / HAS variables
    16.1 Included configuration files
    16.2 Editing the packages-win.cfg file
    16.3 Setup on MS Visual Studio
      16.3.1 Configuring Visual 6 to use srcdeps
      16.3.2 Compiling our first CLAM example
    16.4 Setup on GNU/Linux
      16.4.1 Compiling our first CLAM example
  17 How to set up your own programs using CLAM
    17.1 An out-of-the-box example
    17.2 Customizing your project
  18 CLAM and QT toolkit library
  19 CLAM build system configuration variables reference
    19.1 Build system variables reference
    19.2 CLAM configuration variables
    19.3 External libraries variables
  20 Generating CLAM binaries
  21 Some useful links
  22 Build system troubleshooting
  23 Some common problems while using Microsoft Visual C++
    23.1 Getting lots of LNK2001 errors: redefinition of C/C++ Standard Library symbols
    23.2 Getting lots of compiling errors not related to your Project (What's config.h about?)
    23.3 Not finding a user defined header
    23.4 My dynamic_cast's are failing for no apparent reason
    23.5 I am getting an Internal Compiler Error message!!!
    23.6 My Visual C++ is behaving weirdly and signalling non-sense error messages
    23.7 The compiler does not find FL/Flxxxx.H or DOM/xxxx.hpp
  24 Some common problems while using GNU/Linux and GNU C++ Compiler
    24.1 FFTW
      24.1.1 Getting error when trying to locate fftw header/libs
    24.2 FLTK
      24.2.1 Checking fltk libs fails and config.log contains compiler errors
      24.2.2 Checking fltk libs fails and config.log contains linking errors, or the program test couldn't be executed.
      24.2.3 fltk-config not found
    24.3 QT
      24.3.1 No qt headers found! having qt installed correctly in the system
      24.3.2 Found qt headers but crashed testing lib because library (qt or qt-mt) not found.
      24.3.3 Compiler errors related to exit and throw functions
    24.4 XERCES
      24.4.1 Checking xerces libs fails and config.log contains compiler errors
      24.4.2 Checking xerces libs fails and config.log contains linking errors, or the program test couldn't be executed
    24.5 STL
      24.5.1 Getting these errors:
    24.6 Common problems trying to compile and execute CLAM applications
      24.6.1 Compiling is ok but getting errors trying to link/execute the program

IV Usage tutorial

  25 Introduction
  26 Instanciating Processing objects
  27 Processing Data
  28 Usage examples

V Usage examples

VI Dynamic Types

  29 Scope
  30 Why Dynamic Types ?
  31 Where can DT be found within the CLAM library?
  32 Declaring a DT
  33 Basic usage
  34 Prototypes and copy constructors
  35 Storing and Loading DTs
    35.1 How to explore a DT at debug time

VII Processing classes

  36 Introduction
    36.1 Class hierarchies
    36.2 Coding style and philosophy
  37 Overview of the processing class implementation tasks
    37.1 Declaring the processing interface attributes
    37.2 Implementing the construction mechanism
    37.3 Implementing the configuration mechanism
    37.4 Implementing the execution methods
    37.5 Implementing other optional standard methods
    37.6 Writing the tests
  38 Object construction and configuration interface
    38.1 Processing configuration classes
      38.1.1 The role of processing configuration classes
      38.1.2 Configuration class implementation
    38.2 Processing constructors
    38.3 Configuration methods
  39 Object execution interface
    39.1 Execution states
    39.2 Execution methods
    39.3 Object execution not using ports
      39.3.1 Do method argument conventions
  40 Controls
    40.1 Input Controls
      40.1.1 Regular input controls
      40.1.2 Input controls with call-back method
    40.2 Output Controls
    40.3 Controls initialization
  41 Internal object state
    41.1 Configuration related attributes
    41.2 Execution related attributes
      41.2.1 Initialization
  42 Processing Composite
  43 Exception Handling
    43.1 Assertions
      43.1.1 Where to use assertions
      43.1.2 How to make assertions
    43.2 Run time problems
  44 Writing tests for your classes
    44.1 Why?
    44.2 How?
  45 Helper classes
    45.1 Enumeration classes
    45.2 Flags classes
  46 Prototypes
      46.0.1 Footnotes

VIII Processing Data classes

  47 Scope
  48 Introduction
  49 Basic structural aspects
  50 Efficiency Issues
  51 Introduction to CLAM`s Core PD classes
    51.1 Audio
    51.2 Spectrum
    51.3 SpectralPeak and SpectralPeakArray
    51.4 Fundamental
    51.5 Frame
    51.6 Segment
    51.7 Descriptors
  52 Basic XML support

IX XML Support

  53 Scope
  54 Brief introduction to XML
  55 Storing components
  56 Loading components
  57 Detailed step interface

X Audio File I/O in CLAM

  58 What is able to do?
  59 Usage examples
    59.1 Audio File I/O: File information extraction example
    59.2 AudioFile I/O: Audio file reading example
    59.3 Audio file I/O: Audio file writing example
    59.4 Playing an arbitrary audio file

XI Audio I/O

  60 The AudioManager
  61 The AudioIn and AudioOut classes
    61.1 Specifying the device
    61.2 Specifying the channel

XII MIDI I/O

  62 The MIDIManager
  63 MIDI I/O Processings and their configuration
    63.1 The MIDIIn and MIDIInControl class
    63.2 The MIDIOut and MIDIOutControl class
    63.3 The MIDIIOConfig class
    63.4 Dynamically created InControls and OutControls
  64 The MIDIDevice class
    64.1 Specifying the MIDI device
    64.2 Clocking the MIDI device
  65 MIDI Enums

XIII The Application Classes

  66 BaseAudioApplication
  67 GUIAudioApplication
  68 AudioApplication
  69 Creating and running an Application

XIV Visualization Module

  70 Plots
    70.1 Plots examples
    70.2 Visualization Module Plots: single function plot
    70.3 Visualization Module Plots: multiple function plot
    70.4 SDIF I/O, Segments and plots
  71 Model Adapters and Presentations

XV SDIF SUPPORT

DEVELOPER DOCUMENTATION

XVI CLAM Coding Conventions

  72 Indenting code
  73 Naming conventions
  74 Programming style
  75 Error Conditions
  76 Debugging aids

XVII Error Handling

  77 Use case analysis
    77.1 Actors
    77.2 Stages
    77.3 Mechanisms
  78 Sanity checks and assertions
    78.1 Expression assertions
    78.2 Statement based 'assertions' (checks)
    78.3 Documenting assertions
    78.4 Optimization and assertions
    78.5 Managing assertions from the application
    78.6 Debugging the release mode
  79 Exceptions
    79.1 Previous note
    79.2 When to use Exceptions
    79.3 Contract between throwers and catchers
    79.4 Exception data and exception hierarchy
    79.5 Exception handling
    79.6 Contextualization

XVIII Dynamic Types

  80 DTs that derive from an interface class
  81 Typical Errors
    81.1 Detected errors at compile time:
      81.1.1 Constructor errors
      81.1.2 Attribute position out of bounds
      81.1.3 Attribute not defined
      81.1.4 Duplicated attributes
    81.2 Detected errors at run time
      81.2.1 Compiling in debug mode (the macro _DEBUG defined )
      81.2.2 Compiling in a non debug (release) mode
      81.2.3 Compiling for the best run-time efficency
    81.3 Non detected errors
  82 Constructors and initializers
  83 Tuning a DT
  84 Debugging aids and compilation flags
  85 Pointers as dynamic attributes
  86 Copies of DTs
  87 DTs and XML
    87.1 The default XML Implementation for DynamicTypes
    87.2 XML aware dynamic attributes
    87.3 Customization basics
    87.4 Reordering and skipping
    87.5 Recalling the default implementation
    87.6 Adding content not from dynamic attributes
    87.7 Storing not as XML elements or changing the tag name
    87.8 Keeping several alternative XML formats

XIX Processing Data

  88 Basic structural aspects II
  89 Constructors and initializers
  90 Private members with public interface
  91 Configurations
  92 Customizing XML output
  93 Specific attributes: flags and enums

XX XML

  94 Components and XML
  95 XML Adapters
    95.1 Simple types adapters
    95.2 Simple type C array adapters
    95.3 Component adapters
    95.4 Loading Considerations

XXI C pre-processor macros defined and used by CLAM sources

  96 Global flags
  97 Cross-platformness macros
  98 Dynamic Types Macros
  99 Defensive programming macros
  100 preinclude.hxx Macros
  101 Platform dependant macros
  102 Private Macros

CLAM SAMPLE APPLICATIONS

XXII Introduction

  103 SMS Example
  104 SALTO
  105 Spectral Delay
  106 Rappid

XXIII SMS Example

  107 Introduction
  108 Building the application
  109 An SMSTools walkthrough
  110 Analysis Output
  111 Configuration
  112 Synthesis
  113 Transformation
  114 Implementing your own transformation
  115 Internal class structure and program organisation
  116 SMSSynthesis and SMSAnalysis

XXIV SALTO

XXV Spectral Delay

XXVI Rappid

XXVII Combining CLAM with LADSPA plugins

  117 The LADSPA Toolkit and CLAM, a brief introduction
  118 Using CLAM Processings as LADSPA plugins
  119 Using LADSPA Plugins as CLAM Processings

MIGRATION GUIDELINES

  120 From 0.6.1 to 0.7.0
  121 From 0.5.5 to 0.5.6
  122 From 0.5.4 to 0.5.5
  123 From 0.4.2 to 0.5.0
  124 From 0.2 to 0.3
    124.1 Dynamic Types
    124.2 Processing Data
    124.3 Error handling
    124.4 PARANOID macro
    124.5 Using exceptions as error message generators
    124.6 Using _DEBUG, NDEBUG and so
    124.7 Miscellaneous