* Documentation
This commit is contained in:
Chris Cannam
148
README
Normal file
148
README
Normal file
@@ -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.
|
||||
|
||||
21
TODO
21
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
|
||||
@@ -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;
|
||||
|
||||
Reference in New Issue
Block a user