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) |
31 | template<typename T> class QVector; |
32 | #else |
33 | template<typename T> class QList; |
34 | #endif |
35 | template<typename Key, typename T> class QMap; |
36 | #endif |
37 | |
38 | namespace Phonon |
39 | { |
40 | namespace 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 | |