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 Lesser General Public
6 License as published by the Free Software Foundation; either
7 version 2.1 of the License, or (at your option) version 3, or any
8 later version accepted by the membership of KDE e.V. (or its
9 successor approved by the membership of KDE e.V.), Nokia Corporation
10 (or its successors, if any) and the KDE Free Qt Foundation, which shall
11 act as a proxy defined in Section 6 of version 3 of the license.
12
13 This library is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 Lesser General Public License for more details.
17
18 You should have received a copy of the GNU Lesser General Public
19 License along with this library. If not, see <http://www.gnu.org/licenses/>.
20
21*/
22#ifndef Phonon_AUDIODATAOUTPUT_H
23#define Phonon_AUDIODATAOUTPUT_H
24
25#include "phonon_export.h"
26#include "abstractaudiooutput.h"
27#include "phonondefs.h"
28
29#ifndef K_DOXYGEN
30#if QT_VERSION < QT_VERSION_CHECK(6, 0, 0)
31template<typename T> class QVector;
32#else
33template<typename T> class QList;
34#endif
35template<typename Key, typename T> class QMap;
36#endif
37
38namespace Phonon
39{
40 class AudioDataOutputPrivate;
41
42 /**
43 * \short This class gives you the audio data (for visualizations).
44 *
45 * This class implements a special AbstractAudioOutput that gives your
46 * application the audio data. Don't expect realtime performance. But
47 * the latencies should be low enough to use the audio data for
48 * visualizations. You can also use the audio data for further processing
49 * (e.g. encoding and saving to a file).
50 *
51 * \author Matthias Kretz <kretz@kde.org>
52 */
53 class PHONON_EXPORT AudioDataOutput : public AbstractAudioOutput
54 {
55 Q_OBJECT
56 P_DECLARE_PRIVATE(AudioDataOutput)
57 Q_ENUMS(Channel)
58 Q_PROPERTY(int dataSize READ dataSize WRITE setDataSize)
59 PHONON_HEIR(AudioDataOutput)
60 public:
61 /**
62 * Specifies the channel the audio data belongs to.
63 */
64 enum Channel
65 {
66 LeftChannel,
67 RightChannel,
68 CenterChannel,
69 LeftSurroundChannel,
70 RightSurroundChannel,
71 SubwooferChannel
72 };
73
74 /**
75 * Returns the currently used number of samples passed through
76 * the signal.
77 *
78 * \see setDataSize
79 */
80 int dataSize() const;
81
82 /**
83 * Returns the sample rate in Hz. Common sample rates are 44100 Hz
84 * and 48000 Hz. AudioDataOutput will not do any sample rate
85 * conversion for you. If you need to convert the sample rate you
86 * might want to take a look at libsamplerate. For visualizations it
87 * is often enough to do simple interpolation or even drop/duplicate
88 * samples.
89 *
90 * \return The sample rate as reported by the backend. If the
91 * backend is unavailable -1 is returned.
92 */
93 int sampleRate() const;
94
95 public Q_SLOTS:
96 /**
97 * Sets the number of samples to be passed in one signal emission.
98 *
99 * Defaults to 512 samples per emitted signal.
100 *
101 * \param size the number of samples
102 */
103 void setDataSize(int size);
104
105 Q_SIGNALS:
106 /**
107 * Emitted whenever another dataSize number of samples are ready.
108 *
109 * \param data A mapping of Channel to a vector holding the audio data.
110 */
111 void dataReady(const QMap<Phonon::AudioDataOutput::Channel, QVector<qint16> > &data);
112
113
114 /**
115 * This signal is emitted before the last dataReady signal of a
116 * media is emitted.
117 *
118 * If, for example, the playback of a media file has finished and the
119 * last audio data of that file is going to be passed with the next
120 * dataReady signal, and only the 28 first samples of the data
121 * vector are from that media file endOfMedia will be emitted right
122 * before dataReady with \p remainingSamples = 28.
123 *
124 * \param remainingSamples The number of samples in the next
125 * dataReady vector that belong to the media that was playing to
126 * this point.
127 */
128 void endOfMedia(int remainingSamples);
129 };
130} // namespace Phonon
131
132
133// vim: sw=4 ts=4 tw=80
134#endif // Phonon_AUDIODATAOUTPUT_H
135

source code of phonon/phonon/audiodataoutput.h