CopperSpice API  1.9.1
QAudioOutput Class Reference

The QAudioOutput class provides an interface for sending audio data to an audio output device. More...

Inheritance diagram for QAudioOutput:
QObject

Public Signals

void notify ()
 
void stateChanged (QAudio::State state)
 
- Public Signals inherited from QObject
void destroyed (QObject *obj=nullptr)
 
void objectNameChanged (const QString &objectName)
 

Public Methods

 QAudioOutput (const QAudioDeviceInfo &audioDeviceInfo, const QAudioFormat &format=QAudioFormat (), QObject *parent=nullptr)
 
 QAudioOutput (const QAudioFormat &format=QAudioFormat (), QObject *parent=nullptr)
 
 ~QAudioOutput ()
 
int bufferSize () const
 
int bytesFree () const
 
QString category () const
 
qint64 elapsedUSecs () const
 
QAudio::Error error () const
 
QAudioFormat format () const
 
int notifyInterval () const
 
int periodSize () const
 
qint64 processedUSecs () const
 
void reset ()
 
void resume ()
 
void setBufferSize (int bytes)
 
void setCategory (const QString &category)
 
void setNotifyInterval (int milliSeconds)
 
void setVolume (qreal volume)
 
QIODevicestart ()
 
void start (QIODevice *device)
 
QAudio::State state () const
 
void stop ()
 
void suspend ()
 
qreal volume () const
 
- Public Methods inherited from QObject
 QObject (QObject *parent=nullptr)
 
 ~QObject ()
 
bool blockSignals (bool block)
 
const QList< QObject * > & children () const
 
bool connect (const QObject *sender, const QString &signalMethod, const QString &location, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)
 
bool connect (const QObject *sender, const QString &signalMethod, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)
 
bool disconnect (const QObject *receiver, const QString &slotMethod=QString ()) const
 
bool disconnect (const QString &signalMethod, const QString &location, const QObject *receiver=nullptr, const QString &slotMethod=QString ()) const
 
bool disconnect (const QString &signalMethod=QString (), const QObject *receiver=nullptr, const QString &slotMethod=QString ()) const
 
void dumpObjectInfo ()
 
void dumpObjectTree ()
 
QList< QStringdynamicPropertyNames () const
 
virtual bool event (QEvent *event)
 
virtual bool eventFilter (QObject *watched, QEvent *event)
 
template<typename T >
findChild (const QString &childName=QString ()) const
 
template<class T >
QList< T > findChildren (const QRegularExpression &regExp, Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
 
template<class T >
QList< T > findChildren (const QString &childName=QString (), Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
 
bool inherits (const QString &className) const
 
void installEventFilter (QObject *filterObj)
 
bool isWidgetType () const
 
bool isWindowType () const
 
void killTimer (int id)
 
const QMetaObjectmetaObject () const
 
void moveToThread (QThread *targetThread)
 
QString objectName () const
 
QObject * parent () const
 
template<class T = QVariant>
property (const QString &name) const
 
void removeEventFilter (QObject *obj)
 
void setObjectName (const QString &name)
 
void setParent (QObject *parent)
 
bool setProperty (const QString &name, const QVariant &value)
 
bool signalsBlocked () const
 
int startTimer (int interval, Qt::TimerType timerType=Qt::CoarseTimer)
 
QThreadthread () const
 

Additional Inherited Members

- Public Slots inherited from QObject
void deleteLater ()
 
- Static Public Methods inherited from QObject
static bool connect (const QObject *sender, const QMetaMethod &signalMethod, const QObject *receiver, const QMetaMethod &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)
 
static bool connect (const QObject *sender, const QString &signalMethod, const QObject *receiver, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection, const QString &location=QString ())
 
static bool connect (const QObject *sender, const QString &signalMethod, const QString &location, const QObject *receiver, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class SlotClass , class... SlotArgs, class SlotReturn >
static bool connect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, SlotReturn (SlotClass::*slotMethod)(SlotArgs...), Qt::ConnectionType type=Qt::AutoConnection)
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class T >
static bool connect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, T slotLambda, Qt::ConnectionType type=Qt::AutoConnection)
 
static bool disconnect (const QObject *sender, const QMetaMethod &signalMethod, const QObject *receiver, const QMetaMethod &slotMethod)
 
static bool disconnect (const QObject *sender, const QString &signalMethod, const QObject *receiver, const QString &slotMethod)
 
static bool disconnect (const QObject *sender, const QString &signalMethod, const QString &location, const QObject *receiver, const QString &slotMethod)
 
static bool disconnect (const QObject *sender, std::nullptr_t, const QObject *receiver, std::nullptr_t)
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class SlotClass , class... SlotArgs, class SlotReturn >
static bool disconnect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, SlotReturn (SlotClass::*slotMethod)(SlotArgs...))
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver >
static bool disconnect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, std::nullptr_t slotMethod=nullptr)
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class T >
static bool disconnect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, T slotMethod)
 
static QMetaObjectstaticMetaObject ()
 
static QString tr (const char *text, const char *comment=nullptr, std::optional< int > numArg=std::optional< int >())
 
- Protected Methods inherited from QObject
virtual void childEvent (QChildEvent *event)
 
virtual void connectNotify (const QMetaMethod &signalMethod) const
 
virtual void customEvent (QEvent *event)
 
virtual void disconnectNotify (const QMetaMethod &signalMethod) const
 
bool isSignalConnected (const QMetaMethod &signalMethod) const
 
int receivers (const QString &signal) const
 
QObject * sender () const
 
int senderSignalIndex () const
 
virtual void timerEvent (QTimerEvent *event)
 
- Properties inherited from QObject
 objectName
 

Detailed Description

The QAudioOutput class provides an interface for sending audio data to an audio output device.

You can construct an audio output with the system's default audio output device, QAudioDeviceInfo::defaultOutputDevice(). It is also possible to create QAudioOutput with a specific QAudioDeviceInfo. When creating the audio output you should also set the QAudioFormat be used for the playback. Refer to the QAudioFormat class description for further details.

The following example shows how to play a file. Starting to play an audio stream involves calling start() with a QIODevice and then using this class to fetch the data it needs from the io device. The file will start playing assuming the audio system and output device support playback. If there is a problem you can check the error() method.

QFile inputFile;
QAudioOutput *audioOutput;
void startPlaying() {
inputFile.setFileName("/tmp/test.raw");
inputFile.open(QIODevice::ReadOnly);
format.setFrequency(8000);
format.setChannels(1);
format.setSampleSize(8);
format.setCodec("audio/pcm");
format.setByteOrder(QAudioFormat::LittleEndian);
format.setSampleType(QAudioFormat::UnSignedInt);
if (! info.isFormatSupported(format)) {
qWarning() << "Raw audio format is not supported by this plugin backend, unable to play.";
return;
}
audioOutput = new QAudioOutput(format, this);
connect(audioOutput, SIGNAL(stateChanged(QAudio::State)), SLOT(finishedPlaying(QAudio::State)));
audioOutput->start(&inputFile);
}

After the audio file has finished playing ensure the device is stopped. This slot method can be enhanced to test for other states with the appropriate necessary actions.

void finishedPlaying(QAudio::State newState) {
if (newState == QAudio::IdleState) {
// finished playing, no more data
audioOutput->stop();
inputFile.close();
delete audioOutput;
}
}

At any given time the QAudioOutput will be in one of four states: active, suspended, stopped, or idle. These states are described by the QAudio::State enum. State changes are reported through the stateChanged() signal. You can use this signal to update the user interface as needed. For example, to change the display to indicate the state has changed from Playing to Paused. The state can also be changed within your application by directly calling suspend(), stop(), reset(), resume(), or start().

While the stream is playing you can set a notify interval in milliseconds with setNotifyInterval(). This interval specifies the time between two emissions of the notify() signal. This is relative to the position in the stream. If the QAudioOutput is in the SuspendedState or the IdleState the notify() signal is not emitted. A typical use case would be to update a slider that allows seeking in the stream. If you want the time since playback started regardless of which states the audio output has been in, call the elapsedUSecs() method.

If an error occurs retrieve the error type with the error() method. Refer to the QAudio::Error enum for a description of the possible errors. When an error occurs the state automatically changes to QAudio::StoppedState. You can check for errors by connecting to the stateChanged() signal.

void stateChanged(QAudio::State newState) {
switch (newState) {
case QAudio::StoppedState:
if (audioOutput->error() != QAudio::NoError) {
// error handling
} else {
// normal stop
}
break;
default:
// some other state
break;
}
}
See also
QAudioInput, QAudioDeviceInfo

Constructor & Destructor Documentation

QAudioOutput::QAudioOutput ( const QAudioFormat format = QAudioFormat(),
QObject parent = nullptr 
)
explicit

Construct a new audio output and attach it to parent. The default audio output device is used with the output format parameters.

QAudioOutput::QAudioOutput ( const QAudioDeviceInfo audioDeviceInfo,
const QAudioFormat format = QAudioFormat(),
QObject parent = nullptr 
)
explicit

Construct a new audio output and attach it to parent. The device referenced by audioDeviceInfo is used with the output format parameters.

QAudioOutput::~QAudioOutput ( )

Destroys this audio output.

Method Documentation

int QAudioOutput::bufferSize ( ) const

Returns the audio buffer size in bytes.

If called before start() then this method returns a platform default value. If called before start() but setBufferSize() was called prior, returns the value set by insufferable().

If this method is called after start() it returns the actual buffer size being used. This value may not match the value requested by previously calling setBufferSize().

See also
setBufferSize()
int QAudioOutput::bytesFree ( ) const

Returns the free space available in bytes in the audio buffer. The returned value is only valid while in QAudio::ActiveState or QAudio::IdleState state, otherwise returns zero.

QString QAudioOutput::category ( ) const

Returns the value of the property.

qint64 QAudioOutput::elapsedUSecs ( ) const

Returns the microseconds since start() was called, including time in Idle and Suspend states.

QAudio::Error QAudioOutput::error ( ) const

Returns the error state.

QAudioFormat QAudioOutput::format ( ) const

Returns the QAudioFormat being used.

void QAudioOutput::notify ( )
signal

This signal is emitted when x ms of audio data has been processed the interval set by setNotifyInterval(x).

int QAudioOutput::notifyInterval ( ) const

Returns the notify interval in milliseconds.

See also
setNotifyInterval()
int QAudioOutput::periodSize ( ) const

Returns the period size in bytes. This is the recommended write size in bytes.

qint64 QAudioOutput::processedUSecs ( ) const

Returns the amount of audio data processed by the class since start() was called in microseconds. The amount of audio data played can be determined by subtracting the microseconds of audio data still in the systems audio buffer.

qint64 bytesInBuffer = bufferSize() - bytesFree();
qint64 usInBuffer = (qint64)(1000000) * bytesInBuffer / ( channels() * sampleSize() / 8 ) / frequency();
qint64 usPlayed = processedUSecs() - usInBuffer;
void QAudioOutput::reset ( )

Drops all audio data in the buffers, resets buffers to zero.

void QAudioOutput::resume ( )

Resumes processing audio data after a suspend().

Sets error() to QAudio::NoError. Sets state() to QAudio::ActiveState if you previously called start(QIODevice*). Sets state() to QAudio::IdleState if you previously called start(). emits stateChanged() signal.

This signal will always be emitted during execution of the resume() method.

void QAudioOutput::setBufferSize ( int  bytes)

Sets the audio buffer size to the given bytes.

This method can be called anytime before start(), calls to this are ignored after start(). It should not be assumed that the buffer size set is the actual buffer size used, calling bufferSize() anytime after start() will return the actual buffer size being used.

See also
bufferSize()
void QAudioOutput::setCategory ( const QString category)

Sets the value of the property to category.

void QAudioOutput::setNotifyInterval ( int  milliSeconds)

Sets the interval for notify() signal to be emitted. This is based on the milliSeconds of audio data processed not on actual real-time. The minimum resolution of the timer is platform specific and values should be checked with notifyInterval() to confirm actual value being used.

See also
notifyInterval()
void QAudioOutput::setVolume ( qreal  volume)

Sets the value of the property to volume.

QIODevice * QAudioOutput::start ( )

Returns a pointer to the QIODevice being used to handle the data transfer. This QIODevice can be used to write() audio data directly.

If audio data is successfully transmitted to the given device, then the state is set to QAudio::ActiveState. The error state will be set to QAudio::NoError and the stateChanged() signal is emitted. If a problem occurs during this process the error() is set to QAudio::OpenError, state() is set to QAudio::StoppedState and stateChanged() signal is emitted.

The stateChanged() signal may be emitted either synchronously during execution of start() or asynchronously after start() has returned to the caller.

See also
QIODevice
void QAudioOutput::start ( QIODevice device)

Uses the device as the QIODevice to transfer data. Passing a QIODevice allows the data to be transferred without any extra code. All that is required is to open the QIODevice.

If audio data is successfully transmitted to the given device, then the state is set to QAudio::ActiveState. The error state will be set to QAudio::NoError and the stateChanged() signal is emitted. If a problem occurs during this process the error() is set to QAudio::OpenError, state() is set to QAudio::StoppedState and stateChanged() signal is emitted.

The stateChanged() signal may be emitted either synchronously during execution of start() or asynchronously after start() has returned to the caller.

See also
QIODevice
QAudio::State QAudioOutput::state ( ) const

Returns the state of audio processing.

void QAudioOutput::stateChanged ( QAudio::State  state)
signal

This signal is emitted when the device state has changed. This is the current state of the audio output.

void QAudioOutput::stop ( )

Stops the audio output, detaching from the system resource.

Sets error() to QAudio::NoError, state() to QAudio::StoppedState and emit stateChanged() signal.

void QAudioOutput::suspend ( )

Stops processing audio data, preserving buffered audio data. Sets error() to QAudio::NoError, state() to QAudio::SuspendedState and emit stateChanged() signal.

qreal QAudioOutput::volume ( ) const

Returns the value of the property.