File indexing completed on 2024-05-05 04:44:40
0001 /* This file is part of the KDE project 0002 Copyright (C) 2005-2006 Matthias Kretz <kretz@kde.org> 0003 0004 This library is free software; you can redistribute it and/or 0005 modify it under the terms of the GNU Lesser General Public 0006 License as published by the Free Software Foundation; either 0007 version 2.1 of the License, or (at your option) version 3, or any 0008 later version accepted by the membership of KDE e.V. (or its 0009 successor approved by the membership of KDE e.V.), Nokia Corporation 0010 (or its successors, if any) and the KDE Free Qt Foundation, which shall 0011 act as a proxy defined in Section 6 of version 3 of the license. 0012 0013 This library is distributed in the hope that it will be useful, 0014 but WITHOUT ANY WARRANTY; without even the implied warranty of 0015 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 0016 Lesser General Public License for more details. 0017 0018 You should have received a copy of the GNU Lesser General Public 0019 License along with this library. If not, see <http://www.gnu.org/licenses/>. 0020 0021 */ 0022 #ifndef Phonon_AUDIODATAOUTPUT_H 0023 #define Phonon_AUDIODATAOUTPUT_H 0024 0025 #include "export.h" 0026 #include "../abstractaudiooutput.h" 0027 #include "../phonondefs.h" 0028 0029 #ifndef DOXYGEN_SHOULD_SKIP_THIS 0030 #if QT_VERSION < QT_VERSION_CHECK(6, 0, 0) 0031 template<typename T> class QVector; 0032 #else 0033 template<typename T> class QList; 0034 #endif 0035 template<typename Key, typename T> class QMap; 0036 #endif 0037 0038 namespace Phonon 0039 { 0040 namespace Experimental 0041 { 0042 class AudioDataOutputPrivate; 0043 0044 /** 0045 * \short This class gives you the audio data (for visualizations). 0046 * 0047 * This class implements a special AbstractAudioOutput that gives your 0048 * application the audio data. Don't expect realtime performance. But 0049 * the latencies should be low enough to use the audio data for 0050 * visualizations. You can also use the audio data for further processing 0051 * (e.g. encoding and saving to a file). 0052 * 0053 * The class supports different data formats. One of the most common formats 0054 * is to read vectors of integers (which will only use 16 Bit), but you can 0055 * also request floats which some backends use internally. 0056 * 0057 * \author Matthias Kretz <kretz@kde.org> 0058 */ 0059 class PHONONEXPERIMENTAL_EXPORT AudioDataOutput : public AbstractAudioOutput 0060 { 0061 Q_OBJECT 0062 P_DECLARE_PRIVATE(AudioDataOutput) 0063 Q_ENUMS(Channel Format) 0064 Q_PROPERTY(Format format READ format WRITE setFormat) 0065 Q_PROPERTY(int dataSize READ dataSize WRITE setDataSize) 0066 PHONON_HEIR(AudioDataOutput) 0067 public: 0068 /** 0069 * Specifies the channel the audio data belongs to. 0070 */ 0071 enum Channel 0072 { 0073 LeftChannel, 0074 RightChannel, 0075 CenterChannel, 0076 LeftSurroundChannel, 0077 RightSurroundChannel, 0078 SubwooferChannel 0079 }; 0080 0081 /** 0082 * Used for telling the object whether you want 16 bit Integers or 0083 * 32 bit floats. 0084 * 0085 * \see requestFormat 0086 */ 0087 enum Format 0088 { 0089 /** 0090 * Requests 16 bit signed integers. 0091 * 0092 * \see dataReady(const QVector<qint16> &) 0093 */ 0094 IntegerFormat = 1, 0095 /** 0096 * Requests 32 bit floating point: signed, zero centered, and 0097 * normalized to the unit value (-1.0 to 1.0). 0098 * 0099 * \see dataReady(const QVector<float> &) 0100 */ 0101 FloatFormat = 2 0102 }; 0103 0104 /** 0105 * Returns the currently used format. 0106 * 0107 * \see setFormat 0108 */ 0109 Format format() const; 0110 0111 /** 0112 * Returns the currently used number of samples passed through 0113 * the signal. 0114 * 0115 * \see setDataSize 0116 */ 0117 int dataSize() const; 0118 0119 /** 0120 * Returns the sample rate in Hz. Common sample rates are 44100 Hz 0121 * and 48000 Hz. AudioDataOutput will not do any sample rate 0122 * conversion for you. If you need to convert the sample rate you 0123 * might want to take a look at libsamplerate. For visualizations it 0124 * is often enough to do simple interpolation or even drop/duplicate 0125 * samples. 0126 * 0127 * \return The sample rate as reported by the backend. If the 0128 * backend is unavailable -1 is returned. 0129 */ 0130 int sampleRate() const; 0131 0132 public Q_SLOTS: 0133 /** 0134 * Requests the dataformat you'd like to receive. Only one of the 0135 * signals of this class will be emitted when new data is ready. 0136 * 0137 * The default format is IntegerFormat. 0138 * 0139 * \see format() 0140 */ 0141 void setFormat(Format format); 0142 0143 /** 0144 * Sets the number of samples to be passed in one signal emission. 0145 * 0146 * Defaults to 512 samples per emitted signal. 0147 * 0148 * \param size the number of samples 0149 */ 0150 void setDataSize(int size); 0151 0152 Q_SIGNALS: 0153 /** 0154 * Emitted whenever another dataSize number of samples are ready and 0155 * format is set to IntegerFormat. 0156 * 0157 * If format is set to FloatFormat the signal is not emitted at all. 0158 * 0159 * \param data A mapping of Channel to a vector holding the audio data. 0160 */ 0161 void dataReady(const QMap<Phonon::Experimental::AudioDataOutput::Channel, QVector<qint16> > &data); 0162 0163 /** 0164 * Emitted whenever another dataSize number of samples are ready and 0165 * format is set to FloatFormat. 0166 * 0167 * If format is set to IntegerFormat the signal is not emitted at all. 0168 * 0169 * \param data A mapping of Channel to a vector holding the audio data. 0170 */ 0171 void dataReady(const QMap<Phonon::Experimental::AudioDataOutput::Channel, QVector<float> > &data); 0172 0173 /** 0174 * This signal is emitted before the last dataReady signal of a 0175 * media is emitted. 0176 * 0177 * If, for example, the playback of a media file has finished and the 0178 * last audio data of that file is going to be passed with the next 0179 * dataReady signal, and only the 28 first samples of the data 0180 * vector are from that media file endOfMedia will be emitted right 0181 * before dataReady with \p remainingSamples = 28. 0182 * 0183 * \param remainingSamples The number of samples in the next 0184 * dataReady vector that belong to the media that was playing to 0185 * this point. 0186 */ 0187 void endOfMedia(int remainingSamples); 0188 }; 0189 } // namespace Experimental 0190 } // namespace Phonon 0191 0192 // vim: sw=4 ts=4 tw=80 0193 #endif // Phonon_AUDIODATAOUTPUT_H