/* -*- c-basic-offset: 4 indent-tabs-mode: nil -*- vi:set ts=8 sts=4 sw=4: */ /* Rubber Band An audio time-stretching and pitch-shifting library. Copyright 2007 Chris Cannam. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. See the file COPYING included with this distribution for more information. */ #ifndef _RUBBERBANDSTRETCHER_H_ #define _RUBBERBANDSTRETCHER_H_ #include "TimeStretcher.h" #include namespace RubberBand { class RubberBandStretcher : public TimeStretcher { public: /** * Processing options for the timestretcher. The preferred * options should normally be set in the constructor, as a bitwise * 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 * 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. * * 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 * 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. * * 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 * 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 * 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. * * 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. * * 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 * 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 * 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. * * 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 * construction. * * OptionThreadingAuto - Permit the stretcher to determine its * own threading model. Usually this means using one processing * thread per audio channel in offline mode, and one thread only * in realtime mode. * * OptionThreadingNone - Never use more than one thread. * * 6. Options prefixed 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. * * 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. */ typedef int Options; static const int OptionProcessOffline = 0x00000000; static const int OptionProcessRealTime = 0x00000001; static const int OptionStretchElastic = 0x00000000; static const int OptionStretchPrecise = 0x00000010; static const int OptionTransientsCrisp = 0x00000000; static const int OptionTransientsMixed = 0x00000100; static const int OptionTransientsSmooth = 0x00000200; static const int OptionPhaseAdaptive = 0x00000000; static const int OptionPhasePeakLocked = 0x00001000; static const int OptionPhaseIndependent = 0x00002000; static const int OptionThreadingAuto = 0x00000000; static const int OptionThreadingNone = 0x00010000; static const int OptionWindowStandard = 0x00000000; static const int OptionWindowShort = 0x00100000; static const int OptionWindowLong = 0x00200000; static const int DefaultOptions = 0x00000000; static const int PercussiveOptions = OptionWindowShort | \ OptionPhaseIndependent; /** * Construct a time-and-pitch-scaling object to run at the given * sample rate, with the given number of channels. Processing * options and the time and pitch scaling ratios may be provided. * The time and pitch ratios may be changed after construction, * but most of the options may not. See the option documentation * above for more details. */ RubberBandStretcher(size_t sampleRate, size_t channels, Options options = DefaultOptions, double initialTimeRatio = 1.0, double initialPitchScale = 1.0); virtual ~RubberBandStretcher(); virtual void reset(); virtual void setTimeRatio(double ratio); virtual void setPitchScale(double scale); virtual double getTimeRatio() const; virtual double getPitchScale() const; virtual size_t getLatency() const; virtual void setTransientsOption(Options options); virtual void setPhaseOption(Options options); virtual void setExpectedInputDuration(size_t samples); virtual void setMaxProcessSize(size_t samples); virtual size_t getSamplesRequired() const; // if samples == 0, input may be null virtual void study(const float *const *input, size_t samples, bool final); virtual void process(const float *const *input, size_t samples, bool final); virtual int available() const; // returns -1 if all data processed and nothing further will be available virtual size_t retrieve(float *const *output, size_t samples) const; virtual float getFrequencyCutoff(int n) const; virtual void setFrequencyCutoff(int n, float f); //!!! ideally, this stuff wouldn't be here... virtual size_t getInputIncrement() const; virtual std::vector getOutputIncrements() const; //!!! document particular meaning in RT mode virtual std::vector getPhaseResetCurve() const; //!!! document particular meaning in RT mode virtual std::vector getExactTimePoints() const; //!!! meaningless in RT mode virtual size_t getChannelCount() const; virtual void calculateStretch(); virtual void setDebugLevel(int level); static void setDefaultDebugLevel(int level); protected: class Impl; Impl *m_d; }; } #endif