Overhaul documentation for Qt 6 Release, Second Block

Remove Audio QML type
Add links to technical definitions
Spelling and grammer check
Changes to adhere to Qt Doc guide
Integrated change to qt 6 page (porting guide)
Break out Audio QML type removal into it's own line in changes table
Reflow docs text within 100 characters

Task-number: QTBUG-94646 QTBUG-94906
Change-Id: I65ca7083e68d0bf534fd4faecfa7c501bab83b24
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Reviewed-by: Lars Knoll <lars.knoll@qt.io>

4 files changed, 174 insertions, 180 deletions

diff --git a/src/multimedia/doc/src/changes.qdoc b/src/multimedia/doc/src/changes.qdoc
deleted file mode 100644
index feb077ae6..000000000
--- a/src/multimedia/doc/src/changes.qdoc
+++ /dev/null
@@ -1,161 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2021 The Qt Company Ltd.
-** Contact: https://www.qt.io/licensing/
-**
-** This file is part of the Qt for Multimedia module of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:LGPL$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and The Qt Company. For licensing terms
-** and conditions see https://www.qt.io/terms-conditions. For further
-** information use the contact form at https://www.qt.io/contact-us.
-**
-** GNU Lesser General Public License Usage
-** Alternatively, this file may be used under the terms of the GNU Lesser
-** General Public License version 3 as published by the Free Software
-** Foundation and appearing in the file LICENSE.LGPL3 included in the
-** packaging of this file. Please review the following information to
-** ensure the GNU Lesser General Public License version 3 requirements
-** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
-**
-** GNU General Public License Usage
-** Alternatively, this file may be used under the terms of the GNU
-** General Public License version 2.0 or (at your option) the GNU General
-** Public license version 3 or any later version approved by the KDE Free
-** Qt Foundation. The licenses are as published by the Free Software
-** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
-** included in the packaging of this file. Please review the following
-** information to ensure the GNU General Public License requirements will
-** be met: https://www.gnu.org/licenses/gpl-2.0.html and
-** https://www.gnu.org/licenses/gpl-3.0.html.
-**
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-/*!
-
-\page changes.html
-\title Changes in Qt Multimedia
-\brief A description of changes in this version of Qt Multimedia
-
-
-The Qt Multimedia module in Qt 6 replaces the Qt Multimedia module from Qt 5.x.
-Existing code that uses Qt Multimedia from Qt 5 can be ported with limited effort.
-The \l {changed features} section highlights changes relevant to porting.
-
-\section1 New features in Qt 6
-
-There are a number of new features in Qt Multimedia:
-\list
-    \li QMediaCaptureSession class is the central object for media capture.
-    \li Changed QMediaRecorder class to be a high level class for audio/video
-    recording.
-    \li new QMediaRecorder class to handle encoding of data produced in a capture
-    session.
-    \li Setting up the desired encoding when recording has changed significantly.
-    see QMediaFormat and QMediaRecorder for details.
-    \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.
-\endlist
-
-
-\section1 Removed Features
-
-\table 70%
-    \header
-        \li Removed feature
-        \li Notes or suggested alternative
-    \row
-        \li Playlist in QMediaPlayer
-        \li QMediaPlayer does not do any playlist handling anymore in Qt 6.
-        The QMediaPlayList class does however still exist and provides this
-        functionality. Users will need to connect the playlist to the mediaplayer
-        themselves to handle playlists.
-    \row
-        \li QAudioProbe and QVideoProbe
-        \li The audio and video probing API has been removed.
-    \row
-        \li QAudioRecorder and the Audio QML type
-        \li Use a QMediaCaptureSession or the CaptureSession QML type.
-    \row
-        \li QMediaObject and QMediaBindableInterface
-        \li These classes have been removed in favor of a more direct API for
-        setting up connections between objects using e.g. setVideoOutput and
-        QMediaCaptureSession.
-    \row
-        \li QCameraViewFinderSettings
-        \li This class has been removed. Use QCameraFormat to define the
-        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.
-    \row
-        \li QSound
-        \li Use QSoundEffect instead.
-    \row
-        \li QVideoFilterRunnable
-        \li Use \l{shader effects} in QML instead or access the QVideoFrame's
-        content in C++.
-    \row
-        \li Public back end API
-        \li The back end API of Qt Multimedia is private in Qt 6. This improves
-        response time for supporting new multimedia use cases. This includes all
-        classes that contain "Control" or "Abstract" in the class name in Qt 5.
-    \row
-        \li Back ends as plugins
-        \li Qt Multimedia in Qt 6 does not use a plugin infrastructure for its
-        back ends anymore.
-        This means that users no longer need to ship those back ends with their
-        application. Instead, the back end being used is determined at compile
-        time based on the underlying operating system. Qt uses \l gstreamer on
-        Linux, WMF on Windows, AVFoundation on macOS and iOS and the Android
-        multimedia APIs on Android.
-\endtable
-
-\section1 Changed features
-
-A number of classes previously offered in Qt Multimedia or Qt Multimedia Kit have
-changed in ways that may affect previously written code. The following table
-highlights these changes.
-
-\table 70%
-    \header
-        \li Changed feature
-        \li Notes
-    \row
-        \li Handling of Camera resolutions and frame rates
-        \li Handling of these has been simplified and a new QCameraFormat class
-        helps with selecting the correct resolution and frame rate for the camera.
-    \row
-        \li Video output handling on the C++ side has changed significantly.
-        \li QAbstractVideoSurface has been replaced by the QVideoSink class, and
-        generic rendering support has been enhanced to cover all \l{pixel format}s
-        supported by Qt Multimedia.
-    \row
-        \li Metadata types
-        \li QMediaMetaData has changed significantly: mainly moving from string
-        based to enum based keys, and reducing the set of supported keys to the
-        ones that can be supported on most platforms.
-    \row
-        \li QMediaFormat
-        \li Handling of formats for encoded media and the settings for the media
-        recorder have changed significantly. Qt 5 provides a string based
-        API, a separated file format, and audio and video codecs into 3 classes.
-        However, Qt 6 unifies the formats in the QMediaFormat class. Additional
-        settings are directly specified in QMediaRecorder. Setting up file formats and codecs
-        is now enum based and no longer uses strings. This puts some
-        limitations on the set of codecs that can be used, but helps provide a
-        consistent cross-platform API.
-    \row
-        \li QCameraImageCapture renamed QImageCapture
-        \li None
-\endtable
-
-*/
diff --git a/src/multimedia/doc/src/qm-external-pages.qdoc b/src/multimedia/doc/src/qm-external-pages.qdoc
index ce1066941..16ba23523 100644
--- a/src/multimedia/doc/src/qm-external-pages.qdoc
+++ b/src/multimedia/doc/src/qm-external-pages.qdoc
@@ -60,3 +60,41 @@
     \externalpage https://doc.qt.io/qt-6/qtqml-syntax-imports.html
     \title qtqml import syntax
 */
+
+/*!
+    \externalpage https://en.wikipedia.org/wiki/Sonification
+    \title Sonification
+*/
+/*!
+    \externalpage http://www.sengpielaudio.com/calculator-loudness.htm
+    \title loudness
+*/
+/*!
+    \externalpage https://en.wikipedia.org/wiki/List_of_ISO_639-2_codes
+    \title ISO 639-2 code
+*/
+
+/*!
+    \externalpage https://www.dr-lex.be/info-stuff/volumecontrols.html
+    \title volume controls
+*/
+
+/*!
+    \externalpage https://en.wikipedia.org/wiki/Hyperfocal_distance
+    \title hyperfocal
+*/
+
+/*!
+    \externalpage https://en.wikipedia.org/wiki/Depth_of_field
+    \title DOF
+*/
+/*!
+    \externalpage https://en.wikipedia.org/wiki/Media_type#Mime.types
+    \title MIME type
+*/
+
+/*!
+    \externalpage https://doc.qt.io/qt-5/qml-qtmultimedia-audio.html
+    \title Audio QML Type
+*/
+
diff --git a/src/multimedia/doc/src/qt6-changes.qdoc b/src/multimedia/doc/src/qt6-changes.qdoc
index 9dcaee3e4..b7258c8b7 100644
--- a/src/multimedia/doc/src/qt6-changes.qdoc
+++ b/src/multimedia/doc/src/qt6-changes.qdoc
@@ -38,7 +38,122 @@
     APIs in each release. But some changes were inevitable in an effort to
     make Qt a better framework.
 
-    In this topic we summarize those changes in Qt Multimedia, and provide guidance
-    to handle them.
+The module has been refactored significantly and has changed classification,
+from essential to add-on. The Qt Multimedia module in Qt 6 replaces the
+Qt Multimedia module from Qt 5.x. Existing code that uses Qt Multimedia from
+Qt 5 can be ported with limited effort.
+
+
+\section1 New features in Qt 6
+
+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 Using QMediaFormat and QMediaRecorder, setting up the desired encoding
+    when recording has changed significantly.
+    \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.
+\endlist
+
+
+\section1 Removed features
+
+\table 70%
+    \header
+        \li Removed feature
+        \li Notes or suggested alternative
+    \row
+        \li Playlist in QMediaPlayer
+        \li QMediaPlayer does not do any playlist handling anymore in Qt 6.
+        The QMediaPlayList class does however still exist and provides this
+        functionality. Users will need to connect the playlist to the mediaplayer
+        themselves to handle playlists.
+    \row
+        \li QAudioProbe and QVideoProbe
+        \li The audio and video probing API has been removed.
+    \row
+        \li QAudioRecorder
+        \li Use the QMediaCaptureSession or CaptureSession QML type.
+    \row
+        \li \l{Audio QML type}
+        \li Use MediaPlayer QML type.
+    \row
+        \li QMediaObject and QMediaBindableInterface
+        \li These classes have been removed in favor of a more direct API for
+        setting up connections between objects using, for example, setVideoOutput
+        and QMediaCaptureSession.
+    \row
+        \li QCameraViewFinderSettings
+        \li This class has been removed. Use QCameraFormat to define the
+        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.
+    \row
+        \li QSound
+        \li Use QSoundEffect instead.
+    \row
+        \li QVideoFilterRunnable
+        \li Use \l{shader effects} in QML instead or access the QVideoFrame's
+        content in C++.
+    \row
+        \li Public back-end API
+        \li The back-end API of Qt Multimedia is private in Qt 6. This improves
+        response time for supporting new multimedia use cases. Any classes that
+        contain the words "Control" or "Abstract" in the class name in Qt 5 are
+        now private in Qt 6.
+    \row
+        \li Back-end plugins
+        \li Qt Multimedia in Qt 6 does not use a plugin infrastructure for its
+        back ends anymore.
+        This means that users no longer need to ship those back ends with their
+        application. Instead, the back end being used is determined at compile
+        time based on the underlying operating system. Qt uses \l gstreamer on
+        Linux, WMF on Windows, AVFoundation on macOS and iOS and the Android
+        multimedia APIs on Android.
+\endtable
+
+\section1 Changed features
+
+A number of classes previously offered in Qt Multimedia or Qt Multimedia Kit have
+changed in ways that may affect previously written code. The following table
+highlights these changes.
+
+\table 70%
+    \header
+        \li Changed feature
+        \li Notes
+    \row
+        \li Handling of Camera resolutions and frame rates
+        \li Handling of these has been simplified and a new QCameraFormat class
+        helps with selecting the correct resolution and frame rate for the camera.
+    \row
+        \li Video output handling on the C++ side has changed significantly.
+        \li QAbstractVideoSurface has been replaced by the QVideoSink class, and
+        generic rendering support has been enhanced to cover all \l{pixel format}s
+        supported by Qt Multimedia.
+    \row
+        \li Metadata types
+        \li QMediaMetaData has changed significantly: mainly moving from string
+        based to enum based keys, and reducing the set of supported keys to the
+        ones that can be supported on most platforms.
+    \row
+        \li QMediaFormat
+        \li Handling of formats for encoded media and the settings for the media
+        recorder have changed significantly. Qt 5 provides a string-based
+        API, a separated file format, and audio and video codecs into three classes.
+        However, Qt 6 unifies the formats in the QMediaFormat class. Additional
+        settings are directly specified in QMediaRecorder. Setting up file formats
+        and codecs is now implemented with enums and no longer uses strings. This
+        puts some limitations on the set of codecs that can be used, but helps
+        provide a consistent cross-platform API.
+    \row
+        \li QCameraImageCapture renamed QImageCapture
+        \li None
+\endtable
 
 */
diff --git a/src/multimedia/doc/src/qtmultimedia-index.qdoc b/src/multimedia/doc/src/qtmultimedia-index.qdoc
index 6cd6c46b2..39713ae8a 100644
--- a/src/multimedia/doc/src/qtmultimedia-index.qdoc
+++ b/src/multimedia/doc/src/qtmultimedia-index.qdoc
@@ -55,14 +55,16 @@
       \li \l{QtMultimedia}{Qt Multimedia}
       \li Provides API for multimedia-specific use cases.
      \row
-      \li \l{QtMultimediaWidgets}{Qt Multimedia Widgets}
+      \li \l{Qt Multimedia Widgets}
       \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}.
 
-    The QML types can be \l{qtqml import syntax}{imported} into an
-    application using the following statement in your \c {.qml} file.
+    If you are new to Qt Multimedia, the QML types can be
+    \l{qtqml import syntax}{imported} into an application using the following
+    statement in your \c {.qml} file.
 
     \qml
      import QtMultimedia
@@ -86,19 +88,15 @@
      QT += multimedia multimediawidgets
    \endcode
 
-    \section1 QML Types and C++ Classes
+    \section1 QML Types
 
-    The following is a list of important QML types and C++ classes provided by
-    this module:
+    The following table outlines some important QML types.
 
     \table
     \header
      \li Type
      \li Description
     \row
-     \li \l {QtMultimedia::Audio}{Audio}
-     \li Add audio playback functionality to a scene
-    \row
      \li \l {QtMultimedia::Playlist}{Playlist}
      \li For specifying a list of media to be played.
     \row
@@ -106,14 +104,17 @@
      \li Access camera viewfinder frames
     \row
      \li MediaPlayer
-     \li Add media playback functionality to a scene. It is same as the Audio
-     type, but can be used for video playback with the VideoOutput type.
+     \li Add audio and/or video playback functionality to a scene.
     \row
      \li \l {QtMultimedia::Video}{Video}
      \li Add Video playback functionality to a scene. It uses MediaPlayer and
      VideoOutput types to provide video playback functionality.
     \endtable
 
+    \section1 C++ Classes
+
+    The following table outlines some important C++ Classes
+
     \table
     \header
      \li Class
@@ -126,7 +127,7 @@
      \li Record media content from an audio source.
     \row
      \li \l QCamera
-     \li Access camera viewfinder.
+     \li Access camera preview
     \row
      \li QImageCapture
      \li Capture still images with a camera.
@@ -144,7 +145,7 @@
      \li Class for video presentation.
     \endtable
 
-    \section1 Licenses and Attributions
+    \section1 Licenses and attributions
 
     The Qt Quick Multimedia module is available under commercial licenses from
     \l{The Qt Company}.
@@ -154,17 +155,18 @@
     the \l{GNU General Public License, version 2}.
     See \l{Qt Licensing} for further details.
 
-    \section1 Related Information
+    \section1 Related information
 
     \section2 Guides
      \list
+      \li \l{Changes to Qt Multimedia}{Changes in Qt 6}
       \li \l{Multimedia Overview}
       \li \l{Audio Overview}
       \li \l{Video Overview}
       \li \l{Camera Overview}
      \endlist
 
-    \section2 Platform Notes
+    \section2 Platform notes
 
     For most features, Qt Multimedia builds upon the multimedia framework of the
     underlying operating system. Therefore there are several multimedia back ends
@@ -172,7 +174,7 @@
     \l{Qt Multimedia Backends}{Qt Multimedia back ends wiki}.
 
      \list
-      \li \l{Qt Multimedia on macOS and iOS}{iOS}
+      \li \l{Qt Multimedia on macOS and iOS}{macOS and iOS}
      \endlist
 
     \section2 Reference