CSL 5.2 README

This directory contains the source code and documentation for the  CREATE Signal 
Library (CSL, pronounced "sizzle," previously called the  CREATE Oscillator, CO). 
CSL is being developed at the Center for Research in Electronic Art Technology 
(CREATE) and the Graduate Program in Media Arts and Technology (MAT) at the 
University of California, Santa Barbara (UCSB). It is a work in progress.

This is release 5.2, November, 2012.

The home page for CSL is http://FASTLabInc.com/CSL.

CSL is known to work on Mac OSX, many flavors of UNIX/Linux, iPhones, and (with 
limited features) on MS-Windows. To get started quickly, build the JUCE demo app
and use the combo boxes at the bottom to select among the tests, whose source code
is all in the Tests folder. For the Mac, use the XCode project in the CSL_JUCE/Builds/MacOSX 
folder; for Linux, use the premake script in the Linux folder. Both assume JUCE 2.0 is 
already installed and compiled.

About CSL

CSL is a C++ class library, to use it, you write and compile C++ programs like 
the ones in the CSL/Tests directory. These programs will generally use the CSL 
class library, and may read input files or respond to in-coming MIDI or OSC 
commands. CSL apps can run stand-alone as servers, or have interactive GUIs, or be 
plug-ins to out-board signal processing tools.

This means that the target users for CSL are C++ programmers (familiar with the 
development tools of their platforms, e.g., Xcode on the Mac, Eclipse on Linux, or 
Visual Studio on MS-Windows) who also know some software sound synthesis language 
such as Csound or SuperCollider (see Curtis Roads' "Computer Music Tutorial").

CSL assumes it's installed in the folder ~/Code/CSL; there are some default settings 
in CSL/Kernel/CSL_Types.h that have to be changed if you put it somewhere else.
The system assumes JUCE is in ~/Code/juce (../juce from the root of the CSL hierarchy).

The best way to get started is to look at the Doxygen-generated API documentation in 
	./Doc/html.zip

You can untar this file to get the full HTML doc and to print out and study the files,
	CSL/Kernel/CSL_Types.h (note the system defaults here)
	CSL/Kernel/CSL_Core.h (the kernel classes are here)
and 
	CSL/Sources/SimpleSines.{h,cpp} (a tutorial for writing unit generators)
or
	CSL/Tests/TestSources.cpp (or any of the other tests)

To compile the sources, you will need to create the links in the CSL/Includes folder; 
to do this, open a UNIX shell (terminal, or DOS prompt) and execute the commands,

### change to the Includes folder
	cd ~/Code/CSL/CSL/Includes

### make symbolic links from the include files to this folder
	./remake

### or, on windows
	remake.bat

Note that the release contains a number of files that have not been ported to the 
newest framework; these are generally in subdirectories called "OLD" and may well 
work with a little bit of tweaking; all the really unstable code has been removed.


Platform Requirements

	MacOS X: OS x 10.5 or newer with Xcode 3

	Linux: Tested on Ubuntu 9.04 with X11-libs, ALSA, Freetype, pthreads, openGL/GLUT

	MS-windows: Tested on XP with DirectX 9, ASIO4All, ASIO SDK

	All: JUCE 2.0


Linking with the CSL Libraries

To link CSL programs, you'll need the following packages installed on your machine:
  Either
	JUCE: Cross-platform everything -- http://www.rawmaterialsoftware.com
	Note that we use a version of the JUCE 1.50 libraries with a few extra hooks;
	see the CSL download page and install the changed C++ files in 
	{JUCE}/src/juce_appframework/audio/audio_file_formats.

  OR
	Cross-platform audio I/O: PortAudio (http://www.portaudio.com) V19 or newer;
	Cross-platform MIDI I/O: PortMIDI (http://www-2.cs.cmu.edu/~music/portmusic);
	Cross-platform sound file I/O: libsndfile 
	(http://www.zip.com.au/~erikd/libsndfile) V1.04 or newer; 
	Fast Fourier Transform: FFTW (http://www.fftw.org) package V3.X;

Note that you can use "vanilla" JUCE for the GUI and IO, but libSndFile for sound file 
API if you don't want to patch your JUCE (compile-time option -DUSE_LSND).

The auralizer (obsolete) also requires 
	VRML parser: libcX3D (http://www.cybergarage.org/vrml/cx3d/cx3dcc/index.html)
	(cd CyberX3D; ./bootstrap; ./configure; make)

To use OpenSoundControl (OSC) with CSL, you'll need liblo (http://liblo.sourceforge.net/), 
which is included in  the CSL source folder.

The CREATE CSL web site includes pre-compiled versions of these libraries for 
Mac OS X and MS-Windows.

If you use FFTW (rather than FFTReal),it needs to be compiled in the way described 
in Sources/Spectral.h.


CSL JUCE demo

Building CSL

	On a Mac: ~/CSL/MacOSX/CSL_JUCE.xcodeproj
	On MS-Windows: ~/CSL/Windows/VS8/CSL.sln
	On Linux: cd ~/CSL/Linux; ./runpremake; make

The new standard way of running CSL programs is using the JUCE GUI. 
Take a look at the projects for Mac/Linux/Windows; we create a window with a couple 
of VU meters and oscilloscopes and combo boxes to select a test suite and specific test 
to run. Note that you need JUCE V 1.50 or newer, and that we use several extensions 
to the sound file I/O classes that can be grabbed from the CSL download site.

Here's the JUCE demo GUI's Menu List

Oscillator Tests  -  Test_Oscillators.cpp
              Sweep test	Test a sine with swept freq and volume swell
            Simple sines	Test some simple sine oscilators
      Standard waveforms	Demonstrate the standard wave forms
             Scaled sine	Play a scaled-quiet sine wave
 Wavetable interpolation	Show truncated/interpolated wave tables
             AM/FM sines	Play an AM and FM sine wave
        Dump AM/FM sines	Dump the graph of the AM/FM sine
       SumOfSines cached	Play a sum-of-sines additive oscillator
   SumOfSines non-cached	Play an uncached inharmonic sum-of-sines
        SumOfSines build	Build up a harmonic series on a sum-of-sines
          SumOfSines 1/f	Play a 1/f spectrum sum-of-sines
     Wavetable from file	Play a wave table from a sound file
               SHARC SOS	Load/print the SHARC timbre database, play example
            Vector SHARC	Show vector cross-fade of SHARC spectra

Source Tests  -  Test_Sources.cpp
             Noise tests	Test noise generators
          Plucked string	Waves of string arpeggii, stereo with reverb
    Mono Snd file player	Test playing a sound file
  Stereo Snd file player	Play a stereo sound file
      Snd file transpose	Demonstrate transposing a sound file
        Sample file bank	Play a large sample bank from sound files
           FM instrument	Play the basic FM instrument
     Fancy FM instrument	FM note with attack chiff and vibrato
   SumOfSines instrument	Demonstrate the SumOfSines instrument
     Snd file instrument	Test the sound file instrument
          IFFT synthesis	Make a sound with IFFT synthesis
             Vector IFFT	Vector synthesis with 2 IFFTs
   Soundfile granulation	Random sound file granulation example

Envelope Tests  -  Test_Envelopes.cpp
          Glissando test	Demonstrate a glissando function
     Swell on aqmplitude	Make an amplitude swell
      Frequency envelope	Play a note with a frequency envelope
                 AR sine	Play an AR (attack/release) amplitude envelope
         AM/FM envelopes	Test AM and FM envelopes
                  ADSR 2	Play an ADSR (attack/decay/sustain/release)
                 ADSR FM	Dual-envelope FM example
      Rand Freq envelope	Play a random-walk frequency envelope
        50 Rand F/A envs	Test 50 random frequency envelope players
                Fancy FM	Play a fancy FM note
        Complex envelope	Play a note with a complex amplitude envelope
         Many random SOS	Layer many SumOfSines instruments with envelopes

Effect Tests  -  Test_Effects.cpp
                 Clipper	Demonstrate the signal clipper
              FIR filter	Play an FIR band-pass filter
             All filters	Test different filter types
       Filtered snd file	Dynamic BPF on a voice track
          Dynamic filter	Play a dynamic BP filter on noise
    Many dynamic filters	Many dynamic filtered-noise instruments
                  Reverb	Show mono reverb on impulses
             Stereo-verb	Listen to the stereo reverb
               Multi-tap	Play a multi-tap delay line
          Block up-sizer	Test the block resizer on up-sizing
        Block down-sizer	Test the block resizer on down-sizing
       Sample-avg filter	Demo in-line sample-average-filter class

Panner Tests  -  Test_Panners.cpp
           Stereo panner	Demonstrate the stero panner
                   Mixer	Mixer with 4 sine inputs (slow sum-of-sines)
           Panning mixer	Play a panning stereo mixer
    Bigger panning mixer	Test a mixer with many inputs
                Osc bank	Mix a bank of oscillators
      HRTF horiz circles	Test the HRTF-based binaural panner
      HRTF axial circles	Play a HRTF-panner with axial circles
     HRTF median circles	Play a HRTF-panner with median circles
              Ambisonics	Test the Ambisonic-based spatial panner

Control Tests  -  Test_Control.cpp
              Dump ports	Dump list of MIDI ports to stdout
              Dump input	Dump MIDI input from default device
              MIDI notes	Play MIDI notes (reads MIDI kbd)
             MIDI output	Test sending MIDI output
           MIDI listener	Start the MIDI listener object
        MIDI file player	Play a MIDI file on an instrument library
       OSC client/server	OSC client/server on a library
              OSC server	Start OSC server on a library

Audio Tests  -  Test_Audio.cpp
        Dump audio ports	Dump list of audio ports to stdout
           Echo audio in	Play the microphone in
              Audio echo	Add echo to the live input
            Input panner	Stereo panner on the live input
          Input listener	Demonstrate recording input listener


The source code for all these tests is in the CSL/Tests directory (and in a"Test" 
file group in the IDE); it's a good way to learn CSL to run the JUCE demo in an 
XCode/Eclipse/VisualStudio debugger and set breakpoints in the test functions 
while using the GUI.


CSL main() functions

Note that there are several versions of the main() function; if you're not using
one of the prepared project files, try compiling the library (most of the sources)
with the file Beep_main.cpp as the main. Alternatively, take a look at the bottom 
of Test_Oscillators.cpp (or Test_Sources.cpp) and select a couple of tests to run.

Test targets
	Beep_Test -- simplest FM beep
	CSL_Test -- basic test suite; uses Test_main.cpp
	OSC_Test -- Several; OSC tests, see OSC_main.cpp
	MIDI_Test -- Reads MIDI in
	CSL Client_Server -- compiles 2 executables for remote c/s streaming


Source Code Organization

The subdirectories of CSL are reflected in the project file categories:

	- Tests - Test/demo main() driver functions
	- Kernel - Bufers and FrameStreams
	- Sources - Oscillators, noise, envelopes, PhysMod
	- Processors - Operators, filters, mixers, panners
	- IO - IO drivers and LAN streaming
	- Utilities - Thread and buffer support classes
	- Instruments - OSC/MIDI instrument wrappers
	- Spatializers - Panners and spatializers
	- Doc - a few published papers, Doxygen doc, README, etc.
	- Data - Test sounds, HRTF data, etc.

Reading the source

	Set tabs to 4 spaces so comments line up.
	Use a syntax-coloring editor, if available.
	Note the naming conventions.

Coding Conventions

Naming
	Class, member, and method names are written in "camelCase" as in 
	"UnitGenerator."
	Data members (instance variables) are written with initial "m" followed by 
	embedded caps as in "mOffset."
	Enumeration constants are written with initial "k" followed by embedded caps 
	as in "kDone."

Privacy
	In general data members are protected and have accessor functions where 
	appropriate. 
	The one exception is Buffer which is considered a record class and has public 
	members.

CORE CSL Types & Classes
	sample(float), SampleBuffer, SampleBufferVector, 
	SampleComplex, SampleComplexVector
	PortMap, UGenVector, UGenMap, IODeviceVector, Timestamp, VOIDFCNPTR
	Buffer, UnitGenerator, Controllable, Scalable, Effect
	FanOut, Splitter, Joiner, Interleaver, IO
	Window, Envelope, Oscillator, Filter,Mixer, Panner

Constants
	CSL_PI, CSL_TWOPI, CSL_PIHALF, CSL_SQRT_TWO, CSL_SPEED_OF_SOUND, 
	CSL_EXP_PER_DB, CSL_SAMPS_PER_METER, CSL_DEGS_PER_RAD


Compile-time options 

(These are not set in the header files so that different apps can share the source tree.)

SoundFile type:
	USE_JSND - use the JUCE-based sound file class (requires only JUCE)
	USE_LSND - use libSndFile-based sound file class (supports many file types)
	USE_CASND - use the CoreAudio version (runs on iPhone)

FFT implementation
	USE_FFTW - use FFTW 3 (faster but complicated to build)
	USE_FFTREAL - use FFTReal (smaller and simpler)
	USE_KISSFFT	- use KISS FFT (smaller, untested)
	
Thread implementation
	USE_JTHREADS - use the JUCE thread classes (otherwise use pthreads)

MIDI API
	USE_JMIDI - use JUCE's MIDI I/O

OSC API
	USE_LOSC - use LibLo for OSC (assumes liblio 0.26 is installed)

Main function to use
	USE_JUCE - use a JUCE component for the main() function (otherwise test_main())


Documentation

See the PDF files in the Doc/ directory. (RTFM)

For further information, please join the CSL mailing list at
	http://create.ucsb.edu/mailman/listinfo/CSL

See the file COPYRIGHT for the list of authors and UC copy-left.

stp et al. @ CREATE.UCSB.edu - January, 1998 - November, 2012