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  * This header file contains the declarations of the %AudioEqualizer class.
  22  */
  23
  24 #ifndef _FMEDIA_AUDIO_EQUALIZER_H_
  25 #define _FMEDIA_AUDIO_EQUALIZER_H_
  26
  27 #include <FBaseObject.h>
  28 #include <FMediaPlayer.h>
  29
  30 namespace Tizen { namespace Media
  31 {
  32 /**
  33  * @class AudioEqualizer
  34  * @brief This class is used to apply audio equalizer settings.
  35  *
  36  * @since               2.0
  37  *
  38  * @final This class is not intended for extension.
  39  *
  40  * @remarks             The functionality includes querying and setting the levels of the different frequency bands.
  41  *
  42  * The following example demonstrates how to use the %AudioEqualizer class.
  43  *
  44  * @code
  45  *
  46  * #include <FBase.h>
  47  * #include <FMedia.h>
  48  *
  49  * using namespace Tizen::Base;
  50  * using namespace Tizen::Media;
  51  *
  52  * class EqualizerSample
  53  *     : public Tizen::Media::IPlayerEventListener
  54   * {
  55  * public:
  56  *     result Initialize(void);
  57  *     result Play(void);
  58  *     result Equalize(void);
  59  *     void Stop(void);
  60  *
  61  * protected:
  62  *     // IPlayerEventListener
  63  *     virtual void OnPlayerOpened(result r) {}
  64  *     virtual void OnPlayerEndOfClip(void) {}
  65  *     virtual void OnPlayerBuffering(int percent) {}
  66  *     virtual void OnPlayerErrorOccurred(PlayerErrorReason r) {}
  67  *     virtual void OnPlayerInterrupted(void) {}
  68  *     virtual void OnPlayerReleased(void) {}
  69  *     virtual void OnPlayerSeekCompleted(result r) {}
  70  *     virtual void OnPlayerAudioFocusChanged (void) {}
  71  *
  72  *
  73  * private:
  74  *     Player __player;
  75  *     AudioEqualizer __audioEqualizer;
  76  * };
  77  *
  78  * result
  79  * EqualizerSample::Initialize(void)
  80  * {
  81  *     result r = E_SUCCESS;
  82  *     String filePath = Tizen::App::App::GetInstance()->GetAppRootPath() + L"data/test.mp3";
  83  *
  84  *     r = __player.Construct(*this);
  85  *     if (IsFailed(r))
  86  *     {
  87  *         return r;
  88  *     }
  89  *
  90  *         __audioEqualizer.Construct(__player)
  91  *
  92  *     r = __player.OpenFile(filePath, false);
  93  *     if (IsFailed(r))
  94  *     {
  95  *         return r;
  96  *     }
  97  *     return r;
  98  * }
  99  *
 100  *
 101  * result
 102  * EqualizerSample::Play(void)
 103  * {
 104   * result r = E_SUCCESS;
 105   * r = __player.Play();
 106   * return r;
 107  * }
 108  *
 109  * result
 110  * EqualizerSample::Equalize(void)
 111  * {
 112  *        result r = E_SUCCESS;
 113  *    int count;
 114  *    int level;
 115  *    int minValue;
 116  *    int maxValue;
 117  *
 118  *        count = __audioEqualizer.GetBandCount();
 119  *
 120  *        for (int index = 0; index < count; index++)
 121  *        {
 122  *          r = __audioEqualizer.GetBandLevelRange(index, minValue, maxValue);
 123  *      if (IsFailed(r))
 124  *      {
 125  *              return r;
 126  *      }
 127  *      level = (minValue + maxValue) / 2;
 128  *              r = __audioEqualizer.SetBandLevel(index, level);
 129  *      if (IsFailed(r))
 130  *      {
 131  *              return r;
 132  *      }
 133  *        }
 134  *        return r;
 135  * }
 136  *
 137  *
 138  * void
 139  * EqualizerSample::Stop(void)
 140  * {
 141  *     __audioEqualizer.ResetAllToDefault();
 142  *     __player.Stop();
 143  *     __player.Close();
 144  * }
 145  *
 146  * @endcode
 147  */
 148
 149 class _OSP_EXPORT_ AudioEqualizer
 150         : public Tizen::Base::Object
 151 {
 152 public:
 153         /**
 154         * 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.
 155         *
 156         * @since                2.0
 157         *
 158         * @remarks      After creating an instance of this class, the Construct() method must be called explicitly to
 159         *               initialize this instance.
 160         * @see          Construct()
 161         */
 162         AudioEqualizer(void);
 163
 164         /**
 165         * This destructor overrides Tizen::Base::Object::~Object().
 166         *
 167         * @since                2.0
 168         *
 169         */
 170         virtual ~AudioEqualizer(void);
 171
 172         /**
 173         * Initializes this instance of %AudioEqualizer with the given Player.
 174         *
 175         * @since                2.0
 176         *
 177         * @return               An error code
 178         * @param[in]    player                                  The player instance that the equalizer will be applied
 179         * @exception    E_SUCCESS                                       The method is successful.
 180         * @exception    E_OUT_OF_MEMORY                         The memory is insufficient.
 181         * @exception    E_INVALID_ARG                           The specified input parameter is invalid.
 182         * @exception    E_UNSUPPORTED_OPERATION         This device does not support the audio equalizer feature.
 183         * @remarks If player is deleted, then this instance cannot be used properly.
 184         */
 185         result Construct(Player& player);
 186
 187         /**
 188         * Gets the count of bands that equalizer supports.
 189         *
 190         * @since                2.0
 191         *
 192         * @return               The count of bands, @n
 193         *                                       else @c -1 if it fails
 194         * @exception    E_SUCCESS                                                               The method is successful.
 195         * @exception    E_INVALID_OPERATION                                     The associated audio instance is no longer valid.
 196         * @remarks      The specific error code can be accessed using the GetLastResult() method.
 197         */
 198         int GetBandCount(void) const;
 199
 200         /**
 201         * Gets the level range of the frequency band.
 202         *
 203         * @since                2.0
 204         *
 205         * @return                       An error code
 206         * @param[in]            index                                           Index of the frequency band @n
 207         *                                                                                               Index starts from 0.
 208         * @param[out]   minValue                                The minimum level of the frequency band specified by index
 209         * @param[out]   maxValue                                The maximum level of the frequency band specified by index
 210         * @exception            E_SUCCESS                                       The method is successful.
 211         * @exception            E_INVALID_ARG                           The specified input parameter is invalid.
 212         * @exception            E_INVALID_OPERATION             The associated audio instance is no longer valid.
 213         * @see GetBandCount()
 214         */
 215         result GetBandLevelRange(int index, int& minValue, int& maxValue) const;
 216
 217         /**
 218         * Sets the level of the frequency band specified by index.
 219         *
 220         * @since                2.0
 221         *
 222         * @return                       An error code
 223         * @param[in]            index                                                   Index of the frequency band @n
 224         *                                                                                               Index starts from 0.
 225         * @param[in]            level                                                   The level to which the frequency band should be set
 226         * @exception            E_SUCCESS                                       The method is successful.
 227     * @exception                E_OUT_OF_RANGE          The level value does not lie within minimum and maximum range of frequency band.
 228         * @exception            E_INVALID_ARG                           The specified input parameter is invalid.
 229         * @exception            E_INVALID_OPERATION             The associated audio instance is no longer valid.
 230         * @see GetBandCount()
 231         */
 232         result SetBandLevel(int index, int level);
 233
 234         /**
 235         * Sets the level of all the frequency bands
 236         *
 237         * @since                2.0
 238         *
 239         * @return                       An error code
 240         * @param[in]            pLevels                                         The pointer of the level array which has settings of all the frequency bands
 241         * @exception            E_SUCCESS                                       The method is successful.
 242     * @exception                E_OUT_OF_RANGE          The level values do not lie within minimum and maximum range of frequency bands.
 243     * @exception        E_INVALID_ARG                           The specified input parameter is invalid. List is either empty or does not have level settings for all frequeny bands.
 244         * @exception            E_INVALID_OPERATION             The associated audio instance is no longer valid.
 245         */
 246         result SetAllBandsLevel(const Tizen::Base::Collection::IListT<int>* pLevels);
 247
 248         /**
 249         * Gets the level of frequency band specified by index.
 250         *
 251         * @since                2.0
 252         *
 253         * @return               An error code
 254         * @param[in]            index                                   Index of the frequency band @n
 255         *                                                                                               Index starts from 0.
 256         * @param[out]   level                                           The level of the frequency band specified by index
 257         * @exception            E_SUCCESS                                       The method is successful.
 258         * @exception            E_INVALID_ARG                   The specified input parameter is invalid.
 259         * @exception            E_INVALID_OPERATION             The associated audio instance is no longer valid.
 260         */
 261         result GetBandLevel(int index, int& level) const;
 262
 263         /**
 264         * Gets the center frequency of the frequency band specified by index.
 265         *
 266         * @since                2.0
 267         *
 268         * @return                       An error code
 269         * @param[in]            index                                   Index of the frequency band @n
 270         *                                                                                       Index starts from 0.
 271         * @param[out]   frequency                               The center frequency in Hz of the frequency band specified by index
 272         * @exception            E_SUCCESS                               The method is successful.
 273         * @exception            E_INVALID_ARG                   The specified input parameter is invalid.
 274         * @exception            E_INVALID_OPERATION             The associated audio instance is no longer valid.
 275         */
 276         result GetBandCenterFrequency(int index, int& frequency) const;
 277
 278         /**
 279         * Clears the equalizer effect and resets all bands to the default values.
 280         *
 281         * @since                2.0
 282         *
 283         * @return                       An error code
 284         * @exception            E_SUCCESS                                       The method is successful.
 285         * @exception            E_INVALID_OPERATION     The associated audio instance is no longer valid.
 286         */
 287         result ResetAllToDefault(void);
 288
 289 private:
 290         /**
 291          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 292          *
 293          * @since               2.0
 294          *
 295          */
 296         AudioEqualizer(const AudioEqualizer& rhs);
 297
 298         /**
 299          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 300          *
 301          * @since               2.0
 302          *
 303          */
 304         AudioEqualizer& operator =(const AudioEqualizer& rhs);
 305
 306         class _AudioEqualizerImpl* __pAudioEqualizerImpl;
 307 };
 308
 309 }} // Tizen::Media
 310
 311 #endif
 312