From 2b1693aa3fe4c4c5ba26bc03386a623fdcde284b Mon Sep 17 00:00:00 2001 From: Chris Cannam Date: Fri, 7 Dec 2007 22:11:11 +0000 Subject: [PATCH] * Documentation update --- rubberband/RubberBandStretcher.h | 138 ++++++++++++++++--------------- rubberband/TimeStretcher.h | 9 +- 2 files changed, 78 insertions(+), 69 deletions(-) diff --git a/rubberband/RubberBandStretcher.h b/rubberband/RubberBandStretcher.h index 9c60a68..94f1e88 100644 --- a/rubberband/RubberBandStretcher.h +++ b/rubberband/RubberBandStretcher.h @@ -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; diff --git a/rubberband/TimeStretcher.h b/rubberband/TimeStretcher.h index 9e810df..bad916a 100644 --- a/rubberband/TimeStretcher.h +++ b/rubberband/TimeStretcher.h @@ -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;