QAudioOutput¶
The
QAudioOutput
class provides an interface for sending audio data to an audio output device. More…
Synopsis¶
Functions¶
def
bufferSize
()def
bytesFree
()def
category
()def
elapsedUSecs
()def
error
()def
format
()def
notifyInterval
()def
periodSize
()def
processedUSecs
()def
reset
()def
resume
()def
setBufferSize
(bytes)def
setCategory
(category)def
setNotifyInterval
(milliSeconds)def
setVolume
(arg__1)def
start
()def
start
(device)def
state
()def
stop
()def
suspend
()def
volume
()
Signals¶
def
notify
()def
stateChanged
(state)
Detailed Description¶
You can construct an audio output with the system’s
default 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 calling
start()
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 sourceFile; // class member. QAudioOutput* audio; // class member. { sourceFile.setFileName("/tmp/test.raw"); sourceFile.open(QIODevice::ReadOnly); QAudioFormat format; // Set up the format, eg. format.setSampleRate(8000); format.setChannelCount(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; } audio = new QAudioOutput(format, this); connect(audio, SIGNAL(stateChanged(QAudio::State)), this, SLOT(handleStateChanged(QAudio::State))); audio->start(&sourceFile); }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 the
error()
function.After the file has finished playing, we need to stop the device:
void AudioOutputExample::handleStateChanged(QAudio::State newState) { switch (newState) { case QAudio::IdleState: // Finished playing (no more data) audio->stop(); sourceFile.close(); delete audio; break; case QAudio::StoppedState: // Stopped for other reasons if (audio->error() != QAudio::NoError) { // Error handling } break; default: // ... other cases as appropriate break; } }At any given time, the
QAudioOutput
will be in one of four states: active, suspended, stopped, or idle. These states are described by theState
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 with
setNotifyInterval()
. 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 the
error type
with theerror()
function. Please see theError
enum for a description of the possible errors that are reported. When an error is encountered, the state changes toStoppedState
. You can check for errors by connecting to thestateChanged()
signal:void AudioOutputExample::handleStateChanged(QAudio::State newState) { switch (newState) { case QAudio::IdleState: // Finished playing (no more data) audio->stop(); sourceFile.close(); delete audio; break; case QAudio::StoppedState: // Stopped for other reasons if (audio->error() != QAudio::NoError) { // Error handling } break; default: // ... other cases as appropriate break; } }See also
- class PySide2.QtMultimedia.QAudioOutput(audioDeviceInfo[, format=QAudioFormat()[, parent=None]])¶
PySide2.QtMultimedia.QAudioOutput([format=QAudioFormat()[, parent=None]])
- param parent:
- param audioDeviceInfo:
- param format:
Construct a new audio output and attach it to
parent
. The device referenced byaudioDevice
is used with the outputformat
parameters.Construct a new audio output and attach it to
parent
. The default audio output device is used with the outputformat
parameters.
- PySide2.QtMultimedia.QAudioOutput.bufferSize()¶
- Return type:
int
Returns the audio buffer size in bytes.
If called before
start()
, 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 also
- PySide2.QtMultimedia.QAudioOutput.bytesFree()¶
- Return type:
int
Returns the number of free bytes available in the audio buffer.
Note
The returned value is only valid while in
ActiveState
orIdleState
state, otherwise returns zero.
- PySide2.QtMultimedia.QAudioOutput.category()¶
- Return type:
str
Returns the audio category of this audio stream.
Some platforms can group audio streams into categories and manage their volumes independently, or display them in a system mixer control. You can set this property to allow the platform to distinguish the purpose of your streams.
See also
- PySide2.QtMultimedia.QAudioOutput.elapsedUSecs()¶
- Return type:
int
Returns the microseconds since
start()
was called, including time in Idle and Suspend states.
- PySide2.QtMultimedia.QAudioOutput.format()¶
- Return type:
Returns the
QAudioFormat
being used.
- PySide2.QtMultimedia.QAudioOutput.notify()¶
- PySide2.QtMultimedia.QAudioOutput.notifyInterval()¶
- Return type:
int
Returns the notify interval in milliseconds.
See also
- PySide2.QtMultimedia.QAudioOutput.periodSize()¶
- Return type:
int
Returns the period size in bytes. This is the amount of data required each period to prevent buffer underrun, and to ensure uninterrupted playback.
Note
It is recommended to provide at least enough data for a full period with each write operation.
- PySide2.QtMultimedia.QAudioOutput.processedUSecs()¶
- Return type:
int
Returns the amount of audio data processed since
start()
was called (in microseconds).
- PySide2.QtMultimedia.QAudioOutput.reset()¶
Drops all audio data in the buffers, resets buffers to zero.
- PySide2.QtMultimedia.QAudioOutput.resume()¶
Resumes processing audio data after a
suspend()
.Sets
error()
toNoError
. Setsstate()
toActiveState
if you previously called start(QIODevice
*). Setsstate()
toIdleState
if you previously calledstart()
. emitsstateChanged()
signal.
- PySide2.QtMultimedia.QAudioOutput.setBufferSize(bytes)¶
- Parameters:
bytes – int
Sets the audio buffer size to
value
in bytes.Note
This function can be called anytime before
start()
. Calls to this are ignored afterstart()
. It should not be assumed that the buffer size set is the actual buffer size used - callbufferSize()
anytime afterstart()
to return the actual buffer size being used.See also
- PySide2.QtMultimedia.QAudioOutput.setCategory(category)¶
- Parameters:
category – str
Sets the audio category of this audio stream to
category
.Some platforms can group audio streams into categories and manage their volumes independently, or display them in a system mixer control. You can set this property to allow the platform to distinguish the purpose of your streams.
Not all platforms support audio stream categorization. In this case, the function call will be ignored.
Changing an audio output stream’s category while it is opened will not take effect until it is reopened.
See also
- PySide2.QtMultimedia.QAudioOutput.setNotifyInterval(milliSeconds)¶
- Parameters:
milliSeconds – int
Sets the interval for
notify()
signal to be emitted. This is based on thems
of audio data processed, not on wall clock time. The minimum resolution of the timer is platform specific and values should be checked withnotifyInterval()
to confirm the actual value being used.See also
- PySide2.QtMultimedia.QAudioOutput.setVolume(arg__1)¶
- Parameters:
arg__1 – float
Sets the output volume to
volume
.The volume is scaled linearly from
0.0
(silence) to1.0
(full volume). Values outside this range will be clamped.The default volume is
1.0
.Note: Adjustments to the volume will change the volume of this audio stream, not the global volume.
UI volume controls should usually be scaled nonlinearly. For example, using a logarithmic scale will produce linear changes in perceived loudness, which is what a user would normally expect from a volume control. See
convertVolume()
for more details.See also
- PySide2.QtMultimedia.QAudioOutput.start(device)¶
- Parameters:
device –
PySide2.QtCore.QIODevice
Starts transferring audio data from the
device
to the system’s audio output. Thedevice
must have been opened in theReadOnly
orReadWrite
modes.If the
QAudioOutput
is able to successfully output audio data,state()
returnsActiveState
,error()
returnsNoError
and thestateChanged()
signal is emitted.If a problem occurs during this process,
error()
returnsOpenError
,state()
returnsStoppedState
and thestateChanged()
signal is emitted.See also
QIODevice
- PySide2.QtMultimedia.QAudioOutput.start()
- Return type:
Returns a pointer to the internal
QIODevice
being used to transfer data to the system’s audio output. The device will already be open andwrite()
can write data directly to it.Note
The pointer will become invalid after the stream is stopped or if you start another stream.
If the
QAudioOutput
is able to access the system’s audio device,state()
returnsIdleState
,error()
returnsNoError
and thestateChanged()
signal is emitted.If a problem occurs during this process,
error()
returnsOpenError
,state()
returnsStoppedState
and thestateChanged()
signal is emitted.See also
QIODevice
- PySide2.QtMultimedia.QAudioOutput.state()¶
- Return type:
Returns the state of audio processing.
- PySide2.QtMultimedia.QAudioOutput.stop()¶
Stops the audio output, detaching from the system resource.
Sets
error()
toNoError
,state()
toStoppedState
and emitstateChanged()
signal.
- PySide2.QtMultimedia.QAudioOutput.suspend()¶
Stops processing audio data, preserving buffered audio data.
Sets
error()
toNoError
,state()
toSuspendedState
and emitsstateChanged()
signal.
- PySide2.QtMultimedia.QAudioOutput.volume()¶
- Return type:
float
Returns the volume between 0.0 and 1.0 inclusive.
See also
© 2022 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.