phonon/audiodataoutput.h

   1 /*  This file is part of the KDE project
   2     Copyright (C) 2005-2006 Matthias Kretz <kretz@kde.org>
   3
   4     This library is free software; you can redistribute it and/or
   5     modify it under the terms of the GNU Library General Public
   6     License version 2 as published by the Free Software Foundation.
   7
   8     This library is distributed in the hope that it will be useful,
   9     but WITHOUT ANY WARRANTY; without even the implied warranty of
  10     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  11     Library General Public License for more details.
  12
  13     You should have received a copy of the GNU Library General Public License
  14     along with this library; see the file COPYING.LIB.  If not, write to
  15     the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  16     Boston, MA 02110-1301, USA.
  17
  18 */
  19 #ifndef Phonon_AUDIODATAOUTPUT_H
  20 #define Phonon_AUDIODATAOUTPUT_H
  21
  22 #include <kdelibs_export.h>
  23 #include "abstractaudiooutput.h"
  24 #include "phonondefs.h"
  25
  26 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  27 template<typename T> class QVector;
  28 template<typename Key, typename T> class QMap;
  29 #endif
  30
  31 namespace Phonon
  32 {
  33         class AudioDataOutputPrivate;
  34
  35         /**
  36          * \short This class gives you the audio data (for visualizations).
  37          *
  38          * This class implements a special AbstractAudioOutput that gives your
  39          * application the audio data. Don't expect realtime performance. But
  40          * the latencies should be low enough to use the audio data for
  41          * visualizations. You can also use the audio data for further processing
  42          * (e.g. encoding and saving to a file).
  43          *
  44          * The class supports different data formats. One of the most common formats
  45          * is to read vectors of integers (which will only use 16 Bit), but you can
  46          * also request floats which some backends use internally.
  47          *
  48          * \author Matthias Kretz <kretz@kde.org>
  49          */
  50         class PHONONCORE_EXPORT AudioDataOutput : public AbstractAudioOutput
  51         {
  52                 Q_OBJECT
  53                 K_DECLARE_PRIVATE( AudioDataOutput )
  54                 Q_ENUMS( Channel Format )
  55                 Q_PROPERTY( Format format READ format WRITE setFormat )
  56                 Q_PROPERTY( int dataSize READ dataSize WRITE setDataSize )
  57                 PHONON_HEIR( AudioDataOutput )
  58                 public:
  59                         /**
  60                          * Specifies the channel the audio data belongs to.
  61                          */
  62                         enum Channel
  63                         {
  64                                 LeftChannel,
  65                                 RightChannel,
  66                                 CenterChannel,
  67                                 LeftSurroundChannel,
  68                                 RightSurroundChannel,
  69                                 SubwooferChannel
  70                         };
  71
  72                         /**
  73                          * Used for telling the object whether you want 16 bit Integers or
  74                          * 32 bit floats.
  75                          *
  76                          * \see requestFormat
  77                          */
  78                         enum Format
  79                         {
  80                                 /**
  81                                  * Requests 16 bit signed integers.
  82                                  *
  83                                  * \see dataReady( const QVector<qint16>& )
  84                                  */
  85                                 IntegerFormat = 1,
  86                                 /**
  87                                  * Requests 32 bit floating point: signed, zero centered, and
  88                                  * normalized to the unit value (-1.0 to 1.0).
  89                                  *
  90                                  * \see dataReady( const QVector<float>& )
  91                                  */
  92                                 FloatFormat = 2
  93                         };
  94
  95                         /**
  96                          * Returns the currently used format.
  97                          *
  98                          * \see setFormat
  99                          */
 100                         Format format() const;
 101
 102                         /**
 103                          * Returns the currently used number of samples passed through
 104                          * the signal.
 105                          *
 106                          * \see setDataSize
 107                          */
 108                         int dataSize() const;
 109
 110                         /**
 111                          * Returns the sample rate in Hz. Common sample rates are 44100 Hz
 112                          * and 48000 Hz. AudioDataOutput will not do any sample rate
 113                          * conversion for you. If you need to convert the sample rate you
 114                          * might want to take a look at libsamplerate. For visualizations it
 115                          * is often enough to do simple interpolation or even drop/duplicate
 116                          * samples.
 117                          *
 118                          * \return The sample rate as reported by the backend. If the
 119                          * backend is unavailable -1 is returned.
 120                          */
 121                         int sampleRate() const;
 122
 123                 public Q_SLOTS:
 124                         /**
 125                          * Requests the dataformat you'd like to receive. Only one of the
 126                          * signals of this class will be emitted when new data is ready.
 127                          *
 128                          * The default format is IntegerFormat.
 129                          *
 130                          * \see format()
 131                          */
 132                         void setFormat( Format format );
 133
 134                         /**
 135                          * Sets the number of samples to be passed in one signal emission.
 136                          *
 137                          * Defaults to 512 samples per emitted signal.
 138                          *
 139                          * \param size the number of samples
 140                          */
 141                         void setDataSize( int size );
 142
 143                 Q_SIGNALS:
 144                         /**
 145                          * Emitted whenever another dataSize number of samples are ready and
 146                          * format is set to IntegerFormat.
 147                          *
 148                          * If format is set to FloatFormat the signal is not emitted at all.
 149                          *
 150                          * \param data A mapping of Channel to a vector holding the audio data.
 151                          */
 152                         void dataReady( const QMap<Phonon::AudioDataOutput::Channel, QVector<qint16> >& data );
 153
 154                         /**
 155                          * Emitted whenever another dataSize number of samples are ready and
 156                          * format is set to FloatFormat.
 157                          *
 158                          * If format is set to IntegerFormat the signal is not emitted at all.
 159                          *
 160                          * \param data A mapping of Channel to a vector holding the audio data.
 161                          */
 162                         void dataReady( const QMap<Phonon::AudioDataOutput::Channel, QVector<float> >& data );
 163
 164                         /**
 165                          * This signal is emitted before the last dataReady signal of a
 166                          * media is emitted.
 167                          *
 168                          * If, for example, the playback of a media file has finished and the
 169                          * last audio data of that file is going to be passed with the next
 170                          * dataReady signal, and only the 28 first samples of the data
 171                          * vector are from that media file endOfMedia will be emitted right
 172                          * before dataReady with \p remainingSamples = 28.
 173                          *
 174                          * \param remainingSamples The number of samples in the next
 175                          * dataReady vector that belong to the media that was playing to
 176                          * this point.
 177                          */
 178                         void endOfMedia( int remainingSamples );
 179         };
 180 } //namespace Phonon
 181
 182 // vim: sw=4 ts=4 tw=80
 183 #endif // Phonon_AUDIODATAOUTPUT_H