qtmultimedia-index.qdoc

Go to the documentation of this file.

// Copyright (C) 2021 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
/*!
    \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 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 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 system's
    cameras and microphones.
 
    The functionality of this module is divided into the following submodules:
 
    \table
     \row
      \li \l{Multimedia Overview}{Qt Multimedia}
      \li Provides an API for multimedia-specific use cases.
     \row
      \li \l{Qt Multimedia Widgets}
      \li Provides a widget-based multimedia API.
    \row
      \li \l{Qt Spatial Audio}
      \li Provides an API for implementing sound fields in 3D space.
    \endtable
 
    \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
    \l{qtqml import syntax}{imported} into an application using the following
    statement in your \c {.qml} file.
 
    \qml
     import QtMultimedia
    \endqml
 
    To link against the C++ libraries, add the following to your project's
    \c CMakeLists.txt file. Substitute \c my_project with the name of your
    project.
 
   \code
        find_package(Qt6 REQUIRED COMPONENTS Multimedia)
        target_link_libraries(my_project PRIVATE Qt6::Multimedia)
   \endcode
 
   See \l {Building Qt Multimedia from sources} for guidance on building
   Qt Multimedia from sources.
 
    \section1 Overviews and important topics
 
     \list
      \li \l{Changes to Qt Multimedia}{Changes in Qt 6}
      \li \l{Multimedia Overview}
      \li \l{Audio Overview}
      \li \l{Spatial Audio Overview}
      \li \l{Video Overview}
      \li \l{Camera Overview}
      \li \l{Supported Media Formats}
     \endlist
 
    \section1 QML types
 
    The following table outlines some important QML types.
 
    \table
    \header
     \li Type
     \li Description
    \row
     \li \l{MediaPlayer}
     \li Add audio/video playback functionality to a scene.
    \row
     \li \l {QtMultimedia::CaptureSession}{CaptureSession}
     \li Create a session for capturing audio/video.
    \row
     \li \l {QtMultimedia::Camera}{Camera}
     \li Access a camera connected to the system.
    \row
     \li \l {QtMultimedia::AudioInput}{AudioInput}
     \li Access an audio input (microphone) connected to the system.
    \row
     \li \l {QtMultimedia::AudioOutput}{AudioOutput}
     \li Access an audio output (speaker, headphone) connected to the system.
    \row
     \li \l {QtMultimedia::VideoOutput}{VideoOutput}
     \li Display video content.
    \row
     \li \l {QtMultimedia::MediaRecorder}{MediaRecorder}
     \li Record audio/video from the CaptureSession.
    \row
     \li \l {QtMultimedia::ImageCapture}{ImageCapture}
     \li Capture still images from the Camera.
    \row
     \li \l {QtMultimedia::Video}{Video}
     \li Add Video playback functionality to a scene. Uses MediaPlayer and
     VideoOutput types to provide video playback functionality.
    \row
     \li \l {QtMultimedia::ScreenCapture}{ScreenCapture}
     \li Captures a screen.
    \row
     \li \l {QtMultimedia::WindowCapture}{WindowCapture}
     \li Captures a top-level window.
    \endtable
 
    \section1 C++ classes
 
    The following table outlines some important C++ classes
 
    \table
    \header
     \li Class
     \li Description
    \row
     \li QMediaPlayer
     \li Playback media from a source.
    \row
     \li QVideoWidget
     \li Display video from a media player or a capture session.
    \row
     \li QMediaCaptureSession
     \li Capture audio and video.
    \row
     \li QCamera
     \li Access a camera connected to the system
    \row
     \li QAudioInput
     \li Access an audio input (microphone) connected to the system.
    \row
     \li QAudioOutput
     \li Access an audio output (speaker, headphone) connected to the system.
    \row
     \li QImageCapture
     \li Capture still images with a camera.
    \row
     \li QMediaRecorder
     \li Record media content from a capture session.
    \row
     \li QVideoSink
     \li Access and render individual video frames.
    \row
     \li QAudioSink
     \li Sends raw audio data to an audio output device.
    \row
     \li QScreenCapture
     \li Captures a screen.
    \row
     \li QWindowCapture
     \li Captures a top-level window.
    \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 Multimedia module is available under commercial licenses from
    \l{The Qt Company}.
    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}.
    See \l{Qt Licensing} for further details.
 
    Furthermore, Qt Multimedia in Qt \QtVersion may contain third-party modules
    under following permissive licenses:
 
    \generatelist{groupsbymodule attributions-qtmultimedia}
 
    Note that video compression standards, such as the H.264 media compression
    standard, may be covered by patents and can incur royalty fees. This can
    apply to any implementation, also if the implementation is provided as an
    operating system service, through a third party library, or through any of
    Qt Multimedia's backends. Such fees are not covered by the Qt licenses.
 
    \section1 Target platform and backend notes
    We aim to align the behavior on all the platforms but there are some issues
    to consider.
 
    \section2 Backends
    On most platforms, there are two different backends that can be used for
    Qt Multimedia.
 
    \section3 FFmpeg as the default backend
    In this release the \l {http://ffmpeg.org}{FFmpeg framework} is set as the
    default backend on Windows, macOS, Android, and Linux except Yocto distribution.
 
    The version shipped with Qt binary packages is \b{FFmpeg 6.1.1} and is tested
    by the maintainers.
 
    \note On the Windows platform, Qt's FFmpeg media backend uses
    dynamic linking to the FFmpeg libraries. Windows applications must
    therefore bundle FFmpeg binaries in their installer, and make them
    visible to the application according to Windows dll loading rules.
    We recommend to store the FFmpeg dlls in the same directory as the
    application's executable file, because this guarantees that the
    correct build of FFmpeg is being used if multiple versions are
    available on the system. All necessary FFmpeg dlls are shipped with
    the Qt Online Installer and are automatically deployed if the
    windeployqt tool is used to create the deployment. Applications can
    also deploy their own build of FFmpeg, as long as the FFmpeg major
    version matches the version used by Qt.
 
    \note See \l{Licenses and Attributions} regarding what components are removed
    in the package shipped by Qt.
 
    \section3 Native backends
    These are:
    \list
        \li gstreamer on Linux
        \li AVFoundation on macOS and iOS
        \li WMF Windows
        \li MediaCodec framework on Android
    \endlist
 
    \note These are still available but with \b limited support. The gstreamer
    backend is only available on Linux.
 
    \section2 Backend support
    Maintainers will strive to fix critical issues with the native backends but
    don't guarantee fixing minor issues and won't implement new features for the
    native backends. Furthermore, even some major issues with the gstreamer
    backend (on Linux) won't be fixed since gstreamer is difficult to debug and
    is further complicated as it is dependent on Linux distributions.
 
    We aim to align the behavior on all the platforms, especially, with the
    FFmpeg backend. Despite this fact we still have platform-dependent issues
    with formats, codecs, advanced camera features, and screen capturing due to
    the Qt Multimedia API relying on target platform APIs. For example, with FFmpeg,
    there are specific problems with hardware acceleration on Linux targets with
    ARM architectures.
 
    Backend-dependent limitations will be documented and their status maintained
    in the respective classes.
 
    \section2 Changing backends
 
    In the case of issues with the default FFmpeg backend, we suggest testing with a native backend.
    You can switch to native backends by setting the \c{QT_MEDIA_BACKEND} environment variable
    to \c windows, \c gstreamer (on Linux), \c darwin (on macOS and iOS), or \c android:
 
    \code
    export QT_MEDIA_BACKEND=darwin
    \endcode
 
    In order to force assign FFmpeg as the used backend, set the variable to \c ffmpeg:
 
    \code
    export QT_MEDIA_BACKEND=ffmpeg
    \endcode
 
    On the Qt Multimedia compilation stage the default media backend can be configured
    via cmake variable \c{QT_DEFAULT_MEDIA_BACKEND}.
 
    \section2 Target platform notes
    The following pages list issues for specific target platforms that are not
    related to the multimedia backed.
 
    \list
      \li \l{Qt Multimedia on macOS and iOS}{macOS and iOS}
      \li \l{Qt Multimedia on WebAssembly}{WebAssembly}
    \endlist
 
    \section1 Permissions
 
    Starting from Qt 6.6, the Qt Multimedia module uses new \l QPermission API
    to handle \l {QCameraPermission}{camera} and
    \l {QMicrophonePermission}{microphone} permissions. This means that Qt
    itself no longer queries for these permissions, so this needs to be done
    directly from the client application.
 
    Please refer to the \l {Application Permissions} page for an example of how
    to integrate the new \l QPermission API into the application.
 
    \section1 Reference and examples
    \list
      \li \l{Qt Multimedia QML Types}{QML Types}
      \li \l{Qt Multimedia C++ Classes}{C++ Classes}
      \li \l{Qt Multimedia Examples}{Examples}
    \endlist
*/