<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- videooverview.qdoc -->
<title>Video Overview | Qt Multimedia 5.12.6</title>
<link rel="stylesheet" type="text/css" href="style/offline-simple.css" />
<script type="text/javascript">
document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css");
// loading style sheet breaks anchors that were jumped to before
// so force jumping to anchor again
setTimeout(function() {
var anchor = location.hash;
// need to jump to different anchor first (e.g. none)
location.hash = "#";
setTimeout(function() {
location.hash = anchor;
}, 0);
}, 0);
</script>
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<table><tr>
<td >Qt 5.12</td><td ><a href="qtmultimedia-index.html">Qt Multimedia</a></td><td >Video Overview</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right"><a href="qtmultimedia-index.html">Qt 5.12.6 Reference Documentation</a></td>
</tr></table>
</div>
</div>
<div class="content">
<div class="line">
<div class="content mainContent">
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#video-features">Video Features</a></li>
<li class="level1"><a href="#video-implementation-details">Video Implementation Details</a></li>
<li class="level2"><a href="#playing-video-in-c">Playing Video in C++</a></li>
<li class="level2"><a href="#playing-video-in-qml">Playing Video in QML</a></li>
<li class="level2"><a href="#working-with-low-level-video-frames">Working with Low Level Video Frames</a></li>
<li class="level2"><a href="#recording-video">Recording Video</a></li>
<li class="level2"><a href="#monitoring-video-frames">Monitoring Video Frames</a></li>
<li class="level1"><a href="#examples">Examples</a></li>
<li class="level2"><a href="#c-examples">C++ Examples</a></li>
<li class="level2"><a href="#qml-examples">QML Examples</a></li>
<li class="level1"><a href="#reference-documentation">Reference Documentation</a></li>
<li class="level2"><a href="#c-classes">C++ Classes</a></li>
<li class="level2"><a href="#qml-types">QML Types</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">Video Overview</h1>
<span class="subtitle"></span>
<!-- $$$videooverview.html-description -->
<div class="descr"> <a name="details"></a>
<a name="video-features"></a>
<h2 id="video-features">Video Features</h2>
<p>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 <a href="cameraoverview.html">camera</a> and <a href="audiooverview.html">audio</a> classes, which can be useful.</p>
<a name="video-implementation-details"></a>
<h2 id="video-implementation-details">Video Implementation Details</h2>
<a name="multimedia-playing-video"></a><a name="playing-video-in-c"></a>
<h3 id="playing-video-in-c">Playing Video in C++</h3>
<p>You can use the <a href="qmediaplayer.html">QMediaPlayer</a> class to decode a video file, and display it using <a href="qvideowidget.html">QVideoWidget</a>, <a href="qgraphicsvideoitem.html">QGraphicsVideoItem</a>, or a custom class.</p>
<p>Here's an example of using <a href="qvideowidget.html">QVideoWidget</a>:</p>
<pre class="cpp">
player <span class="operator">=</span> <span class="keyword">new</span> <span class="type"><a href="qmediaplayer.html">QMediaPlayer</a></span>;
playlist <span class="operator">=</span> <span class="keyword">new</span> <span class="type"><a href="qmediaplaylist.html">QMediaPlaylist</a></span>(player);
playlist<span class="operator">-</span><span class="operator">></span>addMedia(<span class="type">QUrl</span>(<span class="string">"http://example.com/myclip1.mp4"</span>));
playlist<span class="operator">-</span><span class="operator">></span>addMedia(<span class="type">QUrl</span>(<span class="string">"http://example.com/myclip2.mp4"</span>));
videoWidget <span class="operator">=</span> <span class="keyword">new</span> <span class="type"><a href="qvideowidget.html">QVideoWidget</a></span>;
player<span class="operator">-</span><span class="operator">></span>setVideoOutput(videoWidget);
videoWidget<span class="operator">-</span><span class="operator">></span>show();
playlist<span class="operator">-</span><span class="operator">></span>setCurrentIndex(<span class="number">1</span>);
player<span class="operator">-</span><span class="operator">></span>play();
</pre>
<p>And an example with <a href="qgraphicsvideoitem.html">QGraphicsVideoItem</a>:</p>
<pre class="cpp">
player <span class="operator">=</span> <span class="keyword">new</span> <span class="type"><a href="qmediaplayer.html">QMediaPlayer</a></span>(<span class="keyword">this</span>);
<span class="type"><a href="qgraphicsvideoitem.html">QGraphicsVideoItem</a></span> <span class="operator">*</span>item <span class="operator">=</span> <span class="keyword">new</span> <span class="type"><a href="qgraphicsvideoitem.html">QGraphicsVideoItem</a></span>;
player<span class="operator">-</span><span class="operator">></span>setVideoOutput(item);
graphicsView<span class="operator">-</span><span class="operator">></span>scene()<span class="operator">-</span><span class="operator">></span>addItem(item);
graphicsView<span class="operator">-</span><span class="operator">></span>show();
player<span class="operator">-</span><span class="operator">></span>setMedia(<span class="type">QUrl</span>(<span class="string">"http://example.com/myclip4.ogv"</span>));
player<span class="operator">-</span><span class="operator">></span>play();
</pre>
<a name="playing-video-in-qml"></a>
<h3 id="playing-video-in-qml">Playing Video in QML</h3>
<p>You can use <a href="qml-qtmultimedia-videooutput.html">VideoOutput</a> to render content that is provided by either a <a href="qml-qtmultimedia-mediaplayer.html">MediaPlayer</a> or a <a href="qml-multimedia.html#camera">Camera</a>. The <a href="qml-qtmultimedia-videooutput.html">VideoOutput</a> is a visual component that can be transformed or acted upon by shaders (as the <a href="qtmultimedia-multimedia-video-qmlvideofx-example.html">QML Video Shader Effects Example</a> shows), while all media decoding and playback control is handled by the <a href="qml-qtmultimedia-mediaplayer.html">MediaPlayer</a>.</p>
<p>Alternatively there is also a higher level <a href="qml-multimedia.html#video">Video</a> type that acts as a single, visual element to play video and control playback.</p>
<a name="working-with-low-level-video-frames"></a>
<h3 id="working-with-low-level-video-frames">Working with Low Level Video Frames</h3>
<p>Qt Multimedia offers a number of low level classes to make handling 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.</p>
<p>The <a href="qvideoframe.html">QVideoFrame</a> class encapsulates a video frame and allows the contents to be mapped into system memory for manipulation or processing, while deriving a class from <a href="qabstractvideosurface.html">QAbstractVideoSurface</a> allows you to receive these frames from <a href="qmediaplayer.html">QMediaPlayer</a> and <a href="qcamera.html">QCamera</a>.</p>
<pre class="cpp">
<span class="keyword">class</span> MyVideoSurface : <span class="keyword">public</span> <span class="type"><a href="qabstractvideosurface.html">QAbstractVideoSurface</a></span>
{
<span class="type">QList</span><span class="operator"><</span><span class="type"><a href="qvideoframe.html">QVideoFrame</a></span><span class="operator">::</span>PixelFormat<span class="operator">></span> supportedPixelFormats(
<span class="type"><a href="qabstractvideobuffer.html">QAbstractVideoBuffer</a></span><span class="operator">::</span>HandleType handleType <span class="operator">=</span> <span class="type"><a href="qabstractvideobuffer.html">QAbstractVideoBuffer</a></span><span class="operator">::</span>NoHandle) <span class="keyword">const</span>
{
Q_UNUSED(handleType);
<span class="comment">// Return the formats you will support</span>
<span class="keyword">return</span> <span class="type">QList</span><span class="operator"><</span><span class="type"><a href="qvideoframe.html">QVideoFrame</a></span><span class="operator">::</span>PixelFormat<span class="operator">></span>() <span class="operator"><</span><span class="operator"><</span> <span class="type"><a href="qvideoframe.html">QVideoFrame</a></span><span class="operator">::</span>Format_RGB565;
}
bool present(<span class="keyword">const</span> <span class="type"><a href="qvideoframe.html">QVideoFrame</a></span> <span class="operator">&</span>frame)
{
Q_UNUSED(frame);
<span class="comment">// Handle the frame and do your processing</span>
<span class="keyword">return</span> <span class="keyword">true</span>;
}
};
</pre>
<p>and with an instance of this surface, <code>myVideoSurface</code>, you can set the surface as the <a href="qmediaplayer.html#setVideoOutput">video output</a> for <a href="qmediaplayer.html">QMediaPlayer</a>.</p>
<pre class="cpp">
player<span class="operator">-</span><span class="operator">></span>setVideoOutput(myVideoSurface);
</pre>
<p>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 <a href="qvideorenderercontrol.html">QVideoRendererControl</a> class, and in QML you can set a custom object for the source of a <a href="qml-qtmultimedia-videooutput.html">VideoOutput</a> with either a writable <code>videoSurface</code> property (that the instance will set it's internal video surface to) or a readable <code>mediaObject</code> property with a <a href="qmediaobject.html">QMediaObject</a> derived class that implements the <a href="qvideorenderercontrol.html">QVideoRendererControl</a> interface.</p>
<p>The following snippet shows a class that has a writable <code>videoSurface</code> property and receives frames through a public slot <code>onNewVideoContentReceived()</code>. These frames are then presented on the surface set in <code>setVideoSurface()</code>.</p>
<pre class="cpp">
<span class="keyword">class</span> MyVideoProducer : <span class="keyword">public</span> <span class="type">QObject</span>
{
Q_OBJECT
Q_PROPERTY(<span class="type"><a href="qabstractvideosurface.html">QAbstractVideoSurface</a></span> <span class="operator">*</span>videoSurface READ videoSurface WRITE setVideoSurface)
<span class="keyword">public</span>:
<span class="type"><a href="qabstractvideosurface.html">QAbstractVideoSurface</a></span><span class="operator">*</span> videoSurface() <span class="keyword">const</span> { <span class="keyword">return</span> m_surface; }
<span class="type">void</span> setVideoSurface(<span class="type"><a href="qabstractvideosurface.html">QAbstractVideoSurface</a></span> <span class="operator">*</span>surface)
{
<span class="keyword">if</span> (m_surface <span class="operator">!</span><span class="operator">=</span> surface <span class="operator">&</span><span class="operator">&</span> m_surface <span class="operator">&</span><span class="operator">&</span> m_surface<span class="operator">-</span><span class="operator">></span>isActive()) {
m_surface<span class="operator">-</span><span class="operator">></span>stop();
}
m_surface <span class="operator">=</span> surface;
<span class="keyword">if</span> (m_surface)
m_surface<span class="operator">-</span><span class="operator">></span>start(m_format);
}
<span class="comment">// ...</span>
<span class="keyword">public</span> <span class="keyword">slots</span>:
<span class="type">void</span> onNewVideoContentReceived(<span class="keyword">const</span> <span class="type"><a href="qvideoframe.html">QVideoFrame</a></span> <span class="operator">&</span>frame)
{
<span class="keyword">if</span> (m_surface)
m_surface<span class="operator">-</span><span class="operator">></span>present(frame);
}
<span class="keyword">private</span>:
<span class="type"><a href="qabstractvideosurface.html">QAbstractVideoSurface</a></span> <span class="operator">*</span>m_surface;
<span class="type"><a href="qvideosurfaceformat.html">QVideoSurfaceFormat</a></span> m_format;
};
</pre>
<a name="recording-video"></a>
<h3 id="recording-video">Recording Video</h3>
<p>You can use the <a href="qmediarecorder.html">QMediaRecorder</a> class in conjunction with other classes to record video to disk. Primarily this is used with the camera, so consult the <a href="cameraoverview.html">Camera Overview</a> for more information.</p>
<a name="monitoring-video-frames"></a>
<h3 id="monitoring-video-frames">Monitoring Video Frames</h3>
<p>You can use the <a href="qvideoprobe.html">QVideoProbe</a> class to access video frames as they flow through different parts of a media pipeline when using other classes like <a href="qmediaplayer.html">QMediaPlayer</a>, <a href="qmediarecorder.html">QMediaRecorder</a> or <a href="qcamera.html">QCamera</a>. 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.</p>
<p>Here's an example of installing a video probe while recording the camera:</p>
<pre class="cpp">
camera <span class="operator">=</span> <span class="keyword">new</span> <span class="type"><a href="qcamera.html">QCamera</a></span>;
viewfinder <span class="operator">=</span> <span class="keyword">new</span> <span class="type"><a href="qcameraviewfinder.html">QCameraViewfinder</a></span>();
camera<span class="operator">-</span><span class="operator">></span>setViewfinder(viewfinder);
camera<span class="operator">-</span><span class="operator">></span>setCaptureMode(<span class="type"><a href="qcamera.html">QCamera</a></span><span class="operator">::</span>CaptureVideo);
videoProbe <span class="operator">=</span> <span class="keyword">new</span> <span class="type"><a href="qvideoprobe.html">QVideoProbe</a></span>(<span class="keyword">this</span>);
<span class="keyword">if</span> (videoProbe<span class="operator">-</span><span class="operator">></span>setSource(camera)) {
<span class="comment">// Probing succeeded, videoProbe->isValid() should be true.</span>
connect(videoProbe<span class="operator">,</span> SIGNAL(videoFrameProbed(<span class="type"><a href="qvideoframe.html">QVideoFrame</a></span>))<span class="operator">,</span>
<span class="keyword">this</span><span class="operator">,</span> SLOT(detectBarcodes(<span class="type"><a href="qvideoframe.html">QVideoFrame</a></span>)));
}
camera<span class="operator">-</span><span class="operator">></span>start();
<span class="comment">// Viewfinder frames should now also be emitted by</span>
<span class="comment">// the video probe, even in still image capture mode.</span>
<span class="comment">// Another alternative is to install the probe on a</span>
<span class="comment">// QMediaRecorder connected to the camera to get the</span>
<span class="comment">// recorded frames, if they are different from the</span>
<span class="comment">// viewfinder frames.</span>
</pre>
<a name="examples"></a>
<h2 id="examples">Examples</h2>
<p>There are both C++ and QML examples available.</p>
<a name="c-examples"></a>
<h3 id="c-examples">C++ Examples</h3>
<a name="qml-examples"></a>
<h3 id="qml-examples">QML Examples</h3>
<a name="reference-documentation"></a>
<h2 id="reference-documentation">Reference Documentation</h2>
<a name="c-classes"></a>
<h3 id="c-classes">C++ Classes</h3>
<div class="table"><table class="annotated">
<tr class="odd topAlign"><td class="tblName"><p><a href="qabstractplanarvideobuffer.html">QAbstractPlanarVideoBuffer</a></p></td><td class="tblDescr"><p>Abstraction for planar video data</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qabstractvideobuffer.html">QAbstractVideoBuffer</a></p></td><td class="tblDescr"><p>Abstraction for video data</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qabstractvideofilter.html">QAbstractVideoFilter</a></p></td><td class="tblDescr"><p>Represents a filter that is applied to the video frames received by a VideoOutput type</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qabstractvideosurface.html">QAbstractVideoSurface</a></p></td><td class="tblDescr"><p>Base class for video presentation surfaces</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qvideofilterrunnable.html">QVideoFilterRunnable</a></p></td><td class="tblDescr"><p>Represents the implementation of a filter that owns all graphics and computational resources, and performs the actual filtering or calculations</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qvideoframe.html">QVideoFrame</a></p></td><td class="tblDescr"><p>Represents a frame of video data</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qvideoprobe.html">QVideoProbe</a></p></td><td class="tblDescr"><p>Allows you to monitor video frames being played or recorded</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qvideosurfaceformat.html">QVideoSurfaceFormat</a></p></td><td class="tblDescr"><p>Specifies the stream format of a video presentation surface</p></td></tr>
</table></div>
<a name="qml-types"></a>
<h3 id="qml-types">QML Types</h3>
<div class="table"><table class="annotated">
<tr class="odd topAlign"><td class="tblName"><p><a href="qml-qtmultimedia-mediaplayer.html">MediaPlayer</a></p></td><td class="tblDescr"><p>Add media playback to a scene</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qml-qtmultimedia-playlist.html">Playlist</a></p></td><td class="tblDescr"><p>For specifying a list of media to be played</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qml-qtmultimedia-playlistitem.html">PlaylistItem</a></p></td><td class="tblDescr"><p>Defines an item in a Playlist</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qml-qtmultimedia-videooutput.html">VideoOutput</a></p></td><td class="tblDescr"><p>Render video or camera viewfinder</p></td></tr>
</table></div>
</div>
<!-- @@@videooverview.html -->
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2019 The Qt Company Ltd.
Documentation contributions included herein are the copyrights of
their respective owners.<br/> The documentation provided herein is licensed under the terms of the <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation License version 1.3</a> as published by the Free Software Foundation.<br/> Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. </p>
</div>
</body>
</html>
