2 // Open Service Platform
3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
5 // Licensed under the Apache License, Version 2.0 (the License);
6 // you may not use this file except in compliance with the License.
7 // You may obtain a copy of the License at
9 // http://www.apache.org/licenses/LICENSE-2.0
11 // Unless required by applicable law or agreed to in writing, software
12 // distributed under the License is distributed on an "AS IS" BASIS,
13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 // See the License for the specific language governing permissions and
15 // limitations under the License.
19 * @file FMediaAudioEqualizer.h
20 * @brief This is the header file for the %AudioEqualizer class.
22 * This header file contains the declarations of the %AudioEqualizer class.
25 #ifndef _FMEDIA_AUDIO_EQUALIZER_H_
26 #define _FMEDIA_AUDIO_EQUALIZER_H_
28 #include <FBaseObject.h>
29 #include <FMediaPlayer.h>
31 namespace Tizen { namespace Media
34 * @class AudioEqualizer
35 * @brief This class is used to apply audio equalizer settings.
39 * @final This class is not intended for extension.
41 * @remarks The functionality includes querying and setting the levels of the different frequency bands.
43 * The following example demonstrates how to use the %AudioEqualizer class.
50 * using namespace Tizen::Base;
51 * using namespace Tizen::Media;
53 * class EqualizerSample
54 * : public Tizen::Media::IPlayerEventListener
57 * result Initialize(void);
59 * result Equalize(void);
63 * // IPlayerEventListener
64 * virtual void OnPlayerOpened(result r) {}
65 * virtual void OnPlayerEndOfClip(void) {}
66 * virtual void OnPlayerBuffering(int percent) {}
67 * virtual void OnPlayerErrorOccurred(PlayerErrorReason r) {}
68 * virtual void OnPlayerInterrupted(void) {}
69 * virtual void OnPlayerReleased(void) {}
70 * virtual void OnPlayerSeekCompleted(result r) {}
71 * virtual void OnPlayerAudioFocusChanged (void) {}
76 * AudioEqualizer __audioEqualizer;
80 * EqualizerSample::Initialize(void)
82 * result r = E_SUCCESS;
83 * String filePath = Tizen::App::App::GetInstance()->GetAppRootPath() + L"data/test.mp3";
85 * r = __player.Construct(*this);
91 * __audioEqualizer.Construct(__player)
93 * r = __player.OpenFile(filePath, false);
103 * EqualizerSample::Play(void)
105 * result r = E_SUCCESS;
106 * r = __player.Play();
111 * EqualizerSample::Equalize(void)
113 * result r = E_SUCCESS;
119 * count = __audioEqualizer.GetBandCount();
121 * for (int index = 0; index < count; index++)
123 * r = __audioEqualizer.GetBandLevelRange(index, minValue, maxValue);
128 * level = (minValue + maxValue) / 2;
129 * r = __audioEqualizer.SetBandLevel(index, level);
140 * EqualizerSample::Stop(void)
142 * __audioEqualizer.ResetAllToDefault();
150 class _OSP_EXPORT_ AudioEqualizer
151 : public Tizen::Base::Object
155 * The object is not fully constructed after this constructor is called. For full construction, the Construct() method must be called right after calling this constructor.
159 * @remarks After creating an instance of this class, the Construct() method must be called explicitly to
160 * initialize this instance.
163 AudioEqualizer(void);
166 * This destructor overrides Tizen::Base::Object::~Object().
171 virtual ~AudioEqualizer(void);
174 * Initializes this instance of %AudioEqualizer with the given Player.
178 * @return An error code
179 * @param[in] player The player instance that the equalizer will be applied
180 * @exception E_SUCCESS The method is successful.
181 * @exception E_OUT_OF_MEMORY The memory is insufficient.
182 * @exception E_INVALID_ARG The specified input parameter is invalid.
183 * @exception E_UNSUPPORTED_OPERATION This device does not support the audio equalizer feature.
184 * @remarks If player is deleted, then this instance cannot be used properly.
186 result Construct(Player& player);
189 * Gets the count of bands that equalizer supports.
193 * @return The count of bands, @n
194 * else @c -1 if it fails
195 * @exception E_SUCCESS The method is successful.
196 * @exception E_INVALID_OPERATION The associated audio instance is no longer valid.
197 * @remarks The specific error code can be accessed using the GetLastResult() method.
199 int GetBandCount(void) const;
202 * Gets the level range of the frequency band.
206 * @return An error code
207 * @param[in] index Index of the frequency band @n
208 * Index starts from 0.
209 * @param[out] minValue The minimum level of the frequency band specified by @c index
210 * @param[out] maxValue The maximum level of the frequency band specified by @c index
211 * @exception E_SUCCESS The method is successful.
212 * @exception E_INVALID_ARG The specified input parameter is invalid.
213 * @exception E_INVALID_OPERATION The associated audio instance is no longer valid.
214 * @see GetBandCount()
216 result GetBandLevelRange(int index, int& minValue, int& maxValue) const;
219 * Sets the level of the frequency band specified by @c index.
223 * @return An error code
224 * @param[in] index Index of the frequency band @n
225 * Index starts from 0.
226 * @param[in] level The level to which the frequency band should be set
227 * @exception E_SUCCESS The method is successful.
228 * @exception E_OUT_OF_RANGE The level value does not lie within minimum and maximum range of frequency band.
229 * @exception E_INVALID_ARG The specified input parameter is invalid.
230 * @exception E_INVALID_OPERATION The associated audio instance is no longer valid.
231 * @see GetBandCount()
233 result SetBandLevel(int index, int level);
236 * Sets the level of all the frequency bands
240 * @return An error code
241 * @param[in] pLevels The pointer of the level array which has settings of all the frequency bands
242 * @exception E_SUCCESS The method is successful.
243 * @exception E_OUT_OF_RANGE The level values do not lie within minimum and maximum range of frequency bands.
244 * @exception E_INVALID_ARG The specified input parameter is invalid. List is either empty or does not have level settings for all frequency bands.
245 * @exception E_INVALID_OPERATION The associated audio instance is no longer valid.
247 result SetAllBandsLevel(const Tizen::Base::Collection::IListT<int>* pLevels);
250 * Gets the level of frequency band specified by @c index.
254 * @return An error code
255 * @param[in] index Index of the frequency band @n
256 * Index starts from 0.
257 * @param[out] level The level of the frequency band specified by @c index
258 * @exception E_SUCCESS The method is successful.
259 * @exception E_INVALID_ARG The specified input parameter is invalid.
260 * @exception E_INVALID_OPERATION The associated audio instance is no longer valid.
262 result GetBandLevel(int index, int& level) const;
265 * Gets the center frequency of the frequency band specified by index.
269 * @return An error code
270 * @param[in] index Index of the frequency band @n
271 * Index starts from 0.
272 * @param[out] frequency The center frequency in Hz of the frequency band specified by @c index
273 * @exception E_SUCCESS The method is successful.
274 * @exception E_INVALID_ARG The specified input parameter is invalid.
275 * @exception E_INVALID_OPERATION The associated audio instance is no longer valid.
277 result GetBandCenterFrequency(int index, int& frequency) const;
280 * Clears the equalizer effect and resets all bands to the default values.
284 * @return An error code
285 * @exception E_SUCCESS The method is successful.
286 * @exception E_INVALID_OPERATION The associated audio instance is no longer valid.
288 result ResetAllToDefault(void);
292 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
297 AudioEqualizer(const AudioEqualizer& rhs);
300 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
305 AudioEqualizer& operator =(const AudioEqualizer& rhs);
307 class _AudioEqualizerImpl* __pAudioEqualizerImpl;