Various fixes to our overview doc pages

Correct various mistakes in our overview documentation and
add some more detail in various places.

Change-Id: Iff26e7f13646a7a421be49dcb473f64732367558
Reviewed-by: Nicholas Bennett <nicholas.bennett@qt.io>
(cherry picked from commit 10733a6a8371d88af5f418dcae1a405f92ed2873)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

13 files changed, 123 insertions, 67 deletions

diff --git a/src/multimedia/doc/snippets/multimedia-snippets/camera.cpp b/src/multimedia/doc/snippets/multimedia-snippets/camera.cpp
index 0abc4062f..b158469da 100644
--- a/src/multimedia/doc/snippets/multimedia-snippets/camera.cpp
+++ b/src/multimedia/doc/snippets/multimedia-snippets/camera.cpp
@@ -76,7 +76,7 @@ void overview_viewfinder()
     camera->setVideoOutput(preview);
     preview->show();
 
-    camera->start(); // to start the viewfinder
+    camera->start(); // to start the camera
     //! [Camera overview viewfinder]
 }
 
diff --git a/src/multimedia/doc/snippets/multimedia-snippets/video.cpp b/src/multimedia/doc/snippets/multimedia-snippets/video.cpp
index ac920d858..ce35d6e74 100644
--- a/src/multimedia/doc/snippets/multimedia-snippets/video.cpp
+++ b/src/multimedia/doc/snippets/multimedia-snippets/video.cpp
@@ -43,7 +43,6 @@
 #include "qvideosink.h"
 #include "qvideowindowcontrol.h"
 #include "qgraphicsvideoitem.h"
-#include "qmediaplaylist.h"
 #include "qvideoframeformat.h"
 
 #include <QFormLayout>
@@ -90,7 +89,6 @@ public:
 
 private:
     // Common naming
-    QMediaPlaylist *playlist;
     QVideoWidget *videoWidget;
     QWidget *widget;
     QFormLayout *layout;
@@ -104,16 +102,12 @@ void VideoExample::VideoWidget()
 {
     //! [Video widget]
     player = new QMediaPlayer;
-
-    playlist = new QMediaPlaylist(player);
-    playlist->addMedia(QUrl("http://example.com/myclip1.mp4"));
-    playlist->addMedia(QUrl("http://example.com/myclip2.mp4"));
+    player->setSource(QUrl("http://example.com/myclip1.mp4"));
 
     videoWidget = new QVideoWidget;
     player->setVideoOutput(videoWidget);
 
     videoWidget->show();
-    playlist->setCurrentIndex(1);
     player->play();
     //! [Video widget]
 
@@ -154,7 +148,7 @@ void VideoExample::VideoGraphicsItem()
     graphicsView->scene()->addItem(item);
     graphicsView->show();
 
-    player->setMedia(QUrl("http://example.com/myclip4.ogv"));
+    player->setSource(QUrl("http://example.com/myclip4.ogv"));
     player->play();
     //! [Video graphics item]
 }
diff --git a/src/multimedia/doc/src/audiooverview.qdoc b/src/multimedia/doc/src/audiooverview.qdoc
index d4c3116ba..045a7617c 100644
--- a/src/multimedia/doc/src/audiooverview.qdoc
+++ b/src/multimedia/doc/src/audiooverview.qdoc
@@ -51,28 +51,62 @@ high level approaches to: audio input, output and processing.
 \section1 Audio Implementation Details
 
 \section2 Playing Compressed Audio
+
 For playing media or audio files that are not simple, uncompressed audio, you
 can use the QMediaPlayer C++ class, or the \l{MediaPlayer} QML type.
 The QMediaPlayer class and associated QML types are also capable of playing
-\l{multimedia-playing-video}{video}, if required. The compressed audio formats
-supported depends on:
+\l{multimedia-playing-video}{video}, if required. The audio formats
+that the player supports depends on:
 \list
     \li The operating system environment.
     \li Any decoder plugins the user may have installed.
 \endlist
 
+The media player needs to be connected to a QAudioOutput object (or the QML AudioOutput
+element) to play back audio.
+
 Here is how you play a local file using C++:
 
     \snippet multimedia-snippets/media.cpp Local playback
 
+The same functionality in QML:
+
+\qml
+MediaPlayer {
+    audioOutput: AudioOutput {}
+    source: "file:///path/to/my/music.mp3"
+    Component.onCompleted: { play() }
+}
+\endqml
+
 \section2 Recording Audio to a File
-For recording audio to a file, the QMediaRecorder class allows you
-to compress audio data from an input device and record it.
+
+To record audio to a file, you need to create a capture session and connect to it an audio
+input and a recorder. These elements are implemented with the QMediaCaptureSession,
+QAudioInput, and QMediaRecorder classes. The default constructed QAudioInput selects the
+system default audio input. The recorder controls the recording process with a simple record()
+and stop() functions. Additionally, you can use it to select the output location, audio
+encoder, or file container format.
+
+A session recording audio from the default microphone would look as follows in C++:
 
     \snippet multimedia-snippets/media.cpp Media recorder
 
-QMediaCaptureSession provides support for more complex use cases involving the
-capturing and recording of audio.
+In QML, the same can be achieved by:
+
+\qml
+CaptureSession {
+    audioInput: AudioInput {}
+    mediaRecorder: MediaRecorder {
+        id: recorder
+        outputLocation: "file:///path/to/test.mp3"
+    }
+    Component.onCompleted: { recorder.record() }
+}
+\endqml
+
+QMediaCaptureSession also provides support for more complex use cases such as image
+capturing or video recording.
 
 \section2 Low Latency Sound Effects
 
@@ -92,7 +126,7 @@ You can adjust the:
 \target raw access
 \section2 Low Level Audio Playback and Recording
 
-Qt Multimedia offers classes for raw access to audio input and output
+The C++ API of Qt Multimedia offers classes for raw access to audio input and output
 facilities, allowing applications to receive raw data from devices like
 microphones, and to write raw data to speakers or other devices. Generally
 these classes do not do any audio decoding, or other processing, but they
diff --git a/src/multimedia/doc/src/cameraoverview.qdoc b/src/multimedia/doc/src/cameraoverview.qdoc
index 87d513eed..c5f9048ff 100644
--- a/src/multimedia/doc/src/cameraoverview.qdoc
+++ b/src/multimedia/doc/src/cameraoverview.qdoc
@@ -206,21 +206,18 @@ is useful for QGraphicsView.
 
 For advanced usage (like processing preview frames as they come, which enables
 detection of objects or patterns), you can also use your own QVideoSink and set
-that as the videoOutput for the QCamera object. In this case, you will need to
-render the viewfinder image yourself by processing the data received from the
+that as the videoOutput for the QMediaCaptureSession. In this case, you will need to
+render the preview image yourself by processing the data received from the
 videoFrameChanged() signal.
 
     \snippet multimedia-snippets/camera.cpp Camera overview surface
 
-On mobile devices, the preview image might not always be in the orientation you
-would expect. The camera sensors on these devices are often mounted in landscape
-while the natural orientation of the screen is portrait. This results in the
-image appearing sideways or inverted depending on the device orientation. In
-order to reflect on screen what the user actually sees, you should make sure
-the viewfinder frames are always rotated to the correct orientation, taking into
-account the camera sensor orientation and the current display orientation.
-
-    \snippet multimedia-snippets/camera.cpp Camera overview viewfinder orientation
+On mobile devices, the preview image is by default oriented in the same way as the device.
+Thus, as the user rotates the device, the preview image will switch between portrait and
+landscape mode. Once you start recording, the orientation will be locked. To avoid a poor
+user experience, you should also lock the orientation of the applications user interface
+while recording. This can be achieved using the
+\l{contentOrientation}{QWindow::contentOrientation} property of QWindow.
 
 \section2 Still Images
 
diff --git a/src/multimedia/doc/src/multimedia-overview.qdoc b/src/multimedia/doc/src/multimedia-overview.qdoc
index 07f5bbc7c..84a7c2b69 100644
--- a/src/multimedia/doc/src/multimedia-overview.qdoc
+++ b/src/multimedia/doc/src/multimedia-overview.qdoc
@@ -87,20 +87,20 @@ For some quick recipes, see this table:
     \row
         \li Playing a sound effect
         \li
-        \li
+        \li \l{SoundEffect}
         \li QSoundEffect
     \row
-        \li Playing low latency audio
+        \li Playing encoded audio (MP3, AAC etc)
+        \li \l{Media Player Example}{player}
+        \li \l{MediaPlayer}
+        \li QMediaPlayer
+    \row
+        \li Playing raw audio data with low latency
         \li \l{Audio Source Example}{audiosource},
             \l{Spectrum Example}{spectrum}
         \li
         \li QAudioSink
     \row
-        \li Playing encoded audio (MP3, AAC etc)
-        \li \l{Media Player Example}{player}
-        \li \l Audio, \l {MediaPlayer}
-        \li QMediaPlayer
-    \row
         \li Accessing raw audio input data
         \li \l{Spectrum Example}{spectrum},
             \l{Audio Source Example}{audiosource}
@@ -109,38 +109,37 @@ For some quick recipes, see this table:
     \row
         \li Recording encoded audio data
         \li \l{Audio Recorder Example}{audiorecorder}
-        \li
-        \li QMediaCaptureSession
+        \li \l{CaptureSession}, \l{AudioInput}, \l{MediaRecorder}
+        \li QMediaCaptureSession, QAudioInput, QMediaRecorder
     \row
-        \li Discovering raw audio devices
+        \li Discovering audio and video devices
         \li \l{Audio Devices Example}{audiodevices}
-        \li
-        \li QAudioDevice
+        \li \l{MediaDevices}, \l{AudioDevice}, \l{CameraDevice}
+        \li QMediaDevices, QAudioDevice, QCameraDevice
     \row
         \li Video Playback
         \li \l{Media Player Example}{player},
             \l{QML Media Player Example}{mediaplayer}
-            \l{QML Video Example}{qmlvideo},
         \li \l MediaPlayer, \l VideoOutput, \l Video
         \li QMediaPlayer, QVideoWidget, QGraphicsVideoItem
     \row
         \li Capturing audio and video
         \li \l {Camera Example}{camera},
             \l {QML Recorder Example}{recorder}
-        \li \l Camera, \l VideoOutput
-        \li QCamera, QVideoWidget, QGraphicsVideoItem
+        \li \l CaptureSession, \l Camera, \l AudioInput \l VideoOutput
+        \li QMediaCaptureSession, QCamera, QAudioInput, QVideoWidget
     \row
         \li Capturing photos
         \li \l {Camera Example}{camera},
             \l {QML Recorder Example}{recorder}
-        \li \l Camera
-        \li QCamera, QImageCapture
+        \li \l CaptureSession, \l Camera, \l ImageCapture
+        \li QMediaCaptureSession, QCamera, QImageCapture
     \row
         \li Capturing movies
         \li \l {Camera Example}{camera},
             \l {QML Recorder Example}{recorder}
-        \li \l Camera
-        \li QCamera, QMediaRecorder
+        \li \l CaptureSession, \l Camera, \l MediaRecorder
+        \li QMediaCaptureSession, QCamera, QMediaRecorder
 \endtable
 
 \section1 Limitations
diff --git a/src/multimedia/doc/src/qt6-changes.qdoc b/src/multimedia/doc/src/qt6-changes.qdoc
index 1a9a9530b..dd37a1355 100644
--- a/src/multimedia/doc/src/qt6-changes.qdoc
+++ b/src/multimedia/doc/src/qt6-changes.qdoc
@@ -49,10 +49,11 @@ Qt 5 can be ported with limited effort.
 There are a number of new features in Qt Multimedia:
 \list
     \li QMediaCaptureSession class is the central object for media capture.
-    \li QMediaRecorder class is now an abstract class for audio/video
-    functionality. It handles encoding of data produced in a capture session.
+    \li QMediaRecorder class is now a class limited to recording audio and video.
+    It handles encoding of data produced in a capture session.
     \li Using QMediaFormat and QMediaRecorder, setting up the desired encoding
     when recording has changed significantly.
+    \li You can now also monitor the audio recorded by a capture session.
     \li Support for selection of audio, video and subtitle tracks when playing
     back media files has been added.
     \li QAudioDecoder is now supported on all platforms.
@@ -92,8 +93,7 @@ There are a number of new features in Qt Multimedia:
         resolution and frame rate the camera should be using.
     \row
         \li QMediaContent
-        \li The class has been removed. Use QMediaPlayList for playlists and
-        QUrl for individual media files instead.
+        \li The class has been removed. Use QUrl for individual media files instead.
     \row
         \li QSound
         \li Use QSoundEffect instead.
@@ -120,7 +120,7 @@ There are a number of new features in Qt Multimedia:
 
 \section1 Changed features
 
-A number of classes previously offered in Qt Multimedia or Qt Multimedia Kit have
+A number of classes previously offered in Qt Multimedia have
 changed in ways that may affect previously written code. The following table
 highlights these changes.
 
@@ -155,6 +155,15 @@ highlights these changes.
     \row
         \li QCameraImageCapture renamed QImageCapture
         \li None
+    \row
+        \li Audio inputs and outputs
+        \li QMediaPlayer and QMediaCaptureSession (and the corresponding QML types MediaPlayer and
+        CaptureSession) are not connected to any audio devices by default. Explicitly connect them
+        to a QAudioInput/AudioInput or QAudioOutput/AudioOutput to capture or play back audio.
+    \row
+        \li Capturing video
+        \li A capture session is by default not connected to a Camera. Connect it to a QCamera object
+        (Camera item) to be able to capture video or still images.
 \endtable
 
 */
diff --git a/src/multimedia/doc/src/qtmultimedia-index.qdoc b/src/multimedia/doc/src/qtmultimedia-index.qdoc
index cd832457b..13f055933 100644
--- a/src/multimedia/doc/src/qtmultimedia-index.qdoc
+++ b/src/multimedia/doc/src/qtmultimedia-index.qdoc
@@ -41,12 +41,14 @@
     \page qtmultimedia-index.html
     \title Qt Multimedia
     \image noun_Media_166644.svg "image of multimedia icons, courtesy of misirlou from the Noun Project"
-    \brief The Qt Multimedia module provides APIs for audio, video and
-    camera-related functionality
+    \brief The Qt Multimedia module provides APIs for playing back and recording
+    audiovisual content
 
     Qt Multimedia is an add-on module that provides a rich set of QML types
-    and C++ classes to handle multimedia content. It also provides necessary
-    APIs to access the camera functionality.
+    and C++ classes to handle multimedia content. It contains an easy to use
+    API for playing back audio and video files and rendering those on screen, as
+    well as a comprehensive API for recording audio and video from the systems
+    cameras and microphones.
 
     The functionality of this module is divided into the following submodules:
 
@@ -59,7 +61,7 @@
       \li Provides the widget-based multimedia API.
     \endtable
 
-   \section1 Getting started
+    \section1 Getting started
     If you are porting from Qt 5 to Qt 6 see \l{Changes to Qt Multimedia}.
 
     If you are new to Qt Multimedia, the QML types can be
@@ -141,11 +143,15 @@
      \li Class for video presentation.
     \endtable
 
+    For playback QMediaPlayer, QAudioOutput and QVideoOutput contain all the required functionality.
+    The other classes are used for capturing audio and video content, where the QMediaCaptureSession is the central
+    class managing the whole capture/recording process.
+
     \section1 Licenses and attributions
 
     The Qt Quick Multimedia module is available under commercial licenses from
     \l{The Qt Company}.
-    In addition, it is available under free software licenses. Since Qt 5.4,
+    In addition, it is available under free software licenses. Since Qt 5.6,
     these free software licenses are
     \l{GNU Lesser General Public License, version 3}, or
     the \l{GNU General Public License, version 2}.
@@ -166,12 +172,20 @@
 
     For most features, Qt Multimedia builds upon the multimedia framework of the
     underlying operating system. Therefore there are several multimedia back ends
-    based on different technologies and APIs. For further details, see the
-    \l{Qt Multimedia Backends}{Qt Multimedia back ends wiki}.
+    based on different technologies and APIs.
 
-     \list
+    While we try to support our full API on all platforms, platform specific limitations do
+    exist in a few places. This is due to the fact that the feature set supported by those
+    frameworks varies, implying that some functionality
+    might not be available on all platforms. This is especially true for the set of
+    supported file formats and codecs, as well as advanced camera functionality.
+
+    Where limitations exist, we aim to document those in the respective classes and
+    methods.
+
+    \list
       \li \l{Qt Multimedia on macOS and iOS}{macOS and iOS}
-     \endlist
+    \endlist
 
     \section2 Reference
     \list
diff --git a/src/multimedia/doc/src/videooverview.qdoc b/src/multimedia/doc/src/videooverview.qdoc
index 1856fe2ac..928f3cc78 100644
--- a/src/multimedia/doc/src/videooverview.qdoc
+++ b/src/multimedia/doc/src/videooverview.qdoc
@@ -34,9 +34,9 @@
 \section1 Video Features
 
 Qt Multimedia offers both high and low level C++ classes for playing and
-manipulating video data, and QML types for playback and control. Some
-of these classes also overlap with both \l {Camera Overview}{camera} and
-\l {Audio Overview}{audio} classes, which can be useful.
+manipulating video data, and QML types for playback and recording. Some
+of the classes presented here overlap with what is presented in the \l {Camera Overview} and
+\l {Audio Overview}.
 
 \section1 Video Implementation Details
 
@@ -58,7 +58,8 @@ You can use \l VideoOutput to render content that is provided by
 either a \l MediaPlayer or a \l Camera. The VideoOutput is a visual
 component that can be embedded into a QQuickScene or \l Window, while
 all media decoding and playback control is handled by the \l MediaPlayer
-or \l CaptureSession. \l Video has also been provided for convenience.
+or \l CaptureSession. A \l Video element has been provided for convenience.
+It combines MediaPlayer, VideoOutput and AudioOutput elements in one item.
 
 \section2 Working with Low Level Video Frames
 
@@ -75,8 +76,9 @@ allows you to receive these frames from \l QMediaPlayer and
 \l QCamera.
 
 \section2 Recording Video
-You can use the \l QMediaRecorder class as a simple way to record video to disk.
-For more advances use cases \l QMediaCaptureSession provides a more flexible API.
+The central class for any type of capturing or recording of audio and video is QMediaCaptureSession
+(or the CaptureSession QML type). You can connect a QCamera (Camera in QML) and a QMediaRecorder
+(MediaRecorder)to the session and then ask the media recorder to start recording.
 
 \section1 Examples
 
diff --git a/src/multimedia/playback/qmediaplayer.cpp b/src/multimedia/playback/qmediaplayer.cpp
index 52a371cec..4c43ec576 100644
--- a/src/multimedia/playback/qmediaplayer.cpp
+++ b/src/multimedia/playback/qmediaplayer.cpp
@@ -60,6 +60,7 @@ QT_BEGIN_NAMESPACE
     \inmodule QtMultimedia
     \ingroup multimedia
     \ingroup multimedia_playback
+    \ingroup multimedia_video
 
     The QMediaPlayer class is a high level media playback class. It can be used
     to playback audio of video media files. The content
diff --git a/src/multimedia/recording/qmediacapturesession.cpp b/src/multimedia/recording/qmediacapturesession.cpp
index 10324313e..0d9ba8d78 100644
--- a/src/multimedia/recording/qmediacapturesession.cpp
+++ b/src/multimedia/recording/qmediacapturesession.cpp
@@ -87,6 +87,8 @@ public:
     \brief The QMediaCaptureSession class allows capturing of audio and video content.
     \inmodule QtMultimedia
     \ingroup multimedia
+    \ingroup multimedia_video
+    \ingroup multimedia_audio
 
     The QMediaCaptureSession is the central class that manages capturing of media on the local device.
 
diff --git a/src/multimedia/recording/qmediarecorder.cpp b/src/multimedia/recording/qmediarecorder.cpp
index 369af9662..8bf587afe 100644
--- a/src/multimedia/recording/qmediarecorder.cpp
+++ b/src/multimedia/recording/qmediarecorder.cpp
@@ -62,6 +62,8 @@ QT_BEGIN_NAMESPACE
     \inmodule QtMultimedia
     \ingroup multimedia
     \ingroup multimedia_recording
+    \ingroup multimedia_video
+    \ingroup multimedia_audio
 
     \brief The QMediaRecorder class is used for encoding and recording a capture session.
 
diff --git a/src/multimedia/video/qvideosink.cpp b/src/multimedia/video/qvideosink.cpp
index e84330535..a35a04812 100644
--- a/src/multimedia/video/qvideosink.cpp
+++ b/src/multimedia/video/qvideosink.cpp
@@ -88,6 +88,7 @@ public:
     \brief The QVideoSink class represents a generic sink for video data.
     \inmodule QtMultimedia
     \ingroup multimedia
+    \ingroup multimedia_video
 
     The QVideoSink class can be used to retrieve video data on a frame by frame
     basis from Qt Multimedia.
diff --git a/src/multimediawidgets/qvideowidget.cpp b/src/multimediawidgets/qvideowidget.cpp
index 3be42b73d..b3331be09 100644
--- a/src/multimediawidgets/qvideowidget.cpp
+++ b/src/multimediawidgets/qvideowidget.cpp
@@ -72,6 +72,7 @@ QT_BEGIN_NAMESPACE
     \brief The QVideoWidget class provides a widget which presents video
     produced by a media object.
     \ingroup multimedia
+    \ingroup multimedia_video
     \inmodule QtMultimediaWidgets
 
     Attaching a QVideoWidget to a QMediaPlayer or QCamera allows it to display the