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