QAudioDecoder Class

The QAudioDecoder class allows decoding audio. More...

Header: #include <QAudioDecoder>
qmake: QT += multimedia
Inherits: QMediaObject

This class is under development and is subject to change.

Public Types

enum Error { NoError, ResourceError, FormatError, AccessDeniedError, ServiceMissingError }
enum State { StoppedState, DecodingState }


Public Functions

QAudioDecoder(QObject *parent = nullptr)
virtual ~QAudioDecoder()
QAudioFormat audioFormat() const
bool bufferAvailable() const
qint64 duration() const
QAudioDecoder::Error error() const
QString errorString() const
qint64 position() const
QAudioBuffer read() const
void setAudioFormat(const QAudioFormat &format)
void setSourceDevice(QIODevice *device)
void setSourceFilename(const QString &fileName)
QIODevice *sourceDevice() const
QString sourceFilename() const
QAudioDecoder::State state() const

Public Slots

void start()
void stop()


void bufferAvailableChanged(bool available)
void bufferReady()
void durationChanged(qint64 duration)
void error(QAudioDecoder::Error error)
void finished()
void formatChanged(const QAudioFormat &format)
void positionChanged(qint64 position)
void sourceChanged()
void stateChanged(QAudioDecoder::State state)

Static Public Members

QMultimedia::SupportEstimate hasSupport(const QString &mimeType, const QStringList &codecs = QStringList())

Detailed Description

The QAudioDecoder class is a high level class for decoding local audio media files. It is similar to the QMediaPlayer class except that audio is provided back through this API rather than routed directly to audio hardware, and playlists and network and streaming based media is not supported.

See also QAudioBuffer.

Member Type Documentation

enum QAudioDecoder::Error

Defines a media player error condition.

QAudioDecoder::NoError0No error has occurred.
QAudioDecoder::ResourceError1A media resource couldn't be resolved.
QAudioDecoder::FormatError2The format of a media resource isn't supported.
QAudioDecoder::AccessDeniedError3There are not the appropriate permissions to play a media resource.
QAudioDecoder::ServiceMissingError4A valid playback service was not found, playback cannot proceed.

enum QAudioDecoder::State

Defines the current state of a media player.

QAudioDecoder::StoppedState0The decoder is not decoding. Decoding will start at the start of the media.
QAudioDecoder::DecodingState1The audio player is currently decoding media.

Property Documentation

bufferAvailable : const bool

This property holds whether there is a decoded audio buffer available

Access functions:

bool bufferAvailable() const

Notifier signal:

void bufferAvailableChanged(bool available)

error : const QString

This property holds a string describing the last error condition.

Access functions:

QString errorString() const

See also error().

sourceFilename : QString

This property holds the active filename being decoded by the decoder object.

Access functions:

QString sourceFilename() const
void setSourceFilename(const QString &fileName)

Notifier signal:

void sourceChanged()

state : const State

This property holds the audio decoder's playback state.

By default this property is QAudioDecoder::Stopped

Access functions:

QAudioDecoder::State state() const

Notifier signal:

void stateChanged(QAudioDecoder::State state)

See also start() and stop().

Member Function Documentation

QAudioDecoder::QAudioDecoder(QObject *parent = nullptr)

Construct an QAudioDecoder instance parented to parent.

[signal] void QAudioDecoder::bufferAvailableChanged(bool available)

Signals the availability (if available is true) of a new buffer.

If available is false, there are no buffers available.

Note: Notifier signal for property bufferAvailable.

See also bufferAvailable() and bufferReady().

[signal] void QAudioDecoder::bufferReady()

Signals that a new decoded audio buffer is available to be read.

See also read() and bufferAvailable().

[signal] void QAudioDecoder::durationChanged(qint64 duration)

Signals that the estimated duration of the decoded data has changed.

See also positionChanged().

[signal] void QAudioDecoder::error(QAudioDecoder::Error error)

Signals that an error condition has occurred.

Note: Signal error is overloaded in this class. To connect to this signal by using the function pointer syntax, Qt provides a convenient helper for obtaining the function pointer as shown in this example:

connect(audioDecoder, QOverload<QAudioDecoder::Error>::of(&QAudioDecoder::error),
    [=](QAudioDecoder::Error error){ /* ... */ });

See also errorString().

[signal] void QAudioDecoder::finished()

Signals that the decoding has finished successfully. If decoding fails, error signal is emitted instead.

See also start(), stop(), and error().

[signal] void QAudioDecoder::formatChanged(const QAudioFormat &format)

Signals that the current audio format of the decoder has changed to format.

See also audioFormat() and setAudioFormat().

[signal] void QAudioDecoder::positionChanged(qint64 position)

Signals that the current position of the decoder has changed.

See also durationChanged().

[signal] void QAudioDecoder::sourceChanged()

Signals that the current source of the decoder has changed.

Note: Notifier signal for property sourceFilename.

See also sourceFilename() and sourceDevice().

[slot] void QAudioDecoder::start()

Starts decoding the audio resource.

As data gets decoded, the bufferReady() signal will be emitted when enough data has been decoded. Calling read() will then return an audio buffer without blocking.

If you call read() before a buffer is ready, an invalid buffer will be returned, again without blocking.

See also read().

[signal] void QAudioDecoder::stateChanged(QAudioDecoder::State state)

Signal the state of the decoder object has changed.

Note: Notifier signal for property state.

[slot] void QAudioDecoder::stop()

Stop decoding audio. Calling start() again will resume decoding from the beginning.

[virtual] QAudioDecoder::~QAudioDecoder()

Destroys the audio decoder object.

QAudioFormat QAudioDecoder::audioFormat() const

Returns the current audio format of the decoded stream.

Any buffers returned should have this format.

See also setAudioFormat() and formatChanged().

bool QAudioDecoder::bufferAvailable() const

Returns true if a buffer is available to be read, and false otherwise. If there is no buffer available, calling the read() function will return an invalid buffer.

Note: Getter function for property bufferAvailable.

qint64 QAudioDecoder::duration() const

Returns total duration (in milliseconds) of the audio stream or -1 if not available.

QAudioDecoder::Error QAudioDecoder::error() const

Returns the current error state.

[static] QMultimedia::SupportEstimate QAudioDecoder::hasSupport(const QString &mimeType, const QStringList &codecs = QStringList())

Returns the level of support an audio decoder has for a mimeType and a set of codecs.

qint64 QAudioDecoder::position() const

Returns position (in milliseconds) of the last buffer read from the decoder or -1 if no buffers have been read.

QAudioBuffer QAudioDecoder::read() const

Read a buffer from the decoder, if one is available. Returns an invalid buffer if there are no decoded buffers currently available, or on failure. In both cases this function will not block.

You should either respond to the bufferReady() signal or check the bufferAvailable() function before calling read() to make sure you get useful data.

void QAudioDecoder::setAudioFormat(const QAudioFormat &format)

Set the desired audio format for decoded samples to format.

This property can only be set while the decoder is stopped. Setting this property at other times will be ignored.

If the decoder does not support this format, error() will be set to FormatError.

If you do not specify a format, the format of the decoded audio itself will be used. Otherwise, some format conversion will be applied.

If you wish to reset the decoded format to that of the original audio file, you can specify an invalid format.

See also audioFormat().

void QAudioDecoder::setSourceDevice(QIODevice *device)

Sets the current audio QIODevice to device.

When this property is set any current decoding is stopped, and any audio buffers are discarded.

You can only specify either a source filename or a source QIODevice. Setting one will unset the other.

See also sourceDevice().

void QAudioDecoder::setSourceFilename(const QString &fileName)

Sets the current audio file name to fileName.

When this property is set any current decoding is stopped, and any audio buffers are discarded.

You can only specify either a source filename or a source QIODevice. Setting one will unset the other.

Note: Setter function for property sourceFilename.

See also sourceFilename().

QIODevice *QAudioDecoder::sourceDevice() const

Returns the current source QIODevice, if one was set. If setSourceFilename() was called, this will be 0.

See also setSourceDevice().

QString QAudioDecoder::sourceFilename() const

Returns the current file name to decode. If setSourceDevice was called, this will be empty.

Note: Getter function for property sourceFilename.

See also setSourceFilename().

© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.