diff options
Diffstat (limited to 'src/multimedia/doc/src')
30 files changed, 1284 insertions, 1478 deletions
diff --git a/src/multimedia/doc/src/audiooverview.qdoc b/src/multimedia/doc/src/audiooverview.qdoc index d39738da4..40a6318a6 100644 --- a/src/multimedia/doc/src/audiooverview.qdoc +++ b/src/multimedia/doc/src/audiooverview.qdoc @@ -1,136 +1,130 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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 Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page audiooverview.html \title Audio Overview -\brief Audio playback, recording and processing +\inlineimage sound-wave-small.jpg +\brief Playback, recording and processing of Audio. +\ingroup explanations-graphicsandmultimedia \section1 Audio Features -Qt Multimedia offers a range of audio classes, covering both low and -high level approaches to audio input, output and processing. In -addition to traditional audio usage, the \l{Qt Audio Engine QML Types}{Qt Audio Engine} -QML types offer high level 3D positional audio for QML applications. -See that documentation for more information. +Qt Multimedia offers a range of audio classes that cover both low and +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 \l QMediaPlayer C++ class, or the \l {Audio} and \l {MediaPlayer} QML types. + +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 does depend -on the operating system environment, and also what media plugins the user -may have installed. +\l{multimedia-playing-video}{video}, if required. + +See \l{Supported Media Formats} for more detail. + +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 -You can also put files (even remote URLs) into a playlist: - \snippet multimedia-snippets/media.cpp Audio playlist +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 \l {QAudioRecorder} class allows you -to compress audio data from an input device and record it. - \snippet multimedia-snippets/media.cpp Audio recorder +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. -\section2 Low Latency Sound Effects +A session recording audio from the default microphone would look as follows in C++: + + \snippet multimedia-snippets/media.cpp Media recorder -In addition to the raw access to sound devices described above, the QSoundEffect class (and -\l {SoundEffect} QML type) offers a slightly higher level way to play -sounds. These classes allow you to specify a WAV format file which can -then be played with low latency when necessary. Both QSoundEffect and -SoundEffect have essentially the same API. +In QML, the same can be achieved by: -You can adjust the number of \l {QSoundEffect::loopCount()}{loops} a sound effect is played, as well as -the \l {QSoundEffect::setVolume()}{volume} (or \l {QSoundEffect::setMuted()}{muting}) of the effect. +\qml +CaptureSession { + audioInput: AudioInput {} + mediaRecorder: MediaRecorder { + id: recorder + outputLocation: "file:///path/to/test.mp3" + } + Component.onCompleted: { recorder.record() } +} +\endqml -For older, Qt 4.x based applications \l QSound is also available. Applications -are recommended to use QSoundEffect where possible. +QMediaCaptureSession also provides support for more complex use cases such as image +capturing or video recording. -\section2 Monitoring Audio Data During Playback or Recording +\section2 Low Latency Sound Effects -The \l QAudioProbe class allows you to monitor audio data being played or -recorded in the higher level classes like \l QMediaPlayer, \l QCamera and -\l QAudioRecorder. After creating your high level class, you can simply -set the source of the probe to your class, and receive audio buffers as they -are processed. This is useful for several audio processing tasks, particularly -for visualization or adjusting gain. You cannot modify the buffers, and -they may arrive at a slightly different time than the media pipeline -processes them. +In addition to \l{raw access} to sound devices, the QSoundEffect +class (and \l{SoundEffect} QML type) offers a more abstract way to play +sounds. This class allows you to specify a \b{WAV format} file, which can +then be played with low latency when necessary. -Here's an example of installing a probe during recording: - \snippet multimedia-snippets/media.cpp Audio probe +You can adjust the: +\list + \li \l{QSoundEffect::loopCount()}{Number of loops} in which a sound effect + is played. + \li \l{QSoundEffect::setVolume()}{Volume} of the sound effect. + \li \l{QSoundEffect::setMuted()}{Muting} of the sound effect. +\endlist +\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 +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 can support different types of raw audio data. -The QAudioOutput class offers raw audio data output, while QAudioInput -offers raw audio data input. Both classes have adjustable buffers and -latency, so they are suitable for both low latency use cases (like games -or VOIP) and high latency (like music playback). The available hardware +The QAudioSink class offers raw audio data output, while QAudioSource +offers raw audio data input. The available hardware determines what audio outputs and inputs are available. \section3 Push and Pull The low level audio classes can operate in two modes - \c push and \c pull. In \c pull mode, the audio device is started by giving it a QIODevice. For -an output device, the QAudioOutput class will pull data from the QIODevice +an output device, the QAudioSink class will pull data from the QIODevice (using \l QIODevice::read()) when more audio data is required. Conversely, -for \c pull mode with QAudioInput, when audio data is available then the +for \c pull mode with QAudioSource, when audio data is available then the data will be written directly to the QIODevice. In \c push mode, the audio device provides a QIODevice instance that -can be written or read to as needed. Typically this results in simpler +can be written or read to as needed. Typically, this results in simpler code but more buffering, which may affect latency. \section2 Decoding Compressed Audio to Memory + In some cases you may want to decode a compressed audio file and do further -processing yourself (for example, mixing multiple samples or using custom -digital signal processing algorithms). QAudioDecoder supports decoding local +processing yourself. For example, mixing multiple samples or using custom +digital signal processing algorithms. QAudioDecoder supports decoding local files or data streams from QIODevice instances. Here's an example of decoding a local file: \snippet multimedia-snippets/audio.cpp Local audio decoding -\section1 Examples - -There are both C++ and QML examples available. +\section2 Spatial Audio -\section2 C++ Examples - -\annotatedlist audio_examples +The \l {Qt Spatial Audio} module provides an API for implementation sound +fields in 3D space. \section1 Reference Documentation @@ -142,4 +136,8 @@ There are both C++ and QML examples available. \annotatedlist multimedia_audio_qml +\section2 Examples + +\annotatedlist audio_examples */ + diff --git a/src/multimedia/doc/src/cameraoverview.qdoc b/src/multimedia/doc/src/cameraoverview.qdoc index 69631fdab..b93954d6d 100644 --- a/src/multimedia/doc/src/cameraoverview.qdoc +++ b/src/multimedia/doc/src/cameraoverview.qdoc @@ -1,82 +1,82 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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 Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page cameraoverview.html \title Camera Overview \brief Camera viewfinder, still image capture, and video recording. +\ingroup explanations-graphicsandmultimedia The Qt Multimedia API provides a number of camera related classes, so you -can access images and videos from mobile device cameras or webcameras. +can access images and videos from mobile device cameras or web cameras. There are both C++ and QML APIs for common tasks. \section1 Camera Features -In order to use the camera classes a quick overview of the way a camera -works is needed. If you're already familiar with this, you can skip ahead to +In order to use the camera classes, a quick overview of the way a camera +works is needed. If you're already familiar with this, you can skip ahead to \l {camera-tldr}{Camera implementation details}. +For a more detailed explanations of how a camera works, see the following YouTube +clip. + +\youtube qS1FmgPVLqw \section2 The Lens Assembly + At one end of the camera assembly is the lens assembly (one or -more lenses, arranged to focus light onto the sensor). The lenses -themselves can sometimes be moved to adjust things like focus and zoom, -or they might be fixed in an arrangement to give a good balance between -objects in focus, and cost. +more lenses, arranged to focus light onto the sensor). The lenses +themselves can sometimes be moved to adjust things like focus and zoom. They +might also be fixed in an arrangement for a good balance between maintaining +focus and cost. + +\image how-focus-works.gif "An animation of how focus works" + +\image Zoom.gif "An animation of how zoom works." Some lens assemblies can automatically be adjusted so that an object at different distances from the camera can be kept in focus. This is usually done by measuring how sharp a particular area of the -frame is, and by adjusting the lens assembly until it is maximally -sharp. In some cases the camera will always use the center of the -frame for this. Other cameras may also allow the region to focus -to be specified (for "touch to zoom", or "face zoom" features). +frame is, and then adjusting the lens assembly to find the peak sharpness. In +some cases, the camera will always use the center of the frame for this. +In other cases, a camera may also allow this target focus region to be specified. +Some examples of this feature include: +\list +\li Face zoom: Using computer vision to detect and use one or more faces as the +target. +\li Touch to zoom: Enabling the user to manually select an area via the preview +screen. +\endlist \section2 The Sensor Once light arrives at the sensor, it gets converted into digital pixels. This process can depend on a number of things but ultimately comes down -to two things - how long the conversion is allowed to take, and how -bright the light is. The longer a conversion can take, the better the -quality. Using a flash can assist with letting more light hit the sensor, +to two things: +\list +\li The length of time conversion is allowed to take. Also known as exposure +time. +\li How bright the light is. +\endlist + +The longer a conversion is allowed to take, the better the resulting image +quality. Using a flash can assist with letting more light hit the sensor, allowing it to convert pixels faster, giving better quality for the same -amount of time. Conversely, allowing a longer conversion time can let you -take photos in darker environments, as long as the camera is steady. +amount of time. Conversely, allowing a longer conversion time can let you +take photos in darker environments, \b{as long as the camera is steady}. If the +camera moves while the sensor is recording, the resulting image is blurred. \section2 Image Processing After the image has been captured by the sensor, the camera firmware performs various image processing tasks on it to compensate for various sensor -characteristics, current lighting, and desired image properties. Faster sensor -pixel conversion times tend to introduce digital noise, so some amount of image -processing can be done to remove this based on the camera sensor settings. +characteristics, current lighting, and desired image properties. Faster sensor +pixel conversion times may introduce digital noise, so some amount of image +processing can be done to remove this, based on the camera sensor settings. The color of the image can also be adjusted at this stage to compensate for different light sources - fluorescent lights and sunlight give very different appearances to the same object, so the image can be adjusted based on the white balance of the picture (due to the different color temperatures of the light sources). +\image image_processing.png "5 examples of various image processing techniques." Some forms of "special effects" can also be performed at this stage. Black and white, sepia, or "negative" style images can be produced. @@ -84,31 +84,24 @@ and white, sepia, or "negative" style images can be produced. \section2 Recording for Posterity Finally, once a perfectly focused, exposed and processed image has been created, it can be put to good use. Camera images can be further processed -by application code (for example, to detect barcodes, or to stitch together a +by application code (for example, to detect bar-codes, or to stitch together a panoramic image), or saved to a common format like JPEG, or used to create a movie. Many of these tasks have classes to assist them. \target camera-tldr \section1 Camera Implementation Details -\section2 Detecting and Selecting Camera +\section2 Detecting and Selecting a Camera -Before using the camera APIs, you should check that a camera is available at runtime. If there -is none, you could for example disable camera related features in your application. To perform this -check in C++, use the \l QCameraInfo::availableCameras() function, as shown in the example below: +Before using the camera APIs, you should check that a camera is available at +runtime. If there is none available, you could disable camera related features +in your application. To perform this check in C++, use the +\l QMediaDevices::videoInputs() function, as shown in the example below: - \snippet multimedia-snippets/camera.cpp Camera overview check - -In QML, use the \l{QtMultimedia::QtMultimedia::availableCameras}{QtMultimedia.availableCameras} -property: -\qml -Item { - property bool isCameraAvailable: QtMultimedia.availableCameras.length > 0 -} -\endqml + \snippet multimedia-snippets/camera.cpp Camera overview check -After determining whether a camera is available, access it using the \l QCamera class in C++ or -the \l Camera type in QML. +Access a camera using the \l QCamera class in C++ or the \l Camera +type in QML. When multiple cameras are available, you can specify which one to use. @@ -116,22 +109,19 @@ In C++: \snippet multimedia-snippets/camera.cpp Camera selection -In QML, you can set the \c Camera \l{Camera::deviceId}{deviceId} property. All available IDs can -be retrieved from \l{QtMultimedia::QtMultimedia::availableCameras}{QtMultimedia.availableCameras}: - -\qml -Camera { - deviceId: QtMultimedia.availableCameras[0].deviceId -} -\endqml - -You can also select the camera by its physical position on the system rather than its device ID. -This is useful on mobile devices, which often have a front-facing and a back-facing camera. +In QML, you can select the camera by setting the \l{Camera::cameraDevice} property. +You can also select a camera by its physical position on the system rather than +by camera info. This is useful on mobile devices, which often have a +front-facing and a back-facing camera. In C++: \snippet multimedia-snippets/camera.cpp Camera overview position + +In QML, you can set the \c Camera \l{Camera::cameraDevice}{cameraDevice} property. +Available cameras can be retrieved with MediaDevices.videoInputs + In QML: \qml @@ -140,66 +130,65 @@ Camera { } \endqml -If neither device ID nor position is specified, the default camera will be used. On desktop -platforms, the default camera is set by the user in the system settings. On a mobile device, the -back-facing camera is usually the default camera. You can get information about the default camera -using \l QCameraInfo::defaultCamera() in C++ or -\l{QtMultimedia::QtMultimedia::defaultCamera}{QtMultimedia.defaultCamera} in QML. -\section2 Viewfinder +If both QCameraDevice and position aren't specified, the default camera +will be used. On desktop platforms, the default camera is set by the +user in the system settings. On a mobile device, the back-facing camera +is usually the default camera. You can get the default camera with +QMediaDevices::defaultVideoInput() or MediaDevices.defaultVideoInput +in QML. + +\section2 Preview While not strictly necessary, it's often useful to be able to see -what the camera is pointing at. Most digital cameras allow an image -feed from the camera sensor at a lower resolution (usually up to -the size of the display of the camera) so you can compose -a photo or video, and then switch to a slower but higher resolution -mode for capturing the image. +what the camera is pointing at. This is known as a preview. Depending on whether you're using QML or C++, you can do this in multiple ways. -In QML, you can use \l Camera and \l VideoOutput together to show a -simple viewfinder: +In QML, you can use \l Camera and videoOutput together to monitor a +captureSession. \qml -VideoOutput { - source: camera +Item { + VideoOutput { + id: output + anchors.fill: parent + } + CaptureSession { + videoOutput: output - Camera { - id: camera - // You can adjust various settings in here + Camera { + // You can adjust various settings in here + } } } \endqml In C++, your choice depends on whether you are using widgets, or QGraphicsView. -The \l QCameraViewfinder class is used in the widgets case, and \l QGraphicsVideoItem +The \l QVideoWidget class is used in the widgets case, and \l QGraphicsVideoItem is useful for QGraphicsView. \snippet multimedia-snippets/camera.cpp Camera overview viewfinder -For advanced usage (like processing viewfinder frames as they come, to detect -objects or patterns), you can also derive from \l QAbstractVideoSurface and -set that as the viewfinder for the QCamera object. In this case you will -need to render the viewfinder image yourself. +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 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 viewfinder 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{QWindow::contentOrientation}{contentOrientation} property of QWindow. \section2 Still Images -After setting up a viewfinder and finding something photogenic, -to capture an image we need to initialize a new QCameraImageCapture -object. All that is then needed is to start the camera, lock it so -that things are in focus and the settings are not different from the -viewfinder while the image capture occurs, capture the image, and -finally unlock the camera ready for the next photo. +After setting up a viewfinder and finding something photogenic, to capture an +image we need to initialize a new QImageCapture object. All that is then +needed is to start the camera and capture the image. \snippet multimedia-snippets/camera.cpp Camera overview capture @@ -213,90 +202,68 @@ well as creating a viewfinder, we will also initialize a media recorder object. \snippet multimedia-snippets/camera.cpp Camera overview movie -Signals from the \e mediaRecorder can be connected to slots to react to -changes in the state of the recorder or error events. Recording itself -starts with the \l {QMediaRecorder::record()}{record()} function of -mediaRecorder being called, this causes the signal \l -{QMediaRecorder::stateChanged()}{stateChanged()} to be emitted. The -recording process can be changed with the \l {QMediaRecorder::record()}{record()}, -\l {QMediaRecorder::stop()}{stop()} and \l {QMediaRecorder::setMuted()}{setMuted()} -slots in \l QMediaRecorder. +Signals from the \e QMediaRecorder can be connected to slots to react to +changes in the state of the encoding process or error events. Recording +starts when \l QMediaRecorder::record() is called. This causes the signal +\l{QMediaRecorder::}{recorderStateChanged()} to be emitted. Recording is +controlled by the record(), stop(), and pause() slots of QMediaRecorder. \section2 Controlling the Imaging Pipeline -Now that the basics of capturing images or movies are covered, there are a number +Now that the basics of capturing images and movies are covered, there are a number of ways to control the imaging pipeline to implement some interesting techniques. As explained earlier, several physical and electronic elements combine to determine the final images, and you can control them with different classes. \section3 Focus and Zoom -Focusing (and zoom) is managed primarily by the \l QCameraFocus class. -QCameraFocus allows the developer to set the general policy by means of the -enums for the \l {QCameraFocus::FocusMode}{FocusMode} and the -\l {QCameraFocus::FocusPointMode}{FocusPointMode}. \l {QCameraFocus::FocusMode}{FocusMode} -deals with settings such as \l {QCameraFocus::FocusMode}{AutoFocus}, -\l {QCameraFocus::FocusMode}{ContinuousFocus} and \l {QCameraFocus::FocusMode}{InfinityFocus}, -whereas \l {QCameraFocus::FocusMode}{FocusPointMode} deals with the -various focus zones within the view that are used for autofocus modes. \l {QCameraFocus::FocusMode}{FocusPointMode} -has support for face recognition (where the camera supports it), center focus and a custom -focus where the focus point can be specified. +QCamera allows you to set the general focus policy by means of the +enums for the \l {QCamera::FocusMode}{FocusMode}. \l {QCamera::FocusMode}{FocusMode} +deals with settings such as \l {QCamera::FocusModeAuto}, +and \l {QCamera::FocusModeInfinity}. -For camera hardware that supports it, \l {QCameraFocus::FocusMode}{Macro focus} allows -imaging of things that are close to the sensor. This is useful in applications like -barcode recognition, or business card scanning. +For camera hardware that supports it, \l QCamera::FocusModeAutoNear allows +imaging of things that are close to the sensor. This is useful in applications +like bar-code recognition, or business card scanning. -In addition to focus, QCameraFocus allows you to control any available optical or -digital zoom. In general, optical zoom is higher quality, but more expensive to -manufacture, so the available zoom range might be limited (or fixed to unity). +In addition to focus, QCamera allows you to control any available zoom +functionality using \l{QCamera::setZoomFactor}{setZoomFactor()} or +\l{QCamera::zoomTo}{zoomTo()}. The +available zoom range might be limited or entirely fixed to unity (1:1). The +allowed range can be checked with \l{QCamera::minimumZoomFactor}{minimumZoomFactor()} +and \l{QCamera::maximumZoomFactor}{maximumZoomFactor()}. -\section3 Exposure, Aperture, Shutter Speed and Flash +\section3 Exposure, Shutter Speed and Flash There are a number of settings that affect the amount of light that hits the -camera sensor, and hence the quality of the resulting image. The \l QCameraExposure -class allows you to adjust these settings. You can use this class to implement -some techniques like High Dynamic Range (HDR) photos by locking the exposure -parameters (with \l {QCamera::searchAndLock()}), or motion blur by setting slow shutter speeds -with small apertures. - -The main settings for automatic image taking are the \l {QCameraExposure::ExposureMode}{exposure mode} -and \l {QCameraExposure::FlashMode}{flash mode}. Several other settings (aperture, ISO setting, - shutter speed) are usually managed automatically but can also be overridden if desired. - -You can also adjust the \l {QCameraExposure::meteringMode()} to control which parts -of the camera frame to measure exposure at. Some camera implementations also allow -you to specify a specific point that should be used for exposure metering - this is -useful if you can let the user touch or click on an interesting part of the viewfinder, -and then use this point so that the image exposure is best at that point. - -Finally, you can control the flash hardware (if present) using this class. In some cases -the hardware may also double as a torch (typically when the flash is LED based, rather than -a xenon or other bulb). See also \l {Torch} for an easy to use API for -torch functionality. +camera sensor, and hence the quality of the resulting image. + +The main settings for automatic image taking are the +\l {QCamera::ExposureMode}{exposure mode} and \l {QCamera::FlashMode}{flash mode}. +Several other settings (such as: ISO setting and exposure time) are usually +managed automatically, but can also be overridden if desired. + +Finally, you can control the flash hardware (if present) using this class. In +some cases the hardware may also double as a torch. \target camera_image_processing \section3 Image Processing -The QCameraImageProcessing class lets you adjust the image processing -part of the pipeline. This includes the \l {QCameraImageProcessing::WhiteBalanceMode}{white balance} -(or color temperature), \l {QCameraImageProcessing::contrast()}{contrast}, -\l {QCameraImageProcessing::saturation()}{saturation}, \l {QCameraImageProcessing::setSharpeningLevel()}{sharpening} -and \l {QCameraImageProcessing::setDenoisingLevel()}{denoising}. Most cameras support automatic settings -for all of these, so you shouldn't need to adjust them unless the user wants a specific setting. +The QCamera class lets you adjust the image processing part of the pipeline. +These settings include: +\list + \li \l {QCamera::WhiteBalanceMode}{white balance} + (also known as color temperature) +\endlist -If you're taking a series of images (for example, to stitch them together for -a panoramic image), you should lock the image processing settings so that all the -images taken appear similar with \e {QCamera::searchAndLock(QCamera::LockWhiteBalance)}/ +Most cameras support automatic settings for all of these, so you shouldn't need +to adjust them unless the user wants a specific setting. \section3 Canceling Asynchronous Operations -Various operations such as image capture and auto focusing occur -asynchrously. These operations can often be canceled by the start of a new -operation as long as this is supported by the camera. For image capture, -the operation can be canceled by calling -\l {QCameraImageCapture::cancelCapture()}{cancelCapture()}. For AutoFocus, -autoexposure or white balance cancellation can be done by calling -\e {QCamera::unlock(QCamera::LockFocus)}. +Various operations, such as image capture and auto focusing, occur asynchronously. +These operations can often be canceled by the start of a new operation, as long +as this is supported by the camera. \section1 Examples diff --git a/src/multimedia/doc/src/changes.qdoc b/src/multimedia/doc/src/changes.qdoc deleted file mode 100644 index fd7188fa3..000000000 --- a/src/multimedia/doc/src/changes.qdoc +++ /dev/null @@ -1,140 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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 Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.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 5 combines (and replaces) two older modules, namely the -Qt Multimedia module from Qt 4.x, and Qt Multimedia Kit module from Qt Mobility. -Existing code that uses Qt Multimedia from Qt 4 can be ported with minimal effort, but -porting code that uses Qt Multimedia Kit may be a more involved process. The -\l {changed features} section highlights changes relevant to porting. - -Also, note that widget-based classes, such as \l QVideoWidget, are now in a separate -module called Qt Multimedia Widgets. - -\section1 New features in Qt 5.0 - -There are a number of new features in Qt Multimedia: -\list -\li Expanded QML API -\li In addition to the \l Video QML type, there is now the option of using \l MediaPlayer and \l VideoOutput together -\li QML \l Torch class -\li New \l QAudioRecorder class -\li Volume support for QAudioOutput and QAudioInput -\li More examples and documentation -\li QSound moved from Qt GUI to Qt Multimedia -\li QSoundEffect available to C++ now, as well as QML -\li Various other API improvements and bugfixes -\endlist - - -\section1 Removed features - -A number of classes or features previously offered in Qt Multimedia or Qt Multimedia Kit have -been removed. - -\table 70% - \header - \li Removed feature - \li Notes - \row - \li QMediaImageViewer - \li This class (and related controls and services) were removed since - their functionality was not suitable for many applications -\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. This table highlights such changes. - -\table 70% - \header - \li Changed feature - \li Notes - \row - \li \c qmake project file changes - \li Previously, to use Qt Multimedia Kit, the \c qmake project file must contain - \code - CONFIG += mobility - MOBILITY += multimedia - \endcode - Now, you only need to write - \code - QT += multimedia - \endcode - Or, if you want to use the widget classes, - \code - QT += multimedia multimediawidgets - \endcode - \row - \li Namespaces - \li The \c QtMultimediaKit namespace has been renamed to QMultimedia. This - affects a few enumerations, namely \c SupportEstimate, \c EncodingQuality, - \c EncodingMode and \c AvailabilityStatus. Searching and replacing - \c QtMultimediaKit with \c QMultimedia will greatly aid porting efforts. Metadata - have been split off into their own namespace, QMediaMetaData. - \row - \li Metadata types - \li In Qt Multimedia Kit, pre-defined metadata keys were enumerations in the - \c QtMultimediaKit namespace. These pre-defined keys have been changed to - string literals in the \c QMediaMetaData namespace, for consistency with - extended keys. - \row - \li Metadata accessor methods - \li In Qt Multimedia Kit, there were two different families of methods to access - metadata. Functions such as \c QMediaObject::metaData() operated on pre-defined - metadata using enumerated keys, while functions such as - \c QMediaObject::extendedMetaData() operated on extended metadata using - string keys. Qt 5 combines both families into one (e.g. QMediaObject::metaData()), - which can operate on both pre-defined and extended metadata, using string keys. - \row - \li Qt Metatype registration - \li Qt 5 registers many more classes and types with the meta-object system than before. - If you have previously applied Q_DECLARE_METATYPE macros to any Qt Multimedia class, - you will probably need to remove them. - \row - \li QSoundEffect availability - \li The SoundEffect QML type was publicly accessible in Qt Multimeda Kit, - and now the C++ version is officially public too. If your code contains the - previously undocumented QSoundEffect, you may need to update it. - \row - \li Camera controls - \li A large number of the camera controls (QCameraImageProcessingControl, - QCameraFocusControl, etc.) have been updated to address a number of - design flaws. In particular, a number of discrete - accessor methods have been collapsed into parametrized methods, and - the ranges or data types of some parameters have been adjusted. - -\endtable - -*/ diff --git a/src/multimedia/doc/src/examples/video-qml-paint-rate.qdocinc b/src/multimedia/doc/src/examples/video-qml-paint-rate.qdocinc index 860f14270..34f7df319 100644 --- a/src/multimedia/doc/src/examples/video-qml-paint-rate.qdocinc +++ b/src/multimedia/doc/src/examples/video-qml-paint-rate.qdocinc @@ -2,7 +2,7 @@ The QML painting rate is calculated by the FrequencyMonitor class, which turns a stream of events (received via the notify() slot), into an instantaneous and an averaged frequency: -\quotefromfile multimedia/video/snippets/frequencymonitor/frequencymonitor.h +\quotefromfile video/qmlvideo/frequencymonitor.h \skipto class FrequencyMonitor : public QObject \printuntil Q_OBJECT \skipto Q_PROPERTY(qreal instantaneousFrequency @@ -19,13 +19,13 @@ instantaneous and an averaged frequency: The FrequencyMonitor class is exposed to QML like this -\quotefromfile multimedia/video/snippets/frequencymonitor/frequencymonitordeclarative.cpp +\quotefromfile video/qmlvideo/frequencymonitordeclarative.cpp \skipto FrequencyMonitor::qmlRegisterType \printuntil } and its data is displayed by defining a QML item called FrequencyItem, like this: -\quotefromfile multimedia/video/snippets/frequencymonitor/qml/frequencymonitor/FrequencyItem.qml +\quotefromfile video/qmlvideo/frequencymonitor/FrequencyItem.qml \skipto import FrequencyMonitor \printuntil id: root \dots @@ -39,5 +39,3 @@ and its data is displayed by defining a QML item called FrequencyItem, like this The result looks like this: \image video-qml-paint-rate.png - - diff --git a/src/multimedia/doc/src/images/Zoom.gif b/src/multimedia/doc/src/images/Zoom.gif Binary files differnew file mode 100644 index 000000000..dfba0faf1 --- /dev/null +++ b/src/multimedia/doc/src/images/Zoom.gif diff --git a/src/multimedia/doc/src/images/camera_correctionAngle_90.png b/src/multimedia/doc/src/images/camera_correctionAngle_90.png Binary files differnew file mode 100644 index 000000000..7a3c169a5 --- /dev/null +++ b/src/multimedia/doc/src/images/camera_correctionAngle_90.png diff --git a/src/multimedia/doc/src/images/how-focus-works.gif b/src/multimedia/doc/src/images/how-focus-works.gif Binary files differnew file mode 100644 index 000000000..a691b49ac --- /dev/null +++ b/src/multimedia/doc/src/images/how-focus-works.gif diff --git a/src/multimedia/doc/src/images/image_processing.png b/src/multimedia/doc/src/images/image_processing.png Binary files differnew file mode 100644 index 000000000..2a52fbce3 --- /dev/null +++ b/src/multimedia/doc/src/images/image_processing.png diff --git a/src/multimedia/doc/src/images/noun_Media_166644.svg b/src/multimedia/doc/src/images/noun_Media_166644.svg new file mode 100644 index 000000000..cc2fa8d83 --- /dev/null +++ b/src/multimedia/doc/src/images/noun_Media_166644.svg @@ -0,0 +1,64 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + version="1.1" + x="0px" + y="0px" + viewBox="0 0 97.908676 59.1375" + enable-background="new 0 0 100 100" + xml:space="preserve" + id="svg26" + sodipodi:docname="noun_Media_166644.svg" + width="97.908676" + height="59.137501" + inkscape:version="1.0.2 (e86c870879, 2021-01-15, custom)"><metadata + id="metadata32"><rdf:RDF><cc:Work + rdf:about=""><dc:format>image/svg+xml</dc:format><dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /></cc:Work></rdf:RDF></metadata><defs + id="defs30" /><sodipodi:namedview + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1" + objecttolerance="10" + gridtolerance="10" + guidetolerance="10" + inkscape:pageopacity="0" + inkscape:pageshadow="2" + inkscape:window-width="2560" + inkscape:window-height="1377" + id="namedview28" + showgrid="false" + inkscape:zoom="8.064" + inkscape:cx="32.007416" + inkscape:cy="20.413416" + inkscape:window-x="1912" + inkscape:window-y="-8" + inkscape:window-maximized="1" + inkscape:current-layer="svg26" + inkscape:document-rotation="0" /><g + transform="matrix(0.13985577,0,0,-0.1432582,-21.001292,1300.868)" + id="g20"><path + d="m 467.5,9080.3 c -2.1,-0.6 -3.7,-1.9 -4.6,-3.7 -0.7,-1.4 -0.8,-6.7 -0.8,-48.2 v -46.6 h 7.1 7.1 v 23.6 23.6 h 105.1 105.1 v -47.8 c 0,-26.2 0.1,-47.8 0.4,-47.8 0.2,0 3.2,0.6 6.7,1.4 l 6.4,1.3 0.1,69.7 c 0.1,68.3 0.1,69.7 -0.8,71.2 -0.5,0.9 -1.7,2 -2.6,2.5 -1.5,0.8 -6.9,0.9 -114.9,1 -62.1,0.2 -113.6,0 -114.3,-0.2 z m 32.5,-25.6 v -11.8 h -11.8 -11.8 v 11.8 11.8 h 11.8 11.8 z m 37.4,0 v -11.8 h -11.6 -11.6 v 11.8 11.8 h 11.6 11.6 z m 37.5,0 v -11.8 h -11.6 -11.6 v 11.8 11.8 h 11.6 11.6 z m 37.4,0 v -11.8 h -11.6 -11.6 v 11.8 11.8 h 11.6 11.6 z m 37.4,0 v -11.8 h -11.6 -11.6 v 11.8 11.8 h 11.6 11.6 z m 36.9,0 v -11.8 H 675.3 664 v 11.8 11.8 h 11.3 11.3 z" + id="path2" /><path + d="m 546,9008.9 c -1.2,-0.5 -2.5,-1.7 -3.1,-2.6 -1,-1.6 -1,-2.4 -1,-53.2 0,-46.4 0.1,-51.8 0.8,-53.3 1.1,-2.2 3.4,-3.6 6.2,-3.6 2,0 5.2,1.9 43.5,25.4 22.7,14 41.8,25.9 42.4,26.4 2.7,2.4 2.5,7.2 -0.2,9.8 -2.5,2.3 -83.1,51.5 -84.8,51.8 -1.2,0.2 -2.4,0 -3.8,-0.7 z m 41.8,-38.4 c 21.8,-13.4 28.3,-17.6 27.8,-18 -0.7,-0.7 -58.2,-36.1 -59.2,-36.5 -0.6,-0.2 -0.7,5.8 -0.7,37 v 37.3 l 1.9,-1.1 c 1,-0.7 14.6,-9.1 30.2,-18.7 z" + id="path4" /><path + d="m 179,8967.7 c -2.5,-0.4 -7.7,-2.3 -10.3,-3.6 -8.4,-4.4 -14.3,-11.9 -17.3,-21.7 l -1.1,-3.6 -0.1,-80.3 c -0.1,-54.6 0,-81.7 0.4,-84.8 1.8,-16.1 13.6,-28.6 29.5,-31.1 2.2,-0.4 49.5,-0.5 149.2,-0.5 120.1,0 146.6,0.1 149.7,0.7 10.8,2 20,8.9 24.9,18.7 3.9,7.9 3.6,2.1 3.6,93.6 0,90.9 0.2,85.5 -3.4,93 -4.6,9.6 -12.9,16.3 -23.3,19 -3.8,1 -5.4,1 -152.1,0.9 -81.8,-0.1 -149,-0.2 -149.7,-0.3 z m 297.5,-14 c 7.9,-1.7 14.6,-8.5 16.1,-16.7 0.7,-3.7 0.7,-159.8 0,-163.7 -1.4,-7.8 -7.3,-14.2 -14.8,-16.2 -2.9,-0.8 -13.8,-0.8 -150.6,-0.7 l -147.5,0.1 -3.3,1.6 c -4.4,2.1 -8.3,6 -10.3,10.3 l -1.6,3.3 -0.1,82.2 c -0.1,81.1 -0.1,82.3 0.9,85.5 2.2,7.1 9,13.2 16.2,14.4 0.7,0.1 66.8,0.2 146.8,0.3 104.9,0.1 146.3,0 148.2,-0.4 z" + id="path6" /><path + d="m 194,8929.6 c -0.8,-0.5 -1.9,-1.7 -2.3,-2.6 -0.8,-1.5 -0.9,-5.9 -0.9,-72.1 v -70.5 l 1.1,-1.7 c 0.7,-1 2,-2 3.4,-2.6 2.3,-1 2.3,-1 4.6,0 1.4,0.6 2.8,1.6 3.4,2.6 l 1.1,1.7 v 70.4 c 0,78 0.2,72.6 -3.2,74.7 -1.9,1.4 -5.2,1.4 -7.2,0.1 z" + id="path8" /><path + d="m 412.5,8929.8 c -3,-1 -7.1,-5 -8.5,-8.1 -1.1,-2.5 -1.2,-3.1 -1.2,-13.2 0,-12.4 0.3,-13.9 4.3,-18.1 4.3,-4.5 4.4,-4.6 27.4,-4.6 23,0 23.1,0 27.4,4.6 4,4.2 4.3,5.7 4.3,18.1 0,10.1 0,10.7 -1.2,13.2 -1.5,3.2 -5.6,7.1 -8.7,8.2 -3.3,1 -40.6,1 -43.8,-0.1 z m 39.5,-21.6 v -8.4 H 434.5 417 l -0.1,7.9 c 0,4.3 0,8.1 0.1,8.5 0.2,0.5 3.7,0.6 17.6,0.5 l 17.4,-0.1 z" + id="path10" /><path + d="m 318.8,8917.6 c -9.3,-1.5 -19.2,-5.4 -26.7,-10.4 -4.8,-3.2 -12.8,-11 -16.2,-15.8 -8.2,-11.4 -12.4,-24.3 -12.4,-38.3 0,-17 6.2,-32.4 17.8,-44.7 16.4,-17.2 40.3,-24.2 63.3,-18.4 25.8,6.5 44.8,28 48.6,54.9 0.7,5.1 0.3,16.2 -0.7,21.2 -2.9,13 -8.7,23.8 -18,33 -9.3,9.3 -19.3,14.8 -32.5,17.8 -5.7,1.2 -17.5,1.6 -23.2,0.7 z m 16.7,-13.8 c 6.7,-0.6 15.6,-4.1 22.5,-8.8 4.5,-3 10.1,-8.9 13.5,-14.1 10,-15.5 11,-34.7 2.5,-51.2 -6.7,-13 -18.1,-22.2 -32.9,-26.2 -3.2,-0.9 -5.2,-1.1 -12.4,-1.1 -10,0 -13.8,0.7 -21.5,4.3 -10.8,5.1 -18.7,12.7 -24,22.9 -4.3,8.3 -6.1,16.5 -5.6,26 0.4,7.1 1.7,12.7 4.5,18.6 3,6.2 5.2,9.5 9.9,14.3 8.3,8.7 19.6,14.2 31.7,15.4 3.7,0.5 5.6,0.5 11.8,-0.1 z" + id="path12" /><path + d="m 326,8893.5 c -0.8,-0.3 -2,-1.3 -2.7,-2 -1,-1.1 -1.2,-1.8 -1.2,-4.5 0,-3.1 0.1,-3.2 1.8,-4.8 1.3,-1.2 2.4,-1.7 4.2,-1.9 9.7,-1.1 13.8,-2.8 19,-7.6 4.8,-4.4 8.2,-11.6 8.3,-17 0,-4.7 2.1,-8.2 5.4,-9.1 3.7,-1 8,1.6 8.7,5.3 0.5,2.6 -0.5,10 -1.9,14.1 -2.3,6.8 -5.4,11.6 -10.5,16.5 -6.3,6.1 -13.1,9.6 -21.6,11 -5.4,0.8 -7.6,0.8 -9.5,0 z" + id="path14" /><path + d="m 752.2,8933.3 c -49.4,-10.4 -90.3,-19.3 -90.9,-19.7 -0.6,-0.4 -1.6,-1.3 -2,-2.1 -0.8,-1.3 -0.9,-6 -1.1,-81.5 l -0.2,-80.2 -3.3,2.7 c -4.3,3.4 -10.8,6.8 -16.3,8.5 -4.1,1.3 -5,1.4 -13,1.4 -7.9,0 -9,-0.1 -12.9,-1.3 -16.9,-5.2 -28.9,-17.6 -33.7,-35 -0.6,-2.4 -0.8,-5 -0.8,-11.4 0,-7.7 0.1,-8.8 1.4,-12.8 5.4,-17.7 19.6,-30.6 37.5,-33.7 4.6,-0.8 15.7,-0.4 19.9,0.7 17.2,4.7 29.5,17.1 34.6,35.1 l 1.1,3.8 0.1,65 0.1,65 81.2,17.7 c 44.7,9.7 81.4,17.5 81.6,17.3 0.2,-0.2 0.4,-21.2 0.5,-46.7 0.1,-45.5 0.1,-46.3 -0.8,-45.6 -0.5,0.4 -2.5,1.9 -4.3,3.2 -11,8.4 -26.3,11.5 -39.9,8 -4.5,-1.1 -12.1,-4.6 -15.7,-7.3 -13.4,-9.7 -20.8,-25.1 -19.8,-41.4 0.7,-12 5,-21.9 13.3,-30.5 9.3,-9.6 20.8,-14.5 34,-14.5 13,0 24.7,4.9 34,14.3 5.7,5.8 9.7,12.8 12.2,21.7 l 1.1,3.8 0.1,104.4 c 0.1,98.8 0,104.5 -0.7,106.1 -1.2,2.2 -3,3.5 -5.4,3.8 -1.5,0.1 -32.1,-6.2 -91.9,-18.8 z m 84.1,-21.2 v -24.4 l -1.1,-0.2 c -3,-0.7 -159.4,-34.7 -161,-35 l -1.8,-0.3 0.1,25 0.1,25 81,17.1 c 44.6,9.4 81.4,17.1 81.9,17.1 0.7,0.1 0.8,-1.4 0.8,-24.3 z m -27.8,-133.7 c 10,-1.8 19.4,-8.9 23.8,-17.9 2.6,-5.2 3.5,-9.4 3.6,-14.8 0,-5.9 -0.8,-9.4 -3.4,-15 -3.8,-8 -11.2,-14.4 -19.8,-17.2 -6.8,-2.3 -16.7,-1.7 -23.5,1.2 -9.2,4.1 -16.7,13 -19.2,22.8 -1.1,4.4 -0.7,13.9 0.7,18.3 1.6,4.8 4.4,9.2 8.5,13.3 7.7,7.8 18.7,11.3 29.3,9.3 z m -176.8,-30.7 c 9.8,-2.1 18.5,-9 23,-18.2 5.5,-11.5 4.2,-24.4 -3.7,-35.1 -5.7,-7.7 -16.2,-12.9 -26.1,-12.9 -10.2,0 -20.8,5.1 -26.7,12.9 -7.8,10.3 -9.2,23.6 -3.6,35.1 3.5,7.2 8.7,12.3 16.1,15.9 6.2,2.9 13.9,3.8 21,2.3 z" + id="path16" /><path + d="m 521.7,8874 v -6.9 h 7.9 7.9 v -11.6 -11.5 h -7.9 -7.9 v -7.1 -7.1 h 61.5 61.5 v 7.1 7.1 h -9.1 -9.1 v 11.6 11.6 h 9.1 9.1 v 6.9 6.9 h -61.5 -61.5 z m 53.2,-18.5 V 8844 h -11.6 -11.6 v 11.6 11.6 h 11.6 11.6 z m 37.4,0 V 8844 h -11.6 -11.6 v 11.6 11.6 h 11.6 11.6 z" + id="path18" /></g></svg> diff --git a/src/multimedia/doc/src/images/qS1FmgPVL.jpg b/src/multimedia/doc/src/images/qS1FmgPVL.jpg Binary files differnew file mode 100644 index 000000000..4dc2bb7c2 --- /dev/null +++ b/src/multimedia/doc/src/images/qS1FmgPVL.jpg diff --git a/src/multimedia/doc/src/images/sound-wave-small.jpg b/src/multimedia/doc/src/images/sound-wave-small.jpg Binary files differnew file mode 100644 index 000000000..1a873d94d --- /dev/null +++ b/src/multimedia/doc/src/images/sound-wave-small.jpg diff --git a/src/multimedia/doc/src/multimedia-overview.qdoc b/src/multimedia/doc/src/multimedia-overview.qdoc new file mode 100644 index 000000000..6da54a7e2 --- /dev/null +++ b/src/multimedia/doc/src/multimedia-overview.qdoc @@ -0,0 +1,142 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + + + +/*! +\page multimediaoverview.html +\title Multimedia Overview +\brief A set of APIs for working with audio, video and camera devices. +\ingroup explanations-graphicsandmultimedia + +Multimedia support in Qt is provided by the \l{Qt Multimedia} module. The Qt +Multimedia module provides a rich feature set that enables you to easily take +advantage of a platform's multimedia capabilities, such as media playback and +the use of camera devices. + +\section1 Features + +Here are some things you can do with the Qt Multimedia APIs: + +\list +\li Access raw audio devices for input and output. +\li Play low latency sound effects. +\li Play 3D spatial audio. +\li Play media files in playlists (such as compressed audio or video files). +\li Record audio and compress it. +\li Use a camera, including viewfinder, image capture, and movie recording +\li Decode audio media files into memory for processing. +\endlist + +\section1 Multimedia Components + +The Qt Multimedia APIs are categorized into three main components. More +information specific to each component is available in the overview pages. You +can also take a look at some \l{Multimedia Recipes}{recipes}. + +\list +\li \l {Audio Overview} +\li \l {Video Overview} +\li \l {Camera Overview} +\li \l {Spatial Audio Overview} (Technology Preview) +\endlist + +\section1 Multimedia Recipes + +For some quick recipes, see this table: + +\table 70% + \header + \li Use case + \li Examples + \li QML Types + \li C++ Classes + \row + \li Playing a sound effect + \li + \li \l{SoundEffect} + \li QSoundEffect + \row + \li Playing 3D sound + \li \l{Spatial Audio Panning Example}{audiopanning} + \li SpatialSound, AudioEngine + \li QSpatialSound, QAudioEngine + \row + \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 Output Example}{audiooutput} + \li + \li QAudioSink + \row + \li Accessing raw audio input data + \li \l{Spectrum Example}{spectrum}, + \l{Audio Source Example}{audiosource} + \li + \li QAudioSource + \row + \li Recording encoded audio data + \li \l{Audio Recorder Example}{audiorecorder} + \li \l{CaptureSession}, \l{AudioInput}, \l{MediaRecorder} + \li QMediaCaptureSession, QAudioInput, QMediaRecorder + \row + \li Discovering audio and video devices + \li \l{Audio Devices Example}{audiodevices} + \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} + \li \l MediaPlayer, \l VideoOutput, \l Video + \li QMediaPlayer, QVideoWidget, QGraphicsVideoItem + \row + \li Capturing audio and video + \li \l {Camera Example}{camera}, + \l {QML Video Recorder}{recorder} + \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 Video Recorder}{recorder} + \li \l CaptureSession, \l Camera, \l ImageCapture + \li QMediaCaptureSession, QCamera, QImageCapture + \row + \li Capturing movies + \li \l {Camera Example}{camera}, + \l {QML Video Recorder}{recorder} + \li \l CaptureSession, \l Camera, \l MediaRecorder + \li QMediaCaptureSession, QCamera, QMediaRecorder +\endtable + +\section1 Limitations + +The Qt Multimedia APIs build upon the multimedia framework of the underlying +platform. This can mean that support for various codecs, or containers will vary +between machines. This support depends on what the end user has installed. +See \l{Supported Media Formats} for more detail. + +\note Qt Multimedia APIs depend on functionality provided by QCoreApplication, +and multimedia objects created using the Qt Multimedia APIs can only be used +during the lifetime of this application object. It is therefore important to +create a QCoreApplication, QGuiApplication, or QApplication before accessing +any of the Qt Multimedia APIs. If the application object is recreated, make +sure that any Qt Multimedia objects are also recreated. + +\section1 Changes from Previous Versions + +If you previously used Qt Multimedia in Qt 5, see +\l{Changes to Qt Multimedia} for more information on what has changed, and what +you might need to change when porting code to Qt 6. + +\section1 Reference Documentation + +\list + \li \l{Qt Multimedia C++ Classes}{C++ Classes} + \li \l{Qt Multimedia QML Types}{QML Types} +\endlist +*/ diff --git a/src/multimedia/doc/src/multimedia.qdoc b/src/multimedia/doc/src/multimedia.qdoc deleted file mode 100644 index dcf394c87..000000000 --- a/src/multimedia/doc/src/multimedia.qdoc +++ /dev/null @@ -1,186 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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 Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page multimediaoverview.html -\title Multimedia -\brief A set of APIs for working with audio, video and camera devices. - -Multimedia support in Qt is provided by the \l{Qt Multimedia} module. The Qt -Multimedia module provides a rich feature set that enables you to easily take -advantage of a platform's multimedia capabilities such as media playback and -the use of camera devices. - -\section1 Features - -Here are some examples of what can be done with Qt Multimedia APIs: - -\list -\li Access raw audio devices for input and output -\li Play low latency sound effects -\li Play media files in playlists (such as compressed audio or video files) -\li Record audio and compress it -\li Use a camera, including viewfinder, image capture, and movie recording -\li Play 3D positional audio with \l{Qt Audio Engine QML Types}{Qt Audio Engine} -\li Decode audio media files into memory for processing -\li Accessing video frames or audio buffers as they are played or recorded -\endlist - -\section1 Multimedia Components - -Qt's multimedia APIs are categorized into four main components. More -information (including background information and class references) is -available here: - -\list -\li \l {Audio Overview} -\li \l {Video Overview} -\li \l {Camera Overview} -\endlist - -\section1 Multimedia Recipes - -For some quick recipes, look at the overviews above and consult this table: - -\table 70% - \header - \li Use case - \li Examples - \li QML Types - \li C++ Classes - \row - \li Playing a sound effect - \li - \li - \li QSoundEffect - \row - \li Playing low latency audio - \li \l{Audio Input Example}{audioinput}, - \l{Spectrum Example}{spectrum} - \li - \li QAudioOutput - \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 Input Example}{audioinput} - \li - \li QAudioInput - \row - \li Recording encoded audio data - \li \l{Audio Recorder Example}{audiorecorder} - \li - \li QAudioRecorder - \row - \li Discovering raw audio devices - \li \l{Audio Devices Example}{audiodevices} - \li - \li QAudioDeviceInfo - \row - \li Video Playback - \li \l{Media Player Example}{player}, - \l{QML Video Example}{qmlvideo}, - \l{QML Video Shader Effects Example}{qmlvideofx} - \li \l MediaPlayer, \l VideoOutput, \l Video - \li QMediaPlayer, QVideoWidget, QGraphicsVideoItem - \row - \li Video Processing - \li \l {QML Video Example}{qmlvideofx} - \li \l {MediaPlayer}, \l VideoOutput - \li QMediaPlayer, QAbstractVideoSurface, QVideoFrame - \row - \li Accessing camera viewfinder - \li \l {Camera Example}{camera}, - \l {QML Camera Example}{declarative-camera} - \li \l Camera, \l VideoOutput - \li QCamera, QVideoWidget, QGraphicsVideoItem - \row - \li Viewfinder processing - \li - \li \l Camera, \l VideoOutput - \li QCamera, QAbstractVideoSurface, QVideoFrame - \row - \li Capturing photos - \li \l {Camera Example}{camera}, - \l {QML Camera Example}{declarative-camera} - \li \l Camera - \li QCamera, QCameraImageCapture - \row - \li Capturing movies - \li \l {Camera Example}{camera}, - \l {QML Camera Example}{declarative-camera} - \li \l Camera - \li QCamera, QMediaRecorder - \row - \li 3D sound sources - \li - \li \l {AudioEngine Example}{Audio Engine} - \li \l {AudioEngine}, \l Sound - \li -\endtable - -\section1 Limitations - -The Qt Multimedia APIs build upon the multimedia framework of the underlying -platform. This can mean that support for various codecs or containers can vary -between machines, depending on what the end user has installed. - -\section1 Advanced Usage - -For developers wishing to access some platform specific settings, or to port the -Qt Multimedia APIs to a new platform or technology, see \l{Multimedia Backend -Development}. - -\section1 Changes from Previous Versions - -If you previously used Qt Multimedia in Qt 4, or used Qt Multimedia Kit in -Qt Mobility, please see \l {Changes in Qt Multimedia} for more information on -what changed, and what you might need to change when porting code. - -\section1 Reference Documentation - -\section2 QML Types -The QML types are accessed by using: -\code -import QtMultimedia 5.8 -\endcode -\annotatedlist multimedia_qml -The following types are accessed by using \l{Qt Audio Engine QML Types}{Qt Audio Engine}: -\qml \QtMinorVersion -import QtAudioEngine 1.\1 -\endqml -\annotatedlist multimedia_audioengine - -\section2 Multimedia Classes - -\annotatedlist multimedia - -*/ diff --git a/src/multimedia/doc/src/multimediabackend.qdoc b/src/multimedia/doc/src/multimediabackend.qdoc deleted file mode 100644 index 48d598999..000000000 --- a/src/multimedia/doc/src/multimediabackend.qdoc +++ /dev/null @@ -1,139 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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 Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - - -/*! - -\title Multimedia Backend Development -\page multimediabackend.html -\brief Information for implementing a new multimedia backend. -\ingroup mobility - -\tableofcontents - -\section1 Overview - -A multimedia backend provides the glue between platform-specific libraries, and -Qt Multimedia. In some cases the available cross-platform Multimedia APIs or -implementations are not sufficient, or not immediately available on a certain -platform. Alternatively, the multimedia implementation on a platform might expose -certain extra properties or functionality that other platforms do not, or a finer -degree of control might be possible. For these cases, it is possible to use -extended controls directly. -\omit -In addition, if you plan to port the Qt Multimedia APIs to a new platform, you do -this by implementing certain control and service classes, as detailed below. - -\section1 Extending the API - -For the developer who wishes to extend the functionality of the Qt Multimedia -classes there are several classes of particular importance. The classes -providing default functionality are QMediaService, QMediaServiceProvider and -QMediaControl. Some of these classes are not in the public API since they -are very seldom useful to application developers. - -To extend the Multimedia API you would use the following three classes or -classes derived from them. - - \list - \li QMediaServiceProvider is used by the top level client class to - request a service. The top level class knowing what kind of service it needs. - - \li \l QMediaService provides a service and when asked by the top level - object, say a component, will return a QMediaControl object. - - \li \l QMediaControl allows the control of the service using a known interface. - \endlist - -Consider a developer creating, for example, a media player class called MyPlayer. -It may have special requirements beyond ordinary media players and so may -need a custom service and a custom control. We can subclass QMediaServiceProvider -to create our MyServiceProvider class. Also we will create a -MyMediaService, and the MyMediaControl to manipulate the media service. - -The MyPlayer object calls MyServiceProvider::requestService() to get an -instance of MyMediaService. Then the MyPlayer object calls this service -object it has just received and calling \l {QMediaService::requestControl()}{requestControl()} -it will receive the control object derived from QMediaControl. - -Now we have all the parts necessary for our media application. We have the service -provider, the service it provides and the control used to manipulate the -service. Since our MyPlayer object has instances of the service and its -control then it would be possible for these to be used by associated classes -that could do additional actions, perhaps with their own control since the -parameter to requestControl() is a zero-terminated string, \e {const char *}, -for the interface. - -\section2 Adding a Media Service Provider - -In general, adding a new media service provider is outside the scope of this documentation. -For best results, consult the existing provider source code, and seek assistance on the relevant -mailing lists and IRC channels. - -The base class for creating new service providers is \l{QMediaServiceProvider}. -The user must implement the \l{QMediaServiceProvider::requestService()}{requestService()} -function - -\code - QMediaService* requestService(const QByteArray &type, const QMediaServiceProviderHint &hint); -\endcode - -The details of implementation will depend on the provider. Looking at the -class \l QMediaServiceProvider for the default implementation. Notice that -\l {QMediaServiceProvider::requestService()}{requestService()} uses the -\l QMediaServiceProviderHint to look for the appropriate plugin and then to -insert it into the plugin map. However, for a specific service provider there -is probably no need for this approach, it will simply depend on what the -developer wants to implement. - -Other methods that may be overloaded -\code - void releaseService(QMediaService *service); - - QtMediaServices::SupportEstimate hasSupport(const QByteArray &serviceType, - const QString &mimeType, - const QStringList& codecs, - int flags) const; - - QStringList supportedMimeTypes(const QByteArray &serviceType, int flags) const; - - QList<QByteArray> devices(const QByteArray &serviceType) const; - - QString deviceDescription(const QByteArray &serviceType, const QByteArray &device); -\endcode - -The choice of what needs to be done depends on what the developer wishes to do with the service. - -\endomit - -\section2 Classes for service implementers. - -\annotatedlist multimedia_control - -*/ - - diff --git a/src/multimedia/doc/src/platform-notes-apple.qdoc b/src/multimedia/doc/src/platform-notes-apple.qdoc new file mode 100644 index 000000000..a9bca07c2 --- /dev/null +++ b/src/multimedia/doc/src/platform-notes-apple.qdoc @@ -0,0 +1,19 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qtmultimedia-apple.html +\title Qt Multimedia on macOS and iOS +\brief Platform notes for iOS + +This page covers the availability of Qt Multimedia features on iOS and macOS. + +\section1 Limitations + +Since Qt Multimedia for iOS uses the camera and microphone, the \c Info.plist +assigned to QMAKE_INFO_PLIST in the project file must contain the keys +\c NSCameraUsageDescription and \c NSMicrophoneUsageDescription. Otherwise, the +application will abort on startup. See \l{Info.plist} documentation from Apple +for more information regarding this key. + +*/ diff --git a/src/multimedia/doc/src/platform-notes-gstreamer-on-android.qdoc b/src/multimedia/doc/src/platform-notes-gstreamer-on-android.qdoc deleted file mode 100644 index 51836d99a..000000000 --- a/src/multimedia/doc/src/platform-notes-gstreamer-on-android.qdoc +++ /dev/null @@ -1,59 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2019 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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 Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page platform-notes-gstreamer-on-android.html -\title Qt Multimedia GStreamer on Android -\brief Platform notes for GStreamer on Android -\since 5.14 - -This page covers the availability of GStreamer on Android. - -\section1 Limitations - -Since GStreamer is licensed under LGPL and distributed in archives (and should be statically linked), -Qt Multimedia does not provide support of GStreamer on Android by default. - -Therefore GStreamer support must be explicitly enabled by configuring Qt with the \c -gstreamer option. - -\section1 Setup - -The GStreamer project provides prebuilt binaries which you can download and unzip into any location of your choice. - -The environment variable \c GSTREAMER_ROOT_ANDROID should be set to the location where you unzipped the downloaded package. - -\section1 Application - -Qt Multimedia does not contain any plugins and all needed plugins must be included -and registered in applications manually by \c GST_PLUGIN_STATIC_DECLARE and \c GST_PLUGIN_STATIC_REGISTER -after \c gst_init(). - -Please refer to the official manual on how to statically link plugins to an application. - -https://gstreamer.freedesktop.org/documentation/gstreamer/gstplugin.html?gi-language=c#GST_PLUGIN_STATIC_REGISTER - -*/ diff --git a/src/multimedia/doc/src/platform-notes-ios.qdoc b/src/multimedia/doc/src/platform-notes-ios.qdoc deleted file mode 100644 index db5cd6d5a..000000000 --- a/src/multimedia/doc/src/platform-notes-ios.qdoc +++ /dev/null @@ -1,43 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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 Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qtmultimedia-ios.html -\title Qt Multimedia on iOS -\brief Platform notes for iOS - -This page covers the availability of Qt Multimedia features on iOS. - -\section1 Limitations - -Since Qt Multimedia for iOS uses the camera, the \c Info.plist assigned to -QMAKE_INFO_PLIST in the project file must contain the key -\c NSCameraUsageDescription. Otherwise the application will -abort on startup. See Info.plist documentation from Apple for more information -regarding this key. - -*/ diff --git a/src/multimedia/doc/src/platform-notes-wasm.qdoc b/src/multimedia/doc/src/platform-notes-wasm.qdoc new file mode 100644 index 000000000..d1a942c9f --- /dev/null +++ b/src/multimedia/doc/src/platform-notes-wasm.qdoc @@ -0,0 +1,35 @@ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qtmultimedia-wasm.html +\title Qt Multimedia on WebAssembly +\brief Platform notes for WebAssembly + +This page covers the availability of Qt Multimedia features on WebAssembly. + +\section1 Limitations + +Due to the asynchronous nature of javascript, some features such as getting the list of +QMediaDevices, will not be readily available and may take some time to request permissions and +gather the list of devices. The audioInputsChanged, audioOutputsChanged and +videoInputChanged signals from QMediaDevices class will be emitted when they are available. + +Playing video currently works by using a html 2d context, so all operations are on the CPU. + +Performance is acceptable, although there is a copy on every frame, so it may be +less performant than desktop platforms when playing hi-def video. + +Using and selecting different Codecs/video formats have not yet been tested, but whatever +video formats the browser supports will most likely work. + +Playing data from a stream (using \c {setSourceDevice(QIODevice*)}), instead +of fetching a URL, isn't supported. + +Some advanced features may or may not work at this time. + +Files can be served from the/any web server, respective +of \l{https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS}{CORS}. Because of +the limited size of local file storage, playing local files is discouraged. + + */ diff --git a/src/multimedia/doc/src/platform-notes-windows.qdoc b/src/multimedia/doc/src/platform-notes-windows.qdoc deleted file mode 100644 index a69e96d99..000000000 --- a/src/multimedia/doc/src/platform-notes-windows.qdoc +++ /dev/null @@ -1,62 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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 Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qtmultimedia-windows.html -\title Qt Multimedia on Windows -\brief Platform notes for Windows - -This page covers the availability of Qt Multimedia features on Windows. - -\section1 Implementation - -Qt Multimedia features for Windows are implemented in two plugins; one -using the Microsoft DirectShow API, and another using WMF (Windows Media -Foundation) framework. DirectShow API was introduced in Windows 98, and -gradually deprecated from Windows XP onwards. Media Foundation framework -was introduced in Windows Vista as a replacement for DirectShow and other -multimedia APIs. Consequently, WMF plugin in Qt is supported only for -Windows Vista and later versions of the operating system. - -The environment variable \c QT_MULTIMEDIA_PREFERRED_PLUGINS can be used to -control the priority of the plugins. For example, setting it to -"windowsmediafoundation" or "directshow" will cause the corresponding plugin -to be the preferred one. - -\section1 Limitations - -The WMF plugin in Qt does not currently provide a camera backend. Instead, -limited support for camera features is provided by the DirectShow -plugin. Basic features such as displaying a viewfinder and capturing a -still image are supported, however, majority of camera controls are not -implemented. - -Video recording is currently not supported. Additionally, the DirectShow -plugin does not support any low-level video functionality such as -monitoring video frames being played or recorded using \l QVideoProbe or -related classes. -*/ diff --git a/src/multimedia/doc/src/plugins/qml-multimedia.qdoc b/src/multimedia/doc/src/plugins/qml-multimedia.qdoc deleted file mode 100644 index b6df70973..000000000 --- a/src/multimedia/doc/src/plugins/qml-multimedia.qdoc +++ /dev/null @@ -1,216 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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 Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page qml-multimedia.html - - \title Qt Multimedia QML API - - \brief A QML API for the Qt Multimedia module. - - - \section1 Overview - - The Qt Multimedia module gives developers a simplified way to use audio and video playback, and access camera functionality. The Multimedia QML API provides a QML friendly interface to these features. - - \section1 Types - - \section2 Audio - - \l Audio is an easy way to add audio playback to a Qt Quick - scene. Qt Multimedia provides properties for control, methods (functions) and signals. - - The code extract below shows the creation and use of an Audio instance. - - \qml - - Item { - width: 640 - height: 360 - - Audio { - id: playMusic - source: "music.wav" - } - - MouseArea { - id: playArea - anchors.fill: parent - onPressed: { playMusic.play() } - } - } - - \endqml - - The snippet above shows how the inclusion of \e playMusic enables audio features on the type that contains it. So that when the parent's MouseArea is clicked the \l {Audio::play()}{play()} method of Audio is run. Other typical audio control methods are available such as \l {Audio::pause}{pause()} and \l {Audio::stop()}{stop()}. - - Much of the getting / setting of \l Audio parameters is done through properties. These include - \table 70% - \header - \li Property - \li Description - \row - \li \l {Audio::source}{source} - \li The source URL of the media. - \row - \li \l {Audio::autoLoad}{autoLoad} - \li Indicates if loading of media should begin immediately. - \row - \li \l{Audio::playing}{playing} - \li Indicates that the media is playing. - \row - \li \l {Audio::paused}{paused} - \li The media is paused. - \row - \li \l{Audio::status}{status} - \li The status of media loading. - \row - \li \l{Audio::duration}{duration} - \li Amount of time in milliseconds the media will play. - \row - \li \l{Audio::position}{position} - \li Current position in the media in milliseconds of play. - \row - \li \l{Audio::volume}{volume} - \li Audio output volume: from 0.0 (silent) to 1.0 (maximum) - \row - \li \l{Audio::muted}{muted} - \li Indicates audio is muted. - \row - \li \l{Audio::bufferProgress}{bufferProgress} - \li Indicates how full the data buffer is: 0.0 (empty) to 1.0 (full). - \row - \li \l{Audio::seekable}{seekable} - \li Indicates whether the audio position can be changed. - \row - \li \l{Audio::playbackRate}{playbackRate} - \li The rate at which audio is played at as a multiple of the normal rate. - \row - \li \l{Audio::error}{error} - \li An error code for the error state including NoError - \row - \li \l{Audio::errorString}{errorString} - \li A description of the current error condition. - \endtable - - The set of signals available allow the developer to create custom behavior when the following events occur, - - \table 70% - \header - \li Signal - \li Description - \row - \li \l{Audio::playing}{playing} - \li Called when playback is started, or when resumed from paused state. - \row - \li \l{Audio::paused}{paused} - \li Called when playback is paused. - \row - \li \l{Audio::stopped}{stopped} - \li Called when playback is stopped. - \row - \li \l{Audio::error}{error} - \li Called when the specified error occurs. - \endtable - - \section2 Camera - - \l Camera enables still image and video capture using - QML. It has a number of properties that help setting it up. - - The details of using a \l Camera are described in further depth - in the \l {Camera Overview} and in the corresponding reference documentation. - - \section2 Video - - Adding video playback, with sound, to a Qt Quick scene is also easy. The process is very similar to that of Audio above, in fact \l {Video} shares many of the property names, methods and signals. Here is the equivalent sample code to implement video playback in a scene - - \qml - - Video { - id: video - width : 800 - height : 600 - source: "video.avi" - - MouseArea { - anchors.fill: parent - onClicked: { - video.play() - } - } - - focus: true - Keys.onSpacePressed: video.paused = !video.paused - Keys.onLeftPressed: video.position -= 5000 - Keys.onRightPressed: video.position += 5000 - } - - \endqml - - There are similar features like \l {Video::play()}{play()} with new - features specific to video. - - In the above sample when the parent of MouseArea is clicked, an area of 800x600 pixels with an id of 'video', the source "video.avi" will play in that area. Notice also that signals for the \l Keys have been defined so that a spacebar will toggle the pause button; the left arrow will move the current position in the video to 5 seconds previously; and the right arrow will advance the current position in the video by 5 seconds. - - Most of the differences will obviously be about video control and information. There are many properties associated with \l {Video}, most of them deal with meta-data, control of the video media and aspects of presentation. - - \section2 SoundEffect - - \l SoundEffect provides a way to play short sound effects, like in video games. Multiple sound effect instances can be played simultaneously. - You should use \l Audio for music playback. - - \qml - - Item { - width: 640 - height: 360 - - SoundEffect { - id: effect - source: "test.wav" - } - MouseArea { - id: playArea - anchors.fill: parent - onPressed: { effect.play() } - } - } - - \endqml - - - In the above sample the sound effect will be played when the MouseArea is clicked. - - For a complete description of this type, see \l SoundEffect - - \section1 Multimedia QML Types - - \annotatedlist multimedia_qml -*/ - - diff --git a/src/multimedia/doc/src/qm-external-pages.qdoc b/src/multimedia/doc/src/qm-external-pages.qdoc new file mode 100644 index 000000000..8a28780c0 --- /dev/null +++ b/src/multimedia/doc/src/qm-external-pages.qdoc @@ -0,0 +1,232 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \externalpage https://gstreamer.freedesktop.org + \title gstreamer +*/ +/*! + \externalpage https://en.wikipedia.org/wiki/Pixel_Format + \title pixel format +*/ + +/*! + \externalpage https://developer.apple.com/documentation/bundleresources/information_property_list + \title Info.plist +*/ + +/*! + \externalpage https://www.wix.com/blog/photography/2018/10/04/photography-terms/ + \title photo glossary +*/ + +/*! + \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 +*/ + +/*! + \externalpage https://en.wikipedia.org/wiki/Windows_Media_Audio + \title Windows Media Audio +*/ + +/*! + \externalpage https://en.wikipedia.org/wiki/Advanced_Audio_Coding + \title Advanced Audio Coding +*/ + +/*! + \externalpage https://en.wikipedia.org/wiki/ALAC + \title Apple Lossless Audio Codec +*/ + +/*! + \externalpage https://en.wikipedia.org/wiki/Matroska + \title Matroska (MKV) +*/ + +/*! + \externalpage https://en.wikipedia.org/wiki/Windows_Media_Video + \title Windows Media Video +*/ + +/*! + \externalpage https://en.wikipedia.org/wiki/MP3 + \title MPEG-1 Audio Layer III or MPEG-2 Audio Layer III +*/ + +/*! + \externalpage https://en.wikipedia.org/wiki/WAV + \title Waveform Audio File Format +*/ + +/*! + \externalpage https://en.wikipedia.org/wiki/Ogg + \title Ogg +*/ + +/*! + \externalpage https://en.wikipedia.org/wiki/MPEG-4 + \title MPEG-4 +*/ + +/*! + \externalpage https://en.wikipedia.org/wiki/Audio_Video_Interleave + \title Audio Video Interleave +*/ + +/*! + \externalpage https://en.wikipedia.org/wiki/QuickTime + \title QuickTime +*/ + +/*! + \externalpage https://en.wikipedia.org/wiki/WebM + \title WebM +*/ + +/*! + \externalpage https://en.wikipedia.org/wiki/MPEG-4_Part_3 + \title MPEG-4 Part 3 or MPEG-4 Audio (formally ISO/IEC 14496-3) +*/ + +/*! + \externalpage https://en.wikipedia.org/wiki/FLAC + \title Free Lossless Audio Codec +*/ + +/*! + \externalpage https://en.wikipedia.org/wiki/Dolby_Digital + \title Dolby Digital +*/ + +/*! + \externalpage https://en.wikipedia.org/wiki/Dolby_Digital_Plus + \title Dolby Digital Plus (EAC3) +*/ + +/*! + \externalpage https://en.wikipedia.org/wiki/Opus_(audio_format) + \title Opus Audio Format +*/ + +/*! + \externalpage https://en.wikipedia.org/wiki/Dolby_TrueHD + \title Dolby TrueHD +*/ + +/*! + \externalpage https://en.wikipedia.org/wiki/Vorbis + \title Ogg Vorbis +*/ + +/*! + \externalpage https://en.wikipedia.org/wiki/VP8 + \title VP8 +*/ + +/*! + \externalpage https://en.wikipedia.org/wiki/MPEG-2 + \title MPEG-2 +*/ + +/*! + \externalpage https://en.wikipedia.org/wiki/MPEG-1 + \title MPEG-1 +*/ + +/*! + \externalpage https://en.wikipedia.org/wiki/High_Efficiency_Video_Coding + \title High Efficiency Video Coding (HEVC) +*/ + +/*! + \externalpage https://en.wikipedia.org/wiki/Advanced_Video_Coding + \title Advanced Video Coding +*/ + +/*! + \externalpage https://en.wikipedia.org/wiki/AV1 + \title AOMedia Video 1 +*/ + +/*! + \externalpage https://en.wikipedia.org/wiki/Motion_JPEG + \title MotionJPEG +*/ + +/*! + \externalpage https://en.wikipedia.org/wiki/VP9 + \title VP9 +*/ + +/*! + \externalpage https://en.wikipedia.org/wiki/Theora + \title Theora +*/ + +/*! + \externalpage https://en.wikipedia.org/wiki/Windows_Media_Player + \title Windows Media Player +*/ + + +/*! + \externalpage https://support.microsoft.com/en-us/topic/file-types-supported-by-windows-media-player-32d9998e-dc8f-af54-7ba1-e996f74375d9 + \title Windows Media Player documentation +*/ + +/*! + \externalpage https://www.codecguide.com/guides.htm + \title codec guide +*/ + +/*! + \externalpage https://developer.android.com/guide/topics/media/media-formats + \title Android supported media formats +*/ + +/*! + \externalpage https://gstreamer.freedesktop.org/ + \title GStreamer +*/ diff --git a/src/multimedia/doc/src/qt6-changes.qdoc b/src/multimedia/doc/src/qt6-changes.qdoc new file mode 100644 index 000000000..ad5ebab74 --- /dev/null +++ b/src/multimedia/doc/src/qt6-changes.qdoc @@ -0,0 +1,145 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page qtmultimedia-changes-qt6.html + \title Changes to Qt Multimedia + \ingroup changes-qt-5-to-6 + \brief Migrate Qt Multimedia to Qt 6. + + Qt 6 is a result of the conscious effort to make the framework more + efficient and easy to use. + + We try to maintain binary and source compatibility for all the public + APIs in each release. But some changes were inevitable in an effort to + make Qt a better framework. + +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 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. +\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. + \row + \li QMediaPlayList + \li This class has been removed from the API. It does however still exist + as part of the \l{Media Player Example}. + \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 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 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 + \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/qtaudioengine.qdoc b/src/multimedia/doc/src/qtaudioengine.qdoc deleted file mode 100644 index c45d4e8af..000000000 --- a/src/multimedia/doc/src/qtaudioengine.qdoc +++ /dev/null @@ -1,59 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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 Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\qmlmodule QtAudioEngine 1.\QtMinorVersion -\title Qt Audio Engine QML Types -\ingroup qmlmodules -\brief Provides QML types for 3D positional audio playback and content management. - -Qt Audio Engine is part of the \l{Qt Multimedia} module. Qt Audio -Engine provides types for 3D positional audio playback and content management. - -The QML types can be imported into your application using the following import -statement in your .qml file: -\qml \QtMinorVersion -import QtAudioEngine 1.\1 -\endqml - -\section1 Qt Audio Engine Features - -Qt Audio Engine enables developers to organize wave files into discrete \l Sound -with different \l {PlayVariation}{play variations}, group sound controls by \l -{AudioCategory} categories and define \l {AttenuationModelLinear}{attenuation -models} and various 3D audio settings all in one place. Playback of \l -{SoundInstance}{sound instances} can be conveniently activated by in-app events -and managed by QtAudioEngine or controlled by explicitly defining \l -SoundInstance for easier QML bindings. - -\section1 Examples -\list - \li \l {AudioEngine Example}{Audio Engine} -\endlist - -\section1 QML Types -*/ diff --git a/src/multimedia/doc/src/qtmultimedia-building-from-source.qdoc b/src/multimedia/doc/src/qtmultimedia-building-from-source.qdoc new file mode 100644 index 000000000..df434c699 --- /dev/null +++ b/src/multimedia/doc/src/qtmultimedia-building-from-source.qdoc @@ -0,0 +1,94 @@ +// Copyright (C) 2024 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qtmultimedia-building-from-source.html +\title Building Qt Multimedia from sources +\brief This document describes how to build Qt Multimedia with full +feature support from source code. + +This page describes the process of configuring and building \l{Qt +Multimedia}. This description assumes familiarity with \l{Building Qt +Sources} which specifies build requirements for your platform, as well +as an overview of \l{Qt Configure Options}. For platform-specific +considerations related to the Qt Multimedia module, see \l{Platform +Notes} below. + +\section1 Building from source + +Building Qt Multimedia with full feature support depends on \l +{https://ffmpeg.org/}{FFmpeg} headers and libraries on most platforms. +It is possible to build Qt Multimedia without the Qt Multimedia FFmpeg +media backend, but this is only recommended when building for platforms +where the FFmpeg backend is not supported. + +FFmpeg developer libraries required to build Qt Multimedia can be built +from sources or downloaded as binary packages. Qt Multimedia can use +either static linking or dynamic linking to FFmpeg libraries. We +recommend using the same major version of FFmpeg that is listed in +\l{FFmpeg as the default backend}. + +To build Qt Multimedia with FFmpeg support, specify the \c{-DFFMPEG_DIR} +CMake variable on the configure command line when building Qt. Note the +\c{--} separator which separates ordinary configure arguments from CMake +parameters. + +\badcode +qt-source/configure -- -DFFMPEG_DIR=<FFMPEG_DIR> +\endcode + +Here, \c{<FFMPEG_DIR>} is the directory containing the FFmpeg include, +lib, and bin directories. To build Qt Multimedia without FFmpeg, omit +the \c{<FFMPEG_DIR>} variable or specify the \c{-no-feature-ffmpeg} +configure option. + +If you prefer not to build all Qt's submodules, you can reduce configure +and build times using the \c{-submodules} configure option. This will +configure a build that only builds Qt Multimedia and its dependencies. + +\badcode +qt-source/configure -submodules qtmultimedia -- -DFFMPEG_DIR=<FFMPEG_DIR> +\endcode + +If you configure Qt Multimedia against FFmpeg built with shared +libraries (dynamic linking), the FFmpeg shared libraries must be in the +module loader's search path to run tests or use examples. + +\note Qt Multimedia requires the FFmpeg avformat, avcodec, swresample, +swscale, and avutil libraries during runtime to be able to use the +FFmpeg media backend. If one or more of these dynamic libraries are not +found during application startup, the FFmpeg media backend will fail to +load, and the system will attempt to load the native backend. Qt +Multimedia doesn't support as many features on native backends. + +If you don't already have these libraries in the \c{path}, specify the +\c{-DQT_DEPLOY_FFMPEG=ON} configure option. With this option enabled, +the necessary FFmpeg binaries will be copied to Qt's install directory +during the build and install steps: + +\badcode +qt-source/configure -submodules qtmultimedia -- -DFFMPEG_DIR=<FFMPEG_DIR> -DQT_DEPLOY_FFMPEG=ON +\endcode + +After configuring Qt Multimedia, carefully review the configure summary +(found in the config.summary file). You can verify that FFmpeg is found +under the "Plugin" section. Then follow the regular build and install +steps described in \l{Building Qt Sources}. + +\section1 Platform Notes + +\section2 Linux + +\list + \li When configuring Qt Multimedia with FFmpeg enabled, the + pulseaudio development package is required. Without this + package, FFmpeg will not be recognized. + \li When using a version of FFmpeg that is built with VAAPI support, + we recommend building Qt Multimedia with VAAPI support as well + to make hardware texture conversion possible. To configure Qt + Multimedia with VAAPI support, VAAPI developer libraries must be + installed on your system. Review the config.summary file to + verify that VAAPI support is enabled under the "Hardware + acceleration and features" section. +\endlist +*/ diff --git a/src/multimedia/doc/src/qtmultimedia-cpp.qdoc b/src/multimedia/doc/src/qtmultimedia-cpp.qdoc index f75ecbfe2..b0c4ea732 100644 --- a/src/multimedia/doc/src/qtmultimedia-cpp.qdoc +++ b/src/multimedia/doc/src/qtmultimedia-cpp.qdoc @@ -1,48 +1,21 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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 Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2015 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \module QtMultimedia \title Qt Multimedia Module C++ Classes \ingroup modules \qtvariable multimedia + \qtcmakepackage Multimedia \brief The \l {Qt Multimedia} module provides audio, video and camera functionality. - To enable Qt Multimedia in a project, add this directive into the - C++ files: - - \snippet doc_src_qtmultimedia.cpp 0 - - To link against the C++ libraries, add the following to your \c qmake project - file: - - \snippet doc_src_qtmultimedia.pro 0 + \include module-use.qdocinc using qt module + \code + find_package(Qt6 REQUIRED COMPONENTS Multimedia) + target_link_libraries(mytarget PRIVATE Qt6::Multimedia) + \endcode */ /*! @@ -54,7 +27,7 @@ QML alternatives. If your application is serving complex use cases such as decoding media files, accessing video or audio buffers, use the C++ alternative. For more details about the complex audio, video, and camera use - cases supported by the C++ classes, refer to \l {Multimedia}{Multimedia Overview}. + cases supported by the C++ classes, refer to \l {Qt Multimedia}{Multimedia Overview}. \section1 Namespaces \annotatedlist multimedia-namespaces @@ -66,4 +39,7 @@ \section2 Qt Multimedia Widgets Module \generatelist {classesbymodule QtMultimediaWidgets} + + \section2 Qt Spatial Audio Module + \generatelist {classesbymodule QtSpatialAudio} */ diff --git a/src/multimedia/doc/src/qtmultimedia-examples.qdoc b/src/multimedia/doc/src/qtmultimedia-examples.qdoc index d8da05c32..e53eed32f 100644 --- a/src/multimedia/doc/src/qtmultimedia-examples.qdoc +++ b/src/multimedia/doc/src/qtmultimedia-examples.qdoc @@ -1,37 +1,15 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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 Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2015 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \group multimedia_examples - \ingroup all-examples \title Qt Multimedia Examples \brief Demonstrates the multimedia functionality provided by Qt. - The \l{Qt Multimedia} module provides low-level audio support on Linux, - Windows and \macos. It also provides audio plugin API to allow developers - implement their own audio support for custom devices and platforms. + The \l{Qt Multimedia} module provides cross-platform multimedia capabilities + for Qt based applications. + + The examples listed below show some typical use cases in various areas, featuring + both low-level audio examples, high level audio and video playback + as well as capturing and recording of audiovisual content using both C++ and QML. */ diff --git a/src/multimedia/doc/src/qtmultimedia-index.qdoc b/src/multimedia/doc/src/qtmultimedia-index.qdoc index 13c686978..74646b84c 100644 --- a/src/multimedia/doc/src/qtmultimedia-index.qdoc +++ b/src/multimedia/doc/src/qtmultimedia-index.qdoc @@ -1,186 +1,288 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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 Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// 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 - \brief The Qt Multimedia module provides APIs for audio, video and - camera-related functionality. + \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 essential 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. The included - \l{Qt Audio Engine QML Types}{Qt Audio Engine} provides types for - 3D positional audio playback and content management. + 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{QtMultimedia}{Qt Multimedia} - \li Provides API for multimedia-specific use cases. + \li \l{Multimedia Overview}{Qt Multimedia} + \li Provides an API for multimedia-specific use cases. \row - \li \l{QtMultimediaWidgets}{Qt Multimedia Widgets} - \li Provides the widget-based multimedia API. + \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 + \section1 Getting started + If you are porting from Qt 5 to Qt 6 see \l{Changes to Qt Multimedia}. - The QML types can be imported into your applciation using the following - import 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 \QtMinorVersion - import QtMultimedia 5.\1 + \qml + import QtMultimedia \endqml - If you intend to use the C++ classes in your application, include the C++ - definitions using the following directive: + 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 - #include <QtMultimedia> - #include <QtMultimediaWidgets> - \endcode + \code + find_package(Qt6 REQUIRED COMPONENTS Multimedia) + target_link_libraries(my_project PRIVATE Qt6::Multimedia) + \endcode - \note If you are using a few classes from this module, we recommend - including those specific classes only instead of the module. + See \l {Building Qt Multimedia from sources} for guidance on building + Qt Multimedia from sources. - To link against the corresponding C++ libraries, add the following to your - \c {qmake} project file: + \section1 Overviews and important topics - \code - QT += multimedia multimediawidgets - \endcode + \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 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 + \li \l{MediaPlayer} + \li Add audio/video playback functionality to a scene. \row - \li \l {QtMultimedia::Playlist}{Playlist} - \li For specifying a list of media to be played. + \li \l {QtMultimedia::CaptureSession}{CaptureSession} + \li Create a session for capturing audio/video. \row \li \l {QtMultimedia::Camera}{Camera} - \li Access camera viewfinder frames + \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 MediaPlayer - \li Add media playback functionality to a scene. It is same as Audio type, - but can be used for video playback with the VideoOutput type. + \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. It uses MediaPlayer and + \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 QAudioOutput - \li Sends audio data to an audio output device + \li QMediaPlayer + \li Playback media from a source. + \row + \li QVideoWidget + \li Display video from a media player or a capture session. \row - \li QAudioRecorder - \li Record media content from an audio source. + \li QMediaCaptureSession + \li Capture audio and video. \row \li QCamera - \li Access camera viewfinder. + \li Access a camera connected to the system \row - \li QCameraImageCapture + \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 camera source. + \li Record media content from a capture session. \row - \li QMediaPlayer - \li Playback media from a source. + \li QVideoSink + \li Access and render individual video frames. + \row + \li QAudioSink + \li Sends raw audio data to an audio output device. \row - \li QMediaPlaylist - \li List of media to be played. + \li QScreenCapture + \li Captures a screen. \row - \li QAbstractVideoSurface - \li Base class for video presentation. + \li QWindowCapture + \li Captures a top-level window. \endtable - \section1 Licenses and Attributions + 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. - 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, + \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. - \section1 Related Information + Furthermore, Qt Multimedia in Qt \QtVersion may contain third-party modules + under following permissive licenses: - \section2 Guides - \list - \li \l Multimedia - overview of multimedia support in Qt - \li \l{Audio Overview} - \li \l{Video Overview} - \li \l{Camera Overview} - \endlist + \generatelist{groupsbymodule attributions-qtmultimedia} - \section2 Platform Notes + 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. - The \l{Qt Multimedia Backends} wiki provides a summary of features - supported by each platform plugin made available by this module. The - following topics provide more platform-specific information. + \section1 Target platform and backend notes + We aim to align the behavior on all the platforms but there are some issues + to consider. - \list - \li \l{Qt Multimedia on Windows}{Windows} - \li \l{Qt Multimedia on iOS}{iOS} - \endlist + \section2 Backends + On most platforms, there are two different backends that can be used for + Qt Multimedia. - \section2 Reference - \list - \li 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 and macOS platforms, Qt's FFmpeg media backend + uses dynamic linking to the FFmpeg libraries. Windows and macOS + applications must therefore bundle FFmpeg binaries in their + installer, and make them visible to the application at runtime. On + Windows, 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 libraries are shipped + with the Qt Online Installer and are automatically deployed if the + windeployqt or macdeployqt tools are 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 \l{Qt Multimedia QML Types}{QML Types} - \li \l{Qt Multimedia C++ Classes}{C++ Classes} - \endlist + \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. + \note MediaCodec on Android is deprecated as of Qt 6.8 and will be removed + in Qt 7.0. + + \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 Qt Audio Engine - \list - \li \l{Qt Audio Engine QML Types}{QML Types} - \endlist + \li \l{Qt Multimedia on macOS and iOS}{macOS and iOS} + \li \l{Qt Multimedia on WebAssembly}{WebAssembly} \endlist - \section2 Examples - \list - \li \l{Qt Multimedia Examples} - \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 */ diff --git a/src/multimedia/doc/src/qtmultimedia-qml-types.qdoc b/src/multimedia/doc/src/qtmultimedia-qml-types.qdoc new file mode 100644 index 000000000..0d61a8917 --- /dev/null +++ b/src/multimedia/doc/src/qtmultimedia-qml-types.qdoc @@ -0,0 +1,45 @@ +// Copyright (C) 2015 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\qmlmodule QtMultimedia +\noautolist +\title Qt Multimedia QML Types +\ingroup qmlmodules +\brief Provides QML types for multimedia support. + +The QML types for \l{Qt Multimedia} support the basic use cases such as: +\list + \li audio and video playback, + \li access camera functionality, + \li record video, + \li and access camera settings. +\endlist + +\section1 QML Types + +Qt Multimedia QML types can be imported into your application using the +following import statement in your .qml file: + +\qml +import QtMultimedia +\endqml + +\generatelist qmltypesbymodule QtMultimedia + +The \QtMultimedia import provides also the following +\l [QtQml]{QML Value Types}{value types}: + +\generatelist qmlvaluetypesbymodule QtMultimedia + +\section2 Qt Spatial Audio Module + +Qt Spatial Audio QML types can be imported into your application using the +following import statement in your .qml file: + +\qml +import QtQuick3D.SpatialAudio +\endqml + +\generatelist qmltypesbymodule QtQuick3D.SpatialAudio +*/ diff --git a/src/multimedia/doc/src/qtmultimedia5.qdoc b/src/multimedia/doc/src/qtmultimedia5.qdoc deleted file mode 100644 index 461cc716f..000000000 --- a/src/multimedia/doc/src/qtmultimedia5.qdoc +++ /dev/null @@ -1,66 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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 Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\qmlmodule QtMultimedia 5.\QtMinorVersion -\title Qt Multimedia QML Types -\ingroup qmlmodules -\brief Provides QML types for multimedia support. - -The QML types for \l{Qt Multimedia} support the basic use cases such as: -\list - \li audio and video playback, - \li access camera functionality, - \li record video, - \li and access camera settings. -\endlist - -\section1 QML Types - -Qt Multimedia QML types can be imported into your application using the -following import statement in your .qml file: - -\qml \QtMinorVersion -import QtMultimedia 5.\1 -\endqml - -\generatelist qmltypesbymodule QtMultimedia - -\section2 Qt Audio Engine - -\l {QtAudioEngine}{Qt Audio Engine} provides types for 3D positional audio -playback and content management. These types can be imported into your -application using the following import statement in your .qml file: - -\qml \QtMinorVersion -import QtAudioEngine 1.\1 -\endqml - -\generatelist qmltypesbymodule QtAudioEngine - -\noautolist -*/ diff --git a/src/multimedia/doc/src/videooverview.qdoc b/src/multimedia/doc/src/videooverview.qdoc index c3fa50f04..3185c9a02 100644 --- a/src/multimedia/doc/src/videooverview.qdoc +++ b/src/multimedia/doc/src/videooverview.qdoc @@ -1,42 +1,19 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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 Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page videooverview.html \title Video Overview \brief Video playback +\ingroup explanations-graphicsandmultimedia \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 @@ -54,69 +31,73 @@ And an example with QGraphicsVideoItem: \section2 Playing Video in QML -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 transformed -or acted upon by shaders (as the \l {QML Video Shader Effects Example} shows), while -all media decoding and playback control is handled by the \l MediaPlayer. - -Alternatively there is also a higher level \l Video type that -acts as a single, visual element to play video and control playback. +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. 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 Qt Multimedia offers a number of low level classes to make handling -video frames a bit easier. These classes are primarily used when +video frames a bit easier. These classes are primarily used when writing code that processes video or camera frames (for example, detecting barcodes, or applying a fancy vignette effect), or needs to display video in a special way that is otherwise unsupported. The \l QVideoFrame class encapsulates a video frame and allows the contents to be mapped into system memory for manipulation or -processing, while deriving a class from \l QAbstractVideoSurface +processing. Using your own QVideoSink allows you to receive these frames from \l QMediaPlayer and \l QCamera. -\snippet multimedia-snippets/video.cpp Derived Surface +\section2 Recording Video +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 Supported Media Formats -and with an instance of this surface, \c myVideoSurface, you can set -the surface as the \l {QMediaPlayer::setVideoOutput()}{video output} for QMediaPlayer. +What media formats are supported ultimately depends on the configuration of the +target system. -\snippet multimedia-snippets/video.cpp Setting surface in player +\section2 Windows +By default what is available on a MS Windows target depends on the version of +\l{Windows Media Player} that was packaged with the OS. See the +\l{Windows Media Player documentation} for official information. -Several of the built-in Qt classes offer this functionality -as well, so if you decode video in your application, you can present -it to classes that offer a \l QVideoRendererControl class, and in QML -you can set a custom object for the source of a \l VideoOutput -with either a writable \c videoSurface property (that the instance will -set it's internal video surface to) or a readable \c mediaObject property -with a QMediaObject derived class that implements the \l QVideoRendererControl -interface. +Independent of Windows Media Player, there are of course numerous codec packs +that could be installed. See the \l{codec guide} site for some examples. -The following snippet shows a class that has a writable \c videoSurface property -and receives frames through a public slot \c onNewVideoContentReceived(). These -frames are then presented on the surface set in \c setVideoSurface(). +\section2 Android +See \l{Android supported media formats} for this information. -\snippet multimedia-snippets/video.cpp Video producer +\section2 Linux +On Linux this is about installing the correct \l{GStreamer} plugins. -\section2 Recording Video -You can use the \l QMediaRecorder class in conjunction with other -classes to record video to disk. Primarily this is used with -the camera, so consult the \l {Camera Overview} for more information. - -\section2 Monitoring Video Frames -You can use the \l QVideoProbe class to access video frames as they -flow through different parts of a media pipeline when using other -classes like \l QMediaPlayer, \l QMediaRecorder or \l QCamera. After -creating the high level media class, you can set the source of the -video probe to that instance. This can be useful for performing -some video processing tasks (like barcode recognition, or object -detection) while the video is rendered normally. You can not affect -the video frames using this class, and they may arrive at a slightly -different time than they are being rendered. - -Here's an example of installing a video probe while recording the camera: - \snippet multimedia-snippets/media.cpp Video probe +\section3 Minimum Required GStreamer Plugins +\list +\li gstreamer1.0-plugins-base +\li gstreamer1.0-plugins-good +\li gstreamer1.0-plugins-pulseaudio +\endlist + +For a Linux desktop target, it is strongly recommended to have \c gstreamer1.0-libav +for good codec coverage and \c gstreamer1.0-vaapi to get hardware acceleration. + +On embedded Linux, the required set of plugins could be somewhat different. + +\section2 Determining Supported Media Formats at Runtime +You can determine what formats are available on a target system at runtime using +the static QMediaFormat API. + +\list +\li Use \l QMediaFormat::isSupported() on a QMediaFormat::ConversionMode to query a + specific format. +\li Use \l QMediaFormat::supportedFileFormats() on a default constructed QMediaFormat + to get all the supported file formats. +\endlist \section1 Examples |
