libs/rubberband/README

   1
   2 Rubber Band
   3 ===========
   4
   5 An audio time-stretching and pitch-shifting library and utility program.
   6
   7 Copyright 2007 Chris Cannam, cannam@all-day-breakfast.com.
   8
   9 Distributed under the GNU General Public License.
  10
  11 Rubber Band is a library and utility program that permits you to
  12 change the tempo and pitch of an audio recording independently of one
  13 another.
  14
  15
  16 Attractive features
  17 ~~~~~~~~~~~~~~~~~~~
  18
  19   * High quality results suitable for musical use
  20
  21     Rubber Band is a phase-vocoder-based frequency domain time
  22     stretcher with partial phase locking to peak frequencies and phase
  23     resynchronisation at noisy transients.  It is suitable for most
  24     musical uses with its default settings, and has a range of options
  25     for fine tuning.
  26
  27   * Real-time capable
  28
  29     In addition to the offline mode (for use in situations where all
  30     audio data is available beforehand), Rubber Band supports a true
  31     real-time, lock-free streaming mode, in which the time and pitch
  32     scaling ratios may be dynamically adjusted during use.
  33
  34   * Sample-accurate duration adjustment
  35
  36     In offline mode, Rubber Band ensures that the output has exactly
  37     the right number of samples for the given stretch ratio.  (In
  38     real-time mode Rubber Band aims to keep as closely as possible to
  39     the exact ratio, although this depends on the audio material
  40     itself.)
  41
  42   * Multiprocessor/multi-core support
  43
  44     Rubber Band's offline mode can take advantage of more than one
  45     processor core if available, when processing data with two or more
  46     audio channels.
  47
  48   * No job too big, or too small
  49
  50     Rubber Band is tuned so as to work well with the default settings
  51     for any stretch ratio, from tiny deviations from the original
  52     speed to very extreme stretches.
  53
  54   * Handy utilities included
  55
  56     The Rubber Band code includes a useful command-line time-stretch
  57     and pitch shift utility (called simply rubberband), two LADSPA
  58     pitch shifter plugins (Rubber Band Mono Pitch Shifter and Rubber
  59     Band Stereo Pitch Shifter), and a Vamp audio analysis plugin which
  60     may be used to inspect the stretch profile decisions Rubber Band
  61     is taking.
  62
  63   * Free Software
  64
  65     Rubber Band is Free Software published under the GNU General
  66     Public License.
  67
  68
  69 Limitations
  70 ~~~~~~~~~~~
  71
  72   * Not especially fast
  73
  74     The algorithm used by Rubber Band is very processor intensive, and
  75     Rubber Band is not the fastest implementation on earth.
  76
  77   * Not especially state of the art
  78
  79     Rubber Band employs well known algorithms which work well in many
  80     situations, but it isn't "cutting edge" in any interesting sense.
  81
  82   * Relatively complex
  83
  84     While the fundamental algorithms in Rubber Band are not especially
  85     complex, the implementation is complicated by the support for
  86     multiple processing modes, exact sample precision, threading, and
  87     other features that add to the flexibility of the API.
  88
  89
  90 Compiling Rubber Band
  91 ---------------------
  92
  93 Rubber Band is supplied with build scripts that have been tested on
  94 Linux platforms.  It is also possible to build Rubber Band on other
  95 platforms, including both POSIX platforms such as OS/X and non-POSIX
  96 platforms such as Win32.  There are some example Makefiles in the misc
  97 directory, but if you're using a proprietary platform and you get
  98 stuck I'm afraid you're on your own, unless you want to pay us...
  99
 100 To build Rubber Band you will also need libsndfile, libsamplerate,
 101 FFTW3, the Vamp plugin SDK, the LADSPA plugin header, the pthread
 102 library (except on Win32), and a C++ compiler.  The code has been
 103 tested with GCC 4.x and with the Intel C++ compiler.
 104
 105 Rubber Band comes with a simple autoconf script.  Run
 106
 107   $ ./configure
 108   $ make
 109
 110 to compile, and optionally
 111
 112   # make install
 113
 114 to install.
 115
 116
 117 Using the Rubber Band utility
 118 -----------------------------
 119
 120 The Rubber Band command-line utility builds as bin/rubberband.  The
 121 basic incantation is
 122
 123   $ rubberband -t <timeratio> -p <pitchratio> <infile.wav> <outfile.wav>
 124
 125 For example,
 126
 127   $ rubberband -t 1.5 -p 2.0 test.wav output.wav
 128
 129 stretches the file test.wav to 50% longer than its original duration,
 130 shifts it up in pitch by one octave, and writes the output to output.wav.
 131
 132 Several further options are available: run "rubberband -h" for help.
 133 In particular, different types of music may benefit from different
 134 "crispness" options (-c <n> where <n> is from 0 to 5).
 135
 136
 137 Using the Rubber Band library
 138 -----------------------------
 139
 140 The Rubber Band library has a public API that consists of one C++
 141 class, called RubberBandStretcher in the RubberBand namespace.  You
 142 should #include <rubberband/RubberBandStretcher.h> to use this class.
 143 There is extensive documentation in the class header.
 144
 145 The source code for the command-line utility (src/main.cpp) provides a
 146 good example of how to use Rubber Band in offline mode; the LADSPA
 147 pitch shifter plugin (src/ladspa/RubberBandPitchShifter.cpp) may be
 148 used as an example of Rubber Band in real-time mode.
 149
 150 IMPORTANT: Please ensure you have read and understood the licensing
 151 terms for Rubber Band before using it in another application.  This
 152 library is provided under the GNU General Public License, which means
 153 that any application that uses it must also be published under the GPL
 154 or a compatible license (i.e. with its full source code also available
 155 for modification and redistribution).  See the file COPYING for more
 156 details.  Alternative commercial and proprietary licensing terms are
 157 available; please contact the author if you are interested.
 158