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

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