* Documentation

README

@@ -0,0 +1,148 @@
+
+Rubber Band
+===========
+
+An audio time-stretching and pitch-shifting library and utility program.
+Copyright 2007 Chris Cannam, cannam@all-day-breakfast.com.
+Distributed under the GNU General Public License.
+
+Rubber Band is a library and utility program that permits you to
+change the timing (duration or speed) and pitch of an audio recording
+independently of one another.
+
+Attractive features:
+
+ ** High quality results suitable for musical use
+
+    Rubber Band is a phase-vocoder-based frequency domain time
+    stretcher with partial phase locking to peak frequencies and phase
+    resynchronisation at noisy transients.  It is suitable for most
+    musical uses with its default settings, and has a range of options
+    to adjust if desired.
+
+ ** Real-time capable
+
+    In addition to the offline mode (where all audio data is available
+    beforehand), Rubber Band supports a true real-time, lock-free
+    streaming mode, in which the time and pitch scaling ratios may be
+    dynamically adjusted during use.
+
+ ** Sample-accurate duration adjustment
+
+    In offline mode, Rubber Band ensures that the output has exactly
+    the right number of samples for the given stretch ratio.  (In
+    real-time mode Rubber Band aims to keep as closely as possible to
+    the exact ratio, although this depends on the audio material
+    itself.)
+
+ ** Multiprocessor/multi-core support
+
+    Rubber Band's offline mode can take advantage of more than one
+    processor core if available, when processing data with two or more
+    audio channels.
+
+ ** No job too big, or too small
+
+    Rubber Band is tuned so as to work well with the default settings
+    for any stretch ratio, from tiny deviations from the original
+    speed to very extreme stretches.
+
+ ** Handy utilities included
+
+    The Rubber Band code includes a useful command-line time-stretch
+    and pitch shift utility (called simply rubberband), two LADSPA
+    pitch shifter plugins (Rubber Band Mono Pitch Shifter and Rubber
+    Band Stereo Pitch Shifter), and a Vamp audio analysis plugin which
+    may be used to inspect the stretch profile decisions Rubber Band
+    is taking.
+
+ ** Free Software
+
+    Rubber Band is Free Software, published under the GNU General
+    Public License.  This means you may use, modify and redistribute
+    it free of charge under certain conditions, such as that you
+    offer the same conditions when re-distributing Rubber Band or
+    works based on it.  Please read the file COPYING for details.
+    Commercial terms are also available for proprietary applications.
+
+Limitations:
+
+ ** Not very fast
+
+    The algorithm used by Rubber Band is fundamentally not all that
+    quick, and Rubber Band is not the fastest implementation on earth.
+
+ ** Not exactly state of the art
+
+    Rubber Band employs well known algorithms which work well in many
+    situations, but it isn't "cutting edge" in any interesting sense.
+
+ ** Relatively complex
+
+    While the fundamental algorithms in Rubber Band are not especially
+    complex, the implementation is complicated by the support for
+    multiple processing modes and other features that add to the
+    flexibility of the API.
+
+
+Compiling Rubber Band
+---------------------
+
+Compiling Rubber Band requires requires libsndfile, libsamplerate,
+FFTW3, the Vamp plugin SDK, the LADSPA plugin header, the pthread
+library, and a C++ compiler.
+
+Rubber Band comes with a simple autoconf script.  Run 
+
+  $ ./configure
+  $ make
+
+to compile, and optionally
+
+  # make install
+
+to install.
+
+
+Using the Rubber Band utility
+-----------------------------
+
+The Rubber Band command-line utility builds as bin/rubberband.  The
+basic incantation is
+
+  $ rubberband -t <timeratio> -p <pitchratio> <infile.wav> <outfile.wav>
+
+For example,
+
+  $ rubberband -t 1.5 -p 2.0 test.wav output.wav
+
+stretches the file test.wav to 50% longer than its original duration,
+shifts it up in pitch by one octave, and writes the output to output.wav.
+
+Several further options are available: run "rubberband -h" for help.
+In particular, different types of music may benefit from different
+"crispness" options (-c <n> where <n> is from 0 to 5).
+
+
+Using the Rubber Band library
+-----------------------------
+
+The Rubber Band library has a public API that consists of one C++
+class, called RubberBandStretcher in the RubberBand namespace.  You
+should #include <rubberband/RubberBandStretcher.h> to use this class.
+There is extensive documentation in the class header.
+
+The source code for the command-line utility (src/main.cpp) provides a
+good example of how to use Rubber Band in offline mode; the LADSPA
+pitch shifter plugin (src/ladspa/RubberBandPitchShifter.cpp) may be
+used as an example of Rubber Band in real-time mode.
+
+IMPORTANT: Please ensure you have read and understood the licensing
+terms for Rubber Band before using it in another application.  This
+library is provided under the GNU General Public License, which means
+that any application that uses it must also be published under the GPL
+or a compatible license (i.e. with its full source code also available
+for modification and redistribution).  See the file COPYING for more
+details.  Alternative commercial and proprietary licensing terms are
+available; please contact the author if you are interested.
+

TODO

@@ -1,21 +0,0 @@
-
-* Fix "!!!" points
-* LADSPA plugin has too much "artificial latency"
-* LADSPA plugin probably doesn't want to go any higher than about +2 octaves
-* Return value check in FFT and resampler!
-* sweeps & tones
-* ensure default options don't produce garbage at any extreme
-
-DONE * implement+test, or remove, reset()
-DONE * Add and test Win32 threading primitives in Thread.cpp
-DONE * Threading lock structure is very slow if it becomes starved of CPUs
-DONE * Rationalise naming further (e.g. use of "lock" for both peak phases
-  and resynchronisation at transients; use of block vs chunk vs frame
-  vs window)
-DONE * Vamp plugin argument no longer properly reflect internal parameters
-DONE * 192kHz
-DONE * save/restore FFTW wisdom if using FFTW
-DONE * Sort out resynthesis gain
-DONE * LADSPA plugin could do with switches for transient/phaselock
-DONE * Solve "for very long stretches" issue in calculateSizes()
-DONE * Rejig crispness options

src/StretcherImpl.cpp

@@ -424,8 +424,8 @@ RubberBandStretcher::Impl::calculateSizes()
 void
 RubberBandStretcher::Impl::configure()
 {
-    std::cerr << "configure[" << this << "]: realtime = " << m_realtime << ", pitch scale = "
+//    std::cerr << "configure[" << this << "]: realtime = " << m_realtime << ", pitch scale = "
-              << m_pitchScale << ", channels = " << m_channels << std::endl;
+//              << m_pitchScale << ", channels = " << m_channels << std::endl;
 
     size_t prevWindowSize = m_windowSize;
     size_t prevOutbufSize = m_outbufSize;