git.maemo.org Git - someplayer/blob - src/taglib/mpeg/id3v2/frames/relativevolumeframe.h

   1 /***************************************************************************
   2     copyright            : (C) 2002 - 2008 by Scott Wheeler
   3     email                : wheeler@kde.org
   4  ***************************************************************************/
   5
   6 /***************************************************************************
   7  *   This library is free software; you can redistribute it and/or modify  *
   8  *   it under the terms of the GNU Lesser General Public License version   *
   9  *   2.1 as published by the Free Software Foundation.                     *
  10  *                                                                         *
  11  *   This library is distributed in the hope that it will be useful, but   *
  12  *   WITHOUT ANY WARRANTY; without even the implied warranty of            *
  13  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU     *
  14  *   Lesser General Public License for more details.                       *
  15  *                                                                         *
  16  *   You should have received a copy of the GNU Lesser General Public      *
  17  *   License along with this library; if not, write to the Free Software   *
  18  *   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  *
  19  *   USA                                                                   *
  20  *                                                                         *
  21  *   Alternatively, this file is available under the Mozilla Public        *
  22  *   License Version 1.1.  You may obtain a copy of the License at         *
  23  *   http://www.mozilla.org/MPL/                                           *
  24  ***************************************************************************/
  25
  26 #ifndef TAGLIB_RELATIVEVOLUMEFRAME_H
  27 #define TAGLIB_RELATIVEVOLUMEFRAME_H
  28
  29 #include "tlist.h"
  30 #include "id3v2frame.h"
  31 #include "taglib_export.h"
  32
  33 namespace TagLib {
  34
  35   namespace ID3v2 {
  36
  37     //! An ID3v2 relative volume adjustment frame implementation
  38
  39     /*!
  40      * This is an implementation of ID3v2 relative volume adjustment.  The
  41      * presence of this frame makes it possible to specify an increase in volume
  42      * for an audio file or specific audio tracks in that file.
  43      *
  44      * Multiple relative volume adjustment frames may be present in the tag
  45      * each with a unique identification and describing volume adjustment for
  46      * different channel types.
  47      */
  48
  49     class TAGLIB_EXPORT RelativeVolumeFrame : public Frame
  50     {
  51       friend class FrameFactory;
  52
  53     public:
  54
  55       /*!
  56        * This indicates the type of volume adjustment that should be applied.
  57        */
  58       enum ChannelType {
  59         //! A type not enumerated below
  60         Other        = 0x00,
  61         //! The master volume for the track
  62         MasterVolume = 0x01,
  63         //! The front right audio channel
  64         FrontRight   = 0x02,
  65         //! The front left audio channel
  66         FrontLeft    = 0x03,
  67         //! The back right audio channel
  68         BackRight    = 0x04,
  69         //! The back left audio channel
  70         BackLeft     = 0x05,
  71         //! The front center audio channel
  72         FrontCentre  = 0x06,
  73         //! The back center audio channel
  74         BackCentre   = 0x07,
  75         //! The subwoofer audio channel
  76         Subwoofer    = 0x08
  77       };
  78
  79       //! Struct that stores the relevant values for ID3v2 peak volume
  80
  81       /*!
  82        * The peak volume is described as a series of bits that is padded to fill
  83        * a block of bytes.  These two values should always be updated in tandem.
  84        */
  85       struct PeakVolume
  86       {
  87         /*!
  88          * Constructs an empty peak volume description.
  89          */
  90         PeakVolume() : bitsRepresentingPeak(0) {}
  91         /*!
  92          * The number of bits (in the range of 0 to 255) used to describe the
  93          * peak volume.
  94          */
  95         unsigned char bitsRepresentingPeak;
  96         /*!
  97          * The array of bits (represented as a series of bytes) used to describe
  98          * the peak volume.
  99          */
 100         ByteVector peakVolume;
 101       };
 102
 103       /*!
 104        * Constructs a RelativeVolumeFrame.  The relevant data should be set
 105        * manually.
 106        */
 107       RelativeVolumeFrame();
 108
 109       /*!
 110        * Constructs a RelativeVolumeFrame based on the contents of \a data.
 111        */
 112       RelativeVolumeFrame(const ByteVector &data);
 113
 114       /*!
 115        * Destroys the RelativeVolumeFrame instance.
 116        */
 117       virtual ~RelativeVolumeFrame();
 118
 119       /*!
 120        * Returns the frame's identification.
 121        *
 122        * \see identification()
 123        */
 124       virtual String toString() const;
 125
 126       /*!
 127        * Returns a list of channels with information currently in the frame.
 128        */
 129       List<ChannelType> channels() const;
 130
 131       /*!
 132        * \deprecated Always returns master volume.
 133        */
 134       ChannelType channelType() const;
 135
 136       /*!
 137        * \deprecated This method no longer has any effect.
 138        */
 139       void setChannelType(ChannelType t);
 140
 141       /*
 142        * There was a terrible API goof here, and while this can't be changed to
 143        * the way it appears below for binary compaibility reasons, let's at
 144        * least pretend that it looks clean.
 145        */
 146
 147 #ifdef DOXYGEN
 148
 149       /*!
 150        * Returns the relative volume adjustment "index".  As indicated by the
 151        * ID3v2 standard this is a 16-bit signed integer that reflects the
 152        * decibils of adjustment when divided by 512.
 153        *
 154        * This defaults to returning the value for the master volume channel if
 155        * available and returns 0 if the specified channel does not exist.
 156        *
 157        * \see setVolumeAdjustmentIndex()
 158        * \see volumeAjustment()
 159        */
 160       short volumeAdjustmentIndex(ChannelType type = MasterVolume) const;
 161
 162       /*!
 163        * Set the volume adjustment to \a index.  As indicated by the ID3v2
 164        * standard this is a 16-bit signed integer that reflects the decibils of
 165        * adjustment when divided by 512.
 166        *
 167        * By default this sets the value for the master volume.
 168        *
 169        * \see volumeAdjustmentIndex()
 170        * \see setVolumeAjustment()
 171        */
 172       void setVolumeAdjustmentIndex(short index, ChannelType type = MasterVolume);
 173
 174       /*!
 175        * Returns the relative volume adjustment in decibels.
 176        *
 177        * \note Because this is actually stored internally as an "index" to this
 178        * value the value returned by this method may not be identical to the
 179        * value set using setVolumeAdjustment().
 180        *
 181        * This defaults to returning the value for the master volume channel if
 182        * available and returns 0 if the specified channel does not exist.
 183        *
 184        * \see setVolumeAdjustment()
 185        * \see volumeAdjustmentIndex()
 186        */
 187       float volumeAdjustment(ChannelType type = MasterVolume) const;
 188
 189       /*!
 190        * Set the relative volume adjustment in decibels to \a adjustment.
 191        *
 192        * By default this sets the value for the master volume.
 193        *
 194        * \note Because this is actually stored internally as an "index" to this
 195        * value the value set by this method may not be identical to the one
 196        * returned by volumeAdjustment().
 197        *
 198        * \see setVolumeAdjustment()
 199        * \see volumeAdjustmentIndex()
 200        */
 201       void setVolumeAdjustment(float adjustment, ChannelType type = MasterVolume);
 202
 203       /*!
 204        * Returns the peak volume (represented as a length and a string of bits).
 205        *
 206        * This defaults to returning the value for the master volume channel if
 207        * available and returns 0 if the specified channel does not exist.
 208        *
 209        * \see setPeakVolume()
 210        */
 211       PeakVolume peakVolume(ChannelType type = MasterVolume) const;
 212
 213       /*!
 214        * Sets the peak volume to \a peak.
 215        *
 216        * By default this sets the value for the master volume.
 217        *
 218        * \see peakVolume()
 219        */
 220       void setPeakVolume(const PeakVolume &peak, ChannelType type = MasterVolume);
 221
 222 #else
 223
 224       // BIC: Combine each of the following pairs of functions (or maybe just
 225       // rework this junk altogether).
 226
 227       short volumeAdjustmentIndex(ChannelType type) const;
 228       short volumeAdjustmentIndex() const;
 229
 230       void setVolumeAdjustmentIndex(short index, ChannelType type);
 231       void setVolumeAdjustmentIndex(short index);
 232
 233       float volumeAdjustment(ChannelType type) const;
 234       float volumeAdjustment() const;
 235
 236       void setVolumeAdjustment(float adjustment, ChannelType type);
 237       void setVolumeAdjustment(float adjustment);
 238
 239       PeakVolume peakVolume(ChannelType type) const;
 240       PeakVolume peakVolume() const;
 241
 242       void setPeakVolume(const PeakVolume &peak, ChannelType type);
 243       void setPeakVolume(const PeakVolume &peak);
 244
 245 #endif
 246
 247       /*!
 248        * Returns the identification for this frame.
 249        */
 250       String identification() const;
 251
 252       /*!
 253        * Sets the identification of the frame to \a s. The string
 254        * is used to identify the situation and/or device where this
 255        * adjustment should apply.
 256        */
 257       void setIdentification(const String &s);
 258
 259     protected:
 260       virtual void parseFields(const ByteVector &data);
 261       virtual ByteVector renderFields() const;
 262
 263     private:
 264       RelativeVolumeFrame(const ByteVector &data, Header *h);
 265       RelativeVolumeFrame(const RelativeVolumeFrame &);
 266       RelativeVolumeFrame &operator=(const RelativeVolumeFrame &);
 267
 268       class RelativeVolumeFramePrivate;
 269       RelativeVolumeFramePrivate *d;
 270     };
 271
 272   }
 273 }
 274 #endif