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

138
rubberband/RubberBandStretcher.h
View File

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

9
rubberband/TimeStretcher.h
View File

@@ -20,6 +20,12 @@
namespace RubberBand
{
/**
* Base class for time stretchers. RubberBand currently provides only
* a single subclass implementation.
*
* @see RubberBandStretcher
*/
class TimeStretcher
{
public:
@@ -32,10 +38,11 @@ public:
virtual void reset() = 0;
virtual void setTimeRatio(double ratio) = 0;
virtual void setPitchScale(double scale) = 0;
virtual size_t getLatency() const = 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 int available() const = 0;
virtual size_t retrieve(float *const *output, size_t samples) const = 0;