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

Inheritance diagram for QAudioOutput:

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)

QIODevice *	start ()

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< QString >	dynamicPropertyNames () const

virtual bool	event (QEvent *event)

virtual bool	eventFilter (QObject watched, QEvent event)

template<typename T >
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 QMetaObject *	metaObject () const

void	moveToThread (QThread *targetThread)

QString	objectName () const

QObject *	parent () const

template<class T = QVariant>
T	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)

QThread *	thread () 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 QMetaObject &	staticMetaObject ()

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

Related Functions inherited from QObject
T	qobject_cast (QObject *object)

	QObjectList

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);
 
   QAudioFormat format;
   format.setFrequency(8000);
   format.setChannels(1);
   format.setSampleSize(8);
   format.setCodec("audio/pcm");
   format.setByteOrder(QAudioFormat::LittleEndian);
   format.setSampleType(QAudioFormat::UnSignedInt);
 
   QAudioDeviceInfo info(QAudioDeviceInfo::defaultOutputDevice());
   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.

Public Signals

Public Methods

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

Method Documentation