Changes to QAudioBuffer and QAudioDecoder (position and duration).

QAudioBuffer:
- Allow to specify startTime in the constructor.
QAudioDecoder:
- Removed WaitingState.
- New signals: finished(), positionChanged(), durationChanged().
- New methods: position(), duration().
- A parameter removed from read() method.

Change-Id: Ifb71502d0756aa306abd0a6bf7873934029952c4
Reviewed-by: Dmytro Poplavskiy <dmytro.poplavskiy@nokia.com>
Reviewed-by: Michael Goddard <michael.goddard@nokia.com>

src/multimedia/audio/qaudiobuffer.cpp

@@ -242,12 +242,16 @@ QAudioBuffer::QAudioBuffer(const QAudioBuffer &other)
     calculated sample size, the excess data will not be used.
 
     This audio buffer will copy the contents of \a data.
+
+    \a startTime (in microseconds) indicates when this buffer
+    starts in the stream.
+    If this buffer is not part of a stream, set it to -1.
  */
-QAudioBuffer::QAudioBuffer(const QByteArray &data, const QAudioFormat &format)
+QAudioBuffer::QAudioBuffer(const QByteArray &data, const QAudioFormat &format, qint64 startTime)
 {
     if (format.isValid()) {
         int sampleCount = (data.size() * 8) / format.sampleSize(); // truncate
-        d = new QAudioBufferPrivate(new QMemoryAudioBufferProvider(data.constData(), sampleCount, format, -1));
+        d = new QAudioBufferPrivate(new QMemoryAudioBufferProvider(data.constData(), sampleCount, format, startTime));
     } else
         d = 0;
 }
@@ -256,10 +260,17 @@ QAudioBuffer::QAudioBuffer(const QByteArray &data, const QAudioFormat &format)
     Creates a new audio buffer with space for \a numSamples samples of
     the given \a format.  The samples will be initialized to the default
     for the format.
+
+    \a startTime (in microseconds) indicates when this buffer
+    starts in the stream.
+    If this buffer is not part of a stream, set it to -1.
  */
-QAudioBuffer::QAudioBuffer(int numSamples, const QAudioFormat &format)
+QAudioBuffer::QAudioBuffer(int numSamples, const QAudioFormat &format, qint64 startTime)
-    : d(new QAudioBufferPrivate(new QMemoryAudioBufferProvider(0, numSamples, format, -1)))
 {
+    if (format.isValid())
+        d = new QAudioBufferPrivate(new QMemoryAudioBufferProvider(0, numSamples, format, startTime));
+    else
+        d = 0;
 }
 
 /*!

src/multimedia/audio/qaudiobuffer.h

@@ -64,8 +64,8 @@ public:
     QAudioBuffer();
     QAudioBuffer(QAbstractAudioBuffer *provider);
     QAudioBuffer(const QAudioBuffer &other);
-    QAudioBuffer(const QByteArray &data, const QAudioFormat &format);
+    QAudioBuffer(const QByteArray &data, const QAudioFormat &format, qint64 startTime = -1);
-    QAudioBuffer(int numSamples, const QAudioFormat &format); // Initialized to empty
+    QAudioBuffer(int numSamples, const QAudioFormat &format, qint64 startTime = -1); // Initialized to empty
 
     QAudioBuffer& operator=(const QAudioBuffer &other);
 

src/multimedia/audio/qaudiodecoder_p.cpp

@@ -152,6 +152,9 @@ QAudioDecoder::QAudioDecoder(QObject *parent)
             connect(d->control, SIGNAL(sourceChanged()), SIGNAL(sourceChanged()));
             connect(d->control, SIGNAL(bufferReady()), this, SIGNAL(bufferReady()));
             connect(d->control ,SIGNAL(bufferAvailableChanged(bool)), this, SIGNAL(bufferAvailableChanged(bool)));
+            connect(d->control ,SIGNAL(finished()), this, SIGNAL(finished()));
+            connect(d->control ,SIGNAL(positionChanged(qint64)), this, SIGNAL(positionChanged(qint64)));
+            connect(d->control ,SIGNAL(durationChanged(qint64)), this, SIGNAL(durationChanged(qint64)));
         }
     }
 }
@@ -377,17 +380,42 @@ bool QAudioDecoder::bufferAvailable() const
 }
 
 /*!
-    Read a buffer from the decoder, with the success or failure stored in \a ok.
+    Returns position (in milliseconds) of the last buffer read from
+    the decoder or -1 if no buffers have been read.
 */
-QAudioBuffer QAudioDecoder::read(bool *ok) const
+
+qint64 QAudioDecoder::position() const
+{
+    Q_D(const QAudioDecoder);
+    if (d->control)
+        return d->control->position();
+    return -1;
+}
+
+/*!
+    Returns total duration (in milliseconds) of the audio stream or -1
+    if not available.
+*/
+
+qint64 QAudioDecoder::duration() const
+{
+    Q_D(const QAudioDecoder);
+    if (d->control)
+        return d->control->duration();
+    return -1;
+}
+
+/*!
+    Read a buffer from the decoder. Returns invalid buffer on failure.
+*/
+
+QAudioBuffer QAudioDecoder::read() const
 {
     Q_D(const QAudioDecoder);
 
     if (d->control) {
-        return d->control->read(ok);
+        return d->control->read();
     } else {
-        if (ok)
-            *ok = false;
         return QAudioBuffer();
     }
 }
@@ -401,8 +429,6 @@ QAudioBuffer QAudioDecoder::read(bool *ok) const
     \value DecodingState The audio player is currently decoding media.
     \value StoppedState The decoder is not decoding.  Decoding will
            start at the start of the media.
-    \value WaitingState The decoder is either waiting for more data
-           to decode, or has filled the required number of buffers.
 */
 
 /*!
@@ -466,6 +492,30 @@ QAudioBuffer QAudioDecoder::read(bool *ok) const
     \sa bufferAvailable(), bufferReady()
 */
 
+/*!
+    \fn void QAudioDecoder::finished()
+
+    Signals that the decoding has finished successfully.
+    If decoding fails, error signal is emitted instead.
+
+    \sa start(), stop(), error
+*/
+
+/*!
+    \fn void QAudioDecoder::positionChanged(qint64 position)
+
+    Signals that the current \a position of the decoder has changed.
+
+    \sa durationChanged
+*/
+
+/*!
+    \fn void QAudioDecoder::durationChanged(qint64 duration)
+
+    Signals that the estimated \a duration of the decoded data has changed.
+
+    \sa positionChanged
+*/
 
 
 // Properties

src/multimedia/audio/qaudiodecoder_p.h

@@ -69,8 +69,7 @@ public:
     enum State
     {
         StoppedState,
-        DecodingState,
+        DecodingState
-        WaitingState
     };
 
     enum Error
@@ -101,11 +100,12 @@ public:
     Error error() const;
     QString errorString() const;
 
-    // Do we need position or duration?
+    QAudioBuffer read() const;
-
-    QAudioBuffer read(bool *ok = 0) const;
     bool bufferAvailable() const;
 
+    qint64 position() const;
+    qint64 duration() const;
+
 public Q_SLOTS:
     void start();
     void stop();
@@ -113,6 +113,7 @@ public Q_SLOTS:
 Q_SIGNALS:
     void bufferAvailableChanged(bool);
     void bufferReady();
+    void finished();
 
     void stateChanged(QAudioDecoder::State newState);
     void formatChanged(const QAudioFormat &format);
@@ -121,6 +122,9 @@ Q_SIGNALS:
 
     void sourceChanged();
 
+    void positionChanged(qint64 position);
+    void durationChanged(qint64 duration);
+
 public:
     virtual bool bind(QObject *);
     virtual void unbind(QObject *);

src/multimedia/controls/qaudiodecodercontrol_p.cpp

@@ -189,7 +189,30 @@ QAudioDecoderControl::QAudioDecoderControl(QObject *parent):
     \sa audioFormat(), setAudioFormat
 */
 
+/*!
+    \fn void QAudioDecoderControl::finished()
 
+    Signals that the decoding has finished successfully.
+    If decoding fails, error signal is emitted instead.
+
+    \sa start(), stop(), error
+*/
+
+/*!
+    \fn void QAudioDecoderControl::positionChanged(qint64 position)
+
+    Signals that the current \a position of the decoder has changed.
+
+    \sa durationChanged
+*/
+
+/*!
+    \fn void QAudioDecoderControl::durationChanged(qint64 duration)
+
+    Signals that the estimated \a duration of the decoded data has changed.
+
+    \sa positionChanged
+*/
 
 /*!
     \fn QAudioDecoderControl::audioFormat()
@@ -215,6 +238,23 @@ QAudioDecoderControl::QAudioDecoderControl(QObject *parent):
     audio file, you can specify an invalid \a format.
 */
 
+/*!
+    \fn QAudioDecoderControl::read()
+    Read a buffer from the decoder. Returns invalid buffer on failure.
+*/
+
+/*!
+    \fn QAudioDecoderControl::position()
+    Returns position (in milliseconds) of the last buffer read from
+    the decoder or -1 if no buffers have been read.
+*/
+
+/*!
+    \fn QAudioDecoderControl::duration()
+    Returns total duration (in milliseconds) of the audio stream
+    or -1 if not available.
+*/
+
 #include "moc_qaudiodecodercontrol_p.cpp"
 QT_END_NAMESPACE
 

src/multimedia/controls/qaudiodecodercontrol_p.h

@@ -77,9 +77,12 @@ public:
     virtual QAudioFormat audioFormat() const = 0;
     virtual void setAudioFormat(const QAudioFormat &format) = 0;
 
-    virtual QAudioBuffer read(bool *ok) = 0;
+    virtual QAudioBuffer read() = 0;
     virtual bool bufferAvailable() const = 0;
 
+    virtual qint64 position() const = 0;
+    virtual qint64 duration() const = 0;
+
 Q_SIGNALS:
     void stateChanged(QAudioDecoder::State newState);
     void formatChanged(const QAudioFormat &format);
@@ -89,6 +92,10 @@ Q_SIGNALS:
 
     void bufferReady();
     void bufferAvailableChanged(bool available);
+    void finished();
+
+    void positionChanged(qint64 position);
+    void durationChanged(qint64 duration);
 
 protected:
     QAudioDecoderControl(QObject* parent = 0);