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 "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{
40namespace Experimental
41{
42 class AudioDataOutputPrivate;
43
44 /**
45 * \short This class gives you the audio data (for visualizations).
46 *
47 * This class implements a special AbstractAudioOutput that gives your
48 * application the audio data. Don't expect realtime performance. But
49 * the latencies should be low enough to use the audio data for
50 * visualizations. You can also use the audio data for further processing
51 * (e.g. encoding and saving to a file).
52 *
53 * The class supports different data formats. One of the most common formats
54 * is to read vectors of integers (which will only use 16 Bit), but you can
55 * also request floats which some backends use internally.
56 *
57 * \author Matthias Kretz <kretz@kde.org>
58 */
59 class PHONONEXPERIMENTAL_EXPORT AudioDataOutput : public AbstractAudioOutput
60 {
61 Q_OBJECT
62 P_DECLARE_PRIVATE(AudioDataOutput)
63 Q_ENUMS(Channel Format)
64 Q_PROPERTY(Format format READ format WRITE setFormat)
65 Q_PROPERTY(int dataSize READ dataSize WRITE setDataSize)
66 PHONON_HEIR(AudioDataOutput)
67 public:
68 /**
69 * Specifies the channel the audio data belongs to.
70 */
71 enum Channel
72 {
73 LeftChannel,
74 RightChannel,
75 CenterChannel,
76 LeftSurroundChannel,
77 RightSurroundChannel,
78 SubwooferChannel
79 };
80
81 /**
82 * Used for telling the object whether you want 16 bit Integers or
83 * 32 bit floats.
84 *
85 * \see requestFormat
86 */
87 enum Format
88 {
89 /**
90 * Requests 16 bit signed integers.
91 *
92 * \see dataReady(const QVector<qint16> &)
93 */
94 IntegerFormat = 1,
95 /**
96 * Requests 32 bit floating point: signed, zero centered, and
97 * normalized to the unit value (-1.0 to 1.0).
98 *
99 * \see dataReady(const QVector<float> &)
100 */
101 FloatFormat = 2
102 };
103
104 /**
105 * Returns the currently used format.
106 *
107 * \see setFormat
108 */
109 Format format() const;
110
111 /**
112 * Returns the currently used number of samples passed through
113 * the signal.
114 *
115 * \see setDataSize
116 */
117 int dataSize() const;
118
119 /**
120 * Returns the sample rate in Hz. Common sample rates are 44100 Hz
121 * and 48000 Hz. AudioDataOutput will not do any sample rate
122 * conversion for you. If you need to convert the sample rate you
123 * might want to take a look at libsamplerate. For visualizations it
124 * is often enough to do simple interpolation or even drop/duplicate
125 * samples.
126 *
127 * \return The sample rate as reported by the backend. If the
128 * backend is unavailable -1 is returned.
129 */
130 int sampleRate() const;
131
132 public Q_SLOTS:
133 /**
134 * Requests the dataformat you'd like to receive. Only one of the
135 * signals of this class will be emitted when new data is ready.
136 *
137 * The default format is IntegerFormat.
138 *
139 * \see format()
140 */
141 void setFormat(Format format);
142
143 /**
144 * Sets the number of samples to be passed in one signal emission.
145 *
146 * Defaults to 512 samples per emitted signal.
147 *
148 * \param size the number of samples
149 */
150 void setDataSize(int size);
151
152 Q_SIGNALS:
153 /**
154 * Emitted whenever another dataSize number of samples are ready and
155 * format is set to IntegerFormat.
156 *
157 * If format is set to FloatFormat the signal is not emitted at all.
158 *
159 * \param data A mapping of Channel to a vector holding the audio data.
160 */
161 void dataReady(const QMap<Phonon::Experimental::AudioDataOutput::Channel, QVector<qint16> > &data);
162
163 /**
164 * Emitted whenever another dataSize number of samples are ready and
165 * format is set to FloatFormat.
166 *
167 * If format is set to IntegerFormat the signal is not emitted at all.
168 *
169 * \param data A mapping of Channel to a vector holding the audio data.
170 */
171 void dataReady(const QMap<Phonon::Experimental::AudioDataOutput::Channel, QVector<float> > &data);
172
173 /**
174 * This signal is emitted before the last dataReady signal of a
175 * media is emitted.
176 *
177 * If, for example, the playback of a media file has finished and the
178 * last audio data of that file is going to be passed with the next
179 * dataReady signal, and only the 28 first samples of the data
180 * vector are from that media file endOfMedia will be emitted right
181 * before dataReady with \p remainingSamples = 28.
182 *
183 * \param remainingSamples The number of samples in the next
184 * dataReady vector that belong to the media that was playing to
185 * this point.
186 */
187 void endOfMedia(int remainingSamples);
188 };
189} // namespace Experimental
190} // namespace Phonon
191
192// vim: sw=4 ts=4 tw=80
193#endif // Phonon_AUDIODATAOUTPUT_H
194

source code of phonon/phonon/experimental/audiodataoutput.h