From a94f3f33577bf9d71166392febbfdf3cace6f1c8 Mon Sep 17 00:00:00 2001 From: Chris Cannam Date: Mon, 10 Dec 2007 16:29:52 +0000 Subject: [PATCH] * Documentation --- README | 148 ++++++++++++++++++++++++++++++++++++++++++ TODO | 21 ------ src/StretcherImpl.cpp | 4 +- 3 files changed, 150 insertions(+), 23 deletions(-) create mode 100644 README delete mode 100644 TODO diff --git a/README b/README new file mode 100644 index 0000000..cd83a60 --- /dev/null +++ b/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 -p + +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 where 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 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. + diff --git a/TODO b/TODO deleted file mode 100644 index bb88259..0000000 --- a/TODO +++ /dev/null @@ -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 diff --git a/src/StretcherImpl.cpp b/src/StretcherImpl.cpp index 7a9fb2e..919cea1 100644 --- a/src/StretcherImpl.cpp +++ b/src/StretcherImpl.cpp @@ -424,8 +424,8 @@ RubberBandStretcher::Impl::calculateSizes() void RubberBandStretcher::Impl::configure() { - std::cerr << "configure[" << this << "]: realtime = " << m_realtime << ", pitch scale = " - << m_pitchScale << ", channels = " << m_channels << std::endl; +// std::cerr << "configure[" << this << "]: realtime = " << m_realtime << ", pitch scale = " +// << m_pitchScale << ", channels = " << m_channels << std::endl; size_t prevWindowSize = m_windowSize; size_t prevOutbufSize = m_outbufSize;