1// Copyright (C) 2025 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
3
4#include "qplaybackoptions.h"
5#include <chrono>
6
7QT_BEGIN_NAMESPACE
8
9class QPlaybackOptionsPrivate : public QSharedData
10{
11public:
12 QPlaybackOptionsPrivate() = default;
13
14 friend bool comparesEqual(const QPlaybackOptionsPrivate &lhs,
15 const QPlaybackOptionsPrivate &rhs)
16 {
17 return lhs.m_networkTimeout == rhs.m_networkTimeout
18 && lhs.m_playbackIntent == rhs.m_playbackIntent
19 && lhs.m_probeSizeBytes == rhs.m_probeSizeBytes;
20 }
21
22 friend Qt::strong_ordering compareThreeWay(const QPlaybackOptionsPrivate &lhs,
23 const QPlaybackOptionsPrivate &rhs)
24 {
25 if (lhs.m_networkTimeout != rhs.m_networkTimeout)
26 return qCompareThreeWay(lhs: lhs.m_networkTimeout.count(), rhs: rhs.m_networkTimeout.count());
27 if (lhs.m_playbackIntent != rhs.m_playbackIntent)
28 return qCompareThreeWay(lhs: lhs.m_playbackIntent, rhs: rhs.m_playbackIntent);
29 return qCompareThreeWay(lhs: lhs.m_probeSizeBytes, rhs: rhs.m_probeSizeBytes);
30 }
31
32 std::chrono::milliseconds m_networkTimeout{ 5'000 };
33 QPlaybackOptions::PlaybackIntent m_playbackIntent = QPlaybackOptions::PlaybackIntent::Playback;
34 int m_probeSizeBytes = -1;
35};
36
37QT_DEFINE_QESDP_SPECIALIZATION_DTOR(QPlaybackOptionsPrivate)
38
39/*!
40 \class QPlaybackOptions
41 \brief The QPlaybackOptions class enables low-level control of media playback options.
42 \inmodule QtMultimedia
43 \ingroup multimedia
44 \ingroup multimedia_playback
45 \ingroup multimedia_video
46 \since 6.10
47
48 QPlaybackOptions gives low-level control of media playback options. Although we strongly
49 recommend to rely on the default settings of \l QMediaPlayer, QPlaybackOptions can be used to
50 optimize media playback to specific use cases where the default options are not ideal.
51
52 Note that options are hints to the media backend, and may be ignored if they are not supported
53 by the current media format or codec.
54
55 Playback options rely on support in the media backend. Availability is documented per option.
56
57 \sa QMediaPlayer
58*/
59
60/*!
61 \qmltype playbackOptions
62 \nativetype QPlaybackOptions
63 \brief Low level media playback options.
64
65 \inqmlmodule QtMultimedia
66 \ingroup multimedia_qml
67 \ingroup multimedia_audio_qml
68 \ingroup multimedia_video_qml
69 \since 6.10
70
71 Playback options gives low-level control of media playback options. Although we strongly
72 recommend to rely on the default settings of \l MediaPlayer, playbackOptions can be used to
73 optimize media playback to specific use cases where the default options are not ideal.
74
75 Note that options are hints to the media backend, and may be ignored if they are not supported
76 by the current media format or codec.
77
78 Playback options rely on support in the media backend. Availability is documented per option.
79
80 \sa MediaPlayer
81*/
82
83QPlaybackOptions::QPlaybackOptions() : d{ new QPlaybackOptionsPrivate } { }
84QPlaybackOptions::QPlaybackOptions(const QPlaybackOptions &) = default;
85QPlaybackOptions &QPlaybackOptions::operator=(const QPlaybackOptions &) = default;
86QPlaybackOptions::~QPlaybackOptions() = default;
87
88bool comparesEqual(const QPlaybackOptions &lhs, const QPlaybackOptions &rhs) noexcept
89{
90 if (lhs.d == rhs.d)
91 return true;
92
93 return comparesEqual(lhs: *lhs.d, rhs: *rhs.d);
94}
95
96Qt::strong_ordering compareThreeWay(const QPlaybackOptions &lhs, const QPlaybackOptions &rhs) noexcept
97{
98 return compareThreeWay(lhs: *lhs.d, rhs: *rhs.d);
99}
100
101/*!
102 \property QPlaybackOptions::networkTimeout
103 \since 6.10
104
105 Determines the network timeout used for socket I/O operations with some
106 network formats.
107
108 This option is only supported with the FFmpeg media backend.
109*/
110
111/*!
112 \qmlproperty qint64 playbackOptions::networkTimeoutMs
113 \since 6.10
114
115 Determines the network timeout (in milliseconds) used for socket I/O operations with some
116 network formats.
117
118 This option is only supported with the FFmpeg media backend.
119*/
120
121std::chrono::milliseconds QPlaybackOptions::networkTimeout() const
122{
123 return d->m_networkTimeout;
124}
125
126void QPlaybackOptions::setNetworkTimeout(std::chrono::milliseconds timeout)
127{
128 d.detach();
129 d->m_networkTimeout = timeout;
130}
131
132void QPlaybackOptions::resetNetworkTimeout()
133{
134 d.detach();
135 d->m_networkTimeout = QPlaybackOptionsPrivate{}.m_networkTimeout;
136}
137
138/*!
139 \enum QPlaybackOptions::PlaybackIntent
140 \since 6.10
141
142 Configures the intent of media playback, to focus on either high quality playback or
143 low latency media streaming.
144
145 \value Playback The intent is robust and high quality media playback, enabling sufficient
146 buffering to prevent glitches during playback.
147 \value LowLatencyStreaming Buffering is reduced to optimize for low latency streaming, but
148 with a higher likelihood of lost frames or other glitches during playback.
149*/
150
151/*!
152 \property QPlaybackOptions::playbackIntent
153 \since 6.10
154
155 Determines if \l QMediaPlayer should optimize for robust high quality video playback (default),
156 or low latency streaming.
157
158 This option is only supported with the FFmpeg media backend.
159*/
160
161/*!
162 \qmlproperty PlaybackOptions::PlaybackIntent PlaybackOptions::playbackIntent
163 \since 6.10
164
165 Determines if \l MediaPlayer should optimize for robust high quality video playback (default),
166 or low latency streaming.
167
168 This option is only supported with the FFmpeg media backend.
169
170 \qmlenumeratorsfrom QPlaybackOptions::PlaybackIntent
171*/
172
173QPlaybackOptions::PlaybackIntent QPlaybackOptions::playbackIntent() const
174{
175 return d->m_playbackIntent;
176}
177
178void QPlaybackOptions::setPlaybackIntent(PlaybackIntent intent)
179{
180 d.detach();
181 d->m_playbackIntent = intent;
182}
183
184void QPlaybackOptions::resetPlaybackIntent()
185{
186 d.detach();
187 d->m_playbackIntent = QPlaybackOptionsPrivate{}.m_playbackIntent;
188}
189
190/*!
191 \property QPlaybackOptions::probeSize
192 \since 6.10
193
194 Probesize defines the amount of data (in bytes) to analyze in order to gather stream
195 information before media playback starts.
196
197 A larger probesize value can give more robust playback but may increase latency. Conversely,
198 a smaller probesize can reduce latency but might miss some stream details. The default
199 probesize is -1, and the actual probesize is determined by the media backend.
200
201 This option is only supported with the FFmpeg media backend.
202*/
203
204/*!
205 \qmlproperty qsizetype PlaybackOptions::probeSize
206 \since 6.10
207
208 Probesize defines the amount of data (in bytes) to analyze in order to gather stream
209 information before media playback starts.
210
211 A larger probesize value can give more robust playback but may increase latency. Conversely,
212 a smaller probesize can reduce latency but might miss some stream details. The default
213 probesize is -1, and the actual probesize is then determined by the media backend.
214
215 Note that a too small probeSize can result in failure to play the media, while a too high
216 probeSize can increase latency.
217
218 This option is only supported with the FFmpeg media backend.
219*/
220
221qsizetype QPlaybackOptions::probeSize() const
222{
223 return d->m_probeSizeBytes;
224}
225
226void QPlaybackOptions::setProbeSize(qsizetype probeSizeBytes)
227{
228 d.detach();
229 d->m_probeSizeBytes = static_cast<int>(probeSizeBytes);
230}
231
232void QPlaybackOptions::resetProbeSize()
233{
234 d.detach();
235 d->m_probeSizeBytes = QPlaybackOptionsPrivate{}.m_probeSizeBytes;
236}
237
238QT_END_NAMESPACE
239
240#include "moc_qplaybackoptions.cpp"
241

source code of qtmultimedia/src/multimedia/playback/qplaybackoptions.cpp