summaryrefslogtreecommitdiff
path: root/src/multimedia
diff options
context:
space:
mode:
authorYoann Lopes <yoann.lopes@qt.io>2016-07-08 15:22:16 +0200
committerYoann Lopes <yoann.lopes@qt.io>2016-08-22 09:50:06 +0000
commitcc12446728d00161116d6e1823e161440415d2d5 (patch)
tree81998ddb81bdb602be6faf76878e849fe675a75a /src/multimedia
parentd47e412b7b196e37196fa7c7469ae3b54eecf6d4 (diff)
downloadqtmultimedia-cc12446728d00161116d6e1823e161440415d2d5.tar.gz
Improve audio volume documentation
Added information about volume scales. Change-Id: Ica8367396147e3e1c814b3575faa5cf0503be031 Reviewed-by: Venugopal Shivashankar <Venugopal.Shivashankar@qt.io> Reviewed-by: Christian Stromme <christian.stromme@qt.io>
Diffstat (limited to 'src/multimedia')
-rw-r--r--src/multimedia/audio/qaudioinput.cpp7
-rw-r--r--src/multimedia/audio/qaudiooutput.cpp13
-rw-r--r--src/multimedia/audio/qsoundeffect.cpp25
-rw-r--r--src/multimedia/controls/qmediaplayercontrol.cpp2
-rw-r--r--src/multimedia/controls/qmediarecordercontrol.cpp6
-rw-r--r--src/multimedia/playback/qmediaplayer.cpp10
-rw-r--r--src/multimedia/recording/qmediarecorder.cpp11
7 files changed, 63 insertions, 11 deletions
diff --git a/src/multimedia/audio/qaudioinput.cpp b/src/multimedia/audio/qaudioinput.cpp
index bc6b6215b..ad54521fa 100644
--- a/src/multimedia/audio/qaudioinput.cpp
+++ b/src/multimedia/audio/qaudioinput.cpp
@@ -330,10 +330,15 @@ int QAudioInput::notifyInterval() const
/*!
Sets the input volume to \a volume.
+ The volume is scaled linearly from \c 0.0 (silence) to \c 1.0 (full volume). Values outside this
+ range will be clamped.
+
If the device does not support adjusting the input
volume then \a volume will be ignored and the input
volume will remain at 1.0.
+ The default volume is \c 1.0.
+
Note: Adjustments to the volume will change the volume of this audio stream, not the global volume.
*/
void QAudioInput::setVolume(qreal volume)
@@ -342,7 +347,7 @@ void QAudioInput::setVolume(qreal volume)
}
/*!
- Returns the input volume (gain).
+ Returns the input volume.
If the device does not support adjusting the input volume
the returned value will be 1.0.
diff --git a/src/multimedia/audio/qaudiooutput.cpp b/src/multimedia/audio/qaudiooutput.cpp
index 585855ace..670dca7bc 100644
--- a/src/multimedia/audio/qaudiooutput.cpp
+++ b/src/multimedia/audio/qaudiooutput.cpp
@@ -349,9 +349,18 @@ QAudio::State QAudioOutput::state() const
}
/*!
- Sets the volume.
- Where \a volume is between 0.0 and 1.0 inclusive.
+ Sets the output volume to \a volume.
+
+ The volume is scaled linearly from \c 0.0 (silence) to \c 1.0 (full volume). Values outside this
+ range will be clamped.
+
+ The default volume is \c 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 QAudio::convertVolume() for more details.
*/
void QAudioOutput::setVolume(qreal volume)
{
diff --git a/src/multimedia/audio/qsoundeffect.cpp b/src/multimedia/audio/qsoundeffect.cpp
index f653de86e..d3b818073 100644
--- a/src/multimedia/audio/qsoundeffect.cpp
+++ b/src/multimedia/audio/qsoundeffect.cpp
@@ -258,12 +258,22 @@ int QSoundEffect::loopsRemaining() const
/*!
\qmlproperty qreal QtMultimedia::SoundEffect::volume
- This property holds the volume of the sound effect playback, from 0.0 (silent) to 1.0 (maximum volume).
+ This property holds the volume of the sound effect playback.
+
+ The volume is scaled linearly from \c 0.0 (silence) to \c 1.0 (full volume). Values outside this
+ range will be clamped.
+
+ The default volume is \c 1.0.
+
+ 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 \l {QtMultimedia::QtMultimedia::convertVolume()}{QtMultimedia.convertVolume()}
+ for more details.
*/
/*!
\property QSoundEffect::volume
- This property holds the volume of the sound effect playback, from 0.0 (silent) to 1.0 (maximum volume).
+ This property holds the volume of the sound effect playback, from 0.0 (silence) to 1.0 (full volume).
*/
/*!
@@ -275,7 +285,16 @@ qreal QSoundEffect::volume() const
}
/*!
- Sets the volume to play the sound effect at to \a volume, from 0.0 (silent) to 1.0 (maximum volume).
+ Sets the sound effect volume to \a volume.
+
+ The volume is scaled linearly from \c 0.0 (silence) to \c 1.0 (full volume). Values outside this
+ range will be clamped.
+
+ The default volume is \c 1.0.
+
+ 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 QAudio::convertVolume() for more details.
*/
void QSoundEffect::setVolume(qreal volume)
{
diff --git a/src/multimedia/controls/qmediaplayercontrol.cpp b/src/multimedia/controls/qmediaplayercontrol.cpp
index cd56dffcb..46de05b51 100644
--- a/src/multimedia/controls/qmediaplayercontrol.cpp
+++ b/src/multimedia/controls/qmediaplayercontrol.cpp
@@ -175,6 +175,8 @@ QMediaPlayerControl::QMediaPlayerControl(QObject *parent):
\fn QMediaPlayerControl::setVolume(int volume)
Sets the audio \a volume of a player control.
+
+ The volume is scaled linearly, ranging from \c 0 (silence) to \c 100 (full volume).
*/
/*!
diff --git a/src/multimedia/controls/qmediarecordercontrol.cpp b/src/multimedia/controls/qmediarecordercontrol.cpp
index 4654d16eb..611f1fdcc 100644
--- a/src/multimedia/controls/qmediarecordercontrol.cpp
+++ b/src/multimedia/controls/qmediarecordercontrol.cpp
@@ -160,13 +160,15 @@ QMediaRecorderControl::~QMediaRecorderControl()
/*!
\fn qreal QMediaRecorderControl::volume() const
- Returns the linear audio gain of media recorder.
+ Returns the audio volume of a media recorder control.
*/
/*!
\fn void QMediaRecorderControl::setVolume(qreal gain)
- Sets the linear audio \a gain of a media recorder.
+ Sets the audio \a volume of a media recorder control.
+
+ The volume is scaled linearly, ranging from \c 0 (silence) to \c 100 (full volume).
*/
/*!
diff --git a/src/multimedia/playback/qmediaplayer.cpp b/src/multimedia/playback/qmediaplayer.cpp
index c5261921a..648c13220 100644
--- a/src/multimedia/playback/qmediaplayer.cpp
+++ b/src/multimedia/playback/qmediaplayer.cpp
@@ -1372,8 +1372,14 @@ QList<QAudio::Role> QMediaPlayer::supportedAudioRoles() const
\property QMediaPlayer::volume
\brief the current playback volume.
- The playback volume is linear in effect and the value can range from 0 -
- 100, values outside this range will be clamped.
+ The playback volume is scaled linearly, ranging from \c 0 (silence) to \c 100 (full volume).
+ Values outside this range will be clamped.
+
+ By default the volume is \c 100.
+
+ 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 QAudio::convertVolume() for more details.
*/
/*!
diff --git a/src/multimedia/recording/qmediarecorder.cpp b/src/multimedia/recording/qmediarecorder.cpp
index a5f4c15ce..7b0234988 100644
--- a/src/multimedia/recording/qmediarecorder.cpp
+++ b/src/multimedia/recording/qmediarecorder.cpp
@@ -556,7 +556,16 @@ void QMediaRecorder::setMuted(bool muted)
/*!
\property QMediaRecorder::volume
- \brief the linear audio gain of media recorder.
+ \brief the current recording audio volume.
+
+ The volume is scaled linearly from \c 0.0 (silence) to \c 1.0 (full volume). Values outside this
+ range will be clamped.
+
+ The default volume is \c 1.0.
+
+ 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 QAudio::convertVolume() for more details.
*/
qreal QMediaRecorder::volume() const