/* * Copyright 2009, The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ #ifndef AUDIOEQUALIZER_H_ #define AUDIOEQUALIZER_H_ #include "AudioCommon.h" namespace android { class AudioShelvingFilter; class AudioPeakingFilter; // A parametric audio equalizer. Supports an arbitrary number of bands and // presets. // The EQ is composed of a low-shelf, zero or more peaking filters and a high // shelf, where each band has frequency and gain controls, and the peaking // filters have an additional bandwidth control. class AudioEqualizer { public: // Configuration of a single band. struct BandConfig { // Gain in millibel. int32_t gain; // Frequency in millihertz. uint32_t freq; // Bandwidth in cents (ignored on shelving filters). uint32_t bandwidth; }; // Preset configuration. struct PresetConfig { // Human-readable name. const char * name; // An array of size nBands where each element is a configuration for the // corresponding band. const BandConfig * bandConfigs; }; // This value is used when requesting current preset, and EQ is not using a // preset. static const int PRESET_CUSTOM = -1; // Get the required memory size for an instance of this class. // nBands Number of bands required in the instance. static size_t GetInstanceSize(int nBands); // Create an instance of this class. // If succeeds, a respective call is expected to freeInstance(), regardless // of who owns the context memory. // pMem A memory buffer of at least the size returned by // GetInstanceSize(), where the instance context is to be // stored. If NULL, it will be automatically allocated (using // malloc). // nBands Number of bands. Must be >= 2. // nChannels Number of input/output channels (interlaced). // sampleRate The input/output sample rate, in Hz. // presets The presets configuration. May be NULL, but in that case the // client is required not to call preset-related functions. // This array is owned by the client and is not copied. It // must be kept valid by the client as long as the instance is // alive. // nPresets Number of elements in the presets array. // returns The instance if success. NULL if pMem is NULL and allocation // failed. static AudioEqualizer * CreateInstance(void * pMem, int nBands, int nChannels, int sampleRate, const PresetConfig * presets, int nPresets); // Reconfiguration of the filter. Changes input/output format, but does not // alter current parameter values. Causes reset of the delay lines. // nChannels Number of input/output channels (interlaced). // sampleRate The input/output sample rate, in Hz. void configure(int nChannels, int sampleRate); // Resets the filter parameters to the following values: // frequency: 0 // gain: 0 // bandwidth: 1200 cents. // It also disables the filter. Does not clear the delay lines. void reset(); // Clears delay lines. Does not alter parameter values. void clear(); // Frees the object. Will free the memory if the object owned it, i.e. if // a NULL pointer was passed to CreateInstance as pMem. void free(); // Sets gain value. Actual change will only take place upon commit(). // This value will be remembered even if the filter is in disabled() state. // band The band to set the gain for. // millibel Gain value in millibel (1/100 of decibel). void setGain(int band, int32_t millibel); // Gets gain of a certain band. This is always the last value set (or // default value after reset). // band The band to get the gain for. // returns Gain value in millibel (1/100 of decibel). int32_t getGain(int band) const; // Sets cutoff frequency value. Actual change will only take place upon // commit(). // This value will be remembered even if the filter is in disabled() state. // band The band to set the frequency for. // millihertz Frequency value in mHz. void setFrequency(int band, uint32_t millihertz); // Gets frequency of a certain band. This is always the last value set (or // default value after reset). // band The band to get the frequency for. // returns Frequency value in mHz. uint32_t getFrequency(int band) const; // Sets bandwidth value. Actual change will only take place upon commit(). // This value will be remembered even if the filter is in disabled() state. // If called on the first or last band, this call is ignored. // band The band to set the frequency for. // cents Bandwidth value in cents (1/1200 octave). void setBandwidth(int band, uint32_t cents); // Gets bandwidth of a certain band. This is always the last value set (or // default value after reset). For the first and last bands, 0 is always // returned. // band The band to get the bandwidth for. // returns Bandwidth value in cents (1/1200 octave). uint32_t getBandwidth(int band) const; // Gets lower and upper boundaries of a band. // For the low shelf, the low bound is 0 and the high bound is the band // frequency. // For the high shelf, the low bound is the band frequency and the high // bound is Nyquist. // For the peaking filters, they are the gain[dB]/2 points. void getBandRange(int band, uint32_t & low, uint32_t & high) const; // Gets a human-readable name for a preset ID. Will return "Custom" if // PRESET_CUSTOM is passed. // preset The preset ID. Must be less than number of presets. const char * getPresetName(int preset) const; // Gets the number of presets. int getNumPresets() const; // Gets the currently set preset ID. // Will return PRESET_CUSTOM in case the EQ parameters have been modified // manually since a preset was set. int getPreset() const; // Sets the current preset by ID. // All the band parameters will be overridden. // Change will not be applied until commit() is called. // preset The preset ID. Must be less than number of presets. // PRESET_CUSTOM is NOT a valid value here. void setPreset(int preset); // Applies all parameter changes done to this point in time. // If the filter is disabled, the new parameters will take place when it is // enabled again. Does not introduce artifacts, unless immediate is set. // immediate Whether to apply change abruptly (ignored if filter is // disabled). void commit(bool immediate = false); // Process a buffer of input data. The input and output should contain // frameCount * nChannels interlaced samples. Processing can be done // in-place, by passing the same buffer as both arguments. // pIn Input buffer. // pOut Output buffer. // frameCount Number of frames to produce on each call to process(). void process(const audio_sample_t * pIn, audio_sample_t * pOut, int frameCount); // Enables the filter, so it would start processing input. Does not // introduce artifacts, unless immediate is set. // immediate Whether to apply change abruptly. void enable(bool immediate = false); // Disabled (bypasses) the filter. Does not introduce artifacts, unless // immediate is set. // immediate Whether to apply change abruptly. void disable(bool immediate = false); // Returns the band with the maximum influence on a given frequency. // Result is unaffected by whether EQ is enabled or not, or by whether // changes have been committed or not. // targetFreq The target frequency, in millihertz. int getMostRelevantBand(uint32_t targetFreq) const; private: // Bottom frequency, in mHz. static const int kMinFreq = 20000; // Sample rate, in Hz. int mSampleRate; // Number of peaking filters. Total number of bands is +2. int mNumPeaking; // Preset configurations. const PresetConfig * mpPresets; // Number of elements in mpPresets; int mNumPresets; // Current preset. int mCurPreset; // Memory space to free when instance is deleted, or NULL if no memory is // owned. void * mpMem; // The low-shelving filter. AudioShelvingFilter * mpLowShelf; // The high-shelving filter. AudioShelvingFilter * mpHighShelf; // An array of size mNumPeaking of peaking filters. AudioPeakingFilter * mpPeakingFilters; // Constructor. Resets the filter (see reset()). Must call init() doing // anything else. // pMem Memory buffer for bands. // nChannels Number of input/output channels (interlaced). // sampleRate The input/output sample rate, in Hz. // ownMem Whether pMem is owned by me. // presets The presets configuration. May be NULL, but in that case the // client is required not to call preset-related functions. // This array is owned by the client and is not copied. It // must be kept valid by the client as long as the instance is // alive. // nPresets Number of elements in the presets array. AudioEqualizer(void * pMem, int nBands, int nChannels, int sampleRate, bool ownMem, const PresetConfig * presets, int nPresets); }; } #endif // AUDIOEQUALIZER_H_