Contents

• Public Functions
• Signals
• Detailed Description

Detailed Description

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

You can construct an audio output with the system'sdefault audio output device. It is also possible to createQAudioOutput with a specificQAudioDeviceInfo. When you create the audio output, you should also send in theQAudioFormat to be used for the playback (see theQAudioFormat class description for details).

To play a file:

Starting to play an audio stream is simply a matter of callingstart() with aQIODevice.QAudioOutput will then fetch the data it needs from the io device. So playing back an audio file is as simple as:

QFile inputFile;// class member.QAudioOutput*audioOutput;// class member.    ...void startPlaying()    {        inputFile.setFileName("/tmp/test.raw");        inputFile.open(QIODevice::ReadOnly);QAudioFormat format;// Set up the format, eg.        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 not supported by backend, cannot play audio.";return;        }        audioOutput=newQAudioOutput(format,this);        connect(audioOutput,SIGNAL(stateChanged(QAudio::State)),SLOT(finishedPlaying(QAudio::State)));        audioOutput->start(&inputFile);    }

The file will start playing assuming that the audio system and output device support it. If you run out of luck, check what's up with theerror() function.

After the file has finished playing, we need to stop the device:

void finishedPlaying(QAudio::State state)    {if (state==QAudio::IdleState) {            audioOutput->stop();            inputFile.close();delete audioOutput;        }    }

At any given time, theQAudioOutput will be in one of four states: active, suspended, stopped, or idle. These states are described by theQAudio::State enum. State changes are reported through thestateChanged() signal. You can use this signal to, for instance, update the GUI of the application; the mundane example here being changing the state of aplay/pause button. You request a state change directly withsuspend(),stop(),reset(),resume(), andstart().

While the stream is playing, you can set a notify interval in milliseconds withsetNotifyInterval(). This interval specifies the time between two emissions of thenotify() signal. This is relative to the position in the stream, i.e., if theQAudioOutput is in the SuspendedState or the IdleState, thenotify() signal is not emitted. A typical use-case would be to update aslider that allows seeking in the stream. If you want the time since playback started regardless of which states the audio output has been in,elapsedUSecs() is the function for you.

If an error occurs, you can fetch theerror type with theerror() function. Please see theQAudio::Error enum for a description of the possible errors that are reported. When an error is encountered, the state changes toQAudio::StoppedState. You can check for errors by connecting to thestateChanged() signal:

void stateChanged(QAudio::State newState)    {switch (newState) {caseQAudio::StoppedState:if (audioOutput->error()!=QAudio::NoError) {// Perform error handling                }else {// Normal stop                }break;

Member Function Documentation

QAudioOutput::QAudioOutput(constQAudioFormat & format = QAudioFormat(),QObject * parent = 0)

Construct a new audio output and attach it toparent. The default audio output device is used with the outputformat parameters.

QAudioOutput::QAudioOutput(constQAudioDeviceInfo & audioDevice, constQAudioFormat & format = QAudioFormat(),QObject * parent = 0)

Construct a new audio output and attach it toparent. The device referenced byaudioDevice is used with the outputformat parameters.

QAudioOutput::~QAudioOutput()

Destroys this audio output.

int QAudioOutput::bufferSize() const

Returns the audio buffer size in bytes.

If called beforestart(), returns platform default value. If called beforestart() butsetBufferSize() was called prior, returns value set bysetBufferSize(). If called afterstart(), returns the actual buffer size being used. This may not be what was set previously bysetBufferSize().

See alsosetBufferSize().

int QAudioOutput::bytesFree() const

Returns the free space available in bytes in the audio buffer.

NOTE: returned value is only valid while inQAudio::ActiveState orQAudio::IdleState state, otherwise returns zero.

qint64 QAudioOutput::elapsedUSecs() const

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

QAudio::Error QAudioOutput::error() const

Returns the error state.

QAudioFormat QAudioOutput::format() const

Returns theQAudioFormat being used.

[signal]void QAudioOutput::notify()

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

int QAudioOutput::notifyInterval() const

Returns the notify interval in milliseconds.

See alsosetNotifyInterval().

int QAudioOutput::periodSize() const

Returns the period size in bytes.

Note: This is the recommended write size in bytes.

qint64 QAudioOutput::processedUSecs() const

Returns the amount of audio data processed by the class sincestart() was called in microseconds.

Note: 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 asuspend().

Setserror() toQAudio::NoError. Setsstate() toQAudio::ActiveState if you previously called start(QIODevice*). Setsstate() toQAudio::IdleState if you previously calledstart(). emitsstateChanged() signal.

Note: signal will always be emitted during execution of the resume() function.

void QAudioOutput::setBufferSize(int value)

Sets the audio buffer size tovalue in bytes.

Note: This function can be called anytime beforestart(), calls to this are ignored afterstart(). It should not be assumed that the buffer size set is the actual buffer size used, callingbufferSize() anytime afterstart() will return the actual buffer size being used.

See alsobufferSize().

void QAudioOutput::setNotifyInterval(int ms)

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

See alsonotifyInterval().

void QAudioOutput::start(QIODevice * device)

Uses thedevice as theQIODevice to transfer data. Passing aQIODevice allows the data to be transferred without any extra code. All that is required is to open theQIODevice.

If able to successfully output audio data to the systems audio device thestate() is set toQAudio::ActiveState,error() is set toQAudio::NoError and thestateChanged() signal is emitted.

If a problem occurs during this process theerror() is set toQAudio::OpenError,state() is set toQAudio::StoppedState andstateChanged() signal is emitted.

In either case, thestateChanged() signal may be emitted either synchronously during execution of the start() function or asynchronously after start() has returned to the caller.

See alsoQIODevice.

QIODevice * QAudioOutput::start()

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

If able to access the systems audio device thestate() is set toQAudio::IdleState,error() is set toQAudio::NoError and thestateChanged() signal is emitted.

If a problem occurs during this process theerror() is set toQAudio::OpenError,state() is set toQAudio::StoppedState andstateChanged() signal is emitted.

In either case, thestateChanged() signal may be emitted either synchronously during execution of thestart() function or asynchronously afterstart() has returned to the caller.

See alsoQIODevice.

QAudio::State QAudioOutput::state() const

Returns the state of audio processing.

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

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

void QAudioOutput::stop()

Stops the audio output, detaching from the system resource.

Setserror() toQAudio::NoError,state() toQAudio::StoppedState and emitstateChanged() signal.

void QAudioOutput::suspend()

Stops processing audio data, preserving buffered audio data.

Setserror() toQAudio::NoError,state() toQAudio::SuspendedState and emitstateChanged() signal.