cannam@95: cannam@95: Rubber Band cannam@95: =========== cannam@95: cannam@95: An audio time-stretching and pitch-shifting library and utility program. cannam@95: cannam@95: Written by Chris Cannam, chris.cannam@breakfastquay.com. cannam@95: Copyright 2007-2012 Particular Programs Ltd. cannam@95: cannam@95: Rubber Band is a library and utility program that permits changing the cannam@95: tempo and pitch of an audio recording independently of one another. cannam@95: cannam@95: See http://breakfastquay.com/rubberband/ for more information. cannam@95: cannam@95: cannam@95: Licence cannam@95: ======= cannam@95: cannam@95: Rubber Band is distributed under the GNU General Public License. See cannam@95: the file COPYING for more information. cannam@95: cannam@95: If you wish to distribute code using the Rubber Band Library under cannam@95: terms other than those of the GNU General Public License, you must cannam@95: obtain a commercial licence from us before doing so. In particular, cannam@95: you may not legally distribute through any Apple App Store unless you cannam@95: have a commercial licence. See http://breakfastquay.com/rubberband/ cannam@95: for licence terms. cannam@95: cannam@95: If you have obtained a valid commercial licence, your licence cannam@95: supersedes this README and the enclosed COPYING file and you may cannam@95: redistribute and/or modify Rubber Band under the terms described in cannam@95: that licence. Please refer to your licence agreement for more details. cannam@95: cannam@95: Note that Rubber Band may link with other GPL libraries or with cannam@95: proprietary libraries, depending on its build configuration. See the cannam@95: section "FFT and resampler selection" below. It is your responsibility cannam@95: to ensure that you redistribute only in accordance with the licence cannam@95: terms of any other libraries you may build with. cannam@95: cannam@95: cannam@95: Contents of this README cannam@95: ----------------------- cannam@95: cannam@95: 1. Code components cannam@95: 2. Using the Rubber Band command-line tool cannam@95: 3. Using the Rubber Band Library cannam@95: 4. Compiling Rubber Band cannam@95: a. FFT and resampler selection cannam@95: b. Other supported #defines cannam@95: c. GNU/POSIX systems and Makefiles cannam@95: d. OS/X and iOS cannam@95: e. Win32 and Visual Studio cannam@95: f. Android and Java cannam@95: 5. Copyright notes for bundled libraries cannam@95: cannam@95: cannam@95: 1. Code components cannam@95: ------------------ cannam@95: cannam@95: Rubber Band consists of: cannam@95: cannam@95: * The Rubber Band library code. This is the code that will normally cannam@95: be used by your applications. The headers for this are in the cannam@95: rubberband/ directory, and the source code is in src/. cannam@95: The Rubber Band library depends upon resampler and FFT code; see cannam@95: section 3a below for details. cannam@95: cannam@95: * The Rubber Band command-line tool. This is in main/main.cpp. cannam@95: This program uses the Rubber Band library and also requires libsndfile cannam@95: (http://www.mega-nerd.com/libsndfile/, licensed under the GNU Lesser cannam@95: General Public License) for audio file loading. cannam@95: cannam@95: * A pitch-shifter LADSPA audio effects plugin. This is in ladspa/. cannam@95: It requires the LADSPA SDK header ladspa.h (not included). cannam@95: cannam@95: * A Vamp audio analysis plugin which may be used to inspect the cannam@95: dynamic stretch ratios and other decisions taken by the Rubber Band cannam@95: library when in use. This is in vamp/. It requires the Vamp cannam@95: plugin SDK (http://www.vamp-plugins.org/develop.html) (not included). cannam@95: cannam@95: cannam@95: 2. Using the Rubber Band command-line tool cannam@95: ------------------------------------------ cannam@95: cannam@95: The Rubber Band command-line tool builds as bin/rubberband. The basic cannam@95: incantation is cannam@95: cannam@95: $ rubberband -t -p cannam@95: cannam@95: For example, cannam@95: cannam@95: $ rubberband -t 1.5 -p 2.0 test.wav output.wav cannam@95: cannam@95: stretches the file test.wav to 50% longer than its original duration, cannam@95: shifts it up in pitch by one octave, and writes the output to output.wav. cannam@95: cannam@95: Several further options are available: run "rubberband -h" for help. cannam@95: In particular, different types of music may benefit from different cannam@95: "crispness" options (-c where is from 0 to 6). cannam@95: cannam@95: cannam@95: 3. Using the Rubber Band library cannam@95: -------------------------------- cannam@95: cannam@95: The Rubber Band library has a public API that consists of one C++ cannam@95: class, called RubberBandStretcher in the RubberBand namespace. You cannam@95: should #include to use this class. cannam@95: There is extensive documentation in the class header. cannam@95: cannam@95: A header with C language bindings is also provided in cannam@95: . This is a wrapper around the C++ cannam@95: implementation, and as the implementation is the same, it also cannam@95: requires linkage against the C++ standard libraries. It is not yet cannam@95: documented separately from the C++ header. You should include only cannam@95: one of the two headers, not both. cannam@95: cannam@95: The source code for the command-line utility (main/main.cpp) provides cannam@95: a good example of how to use Rubber Band in offline mode; the LADSPA cannam@95: pitch shifter plugin (ladspa/RubberBandPitchShifter.cpp) may be used cannam@95: as an example of Rubber Band in real-time mode. cannam@95: cannam@95: IMPORTANT: Please ensure you have read and understood the licensing cannam@95: terms for Rubber Band before using it in your application. This cannam@95: library is provided under the GNU General Public License, which means cannam@95: that any application that uses it must also be published under the GPL cannam@95: or a compatible licence (i.e. with its full source code also available cannam@95: for modification and redistribution) unless you have separately cannam@95: acquired a commercial licence from the author. cannam@95: cannam@95: cannam@95: 4. Compiling Rubber Band cannam@95: ------------------------ cannam@95: cannam@95: 4a. FFT and resampler selection cannam@95: ------------------------------- cannam@95: cannam@95: Rubber Band requires additional library code for FFT calculation and cannam@95: resampling. Several libraries are supported. The selection is cannam@95: controlled using preprocessor flags at compile time, as detailed in cannam@95: the tables below. cannam@95: cannam@95: Flags that declare that you want to use an external library begin with cannam@95: HAVE_; flags that select from the bundled options begin with USE_. cannam@95: cannam@95: You must enable one resampler implementation and one FFT cannam@95: implementation. Do not enable more than one of either unless you know cannam@95: what you're doing. cannam@95: cannam@95: If you are building this software using one of the bundled library cannam@95: options (Speex or KissFFT), please be sure to review the terms for cannam@95: those libraries in src/speex/COPYING and src/kissfft/COPYING as cannam@95: applicable. cannam@95: cannam@95: FFT libraries supported cannam@95: ----------------------- cannam@95: cannam@95: Name Flags required Notes cannam@95: ---- -------------- ----- cannam@95: cannam@95: FFTW3 -DHAVE_FFTW GPL. cannam@95: cannam@95: Accelerate -DHAVE_VDSP Platform library on OS/X and iOS. cannam@95: cannam@95: Intel IPP -DHAVE_IPP Proprietary library, can only be used with cannam@95: Rubber Band commercial licence. Define cannam@95: USE_IPP_STATIC as well to build with static cannam@95: IPP libraries. cannam@95: cannam@95: KissFFT -DUSE_KISSFFT Bundled, can be used with GPL or commercial cannam@95: licence. Single-precision. Slower than the cannam@95: above options. cannam@95: cannam@95: Resampler libraries supported cannam@95: ----------------------------- cannam@95: cannam@95: Name Flags required Notes cannam@95: ---- -------------- ----- cannam@95: cannam@95: libsamplerate -DHAVE_LIBSAMPLERATE GPL. cannam@95: cannam@95: libresample -DHAVE_LIBRESAMPLE LGPL. cannam@95: cannam@95: Speex -DUSE_SPEEX Bundled, can be used with GPL or commercial cannam@95: licence. cannam@95: cannam@95: cannam@95: 4b. Other supported #defines cannam@95: ---------------------------- cannam@95: cannam@95: Other symbols you may define at compile time are as follows. (Usually cannam@95: the supplied build files will handle these for you.) cannam@95: cannam@95: -DLACK_BAD_ALLOC cannam@95: Define on systems lacking std::bad_alloc in the C++ library. cannam@95: cannam@95: -DLACK_POSIX_MEMALIGN cannam@95: Define on systems lacking posix_memalign. cannam@95: cannam@95: -DUSE_OWN_ALIGNED_MALLOC cannam@95: Define on systems lacking any aligned malloc implementation. cannam@95: cannam@95: -DLACK_SINCOS cannam@95: Define on systems lacking sincos(). cannam@95: cannam@95: -DNO_EXCEPTIONS cannam@95: Build without use of C++ exceptions. cannam@95: cannam@95: -DNO_THREADING cannam@95: Build without any multithread support. cannam@95: cannam@95: -DUSE_PTHREADS cannam@95: Use the pthreads library (required unless NO_THREADING or on Windows) cannam@95: cannam@95: -DPROCESS_SAMPLE_TYPE=float cannam@95: Select single precision for internal calculations. The default is cannam@95: double precision. Consider using for mobile architectures with cannam@95: slower double-precision support. cannam@95: cannam@95: -DUSE_POMMIER_MATHFUN cannam@95: Select the Julien Pommier implementations of trig functions for ARM cannam@95: NEON or x86 SSE architectures. These are usually faster but may be cannam@95: of lower precision than system implementations. Consider using this cannam@95: for mobile architectures. cannam@95: cannam@95: cannam@95: 4c. GNU/POSIX systems and Makefiles cannam@95: ----------------------------------- cannam@95: cannam@95: A GNU-style configure script is included for use on Linux and similar cannam@95: systems. cannam@95: cannam@95: Run ./configure, then adjust the generated Makefile according to your cannam@95: preference for FFT and resampler implementations. The default is to cannam@95: use FFTW3 and libsamplerate. cannam@95: cannam@95: The following Makefile targets are available: cannam@95: cannam@95: static -- build static libraries only cannam@95: dynamic -- build dynamic libraries only cannam@95: library -- build static and dynamic libraries only cannam@95: program -- build the command-line tool cannam@95: vamp -- build Vamp plugin cannam@95: ladspa -- build LADSPA plugin cannam@95: all -- build everything. cannam@95: cannam@95: The default target is "all". cannam@95: cannam@95: cannam@95: 4d. OS/X and iOS cannam@95: ---------------- cannam@95: cannam@95: A Makefile for OS/X is provided as Makefile.osx. cannam@95: cannam@95: Adjust the Makefile according to your preference for compiler and cannam@95: platform SDK, FFT and resampler implementations. The default is to cannam@95: use the Accelerate framework and the Speex resampler. cannam@95: cannam@95: The following Makefile targets are available: cannam@95: cannam@95: static -- build static libraries only cannam@95: dynamic -- build dynamic libraries only cannam@95: library -- build static and dynamic libraries only cannam@95: program -- build the command-line tool cannam@95: vamp -- build Vamp plugin cannam@95: ladspa -- build LADSPA plugin cannam@95: all -- build everything. cannam@95: cannam@95: The default target is to build the static and dynamic libraries and cannam@95: the command line tool. The sndfile library is required for the cannam@95: command line tool. cannam@95: cannam@95: If you prefer to add the Rubber Band library files to an existing cannam@95: build project instead of using the Makefile, the files in src/ (except cannam@95: for RubberBandStretcherJNI.cpp) and the API headers in rubberband/ cannam@95: should be all you need. cannam@95: cannam@95: Note that you cannot legally distribute applications using Rubber Band cannam@95: through the iPhone/iPad App Store or OS/X App Store unless you have a cannam@95: valid commercial licence. GPL code is not permitted in these stores. cannam@95: cannam@95: cannam@95: 4e. Win32 and Visual Studio cannam@95: --------------------------- cannam@95: cannam@95: Two Visual Studio 2005 projects are supplied. cannam@95: cannam@95: rubberband-library.vcproj builds the Rubber Band static libraries cannam@95: only. cannam@95: cannam@95: rubberband-program.vcproj builds the Rubber Band command-line tool cannam@95: only (requires the Rubber Band libraries, and libsndfile). cannam@95: cannam@95: You will need to adjust the project settings so as to set the compile cannam@95: flags according to your preference for FFT and resampler cannam@95: implementation, and set the include path and library path cannam@95: appropriately. The default is to use the bundled KissFFT and the cannam@95: Speex resampler. cannam@95: cannam@95: If you prefer to add the Rubber Band library files to an existing cannam@95: build project instead of using the supplied one, the files in src/ cannam@95: (except for RubberBandStretcherJNI.cpp) and the API headers in cannam@95: rubberband/ should be all you need. cannam@95: cannam@95: cannam@95: 4f. Android and Java cannam@95: -------------------- cannam@95: cannam@95: An Android NDK build file is provided as Android.mk. This includes cannam@95: compile definitions for a shared library built for ARM architectures cannam@95: which can be loaded from a Java application using the Java native cannam@95: interface (i.e. the Android NDK). cannam@95: cannam@95: The Java side of the interface can be found in cannam@95: com/breakfastquay/rubberband/RubberBandStretcher.java. cannam@95: cannam@95: The supplied .mk file uses KissFFT and the Speex resampler. cannam@95: cannam@95: cannam@95: 5. Copyright notes for bundled libraries cannam@95: ======================================== cannam@95: cannam@95: 5a. Speex cannam@95: --------- cannam@95: cannam@95: [files in src/speex] cannam@95: cannam@95: Copyright 2002-2007 Xiph.org Foundation cannam@95: Copyright 2002-2007 Jean-Marc Valin cannam@95: Copyright 2005-2007 Analog Devices Inc. cannam@95: Copyright 2005-2007 Commonwealth Scientific and Industrial Research cannam@95: Organisation (CSIRO) cannam@95: Copyright 1993, 2002, 2006 David Rowe cannam@95: Copyright 2003 EpicGames cannam@95: Copyright 1992-1994 Jutta Degener, Carsten Bormann cannam@95: cannam@95: Redistribution and use in source and binary forms, with or without cannam@95: modification, are permitted provided that the following conditions cannam@95: are met: cannam@95: cannam@95: - Redistributions of source code must retain the above copyright cannam@95: notice, this list of conditions and the following disclaimer. cannam@95: cannam@95: - Redistributions in binary form must reproduce the above copyright cannam@95: notice, this list of conditions and the following disclaimer in the cannam@95: documentation and/or other materials provided with the distribution. cannam@95: cannam@95: - Neither the name of the Xiph.org Foundation nor the names of its cannam@95: contributors may be used to endorse or promote products derived from cannam@95: this software without specific prior written permission. cannam@95: cannam@95: THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS cannam@95: ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT cannam@95: LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR cannam@95: A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR cannam@95: CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, cannam@95: EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, cannam@95: PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR cannam@95: PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF cannam@95: LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING cannam@95: NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS cannam@95: SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. cannam@95: cannam@95: cannam@95: 5b. KissFFT cannam@95: ----------- cannam@95: cannam@95: [files in src/kissfft] cannam@95: cannam@95: Copyright (c) 2003-2004 Mark Borgerding cannam@95: cannam@95: All rights reserved. cannam@95: cannam@95: Redistribution and use in source and binary forms, with or without cannam@95: modification, are permitted provided that the following conditions are cannam@95: met: cannam@95: cannam@95: * Redistributions of source code must retain the above copyright cannam@95: notice, this list of conditions and the following disclaimer. cannam@95: * Redistributions in binary form must reproduce the above cannam@95: copyright notice, this list of conditions and the following cannam@95: disclaimer in the documentation and/or other materials provided cannam@95: with the distribution. cannam@95: * Neither the author nor the names of any contributors may be used cannam@95: to endorse or promote products derived from this software cannam@95: without specific prior written permission. cannam@95: cannam@95: THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS cannam@95: "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT cannam@95: LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR cannam@95: A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT cannam@95: OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, cannam@95: SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT cannam@95: LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, cannam@95: DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY cannam@95: THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT cannam@95: (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE cannam@95: OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. cannam@95: cannam@95: cannam@95: 5c. Pommier math functions cannam@95: -------------------------- cannam@95: cannam@95: [files in src/pommier] cannam@95: cannam@95: Copyright (C) 2011 Julien Pommier cannam@95: cannam@95: This software is provided 'as-is', without any express or implied cannam@95: warranty. In no event will the authors be held liable for any damages cannam@95: arising from the use of this software. cannam@95: cannam@95: Permission is granted to anyone to use this software for any purpose, cannam@95: including commercial applications, and to alter it and redistribute it cannam@95: freely, subject to the following restrictions: cannam@95: cannam@95: 1. The origin of this software must not be misrepresented; you must not cannam@95: claim that you wrote the original software. If you use this software cannam@95: in a product, an acknowledgment in the product documentation would be cannam@95: appreciated but is not required. cannam@95: 2. Altered source versions must be plainly marked as such, and must not be cannam@95: misrepresented as being the original software. cannam@95: 3. This notice may not be removed or altered from any source distribution. cannam@95: cannam@95: cannam@95: 5d. float_cast cannam@95: -------------- cannam@95: cannam@95: [files in src/float_cast] cannam@95: cannam@95: Copyright (C) 2001 Erik de Castro Lopo cannam@95: cannam@95: Permission to use, copy, modify, distribute, and sell this file for any cannam@95: purpose is hereby granted without fee, provided that the above copyright cannam@95: and this permission notice appear in all copies. No representations are cannam@95: made about the suitability of this software for any purpose. It is cannam@95: provided "as is" without express or implied warranty. cannam@95: cannam@95: cannam@95: 5d. getopt cannam@95: ---------- cannam@95: cannam@95: [files in src/getopt, used by command-line tool on some platforms] cannam@95: cannam@95: Copyright (c) 2000 The NetBSD Foundation, Inc. cannam@95: All rights reserved. cannam@95: cannam@95: This code is derived from software contributed to The NetBSD Foundation cannam@95: by Dieter Baron and Thomas Klausner. cannam@95: cannam@95: Redistribution and use in source and binary forms, with or without cannam@95: modification, are permitted provided that the following conditions cannam@95: are met: cannam@95: 1. Redistributions of source code must retain the above copyright cannam@95: notice, this list of conditions and the following disclaimer. cannam@95: 2. Redistributions in binary form must reproduce the above copyright cannam@95: notice, this list of conditions and the following disclaimer in the cannam@95: documentation and/or other materials provided with the distribution. cannam@95: 3. All advertising materials mentioning features or use of this software cannam@95: must display the following acknowledgement: cannam@95: This product includes software developed by the NetBSD cannam@95: Foundation, Inc. and its contributors. cannam@95: 4. Neither the name of The NetBSD Foundation nor the names of its cannam@95: contributors may be used to endorse or promote products derived cannam@95: from this software without specific prior written permission. cannam@95: cannam@95: THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS cannam@95: ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED cannam@95: TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR cannam@95: PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS cannam@95: BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR cannam@95: CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF cannam@95: SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS cannam@95: INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN cannam@95: CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) cannam@95: ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE cannam@95: POSSIBILITY OF SUCH DAMAGE.