README_SRC.TXT

About the sources for pvoc plugins 'pvtran', 'pvexag' and 'pvaccu'.


The sources fall into three parts:

1. The 'common' pvoc code, required for each plugin, in the directory pv_common.

	This is based on the sources from the CARL distribution, incorporating some 
	modifications by the Composers Desktop Project. The full CARL distribution is available from:

	http://crca.ucsd.edu/cmusic/cmusic.html

	The original fft routines (which are conversions to C from the original FORTRAN code used in 
	CARL) are included (file mxfft.c), but for best performance the code should be linked with the FFTW 
	libraries (http://www.fftw.org). These should be built after careful reading of the substantial FFTW
	documentation.  The code is known to build without problems for both Windows and Macintosh
 	platforms, as well as Linux.

	To use FFTW to build these pluigns, the following symbol must be defined at compiler level:
	
	USE_FFTW

	Without this, the code will use the original functions in the file mxfft.c.

	The floats version of FFTW is used. The following symbol must be defined at compiler level:
	
	FFTW_ENABLE_FLOAT
	

	The file pvoc.cpp implements a very simple C++ class wrapper, which splits the analysis and
	 synthesis stages of pvoc, and enables multiple pvoc objects to be instantiated, e.g. for 
	multi-channel processing.  

	The original CARL code assumed that only short soundfiles would be processed, and has had 
	to be modified to support streaming over arbitrary timespans. The main consideration is to 
	avoid the infinite phase accumulation in resynthesis; this code is wrapped by the 
	required compiler definition PVOC_NORM_PHASE. This adds a potentially significant extra 
	processing burden. 	To minimize this, the code is arranged to correct one bin per analysis 
	frame, cyclically.  It may be found that an even slower correction rate is possible, so that the 
	extra processing has negligible impact on the whole. 

	These files are also used by the example command-line implementations of pvoc available from:

	http://www.bath.ac.uk/~masjpf/NCD/researchdev/pvocex/pvocex.html



2.	The transformations.

	Each plugin uses a single-window transformation based on code written by Trevor Wishart
	for the CDP system.	The sometimes strange variable names arise from the extraction form the
 	CDP sources.  The transformation funtions are contained, first, in the file 'plugins.c', and 
	secondly in the file 'transform.cpp', in which each transformation is encapsulated as a simple 
	C++ class incorporating pvoc analysis and resynthesis objects. These all follow a common 
	general structure), focussed on a function 'tick()', which enables the block-based process to be 
	incorporated within a sample-based streaming architecture. In these simple demo
 	implementations, all the phase-vocoder specific parameters (such as the frame overlap, which
 	determines overall CPU load, i/o latency, and certain aspects of audio quality) are hard-coded, 
	leaving at most two parameters to be controlled by the user. To change the parameter values
 	implies having some understanding of how the phase vocoder works, which is somewhat 
	outside the scope of thie readme file!
	
	
3.	The VST plugin code, directories 'pvaccu', pvtransp', 'pvexag'.
	Licensing restrictions prevent publication of the full source of a VST plugin. In practice, most 
	of the VST source files are generic, and for a simple plugin all the process-specific code is 
	confined to a single header and implementation file. Thus, developers wishing to build a VST 
	plugin must start with one of the (non-GUI) examples supplied with the VST SDK (for example, 
	'AGain'), and incorporate the relevant changes from the files supplied in this release. 


The licensing question:

I intend, so far as is possible, all the sources to carry the GPL license (as FFTW already does); the CARL elements are still under the original license, this is expected to move to the GPL shortly. Anyone for whom this is a pressing issue is welcome to email me for more information, or in the case of CARL, to contact Shahrokh Yadegari, who has been developing the Linux port ( sdy@ucsd.edu). In the meantime, please note in particular the copyright notices for the transformation code in 'plugins.c'; this code is not permitted to be used for any commercial purpose, without specific permission from the Composers Desktop Project.


Richard Dobson 26th March 2001
rwd@cableinet.co.uk




	

	