1// Copyright (C) 2017 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 "qmediametadata.h"
5
6#include <QtCore/qcoreapplication.h>
7#include <QtCore/qdatetime.h>
8#include <QtCore/qobject.h>
9#include <QtCore/qsize.h>
10#include <QtCore/qurl.h>
11#include <QtCore/qvariant.h>
12#include <QtGui/qimage.h>
13#include <QtMultimedia/qmediaformat.h>
14
15QT_BEGIN_NAMESPACE
16
17/*!
18 \class QMediaMetaData
19 \inmodule QtMultimedia
20
21 \brief Provides meta-data for media files.
22
23 \note Not all identifiers are supported on all platforms.
24
25 \table 60%
26 \header \li {3,1}
27 Common attributes
28 \header \li Value \li Description \li Type
29 \row \li Title \li The title of the media. \li QString
30 \row \li Author \li The authors of the media. \li QStringList
31 \row \li Comment \li A user comment about the media. \li QString
32 \row \li Description \li A description of the media. \li QString
33 \row \li Genre \li The genre of the media. \li QStringList
34 \row \li Date \li The date of the media. \li QDateTime.
35 \row \li Language \li The language of media. \li QLocale::Language
36
37 \row \li Publisher \li The publisher of the media. \li QString
38 \row \li Copyright \li The media's copyright notice. \li QString
39 \row \li Url \li A Url pointing to the origin of the media. \li QUrl
40
41 \header \li {3,1}
42 Media attributes
43 \row \li MediaType \li The type of the media (audio, video, etc). \li QString
44 \row \li FileFormat \li The file format of the media. \li QMediaFormat::FileFormat
45 \row \li Duration \li The duration in milliseconds of the media. \li qint64
46
47 \header \li {3,1}
48 Audio attributes
49 \row \li AudioBitRate \li The bit rate of the media's audio stream in bits per second. \li int
50 \row \li AudioCodec \li The codec of the media's audio stream. \li QMediaFormat::AudioCodec
51
52 \header \li {3,1}
53 Video attributes
54 \row \li VideoFrameRate \li The frame rate of the media's video stream. \li qreal
55 \row \li VideoBitRate \li The bit rate of the media's video stream in bits per second. \li int
56 \row \li VideoCodec \li The codec of the media's video stream. \li QMediaFormat::VideoCodec
57 \row \li HasHdrContent \li True if video is intended for HDR display (FFmpeg and Darwin media backends only). \li bool
58
59 \header \li {3,1}
60 Music attributes
61 \row \li AlbumTitle \li The title of the album the media belongs to. \li QString
62 \row \li AlbumArtist \li The principal artist of the album the media belongs to. \li QString
63 \row \li ContributingArtist \li The artists contributing to the media. \li QStringList
64 \row \li TrackNumber \li The track number of the media. \li int
65 \row \li Composer \li The composer of the media. \li QStringList
66 \row \li LeadPerformer \li The lead performer in the media. \li QStringList
67
68 \row \li ThumbnailImage \li An embedded thumbnail image if present in metadata. \li QImage
69 \row \li CoverArtImage \li An embedded cover art image. \li QImage
70
71 \header \li {3,1}
72 Image and video attributes
73 \row \li Orientation \li The rotation angle of an image or video. \li int
74 \row \li Resolution \li The dimensions of an image or video. \li QSize
75
76 \endtable
77*/
78
79
80/*!
81 Returns the meta type used to store data for Key \a key.
82*/
83QMetaType QMediaMetaData::keyType(Key key)
84{
85 switch (key) {
86 case Title:
87 case Comment:
88 case Description:
89 case Publisher:
90 case Copyright:
91 case MediaType:
92 case AlbumTitle:
93 case AlbumArtist:
94 return QMetaType::fromType<QString>();
95 case Genre:
96 case Author:
97 case ContributingArtist:
98 case Composer:
99 case LeadPerformer:
100 return QMetaType::fromType<QStringList>();
101
102 case Date:
103 return QMetaType::fromType<QDateTime>();
104
105 case Language:
106 return QMetaType::fromType<QLocale::Language>();
107 case Url:
108 return QMetaType::fromType<QUrl>();
109
110 case Duration:
111 return QMetaType::fromType<qint64>();
112 case FileFormat:
113 return QMetaType::fromType<QMediaFormat::FileFormat>();
114
115 case AudioBitRate:
116 case VideoBitRate:
117 case TrackNumber:
118 case Orientation:
119 return QMetaType::fromType<int>();
120 case AudioCodec:
121 return QMetaType::fromType<QMediaFormat::AudioCodec>();
122 case VideoCodec:
123 return QMetaType::fromType<QMediaFormat::VideoCodec>();
124 case VideoFrameRate:
125 return QMetaType::fromType<qreal>();
126
127
128 case ThumbnailImage:
129 case CoverArtImage:
130 return QMetaType::fromType<QImage>();
131
132 case Resolution:
133 return QMetaType::fromType<QSize>();
134
135 case HasHdrContent:
136 return QMetaType::fromType<bool>();
137
138 default:
139 return QMetaType::fromType<void>();
140 }
141}
142
143/*!
144 \qmlvaluetype mediaMetaData
145 \ingroup qmlvaluetypes
146 \inqmlmodule QtMultimedia
147 \since 6.2
148 //! \nativetype QMediaMetaData
149 \brief Provides meta-data for media files.
150 \ingroup multimedia_qml
151 \ingroup multimedia_audio_qml
152 \ingroup multimedia_video_qml
153
154 Meta-data is supplementary data describing media.
155 See QMediaMetaData for available meta data attributes.
156*/
157
158/*
159 Some potential attributes to add if we can properly support them.
160 Might require that we add EXIF support to Qt Multimedia
161
162 \header \li {3,1}
163 Photo attributes.
164 \row \li CameraManufacturer \li The manufacturer of the camera used to capture the media. \li QString
165 \row \li CameraModel \li The model of the camera used to capture the media. \li QString
166 \row \li Event \li The event during which the media was captured. \li QString
167 \row \li Subject \li The subject of the media. \li QString
168 \row \li ExposureTime \li Exposure time, given in seconds. \li qreal
169 \row \li FNumber \li The F Number. \li int
170 \row \li ExposureProgram
171 \li The class of the program used by the camera to set exposure when the picture is taken. \li QString
172 \row \li ISOSpeedRatings
173 \li Indicates the ISO Speed and ISO Latitude of the camera or input device as specified in ISO 12232. \li qreal
174 \row \li ExposureBiasValue
175 \li The exposure bias.
176 The unit is the APEX (Additive System of Photographic Exposure) setting. \li qreal
177 \row \li DateTimeOriginal \li The date and time when the original image data was generated. \li QDateTime
178 \row \li DateTimeDigitized \li The date and time when the image was stored as digital data. \li QDateTime
179 \row \li SubjectDistance \li The distance to the subject, given in meters. \li qreal
180 \row \li LightSource
181 \li The kind of light source. \li QString
182 \row \li Flash
183 \li Status of flash when the image was shot. \li QCamera::FlashMode
184 \row \li FocalLength
185 \li The actual focal length of the lens, in mm. \li qreal
186 \row \li ExposureMode
187 \li Indicates the exposure mode set when the image was shot. \li QCamera::ExposureMode
188 \row \li WhiteBalance
189 \li Indicates the white balance mode set when the image was shot. \li QCamera::WhiteBalanceMode
190 \row \li DigitalZoomRatio
191 \li Indicates the digital zoom ratio when the image was shot. \li qreal
192 \row \li FocalLengthIn35mmFilm
193 \li Indicates the equivalent focal length assuming a 35mm film camera, in mm. \li qreal
194 \row \li SceneCaptureType
195 \li Indicates the type of scene that was shot.
196 It can also be used to record the mode in which the image was shot. \li QString
197 \row \li GainControl
198 \li Indicates the degree of overall image gain adjustment. \li qreal
199 \row \li Contrast
200 \li Indicates the direction of contrast processing applied by the camera when the image was shot. \li qreal
201 \row \li Saturation
202 \li Indicates the direction of saturation processing applied by the camera when the image was shot. \li qreal
203 \row \li Sharpness
204 \li Indicates the direction of sharpness processing applied by the camera when the image was shot. \li qreal
205 \row \li DeviceSettingDescription
206 \li Exif tag, indicates information on the picture-taking conditions of a particular camera model. \li QString
207
208 \row \li GPSLatitude
209 \li Latitude value of the geographical position (decimal degrees).
210 A positive latitude indicates the Northern Hemisphere,
211 and a negative latitude indicates the Southern Hemisphere. \li double
212 \row \li GPSLongitude
213 \li Longitude value of the geographical position (decimal degrees).
214 A positive longitude indicates the Eastern Hemisphere,
215 and a negative longitude indicates the Western Hemisphere. \li double
216 \row \li GPSAltitude
217 \li The value of altitude in meters above sea level. \li double
218 \row \li GPSTimeStamp
219 \li Time stamp of GPS data. \li QDateTime
220 \row \li GPSSatellites
221 \li GPS satellites used for measurements. \li QString
222 \row \li GPSStatus
223 \li Status of GPS receiver at image creation time. \li QString
224 \row \li GPSDOP
225 \li Degree of precision for GPS data. \li qreal
226 \row \li GPSSpeed
227 \li Speed of GPS receiver movement in kilometers per hour. \li qreal
228 \row \li GPSTrack
229 \li Direction of GPS receiver movement.
230 The range of values is [0.0, 360),
231 with 0 direction pointing on either true or magnetic north,
232 depending on GPSTrackRef. \li qreal
233 \row \li GPSTrackRef
234 \li Reference for movement direction. \li QChar.
235 'T' means true direction and 'M' is magnetic direction.
236 \row \li GPSImgDirection
237 \li Direction of image when captured. \li qreal
238 The range of values is [0.0, 360).
239 \row \li GPSImgDirectionRef
240 \li Reference for image direction. \li QChar.
241 'T' means true direction and 'M' is magnetic direction.
242 \row \li GPSMapDatum
243 \li Geodetic survey data used by the GPS receiver. \li QString
244 \row \li GPSProcessingMethod
245 \li The name of the method used for location finding. \li QString
246 \row \li GPSAreaInformation
247 \li The name of the GPS area. \li QString
248
249 \endtable
250*/
251
252/*!
253 \enum QMediaMetaData::Key
254
255 The following meta data keys can be used:
256
257 \value Title Media title
258 \value Author Media author
259 \value Comment Comment
260 \value Description Brief desripttion
261 \value Genre Genre the media belongs to
262 \value Date Creation date
263 \value Language Media language
264 \value Publisher Media publisher info.
265 \value Copyright Media copyright info.
266 \value Url Publisher's website URL
267 \value Duration Media playback duration
268 \value MediaType Type of the media
269 \value FileFormat File format
270 \value AudioBitRate
271 \value AudioCodec
272 \value VideoBitRate
273 \value VideoCodec
274 \value VideoFrameRate
275 \value AlbumTitle Album's title
276 \value AlbumArtist Artist's info.
277 \value ContributingArtist
278 \value TrackNumber
279 \value Composer Media composer's info.
280 \value LeadPerformer
281 \value ThumbnailImage Media thumbnail image (if embedded in metadata)
282 \value CoverArtImage Media cover art
283 \value Orientation
284 \value Resolution
285 \value [since 6.8] HasHdrContent Video may have HDR content (read only, FFmpeg and Darwin media backends only)
286*/
287
288/*!
289 \variable QMediaMetaData::NumMetaData
290 \internal
291*/
292
293/*!
294 \qmlmethod variant QtMultimedia::mediaMetaData::value(Key key)
295
296 Returns the meta data value for Key \a key, or a null QVariant if no
297 meta-data for the key is available.
298*/
299
300/*!
301 \fn QVariant QMediaMetaData::value(QMediaMetaData::Key key) const
302
303 Returns the meta data value for Key \a key, or a null QVariant if no
304 meta data for the key is available.
305*/
306
307/*!
308 \qmlmethod bool QtMultimedia::mediaMetaData::isEmpty()
309 Returns \c true if the meta data contains no items: otherwise returns \c{false}.
310*/
311
312/*!
313 \fn bool QMediaMetaData::isEmpty() const
314 Returns \c true if the meta data contains no items: otherwise returns \c{false}.
315*/
316
317/*!
318 \qmlmethod void QtMultimedia::mediaMetaData::clear()
319 Removes all data from the MediaMetaData object.
320*/
321
322/*!
323 \fn void QMediaMetaData::clear()
324 Removes all data from the meta data object.
325*/
326
327/*!
328 \qmlmethod void QtMultimedia::mediaMetaData::insert(Key k, variant value)
329 Inserts a \a value into a Key: \a{k}.
330*/
331
332/*!
333 \fn void QMediaMetaData::insert(QMediaMetaData::Key k, const QVariant &value)
334 Inserts a \a value into a Key: \a{k}.
335*/
336/*!
337 \qmlmethod void QtMultimedia::mediaMetaData::remove(Key k)
338 Removes meta data from a Key: \a{k}.
339*/
340
341/*!
342 \fn void QMediaMetaData::remove(QMediaMetaData::Key k)
343 Removes meta data from a Key: \a{k}.
344*/
345
346/*!
347 \qmlmethod list<Key> QtMultimedia::mediaMetaData::keys()
348 Returns a list of MediaMetaData.Keys.
349*/
350
351/*!
352 \fn QMediaMetaData::keys() const
353 Returns a QList of QMediaMetaData::Keys.
354*/
355
356/*!
357 \qmlmethod string QtMultimedia::mediaMetaData::stringValue(Key key)
358 Returns the meta data for key \a key as a QString.
359
360 This is mainly meant to simplify presenting the meta data to a user.
361*/
362/*!
363 Returns the meta data for key \a key as a QString.
364
365 This is mainly meant to simplify presenting the meta data to a user.
366*/
367QString QMediaMetaData::stringValue(QMediaMetaData::Key key) const
368{
369 QVariant value = data.value(key);
370 if (value.isNull())
371 return QString();
372
373 switch (key) {
374 // string based or convertible to string
375 case Title:
376 case Author:
377 case Comment:
378 case Description:
379 case Genre:
380 case Publisher:
381 case Copyright:
382 case Date:
383 case Url:
384 case MediaType:
385 case AudioBitRate:
386 case VideoBitRate:
387 case VideoFrameRate:
388 case AlbumTitle:
389 case AlbumArtist:
390 case ContributingArtist:
391 case TrackNumber:
392 case Composer:
393 case Orientation:
394 case LeadPerformer:
395 case HasHdrContent:
396 return value.toString();
397 case Language: {
398 auto l = value.value<QLocale::Language>();
399 return QLocale::languageToString(language: l);
400 }
401 case Duration: {
402 QTime time = QTime::fromMSecsSinceStartOfDay(msecs: value.toInt());
403 return time.toString();
404 }
405 case FileFormat:
406 return QMediaFormat::fileFormatName(fileFormat: value.value<QMediaFormat::FileFormat>());
407 case AudioCodec:
408 return QMediaFormat::audioCodecName(codec: value.value<QMediaFormat::AudioCodec>());
409 case VideoCodec:
410 return QMediaFormat::videoCodecName(codec: value.value<QMediaFormat::VideoCodec>());
411 case Resolution: {
412 QSize size = value.toSize();
413 return QStringLiteral("%1 x %2").arg(a: size.width()).arg(a: size.height());
414 }
415 case ThumbnailImage:
416 case CoverArtImage:
417 break;
418 }
419 return QString();
420}
421/*!
422 \qmlmethod string QtMultimedia::mediaMetaData::metaDataKeyToString(Key key)
423 returns a string representation of \a key that can be used when presenting
424 meta data to users.
425*/
426
427/*!
428 returns a string representation of \a key that can be used when presenting
429 meta data to users.
430*/
431QString QMediaMetaData::metaDataKeyToString(QMediaMetaData::Key key)
432{
433 switch (key) {
434 case QMediaMetaData::Title:
435 return (QCoreApplication::translate(context: "QMediaMetaData", key: "Title"));
436 case QMediaMetaData::Author:
437 return (QCoreApplication::translate(context: "QMediaMetaData", key: "Author"));
438 case QMediaMetaData::Comment:
439 return (QCoreApplication::translate(context: "QMediaMetaData", key: "Comment"));
440 case QMediaMetaData::Description:
441 return (QCoreApplication::translate(context: "QMediaMetaData", key: "Description"));
442 case QMediaMetaData::Genre:
443 return (QCoreApplication::translate(context: "QMediaMetaData", key: "Genre"));
444 case QMediaMetaData::Date:
445 return (QCoreApplication::translate(context: "QMediaMetaData", key: "Date"));
446 case QMediaMetaData::Language:
447 return (QCoreApplication::translate(context: "QMediaMetaData", key: "Language"));
448 case QMediaMetaData::Publisher:
449 return (QCoreApplication::translate(context: "QMediaMetaData", key: "Publisher"));
450 case QMediaMetaData::Copyright:
451 return (QCoreApplication::translate(context: "QMediaMetaData", key: "Copyright"));
452 case QMediaMetaData::Url:
453 return (QCoreApplication::translate(context: "QMediaMetaData", key: "Url"));
454 case QMediaMetaData::Duration:
455 return (QCoreApplication::translate(context: "QMediaMetaData", key: "Duration"));
456 case QMediaMetaData::MediaType:
457 return (QCoreApplication::translate(context: "QMediaMetaData", key: "Media type"));
458 case QMediaMetaData::FileFormat:
459 return (QCoreApplication::translate(context: "QMediaMetaData", key: "Container Format"));
460 case QMediaMetaData::AudioBitRate:
461 return (QCoreApplication::translate(context: "QMediaMetaData", key: "Audio bit rate"));
462 case QMediaMetaData::AudioCodec:
463 return (QCoreApplication::translate(context: "QMediaMetaData", key: "Audio codec"));
464 case QMediaMetaData::VideoBitRate:
465 return (QCoreApplication::translate(context: "QMediaMetaData", key: "Video bit rate"));
466 case QMediaMetaData::VideoCodec:
467 return (QCoreApplication::translate(context: "QMediaMetaData", key: "Video codec"));
468 case QMediaMetaData::VideoFrameRate:
469 return (QCoreApplication::translate(context: "QMediaMetaData", key: "Video frame rate"));
470 case QMediaMetaData::AlbumTitle:
471 return (QCoreApplication::translate(context: "QMediaMetaData", key: "Album title"));
472 case QMediaMetaData::AlbumArtist:
473 return (QCoreApplication::translate(context: "QMediaMetaData", key: "Album artist"));
474 case QMediaMetaData::ContributingArtist:
475 return (QCoreApplication::translate(context: "QMediaMetaData", key: "Contributing artist"));
476 case QMediaMetaData::TrackNumber:
477 return (QCoreApplication::translate(context: "QMediaMetaData", key: "Track number"));
478 case QMediaMetaData::Composer:
479 return (QCoreApplication::translate(context: "QMediaMetaData", key: "Composer"));
480 case QMediaMetaData::ThumbnailImage:
481 return (QCoreApplication::translate(context: "QMediaMetaData", key: "Thumbnail image"));
482 case QMediaMetaData::CoverArtImage:
483 return (QCoreApplication::translate(context: "QMediaMetaData", key: "Cover art image"));
484 case QMediaMetaData::Orientation:
485 return (QCoreApplication::translate(context: "QMediaMetaData", key: "Orientation"));
486 case QMediaMetaData::Resolution:
487 return (QCoreApplication::translate(context: "QMediaMetaData", key: "Resolution"));
488 case QMediaMetaData::LeadPerformer:
489 return (QCoreApplication::translate(context: "QMediaMetaData", key: "Lead performer"));
490 case QMediaMetaData::HasHdrContent:
491 return (QCoreApplication::translate(context: "QMediaMetaData", key: "Has HDR content"));
492 }
493 return QString();
494}
495
496QDebug operator<<(QDebug dbg, const QMediaMetaData &metaData)
497{
498 QDebugStateSaver sv(dbg);
499 dbg.nospace();
500
501 dbg << "QMediaMetaData{";
502 auto range = metaData.asKeyValueRange();
503 auto begin = std::begin(cont&: range);
504
505 for (auto it = begin; it != std::end(cont&: range); ++it) {
506 if (it != begin)
507 dbg << ", ";
508 dbg << it->first << ": " << it->second;
509 }
510
511 dbg << "}";
512 return dbg;
513}
514
515// operator documentation
516/*!
517\fn QVariant &QMediaMetaData::operator[](QMediaMetaData::Key k)
518 Returns data stored at the Key \a{k}.
519 \code
520 QMediaMetaData rockBallad1;
521 rockBalad[QMediaMetaData::Genre]="Rock"
522 \endcode
523*/
524
525/*!
526\fn bool QMediaMetaData::operator==(const QMediaMetaData &a, const QMediaMetaData &b)
527 Compares two meta data objects \a a and \a b, and returns
528 \c true if they are identical or \c false if they differ.
529*/
530
531/*!
532\fn bool QMediaMetaData::operator!=(const QMediaMetaData &a, const QMediaMetaData &b)
533 Compares two meta data objects \a a and \a b, and returns
534 \c false if they are identical or \c true if they differ.
535*/
536
537/*!
538 \variable QMediaMetaData::data
539 \brief the meta data.
540 \note this is a \c protected member of its class.
541*/
542
543/*!
544 \fn auto QMediaMetaData::asKeyValueRange() const
545 \internal
546*/
547
548QT_END_NAMESPACE
549
550#include "moc_qmediametadata.cpp"
551

source code of qtmultimedia/src/multimedia/qmediametadata.cpp