A class that reduces the level of sound above a certain threshold. More...

#include <omSoundCompressor.h>

Inheritance diagram for om::sound::filters::Compressor:

Public Member Functions
	Compressor ()
	Create a new compressor with the default compression parameters. More...

	Compressor (Gain threshold, Float ratio, Float attack, Float release)
	Create a new compressor with specified linear threshold, ratio, attack, and release. More...

Gain	getInputGain () const
	Return the current linear input gain factor of this compressor. More...

Gain	getInputGainDB () const
	Return the current input gain factor in decibels of this compressor. More...

void	setInputGain (Gain newInputGain)
	Set the target linear input gain for compressor. More...

void	setInputGainDB (Gain newDBInputGain)
	Set the target input gain in decibels for this compressor. More...

Gain	getOutputGain () const
	Return the current linear output gain factor of this compressor. More...

Gain	getOutputGainDB () const
	Return the current output gain factor in decibels of this compressor. More...

void	setOutputGain (Gain newOutputGain)
	Set the target linear output gain for this compressor. More...

void	setOutputGainDB (Gain newDBOutputGain)
	Set the target output gain in decibels for this compressor. More...

Gain	getMix () const
	Return the ratio of input signal to compressed signal sent to the output of the compressor. More...

void	setMix (Gain newMix)
	Set the ratio of input signal to compressed signal sent to the output of the compressor. More...

Gain	getThreshold () const
	Return the linear full-scale value above which the compressor applies gain reduction. More...

Gain	getThresholdDB () const
	Return the logarithmic full-scale value above which the compressor applies gain reduction. More...

void	setThreshold (Gain newThreshold)
	Set the linear full-scale value above which the compressor applies gain reduction. More...

void	setThresholdDB (Gain newThresholdDB)
	Set the logarithmic full-scale value above which the compressor applies gain reduction. More...

Float	getRatio () const
	Return the compression ratio that the compressor is using. More...

void	setRatio (Float newRatio)
	Set the compression ratio that the compressor is using. More...

Gain	getKnee () const
	Return the knee radius of this compressor in decibels. More...

void	setKnee (Gain newKnee)
	Set the knee radius of this compressor in decibels. More...

Float	getAttack () const
	Return the attack of this compressor in seconds. More...

void	setAttack (Float newAttack)
	Set the attack of this compressor in seconds. More...

Float	getRelease () const
	Return the release of this compressor in seconds. More...

void	setRelease (Float newRelease)
	Set the release of this compressor in seconds. More...

Float	getRMSTime () const
	Return the RMS averaging time for the compressor, expressed in seconds. More...

void	setRMSTime (Float newRMSTime)
	Set the RMS averaging time for the compressor, expressed in seconds. More...

Bool	getChannelsAreLinked () const
	Return whether or not all channels in the compressor are linked together. More...

void	setChannelsAreLinked (Bool newChannelsAreLinked)
	Set whether or not all channels in the compressor are linked together. More...

Gain	getGainReductionDB () const
	Return the current gain reduction of the compressor in decibels. More...

Gain	getGainReduction () const
	Return the current gain reduction of the compressor on a linear scale. More...

Gain	evaluateTransferFunction (Gain input) const
	Evaluate the transfer function of the compressor for an envelope with the specified amplitude. More...

Gain	evaluateTransferFunctionDB (Gain input) const
	Evaluate the transfer function of the compressor for an envelope with the specified amplitude. More...

virtual UTF8String	getInputName (Index inputIndex) const
	Return a human-readable name of the compressor input at the specified index. More...

virtual UTF8String	getName () const
	Return a human-readable name for this compressor. More...

virtual UTF8String	getManufacturer () const
	Return the manufacturer name of this compressor. More...

virtual FilterVersion	getVersion () const
	Return an object representing the version of this compressor. More...

virtual FilterCategory	getCategory () const
	Return an object that describes the category of effect that this filter implements. More...

virtual Bool	allowsInPlaceProcessing () const
	Return whether or not this compressor can process audio data in-place. More...

virtual Size	getParameterCount () const
	Return the total number of generic accessible parameters this filter has. More...

virtual Bool	getParameterInfo (Index parameterIndex, FilterParameterInfo &info) const
	Get information about the filter parameter at the specified index. More...

Public Member Functions inherited from om::sound::filters::SoundFilter
virtual	~SoundFilter ()
	Destroy this sound filter object. More...

SoundResult	read (SoundBuffer &outputBuffer, Size numSamples)
	Fill the specified output buffer with the requested number of samples, based on internal filter state. More...

SoundResult	read (SoundFrame &outputFrame, Size numSamples)
	Fill the specified output frame with the requested number of samples, based on internal filter state. More...

SoundResult	write (const SoundBuffer &inputBuffer, Size numSamples)
	Process the specified input buffer samples and do something with them. More...

SoundResult	write (const SoundFrame &inputFrame, Size numSamples)
	Process the specified input frame samples and do something with them. More...

SoundResult	process (const SoundBuffer &inputBuffer, SoundBuffer &outputBuffer, Size numSamples)
	Apply this filter to the specified input buffer data, placing the result in the output buffer. More...

SoundResult	process (const SoundBuffer &inputBuffer, SoundFrame &outputFrame, Size numSamples)
	Apply this filter to the specified input buffer data, placing the result in the output frame. More...

SoundResult	process (const SoundFrame &inputFrame, SoundFrame &outputFrame, Size numSamples)
	Apply this filter to the specified input frame data, placing the result in the output frame. More...

SoundResult	process (const SoundFrame &inputBuffer, SoundBuffer &outputBuffer, Size numSamples)
	Apply this filter to the specified input frame data, placing the result in the output buffer. More...

void	reset ()
	Signal to the filter that the audio stream is restarting. More...

UInt64	getFrameIndex () const
	Return the index of the next frame to be processed (or the current one if currently processing). More...

Size	getInputCount () const
	Return the current number of audio inputs that this filter has. More...

Size	getOutputCount () const
	Return the current number of audio outputs that this filter has. More...

virtual UTF8String	getOutputName (Index outputIndex) const
	Return a human-readable name of the filter audio output at the specified index. More...

Size	getMIDIInputCount () const
	Return the current number of MIDI inputs that this filter has. More...

virtual UTF8String	getMIDIInputName (Index inputIndex) const
	Return a human-readable name of the filter MIDI input at the specified index. More...

Size	getMIDIOutputCount () const
	Return the current number of MIDI outputs that this filter has. More...

virtual UTF8String	getMIDIOutputName (Index outputIndex) const
	Return a human-readable name of the filter MIDI output at the specified index. More...

virtual Time	getLatency () const
	Return a Time value indicating the latency of this sound filter in seconds. More...

virtual Bool	getParameterIndex (const UTF8String &parameterName, Index &parameterIndex) const
	Query the index of the parameter with the specified name. More...

virtual Bool	getParameterValueName (Index parameterIndex, const FilterParameter &value, UTF8String &name) const
	Get any special name associated with the specified value of an indexed parameter. More...

Bool	getParameter (Index parameterIndex, FilterParameter &value) const
	Place the value of the parameter at the specified index in the output parameter. More...

Bool	getParameter (Index parameterIndex, Bool &value) const
	Place the value of the parameter at the specified index in the output parameter. More...

Bool	getParameter (Index parameterIndex, Int64 &value) const
	Place the value of the parameter at the specified index in the output parameter. More...

Bool	getParameter (Index parameterIndex, Float32 &value) const
	Place the value of the parameter at the specified index in the output parameter. More...

Bool	getParameter (Index parameterIndex, Float64 &value) const
	Place the value of the parameter at the specified index in the output parameter. More...

template<typename ParameterType >
Bool	getParameter (const UTF8String &name, ParameterType &value) const
	Place the value of the parameter with the specified name in the output parameter. More...

template<typename ParameterType >
Bool	getParameter (const char *name, ParameterType &value) const
	Place the value of the parameter with the specified name in the output parameter. More...

Bool	setParameter (Index parameterIndex, const FilterParameter &value)
	Attempt to set the parameter value at the specified index. More...

Bool	setParameter (Index parameterIndex, Bool value)
	Attempt to set the parameter value at the specified index. More...

Bool	setParameter (Index parameterIndex, Int64 value)
	Attempt to set the parameter value at the specified index. More...

Bool	setParameter (Index parameterIndex, Float32 value)
	Attempt to set the parameter value at the specified index. More...

Bool	setParameter (Index parameterIndex, Float64 value)
	Attempt to set the parameter value at the specified index. More...

template<typename ParameterType >
Bool	setParameter (const UTF8String &name, ParameterType value)
	Attempt to set the parameter value with the specified name. More...

template<typename ParameterType >
Bool	setParameter (const char *name, ParameterType value)
	Attempt to set the parameter value with the specified name. More...

virtual Bool	writeState (DataOutputStream &stream) const
	Write the current state of this sound filter to a data output stream. More...

virtual Bool	readState (DataInputStream &stream)
	Read a previously saved filter state from the specified data input stream and replace the filter's state. More...

virtual Size	getPresetCount () const
	Return the number of standard configuration presets that this sound filter has. More...

virtual Bool	getPreset (Index presetIndex, FilterPreset &preset) const
	Get the standard preset for this sound filter with the specified index. More...

Bool	getIsSynchronized () const
	Return whether or not this sound filter performs thread synchronization. More...

void	setIsSynchronized (Bool newIsSynchronized)
	Set whether or not this sound filter performs thread synchronization. More...

Static Public Attributes
static const UTF8String	NAME
	A string indicating the human-readable name of this compressor. More...

static const UTF8String	MANUFACTURER
	A string indicating the manufacturer name of this compressor. More...

static const FilterVersion	VERSION
	An object indicating the version of this compressor. More...

Static Public Attributes inherited from om::sound::filters::SoundFilter
static const om::resources::ResourceType	RESOURCE_TYPE
	The resource type for a sound filter. More...

Additional Inherited Members
Static Public Member Functions inherited from om::sound::filters::SoundFilter
static Size	getMaximumNumberOfInputs ()
	Return the maximum number of audio inputs that a SoundFilter can support. More...

static Size	getMaximumNumberOfOutputs ()
	Return the maximum number of audio outputs that a SoundFilter can support. More...

static Size	getMaximumNumberOfMIDIInputs ()
	Return the maximum number of MIDI inputs that a SoundFilter can support. More...

static Size	getMaximumNumberOfMIDIOutputs ()
	Return the maximum number of MIDI outputs that a SoundFilter can support. More...

Protected Member Functions inherited from om::sound::filters::SoundFilter
	SoundFilter ()
	Create a new sound filter with 1 audio input and output, and no MIDI inputs or outputs. More...

	SoundFilter (Size numInputs, Size numOutputs)
	Create a new sound filter with the specified number of audio inputs and outputs. More...

	SoundFilter (Size numInputs, Size numOutputs, Size numMIDIInputs, Size numMIDIOutputs)
	Create a new sound filter with the specified number of audio inputs and outputs. More...

void	setInputCount (Size newNumInputs)
	Set the number of inputs that this filter should have. More...

void	setOutputCount (Size newNumOutputs)
	Set the number of outputs that this filter should have. More...

void	setMIDIInputCount (Size newNumMIDIInputs)
	Set the number of MIDI inputs that this filter should have. More...

void	setMIDIOutputCount (Size newNumMIDIOutputs)
	Set the number of MIDI outputs that this filter should have. More...

Bool	isFirstFrame () const
	Return whether or not the filter's next frame to be processed is also its first frame. More...

void	lockMutex () const
	Acquire a mutex which handles subclass rendering parameter synchronization. More...

void	unlockMutex () const
	Release a mutex which handles subclass rendering parameter synchronization. More...

Detailed Description

A class that reduces the level of sound above a certain threshold.

This compressor class uses an arbitrary-length RMS peak sensing function to determine the envelope level at each sample. If the envelope is above a user-defined threshold, the compressor applies gain reduction to the sound at the compressor's logarithmic compression ratio. The compressor also has a variable-hardness knee which allows the user to smooth the transition from compressed to non- compressed audio.

This compressor can also be used as a limiter by setting the ratio to be equal to positive infinity.

Constructor & Destructor Documentation

om::sound::filters::Compressor::Compressor ( )

Create a new compressor with the default compression parameters.

These are - threshold: -6dB, ratio: 2:1, knee: 0dB, attack: 15ms, release: 50ms, input gain: 0dB, output gain: 0dB, RMS time of 0 seconds (peak detection), with unlinked channels.

om::sound::filters::Compressor::Compressor	(	Gain	threshold,
		Float	ratio,
		Float	attack,
		Float	release
	)

Create a new compressor with specified linear threshold, ratio, attack, and release.

This compressor uses peak-sensing detection (RMS time of 0), and has unlinked channels. The compressor has the default knee of 0dB. The input and output gains of the compressor are 0dB. All gain and threshold values are specified on a linear scale.

Member Function Documentation

Gain om::sound::filters::Compressor::getInputGain ( ) const

inline

Return the current linear input gain factor of this compressor.

This is the gain applied to the input signal before being sent to the compressor. This allows the user to scale the input to match the compressor without having to change the compressor threshold.

Gain om::sound::filters::Compressor::getInputGainDB ( ) const

inline

Return the current input gain factor in decibels of this compressor.

This is the gain applied to the input signal before being sent to the compressor. This allows the user to scale the input to match the compressor without having to change the compressor threshold.

void om::sound::filters::Compressor::setInputGain ( Gain newInputGain )

inline

Set the target linear input gain for compressor.

This is the gain applied to the input signal before being sent to the compressor. This allows the user to scale the input to match the compressor without having to change the compressor threshold.

void om::sound::filters::Compressor::setInputGainDB ( Gain newDBInputGain )

inline

Set the target input gain in decibels for this compressor.

This is the gain applied to the input signal before being sent to the compressor. This allows the user to scale the input to match the compressor without having to change the compressor threshold.

Gain om::sound::filters::Compressor::getOutputGain ( ) const

inline

Return the current linear output gain factor of this compressor.

This is the gain applied to the signal after being sent to the compressor. This value is used to apply make-up gain to the signal after is has been compressed.

Gain om::sound::filters::Compressor::getOutputGainDB ( ) const

inline

Return the current output gain factor in decibels of this compressor.

This is the gain applied to the signal after being sent to the compressor. This value is used to apply make-up gain to the signal after is has been compressed.

void om::sound::filters::Compressor::setOutputGain ( Gain newOutputGain )

inline

Set the target linear output gain for this compressor.

This is the gain applied to the signal after being sent to the compressor. This value is used to apply make-up gain to the signal after is has been compressed.

void om::sound::filters::Compressor::setOutputGainDB ( Gain newDBOutputGain )

inline

Set the target output gain in decibels for this compressor.

This is the gain applied to the signal after being sent to the compressor. This value is used to apply make-up gain to the signal after is has been compressed.

Gain om::sound::filters::Compressor::getMix ( ) const

inline

Return the ratio of input signal to compressed signal sent to the output of the compressor.

Valid mix values are in the range [0,1]. A mix value of 1 indicates that only the output of the compressor should be heard at the output, while a value of 0 indicates that only the input of the compressor should be heard at the output. A value of 0.5 indicates that both should be mixed together equally at -6dB.

void om::sound::filters::Compressor::setMix ( Gain newMix )

inline

Set the ratio of input signal to compressed signal sent to the output of the compressor.

Valid mix values are in the range [0,1]. A mix value of 1 indicates that only the output of the compressor should be heard at the output, while a value of 0 indicates that only the input of the compressor should be heard at the output. A value of 0.5 indicates that both should be mixed together equally at -6dB.

The new mix value is clamped to the valid range of [0,1].

Gain om::sound::filters::Compressor::getThreshold ( ) const

inline

Return the linear full-scale value above which the compressor applies gain reduction.

Gain om::sound::filters::Compressor::getThresholdDB ( ) const

inline

Return the logarithmic full-scale value above which the compressor applies gain reduction.

void om::sound::filters::Compressor::setThreshold ( Gain newThreshold )

inline

Set the linear full-scale value above which the compressor applies gain reduction.

The value is clamped to the valid range of [0,infinity] before being stored.

void om::sound::filters::Compressor::setThresholdDB ( Gain newThresholdDB )

inline

Set the logarithmic full-scale value above which the compressor applies gain reduction.

Float om::sound::filters::Compressor::getRatio ( ) const

inline

Return the compression ratio that the compressor is using.

This value is expressed as a ratio of input to output gain above the compression threshold, expressed in decibels. For instance, a ratio of 2 indicates that for ever 2 decibels that the signal is over the threshold, the output signal will only be 1 decibel over the threshold. Thus, higher ratios indicate harder compression. A ratio of +infinity is equivalent to a brickwall limiter.

void om::sound::filters::Compressor::setRatio ( Float newRatio )

inline

Set the compression ratio that the compressor is using.

This value is expressed as a ratio of input to output gain above the compression threshold, expressed in decibels. For instance, a ratio of 2 indicates that for ever 2 decibels that the signal is over the threshold, the output signal will only be 1 decibel over the threshold. Thus, higher ratios indicate harder compression. A ratio of +infinity is equivalent to a brickwall limiter.

The new ratio is clamped to the range of [1,+infinity].

Gain om::sound::filters::Compressor::getKnee ( ) const

inline

Return the knee radius of this compressor in decibels.

This is the amount below the compressor's threshold at which the compressor first starts compressing, as well as the amount above the compressor's threshold where the actual compressor ratio starts to be used. A higher knee will result in a compressor that starts to apply gain reduction to envelopes that approach the threshold, resulting in a smoother transition from no gain reduction to full gain reduction.

void om::sound::filters::Compressor::setKnee ( Gain newKnee )

inline

Set the knee radius of this compressor in decibels.

This is the amount below the compressor's threshold at which the compressor first starts compressing, as well as the amount above the compressor's threshold where the actual compressor ratio starts to be used. A higher knee will result in a compressor that starts to apply gain reduction to envelopes that approach the threshold, resulting in a smoother transition from no gain reduction to full gain reduction.

The new knee value is clamped to the valid range of [0,+infinity].

Float om::sound::filters::Compressor::getAttack ( ) const

inline

Return the attack of this compressor in seconds.

This value indicates the time in seconds that it takes for the compressor's detection envelope to respond to a sudden increase in signal level. Thus, a very small attack softens transients more than a slower attack which lets the transients through the compressor.

void om::sound::filters::Compressor::setAttack ( Float newAttack )

inline

Set the attack of this compressor in seconds.

This value indicates the time in seconds that it takes for the compressor's detection envelope to respond to a sudden increase in signal level. Thus, a very small attack softens transients more than a slower attack which lets the transients through the compressor.

The new attack value is clamped to the range of [0,+infinity].

Float om::sound::filters::Compressor::getRelease ( ) const

inline

Return the release of this compressor in seconds.

This value indicates the time in seconds that it takes for the compressor's detection envelope to respond to a sudden decrease in signal level. Thus, a very short release doesn't compress the signal after a transient for as long as a longer release. Beware, very short release times (< 5ms) can result in audible distortion.

void om::sound::filters::Compressor::setRelease ( Float newRelease )

inline

Set the release of this compressor in seconds.

This value indicates the time in seconds that it takes for the compressor's detection envelope to respond to a sudden decrease in signal level. Thus, a very short release doesn't compress the signal after a transient for as long as a longer release. Beware, very short release times (< 5ms) can result in audible distortion.

The new release value is clamped to the valid range of [0,+infinity].

Float om::sound::filters::Compressor::getRMSTime ( ) const

inline

Return the RMS averaging time for the compressor, expressed in seconds.

This value indicates the total time in seconds over which the compressor is applying an RMS averaging function. The default value is 0, indicating that no RMS detection is desired, peak detection is used instead. A compressor with a longer RMS time will compress the input signal more smoothly than peak detection but may not respond to transients as quickly.

void om::sound::filters::Compressor::setRMSTime ( Float newRMSTime )

inline

Set the RMS averaging time for the compressor, expressed in seconds.

This value indicates the total time in seconds over which the compressor is applying an RMS averaging function. The default value is 0, indicating that no RMS detection is desired, peak detection is used instead. A compressor with a longer RMS time will compress the input signal more smoothly than peak detection but may not respond to transients as quickly.

The new RMS averaging time is clamped to the valid range of [0,+infinity].

Bool om::sound::filters::Compressor::getChannelsAreLinked ( ) const

inline

Return whether or not all channels in the compressor are linked together.

If the value is TRUE, all channels are compressed by the maximum compression amount selected from all channel envelopes. This allows the compressor to maintain the stereo image of the audio when compressing hard-panned sounds.

void om::sound::filters::Compressor::setChannelsAreLinked ( Bool newChannelsAreLinked )

inline

Set whether or not all channels in the compressor are linked together.

If the value is TRUE, all channels are compressed by the maximum compression amount selected from all channel envelopes. This allows the compressor to maintain the stereo image of the audio when compressing hard-panned sounds.

Gain om::sound::filters::Compressor::getGainReductionDB ( ) const

inline

Return the current gain reduction of the compressor in decibels.

This value can be used as a way for humans to visualize how much the compressor is compressing at any given time.

Gain om::sound::filters::Compressor::getGainReduction ( ) const

inline

Return the current gain reduction of the compressor on a linear scale.

This value can be used as a way for humans to visualize how much the compressor is compressing at any given time.

Gain om::sound::filters::Compressor::evaluateTransferFunction ( Gain input ) const

Evaluate the transfer function of the compressor for an envelope with the specified amplitude.

This method returns the output gain applied

Gain om::sound::filters::Compressor::evaluateTransferFunctionDB ( Gain input ) const

inline

Evaluate the transfer function of the compressor for an envelope with the specified amplitude.

virtual UTF8String om::sound::filters::Compressor::getInputName ( Index inputIndex ) const

virtual

Return a human-readable name of the compressor input at the specified index.

The compressor has 2 inputs:

0: the compressor's main input, the source of the signal that is going to be compressed.
1: the compressor's sidechain input, the main input is compressed using this input if provided.

The main input's name is "Main Input", while the sidechain's name is "Sidechain".

Reimplemented from om::sound::filters::SoundFilter.

virtual UTF8String om::sound::filters::Compressor::getName ( ) const

virtual

Return a human-readable name for this compressor.

The method returns the string "Compressor".

Reimplemented from om::sound::filters::SoundFilter.

virtual UTF8String om::sound::filters::Compressor::getManufacturer ( ) const

virtual

Return the manufacturer name of this compressor.

The method returns the string "Om Sound".

Reimplemented from om::sound::filters::SoundFilter.