inc/FMediaAudioEqualizer.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   4 //
   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
   8 //
   9 //     http://www.apache.org/licenses/LICENSE-2.0
  10 //
  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.
  16 //
  17
  18 /**
  19  * @file   FMediaAudioEqualizer.h
  20  * @brief  This is the header file for the %AudioEqualizer class.
  21  *
  22  * This header file contains the declarations of the %AudioEqualizer class.
  23  */
  24
  25 #ifndef _FMEDIA_AUDIO_EQUALIZER_H_
  26 #define _FMEDIA_AUDIO_EQUALIZER_H_
  27
  28 #include <FBaseObject.h>
  29 #include <FMediaPlayer.h>
  30
  31 namespace Tizen { namespace Media
  32 {
  33 /**
  34  * @class AudioEqualizer
  35  * @brief This class is used to apply audio equalizer settings.
  36  *
  37  * @since               2.0
  38  *
  39  * @final This class is not intended for extension.
  40  *
  41  * @remarks             The functionality includes querying and setting the levels of the different frequency bands.
  42  *
  43  * The following example demonstrates how to use the %AudioEqualizer class.
  44  *
  45  * @code
  46  *
  47  * #include <FBase.h>
  48  * #include <FMedia.h>
  49  *
  50  * using namespace Tizen::Base;
  51  * using namespace Tizen::Media;
  52  *
  53  * class EqualizerSample
  54  *     : public Tizen::Media::IPlayerEventListener
  55   * {
  56  * public:
  57  *     result Initialize(void);
  58  *     result Play(void);
  59  *     result Equalize(void);
  60  *     void Stop(void);
  61  *
  62  * protected:
  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) {}
  72  *
  73  *
  74  * private:
  75  *     Player __player;
  76  *     AudioEqualizer __audioEqualizer;
  77  * };
  78  *
  79  * result
  80  * EqualizerSample::Initialize(void)
  81  * {
  82  *     result r = E_SUCCESS;
  83  *     String filePath = Tizen::App::App::GetInstance()->GetAppRootPath() + L"data/test.mp3";
  84  *
  85  *     r = __player.Construct(*this);
  86  *     if (IsFailed(r))
  87  *     {
  88  *         return r;
  89  *     }
  90  *
  91  *         __audioEqualizer.Construct(__player)
  92  *
  93  *     r = __player.OpenFile(filePath, false);
  94  *     if (IsFailed(r))
  95  *     {
  96  *         return r;
  97  *     }
  98  *     return r;
  99  * }
 100  *
 101  *
 102  * result
 103  * EqualizerSample::Play(void)
 104  * {
 105   * result r = E_SUCCESS;
 106   * r = __player.Play();
 107   * return r;
 108  * }
 109  *
 110  * result
 111  * EqualizerSample::Equalize(void)
 112  * {
 113  *        result r = E_SUCCESS;
 114  *    int count;
 115  *    int level;
 116  *    int minValue;
 117  *    int maxValue;
 118  *
 119  *        count = __audioEqualizer.GetBandCount();
 120  *
 121  *        for (int index = 0; index < count; index++)
 122  *        {
 123  *          r = __audioEqualizer.GetBandLevelRange(index, minValue, maxValue);
 124  *      if (IsFailed(r))
 125  *      {
 126  *              return r;
 127  *      }
 128  *      level = (minValue + maxValue) / 2;
 129  *              r = __audioEqualizer.SetBandLevel(index, level);
 130  *      if (IsFailed(r))
 131  *      {
 132  *              return r;
 133  *      }
 134  *        }
 135  *        return r;
 136  * }
 137  *
 138  *
 139  * void
 140  * EqualizerSample::Stop(void)
 141  * {
 142  *     __audioEqualizer.ResetAllToDefault();
 143  *     __player.Stop();
 144  *     __player.Close();
 145  * }
 146  *
 147  * @endcode
 148  */
 149
 150 class _OSP_EXPORT_ AudioEqualizer
 151         : public Tizen::Base::Object
 152 {
 153 public:
 154         /**
 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.
 156         *
 157         * @since                2.0
 158         *
 159         * @remarks      After creating an instance of this class, the Construct() method must be called explicitly to
 160         *               initialize this instance.
 161         * @see          Construct()
 162         */
 163         AudioEqualizer(void);
 164
 165         /**
 166         * This destructor overrides Tizen::Base::Object::~Object().
 167         *
 168         * @since                2.0
 169         *
 170         */
 171         virtual ~AudioEqualizer(void);
 172
 173         /**
 174         * Initializes this instance of %AudioEqualizer with the given Player.
 175         *
 176         * @since                2.0
 177         *
 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.
 185         */
 186         result Construct(Player& player);
 187
 188         /**
 189         * Gets the count of bands that equalizer supports.
 190         *
 191         * @since                2.0
 192         *
 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.
 198         */
 199         int GetBandCount(void) const;
 200
 201         /**
 202         * Gets the level range of the frequency band.
 203         *
 204         * @since                2.0
 205         *
 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()
 215         */
 216         result GetBandLevelRange(int index, int& minValue, int& maxValue) const;
 217
 218         /**
 219         * Sets the level of the frequency band specified by @c index.
 220         *
 221         * @since                2.0
 222         *
 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()
 232         */
 233         result SetBandLevel(int index, int level);
 234
 235         /**
 236         * Sets the level of all the frequency bands
 237         *
 238         * @since                2.0
 239         *
 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.
 246         */
 247         result SetAllBandsLevel(const Tizen::Base::Collection::IListT<int>* pLevels);
 248
 249         /**
 250         * Gets the level of frequency band specified by @c index.
 251         *
 252         * @since                2.0
 253         *
 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.
 261         */
 262         result GetBandLevel(int index, int& level) const;
 263
 264         /**
 265         * Gets the center frequency of the frequency band specified by index.
 266         *
 267         * @since                2.0
 268         *
 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.
 276         */
 277         result GetBandCenterFrequency(int index, int& frequency) const;
 278
 279         /**
 280         * Clears the equalizer effect and resets all bands to the default values.
 281         *
 282         * @since                2.0
 283         *
 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.
 287         */
 288         result ResetAllToDefault(void);
 289
 290 private:
 291         /**
 292          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 293          *
 294          * @since               2.0
 295          *
 296          */
 297         AudioEqualizer(const AudioEqualizer& rhs);
 298
 299         /**
 300          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 301          *
 302          * @since               2.0
 303          *
 304          */
 305         AudioEqualizer& operator =(const AudioEqualizer& rhs);
 306
 307         class _AudioEqualizerImpl* __pAudioEqualizerImpl;
 308 };
 309
 310 }} // Tizen::Media
 311
 312 #endif
 313