david/librubberband
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

* Documentation update

Browse Source
This commit is contained in:
Chris Cannam
2007-12-07 22:11:11 +00:00
parent f39fd78ab5
commit 2b1693aa3f
2 changed files with 78 additions and 69 deletions
Download Patch File Download Diff File Expand all files Collapse all files

136
rubberband/RubberBandStretcher.h
View File

@@ -32,123 +32,125 @@ public:
* OR of the option flags. The default value (DefaultOptions) is * OR of the option flags. The default value (DefaultOptions) is
* intended to give good results in most situations. * intended to give good results in most situations.
* *
* 1. Flags prefixed OptionProcess determine how the timestretcher * 1. Flags prefixed \c OptionProcess determine how the timestretcher
* will be invoked. These options may not be changed after * will be invoked. These options may not be changed after
* construction. * construction.
* *
* OptionProcessOffline - Run the stretcher in offline mode. In * \li \c OptionProcessOffline - Run the stretcher in offline
* this mode the input data needs to be provided twice, once to * mode. In this mode the input data needs to be provided
* study(), which calculates a stretch profile for the audio, * twice, once to study(), which calculates a stretch profile
* and once to process(), which stretches it. * for the audio, and once to process(), which stretches it.
* *
* OptionProcessRealTime - Run the stretcher in real-time mode. * \li \c OptionProcessRealTime - Run the stretcher in real-time
* In this mode only process() should be called, and the * mode. In this mode only process() should be called, and the
* stretcher adjusts dynamically in response to the input audio. * stretcher adjusts dynamically in response to the input audio.
* *
* The Process setting is likely to depend on your architecture: * The Process setting is likely to depend on your architecture:
* non-real-time operation on seekable files: Offline; real-time * non-real-time operation on seekable files: Offline; real-time
* or streaming operation: RealTime. * or streaming operation: RealTime.
* *
* 2. Flags prefixed OptionStretch control the profile used for * 2. Flags prefixed \c OptionStretch control the profile used for
* variable timestretching. Rubber Band always adjusts the * variable timestretching. Rubber Band always adjusts the
* stretch profile to minimise stretching of busy broadband * stretch profile to minimise stretching of busy broadband
* transient sounds, but the degree to which it does so is * transient sounds, but the degree to which it does so is
* adjustable. These options may not be changed after * adjustable. These options may not be changed after
* construction. * construction.
* *
* OptionStretchElastic - Only meaningful in offline mode, and * \li \c OptionStretchElastic - Only meaningful in offline
* the default in that mode. The audio will be stretched at a * mode, and the default in that mode. The audio will be
* variable rate, aimed at preserving the quality of transient * stretched at a variable rate, aimed at preserving the quality
* sounds as much as possible. The timings of low activity * of transient sounds as much as possible. The timings of low
* regions between transients may be less exact than when the * activity regions between transients may be less exact than
* precise flag is set. * when the precise flag is set.
* *
* OptionStretchPrecise - Although still using a variable * \li \c OptionStretchPrecise - Although still using a variable
* stretch rate, the audio will be stretched so as to maintain * stretch rate, the audio will be stretched so as to maintain
* as close as possible to a linear stretch ratio throughout. * as close as possible to a linear stretch ratio throughout.
* Timing may be better than when using OptionStretchElastic, at * Timing may be better than when using \c OptionStretchElastic, at
* slight cost to the sound quality of transients. This setting * slight cost to the sound quality of transients. This setting
* is always used when running in real-time mode. * is always used when running in real-time mode.
* *
* 3. Flags prefixed OptionTransients control the component * 3. Flags prefixed \c OptionTransients control the component
* frequency phase-reset mechanism that may be used at transient * frequency phase-reset mechanism that may be used at transient
* points to provide clarity and realism to percussion and other * points to provide clarity and realism to percussion and other
* significant transient sounds. These options may be changed * significant transient sounds. These options may be changed
* after construction when running in real-time mode, but not when * after construction when running in real-time mode, but not when
* running in offline mode. * running in offline mode.
* *
* OptionTransientsCrisp - Reset component phases at the peak of * \li \c OptionTransientsCrisp - Reset component phases at the
* each transient (the start of a significant note or percussive * peak of each transient (the start of a significant note or
* event). This, the default setting, usually results in a * percussive event). This, the default setting, usually
* clear-sounding output; but it is not always consistent, and * results in a clear-sounding output; but it is not always
* may cause interruptions in stable sounds present at the same * consistent, and may cause interruptions in stable sounds
* time as transient events. * present at the same time as transient events.
* *
* OptionTransientsMixed - Reset component phases at the peak of * \li \c OptionTransientsMixed - Reset component phases at the
* each transient, outside a frequency range typical of musical * peak of each transient, outside a frequency range typical of
* fundamental frequencies. The results may be more regular for * musical fundamental frequencies. The results may be more
* mixed stable and percussive notes than OptionTransientsCrisp, * regular for mixed stable and percussive notes than
* but with a "phasier" sound. The balance may sound very good * \c OptionTransientsCrisp, but with a "phasier" sound. The
* for certain types of music and fairly bad for others. * balance may sound very good for certain types of music and
* fairly bad for others.
* *
* OptionTransientsSmooth - Do not reset component phases at any * \li \c OptionTransientsSmooth - Do not reset component phases
* point. The results will be smoother and more regular but may * at any point. The results will be smoother and more regular
* be less clear than with either of the other transients flags. * but may be less clear than with either of the other
* transients flags.
* *
* 4. Flags prefixed OptionPhase control the adjustment of * 4. Flags prefixed \c OptionPhase control the adjustment of
* component frequency phases from one analysis window to the next * component frequency phases from one analysis window to the next
* during non-transient segments. These options may be changed at * during non-transient segments. These options may be changed at
* any time. * any time.
* *
* OptionPhaseAdaptive - Lock the adjustments of phase for * \li \c OptionPhaseAdaptive - Lock the adjustments of phase
* frequencies close to peak frequencies to those of the peak, * for frequencies close to peak frequencies to those of the
* but reduce the degree of locking as the stretch ratio gets * peak, but reduce the degree of locking as the stretch ratio
* longer. This, the default setting, should give a good * gets longer. This, the default setting, should give a good
* balance between clarity and smoothness in most situations. * balance between clarity and smoothness in most situations.
* *
* OptionPhasePeakLocked - Lock the adjustments of phase for * \li \c OptionPhasePeakLocked - Lock the adjustments of phase
* frequencies close to peak frequencies to those of the peak. * for frequencies close to peak frequencies to those of the
* This should give a clear result in situations with relatively * peak. This should give a clear result in situations with
* low stretch ratios, but a relatively metallic sound at longer * relatively low stretch ratios, but a relatively metallic
* stretches. * sound at longer stretches.
* *
* OptionPhaseIndependent - Do not lock phase adjustments to * \li \c OptionPhaseIndependent - Do not lock phase adjustments
* peak frequencies. This usually results in a softer, phasier * to peak frequencies. This usually results in a softer,
* sound. * phasier sound.
* *
* 5. Options prefixed OptionThreading control the threading model * 5. Flags prefixed \c OptionThreading control the threading
* of the stretcher. These options may not be changed after * model of the stretcher. These options may not be changed after
* construction. * construction.
* *
* OptionThreadingAuto - Permit the stretcher to determine its * \li \c OptionThreadingAuto - Permit the stretcher to
* own threading model. Usually this means using one processing * determine its own threading model. Usually this means using
* thread per audio channel in offline mode if the stretcher is * one processing thread per audio channel in offline mode if
* able to determine that more than one CPU is available, and * the stretcher is able to determine that more than one CPU is
* one thread only in realtime mode. * available, and one thread only in realtime mode.
* *
* OptionThreadingNever - Never use more than one thread. * \li \c OptionThreadingNever - Never use more than one thread.
* *
* OptionThreadingAlways - Use multiple threads in any situation * \li \c OptionThreadingAlways - Use multiple threads in any
* where OptionThreadingAuto would do so, except omit the check * situation where \c OptionThreadingAuto would do so, except omit
* for multiple CPUs and instead assume it to be true. * the check for multiple CPUs and instead assume it to be true.
* *
* 6. Options prefixed OptionWindow control the window size for * 6. Flags prefixed \c OptionWindow control the window size for
* FFT processing. The window size actually used will depend on * FFT processing. The window size actually used will depend on
* many factors, but it can be influenced. These options may not * many factors, but it can be influenced. These options may not
* be changed after construction. * be changed after construction.
* *
* OptionWindowStandard - Use the default window size. The * \li \c OptionWindowStandard - Use the default window size.
* actual size will vary depending on other parameters. This * The actual size will vary depending on other parameters.
* option is expected to produce better results than the other * This option is expected to produce better results than the
* window options in most situations. * other window options in most situations.
* *
* OptionWindowShort - Use a shorter window. This may result in * \li \c OptionWindowShort - Use a shorter window. This may
* crisper sound for audio that depends strongly on its timing * result in crisper sound for audio that depends strongly on
* qualities. * its timing qualities.
* *
* OptionWindowLong - Use a longer window. This is likely to * \li \c OptionWindowLong - Use a longer window. This is
* result in a smoother sound at the expense of clarity and * likely to result in a smoother sound at the expense of
* timing. * clarity and timing.
*/ */
typedef int Options; typedef int Options;

9
rubberband/TimeStretcher.h
View File

@@ -20,6 +20,12 @@
namespace RubberBand namespace RubberBand
{ {
/**
* Base class for time stretchers. RubberBand currently provides only
* a single subclass implementation.
*
* @see RubberBandStretcher
*/
class TimeStretcher class TimeStretcher
{ {
public: public:
@@ -32,10 +38,11 @@ public:
virtual void reset() = 0; virtual void reset() = 0;
virtual void setTimeRatio(double ratio) = 0; virtual void setTimeRatio(double ratio) = 0;
virtual void setPitchScale(double scale) = 0;
virtual size_t getLatency() const = 0; virtual size_t getLatency() const = 0;
virtual void study(const float *const *input, size_t samples, bool final) = 0; virtual void study(const float *const *input, size_t samples, bool final) = 0;
virtual size_t getSamplesRequired() const = 0; // to cause processing to happen virtual size_t getSamplesRequired() const = 0;
virtual void process(const float *const *input, size_t samples, bool final) = 0; virtual void process(const float *const *input, size_t samples, bool final) = 0;
virtual int available() const = 0; virtual int available() const = 0;
virtual size_t retrieve(float *const *output, size_t samples) const = 0; virtual size_t retrieve(float *const *output, size_t samples) const = 0;