mirror of
https://github.com/RetroDECK/Duckstation.git
synced 2024-12-11 15:05:39 +00:00
349 lines
15 KiB
C
349 lines
15 KiB
C
|
//////////////////////////////////////////////////////////////////////////////
|
||
|
///
|
||
|
/// SoundTouch - main class for tempo/pitch/rate adjusting routines.
|
||
|
///
|
||
|
/// Notes:
|
||
|
/// - Initialize the SoundTouch object instance by setting up the sound stream
|
||
|
/// parameters with functions 'setSampleRate' and 'setChannels', then set
|
||
|
/// desired tempo/pitch/rate settings with the corresponding functions.
|
||
|
///
|
||
|
/// - The SoundTouch class behaves like a first-in-first-out pipeline: The
|
||
|
/// samples that are to be processed are fed into one of the pipe by calling
|
||
|
/// function 'putSamples', while the ready processed samples can be read
|
||
|
/// from the other end of the pipeline with function 'receiveSamples'.
|
||
|
///
|
||
|
/// - The SoundTouch processing classes require certain sized 'batches' of
|
||
|
/// samples in order to process the sound. For this reason the classes buffer
|
||
|
/// incoming samples until there are enough of samples available for
|
||
|
/// processing, then they carry out the processing step and consequently
|
||
|
/// make the processed samples available for outputting.
|
||
|
///
|
||
|
/// - For the above reason, the processing routines introduce a certain
|
||
|
/// 'latency' between the input and output, so that the samples input to
|
||
|
/// SoundTouch may not be immediately available in the output, and neither
|
||
|
/// the amount of outputtable samples may not immediately be in direct
|
||
|
/// relationship with the amount of previously input samples.
|
||
|
///
|
||
|
/// - The tempo/pitch/rate control parameters can be altered during processing.
|
||
|
/// Please notice though that they aren't currently protected by semaphores,
|
||
|
/// so in multi-thread application external semaphore protection may be
|
||
|
/// required.
|
||
|
///
|
||
|
/// - This class utilizes classes 'TDStretch' for tempo change (without modifying
|
||
|
/// pitch) and 'RateTransposer' for changing the playback rate (that is, both
|
||
|
/// tempo and pitch in the same ratio) of the sound. The third available control
|
||
|
/// 'pitch' (change pitch but maintain tempo) is produced by a combination of
|
||
|
/// combining the two other controls.
|
||
|
///
|
||
|
/// Author : Copyright (c) Olli Parviainen
|
||
|
/// Author e-mail : oparviai 'at' iki.fi
|
||
|
/// SoundTouch WWW: http://www.surina.net/soundtouch
|
||
|
///
|
||
|
////////////////////////////////////////////////////////////////////////////////
|
||
|
//
|
||
|
// License :
|
||
|
//
|
||
|
// SoundTouch audio processing library
|
||
|
// Copyright (c) Olli Parviainen
|
||
|
//
|
||
|
// This library is free software; you can redistribute it and/or
|
||
|
// modify it under the terms of the GNU Lesser General Public
|
||
|
// License as published by the Free Software Foundation; either
|
||
|
// version 2.1 of the License, or (at your option) any later version.
|
||
|
//
|
||
|
// This library is distributed in the hope that it will be useful,
|
||
|
// but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||
|
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
||
|
// Lesser General Public License for more details.
|
||
|
//
|
||
|
// You should have received a copy of the GNU Lesser General Public
|
||
|
// License along with this library; if not, write to the Free Software
|
||
|
// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
|
||
|
//
|
||
|
////////////////////////////////////////////////////////////////////////////////
|
||
|
|
||
|
#ifndef SoundTouch_H
|
||
|
#define SoundTouch_H
|
||
|
|
||
|
#include "FIFOSamplePipe.h"
|
||
|
#include "STTypes.h"
|
||
|
|
||
|
namespace soundtouch
|
||
|
{
|
||
|
|
||
|
/// Soundtouch library version string
|
||
|
#define SOUNDTOUCH_VERSION "2.3.1"
|
||
|
|
||
|
/// SoundTouch library version id
|
||
|
#define SOUNDTOUCH_VERSION_ID (20301)
|
||
|
|
||
|
//
|
||
|
// Available setting IDs for the 'setSetting' & 'get_setting' functions:
|
||
|
|
||
|
/// Enable/disable anti-alias filter in pitch transposer (0 = disable)
|
||
|
#define SETTING_USE_AA_FILTER 0
|
||
|
|
||
|
/// Pitch transposer anti-alias filter length (8 .. 128 taps, default = 32)
|
||
|
#define SETTING_AA_FILTER_LENGTH 1
|
||
|
|
||
|
/// Enable/disable quick seeking algorithm in tempo changer routine
|
||
|
/// (enabling quick seeking lowers CPU utilization but causes a minor sound
|
||
|
/// quality compromising)
|
||
|
#define SETTING_USE_QUICKSEEK 2
|
||
|
|
||
|
/// Time-stretch algorithm single processing sequence length in milliseconds. This determines
|
||
|
/// to how long sequences the original sound is chopped in the time-stretch algorithm.
|
||
|
/// See "STTypes.h" or README for more information.
|
||
|
#define SETTING_SEQUENCE_MS 3
|
||
|
|
||
|
/// Time-stretch algorithm seeking window length in milliseconds for algorithm that finds the
|
||
|
/// best possible overlapping location. This determines from how wide window the algorithm
|
||
|
/// may look for an optimal joining location when mixing the sound sequences back together.
|
||
|
/// See "STTypes.h" or README for more information.
|
||
|
#define SETTING_SEEKWINDOW_MS 4
|
||
|
|
||
|
/// Time-stretch algorithm overlap length in milliseconds. When the chopped sound sequences
|
||
|
/// are mixed back together, to form a continuous sound stream, this parameter defines over
|
||
|
/// how long period the two consecutive sequences are let to overlap each other.
|
||
|
/// See "STTypes.h" or README for more information.
|
||
|
#define SETTING_OVERLAP_MS 5
|
||
|
|
||
|
|
||
|
/// Call "getSetting" with this ID to query processing sequence size in samples.
|
||
|
/// This value gives approximate value of how many input samples you'll need to
|
||
|
/// feed into SoundTouch after initial buffering to get out a new batch of
|
||
|
/// output samples.
|
||
|
///
|
||
|
/// This value does not include initial buffering at beginning of a new processing
|
||
|
/// stream, use SETTING_INITIAL_LATENCY to get the initial buffering size.
|
||
|
///
|
||
|
/// Notices:
|
||
|
/// - This is read-only parameter, i.e. setSetting ignores this parameter
|
||
|
/// - This parameter value is not constant but change depending on
|
||
|
/// tempo/pitch/rate/samplerate settings.
|
||
|
#define SETTING_NOMINAL_INPUT_SEQUENCE 6
|
||
|
|
||
|
|
||
|
/// Call "getSetting" with this ID to query nominal average processing output
|
||
|
/// size in samples. This value tells approcimate value how many output samples
|
||
|
/// SoundTouch outputs once it does DSP processing run for a batch of input samples.
|
||
|
///
|
||
|
/// Notices:
|
||
|
/// - This is read-only parameter, i.e. setSetting ignores this parameter
|
||
|
/// - This parameter value is not constant but change depending on
|
||
|
/// tempo/pitch/rate/samplerate settings.
|
||
|
#define SETTING_NOMINAL_OUTPUT_SEQUENCE 7
|
||
|
|
||
|
|
||
|
/// Call "getSetting" with this ID to query initial processing latency, i.e.
|
||
|
/// approx. how many samples you'll need to enter to SoundTouch pipeline before
|
||
|
/// you can expect to get first batch of ready output samples out.
|
||
|
///
|
||
|
/// After the first output batch, you can then expect to get approx.
|
||
|
/// SETTING_NOMINAL_OUTPUT_SEQUENCE ready samples out for every
|
||
|
/// SETTING_NOMINAL_INPUT_SEQUENCE samples that you enter into SoundTouch.
|
||
|
///
|
||
|
/// Example:
|
||
|
/// processing with parameter -tempo=5
|
||
|
/// => initial latency = 5509 samples
|
||
|
/// input sequence = 4167 samples
|
||
|
/// output sequence = 3969 samples
|
||
|
///
|
||
|
/// Accordingly, you can expect to feed in approx. 5509 samples at beginning of
|
||
|
/// the stream, and then you'll get out the first 3969 samples. After that, for
|
||
|
/// every approx. 4167 samples that you'll put in, you'll receive again approx.
|
||
|
/// 3969 samples out.
|
||
|
///
|
||
|
/// This also means that average latency during stream processing is
|
||
|
/// INITIAL_LATENCY-OUTPUT_SEQUENCE/2, in the above example case 5509-3969/2
|
||
|
/// = 3524 samples
|
||
|
///
|
||
|
/// Notices:
|
||
|
/// - This is read-only parameter, i.e. setSetting ignores this parameter
|
||
|
/// - This parameter value is not constant but change depending on
|
||
|
/// tempo/pitch/rate/samplerate settings.
|
||
|
#define SETTING_INITIAL_LATENCY 8
|
||
|
|
||
|
|
||
|
class SoundTouch : public FIFOProcessor
|
||
|
{
|
||
|
private:
|
||
|
/// Rate transposer class instance
|
||
|
class RateTransposer *pRateTransposer;
|
||
|
|
||
|
/// Time-stretch class instance
|
||
|
class TDStretch *pTDStretch;
|
||
|
|
||
|
/// Virtual pitch parameter. Effective rate & tempo are calculated from these parameters.
|
||
|
double virtualRate;
|
||
|
|
||
|
/// Virtual pitch parameter. Effective rate & tempo are calculated from these parameters.
|
||
|
double virtualTempo;
|
||
|
|
||
|
/// Virtual pitch parameter. Effective rate & tempo are calculated from these parameters.
|
||
|
double virtualPitch;
|
||
|
|
||
|
/// Flag: Has sample rate been set?
|
||
|
bool bSrateSet;
|
||
|
|
||
|
/// Accumulator for how many samples in total will be expected as output vs. samples put in,
|
||
|
/// considering current processing settings.
|
||
|
double samplesExpectedOut;
|
||
|
|
||
|
/// Accumulator for how many samples in total have been read out from the processing so far
|
||
|
long samplesOutput;
|
||
|
|
||
|
/// Calculates effective rate & tempo valuescfrom 'virtualRate', 'virtualTempo' and
|
||
|
/// 'virtualPitch' parameters.
|
||
|
void calcEffectiveRateAndTempo();
|
||
|
|
||
|
protected :
|
||
|
/// Number of channels
|
||
|
uint channels;
|
||
|
|
||
|
/// Effective 'rate' value calculated from 'virtualRate', 'virtualTempo' and 'virtualPitch'
|
||
|
double rate;
|
||
|
|
||
|
/// Effective 'tempo' value calculated from 'virtualRate', 'virtualTempo' and 'virtualPitch'
|
||
|
double tempo;
|
||
|
|
||
|
public:
|
||
|
SoundTouch();
|
||
|
virtual ~SoundTouch() override;
|
||
|
|
||
|
/// Get SoundTouch library version string
|
||
|
static const char *getVersionString();
|
||
|
|
||
|
/// Get SoundTouch library version Id
|
||
|
static uint getVersionId();
|
||
|
|
||
|
/// Sets new rate control value. Normal rate = 1.0, smaller values
|
||
|
/// represent slower rate, larger faster rates.
|
||
|
void setRate(double newRate);
|
||
|
|
||
|
/// Sets new tempo control value. Normal tempo = 1.0, smaller values
|
||
|
/// represent slower tempo, larger faster tempo.
|
||
|
void setTempo(double newTempo);
|
||
|
|
||
|
/// Sets new rate control value as a difference in percents compared
|
||
|
/// to the original rate (-50 .. +100 %)
|
||
|
void setRateChange(double newRate);
|
||
|
|
||
|
/// Sets new tempo control value as a difference in percents compared
|
||
|
/// to the original tempo (-50 .. +100 %)
|
||
|
void setTempoChange(double newTempo);
|
||
|
|
||
|
/// Sets new pitch control value. Original pitch = 1.0, smaller values
|
||
|
/// represent lower pitches, larger values higher pitch.
|
||
|
void setPitch(double newPitch);
|
||
|
|
||
|
/// Sets pitch change in octaves compared to the original pitch
|
||
|
/// (-1.00 .. +1.00)
|
||
|
void setPitchOctaves(double newPitch);
|
||
|
|
||
|
/// Sets pitch change in semi-tones compared to the original pitch
|
||
|
/// (-12 .. +12)
|
||
|
void setPitchSemiTones(int newPitch);
|
||
|
void setPitchSemiTones(double newPitch);
|
||
|
|
||
|
/// Sets the number of channels, 1 = mono, 2 = stereo
|
||
|
void setChannels(uint numChannels);
|
||
|
|
||
|
/// Sets sample rate.
|
||
|
void setSampleRate(uint srate);
|
||
|
|
||
|
/// Get ratio between input and output audio durations, useful for calculating
|
||
|
/// processed output duration: if you'll process a stream of N samples, then
|
||
|
/// you can expect to get out N * getInputOutputSampleRatio() samples.
|
||
|
///
|
||
|
/// This ratio will give accurate target duration ratio for a full audio track,
|
||
|
/// given that the the whole track is processed with same processing parameters.
|
||
|
///
|
||
|
/// If this ratio is applied to calculate intermediate offsets inside a processing
|
||
|
/// stream, then this ratio is approximate and can deviate +- some tens of milliseconds
|
||
|
/// from ideal offset, yet by end of the audio stream the duration ratio will become
|
||
|
/// exact.
|
||
|
///
|
||
|
/// Example: if processing with parameters "-tempo=15 -pitch=-3", the function
|
||
|
/// will return value 0.8695652... Now, if processing an audio stream whose duration
|
||
|
/// is exactly one million audio samples, then you can expect the processed
|
||
|
/// output duration be 0.869565 * 1000000 = 869565 samples.
|
||
|
double getInputOutputSampleRatio();
|
||
|
|
||
|
/// Flushes the last samples from the processing pipeline to the output.
|
||
|
/// Clears also the internal processing buffers.
|
||
|
//
|
||
|
/// Note: This function is meant for extracting the last samples of a sound
|
||
|
/// stream. This function may introduce additional blank samples in the end
|
||
|
/// of the sound stream, and thus it's not recommended to call this function
|
||
|
/// in the middle of a sound stream.
|
||
|
void flush();
|
||
|
|
||
|
/// Adds 'numSamples' pcs of samples from the 'samples' memory position into
|
||
|
/// the input of the object. Notice that sample rate _has_to_ be set before
|
||
|
/// calling this function, otherwise throws a runtime_error exception.
|
||
|
virtual void putSamples(
|
||
|
const SAMPLETYPE *samples, ///< Pointer to sample buffer.
|
||
|
uint numSamples ///< Number of samples in buffer. Notice
|
||
|
///< that in case of stereo-sound a single sample
|
||
|
///< contains data for both channels.
|
||
|
) override;
|
||
|
|
||
|
/// Output samples from beginning of the sample buffer. Copies requested samples to
|
||
|
/// output buffer and removes them from the sample buffer. If there are less than
|
||
|
/// 'numsample' samples in the buffer, returns all that available.
|
||
|
///
|
||
|
/// \return Number of samples returned.
|
||
|
virtual uint receiveSamples(SAMPLETYPE *output, ///< Buffer where to copy output samples.
|
||
|
uint maxSamples ///< How many samples to receive at max.
|
||
|
) override;
|
||
|
|
||
|
/// Adjusts book-keeping so that given number of samples are removed from beginning of the
|
||
|
/// sample buffer without copying them anywhere.
|
||
|
///
|
||
|
/// Used to reduce the number of samples in the buffer when accessing the sample buffer directly
|
||
|
/// with 'ptrBegin' function.
|
||
|
virtual uint receiveSamples(uint maxSamples ///< Remove this many samples from the beginning of pipe.
|
||
|
) override;
|
||
|
|
||
|
/// Clears all the samples in the object's output and internal processing
|
||
|
/// buffers.
|
||
|
virtual void clear() override;
|
||
|
|
||
|
/// Changes a setting controlling the processing system behaviour. See the
|
||
|
/// 'SETTING_...' defines for available setting ID's.
|
||
|
///
|
||
|
/// \return 'true' if the setting was successfully changed
|
||
|
bool setSetting(int settingId, ///< Setting ID number. see SETTING_... defines.
|
||
|
int value ///< New setting value.
|
||
|
);
|
||
|
|
||
|
/// Reads a setting controlling the processing system behaviour. See the
|
||
|
/// 'SETTING_...' defines for available setting ID's.
|
||
|
///
|
||
|
/// \return the setting value.
|
||
|
int getSetting(int settingId ///< Setting ID number, see SETTING_... defines.
|
||
|
) const;
|
||
|
|
||
|
/// Returns number of samples currently unprocessed.
|
||
|
virtual uint numUnprocessedSamples() const;
|
||
|
|
||
|
/// Return number of channels
|
||
|
uint numChannels() const
|
||
|
{
|
||
|
return channels;
|
||
|
}
|
||
|
|
||
|
/// Other handy functions that are implemented in the ancestor classes (see
|
||
|
/// classes 'FIFOProcessor' and 'FIFOSamplePipe')
|
||
|
///
|
||
|
/// - receiveSamples() : Use this function to receive 'ready' processed samples from SoundTouch.
|
||
|
/// - numSamples() : Get number of 'ready' samples that can be received with
|
||
|
/// function 'receiveSamples()'
|
||
|
/// - isEmpty() : Returns nonzero if there aren't any 'ready' samples.
|
||
|
/// - clear() : Clears all samples from ready/processing buffers.
|
||
|
};
|
||
|
|
||
|
}
|
||
|
#endif
|