Doc: Fix missing element name in Video
[qt:qtmultimedia.git] / src / imports / multimedia / Video.qml
1 /****************************************************************************
2 **
3 ** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/legal
5 **
6 ** This file is part of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:LGPL$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and Digia.  For licensing terms and
14 ** conditions see http://qt.digia.com/licensing.  For further information
15 ** use the contact form at http://qt.digia.com/contact-us.
16 **
17 ** GNU Lesser General Public License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Lesser
19 ** General Public License version 2.1 as published by the Free Software
20 ** Foundation and appearing in the file LICENSE.LGPL included in the
21 ** packaging of this file.  Please review the following information to
22 ** ensure the GNU Lesser General Public License version 2.1 requirements
23 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
24 **
25 ** In addition, as a special exception, Digia gives you certain additional
26 ** rights.  These rights are described in the Digia Qt LGPL Exception
27 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
28 **
29 ** GNU General Public License Usage
30 ** Alternatively, this file may be used under the terms of the GNU
31 ** General Public License version 3.0 as published by the Free Software
32 ** Foundation and appearing in the file LICENSE.GPL included in the
33 ** packaging of this file.  Please review the following information to
34 ** ensure the GNU General Public License version 3.0 requirements will be
35 ** met: http://www.gnu.org/copyleft/gpl.html.
36 **
37 **
38 ** $QT_END_LICENSE$
39 **
40 ****************************************************************************/
41
42 import QtQuick 2.0
43 import QtMultimedia 5.0
44
45 /*!
46     \qmltype Video
47     \inherits Item
48     \ingroup multimedia_qml
49     \ingroup multimedia_video_qml
50     \inqmlmodule QtMultimedia 5.0
51     \brief A convenience type for showing a specified video.
52
53     \c Video is a convenience type combining the functionality
54     of a \l MediaPlayer and a \l VideoOutput into one. It provides
55     simple video playback functionality without having to declare multiple
56     types.
57
58     \qml
59     import QtQuick 2.0
60     import QtMultimedia 5.0
61
62     Video {
63         id: video
64         width : 800
65         height : 600
66         source: "video.avi"
67
68         MouseArea {
69             anchors.fill: parent
70             onClicked: {
71                 video.play()
72             }
73         }
74
75         focus: true
76         Keys.onSpacePressed: video.playbackState == MediaPlayer.PlayingState ? video.pause() : video.play()
77         Keys.onLeftPressed: video.seek(video.position - 5000)
78         Keys.onRightPressed: video.seek(video.position + 5000)
79     }
80     \endqml
81
82     \c Video supports untransformed, stretched, and uniformly scaled
83     video presentation. For a description of stretched uniformly scaled
84     presentation, see the \l fillMode property description.
85
86     \sa MediaPlayer, VideoOutput
87
88     \section1 Screen Saver
89
90     If it is likely that an application will be playing video for an extended
91     period of time without user interaction, it may be necessary to disable
92     the platform's screen saver. The \l ScreenSaver (from \l QtSystemInfo)
93     may be used to disable the screensaver in this fashion:
94
95     \qml
96     import QtSystemInfo 5.0
97
98     ScreenSaver { screenSaverEnabled: false }
99     \endqml
100 */
101
102 Item {
103     id: video
104
105     /*** Properties of VideoOutput ***/
106     /*!
107         \qmlproperty enumeration Video::fillMode
108
109         Set this property to define how the video is scaled to fit the target
110         area.
111
112         \list
113         \li VideoOutput.Stretch - the video is scaled to fit
114         \li VideoOutput.PreserveAspectFit - the video is scaled uniformly to fit without
115             cropping
116         \li VideoOutput.PreserveAspectCrop - the video is scaled uniformly to fill, cropping
117             if necessary
118         \endlist
119
120         Because this type is for convenience in QML, it does not
121         support enumerations directly, so enumerations from \c VideoOutput are
122         used to access the available fill modes.
123
124         The default fill mode is preserveAspectFit.
125     */
126     property alias fillMode:            videoOut.fillMode
127
128     /*!
129         \qmlproperty int Video::orientation
130
131         The orientation of the \c Video in degrees. Only multiples of 90
132         degrees is supported, that is 0, 90, 180, 270, 360, etc.
133     */
134     property alias orientation:         videoOut.orientation
135
136
137     /*** Properties of MediaPlayer ***/
138
139     /*!
140         \qmlproperty enumeration Video::playbackState
141
142         This read only property indicates the playback state of the media.
143
144         \list
145         \li MediaPlayer.PlayingState - the media is playing
146         \li MediaPlayer.PausedState - the media is paused
147         \li MediaPlayer.StoppedState - the media is stopped
148         \endlist
149
150         The default state is MediaPlayer.StoppedState.
151     */
152     property alias playbackState:        player.playbackState
153
154     /*!
155         \qmlproperty bool Video::autoLoad
156
157         This property indicates if loading of media should begin immediately.
158
159         Defaults to true, if false media will not be loaded until playback is
160         started.
161     */
162     property alias autoLoad:        player.autoLoad
163
164     /*!
165         \qmlproperty real Video::bufferProgress
166
167         This property holds how much of the data buffer is currently filled,
168         from 0.0 (empty) to 1.0
169         (full).
170     */
171     property alias bufferProgress:  player.bufferProgress
172
173     /*!
174         \qmlproperty int Video::duration
175
176         This property holds the duration of the media in milliseconds.
177
178         If the media doesn't have a fixed duration (a live stream for example)
179         this will be 0.
180     */
181     property alias duration:        player.duration
182
183     /*!
184         \qmlproperty enumeration Video::error
185
186         This property holds the error state of the video.  It can be one of:
187
188         \list
189         \li MediaPlayer.NoError - there is no current error.
190         \li MediaPlayer.ResourceError - the video cannot be played due to a problem
191             allocating resources.
192         \li MediaPlayer.FormatError - the video format is not supported.
193         \li MediaPlayer.NetworkError - the video cannot be played due to network issues.
194         \li MediaPlayer.AccessDenied - the video cannot be played due to insufficient
195             permissions.
196         \li MediaPlayer.ServiceMissing -  the video cannot be played because the media
197             service could not be
198         instantiated.
199         \endlist
200     */
201     property alias error:           player.error
202
203     /*!
204         \qmlproperty string Video::errorString
205
206         This property holds a string describing the current error condition in more detail.
207     */
208     property alias errorString:     player.errorString
209
210     /*!
211         \qmlproperty enumeration Video::availability
212
213         Returns the availability state of the video instance.
214
215         This is one of:
216         \table
217         \header \li Value \li Description
218         \row \li MediaPlayer.Available
219             \li The video player is available to use.
220         \row \li MediaPlayer.Busy
221             \li The video player is usually available, but some other
222                process is utilizing the hardware necessary to play media.
223         \row \li MediaPlayer.Unavailable
224             \li There are no supported video playback facilities.
225         \row \li MediaPlayer.ResourceMissing
226             \li There is one or more resources missing, so the video player cannot
227                be used.  It may be possible to try again at a later time.
228         \endtable
229      */
230     property alias availability:    player.availability
231
232     /*!
233         \qmlproperty bool Video::hasAudio
234
235         This property holds whether the current media has audio content.
236     */
237     property alias hasAudio:        player.hasAudio
238
239     /*!
240         \qmlproperty bool Video::hasVideo
241
242         This property holds whether the current media has video content.
243     */
244     property alias hasVideo:        player.hasVideo
245
246     /* documented below due to length of metaData documentation */
247     property alias metaData:        player.metaData
248
249     /*!
250         \qmlproperty bool Video::muted
251
252         This property holds whether the audio output is muted.
253     */
254     property alias muted:           player.muted
255
256     /*!
257         \qmlproperty real Video::playbackRate
258
259         This property holds the rate at which video is played at as a multiple
260         of the normal rate.
261     */
262     property alias playbackRate:    player.playbackRate
263
264     /*!
265         \qmlproperty int Video::position
266
267         This property holds the current playback position in milliseconds.
268
269         To change this position, use the \l seek() method.
270
271         \sa seek()
272     */
273     property alias position:        player.position
274
275     /*!
276         \qmlproperty bool Video::seekable
277
278         This property holds whether the playback position of the video can be
279         changed.
280
281         If true, calling the \l seek() method will cause playback to seek to the new position.
282     */
283     property alias seekable:        player.seekable
284
285     /*!
286         \qmlproperty url Video::source
287
288         This property holds the source URL of the media.
289     */
290     property alias source:          player.source
291
292     /*!
293         \qmlproperty enumeration Video::status
294
295         This property holds the status of media loading. It can be one of:
296
297         \list
298         \li MediaPlayer.NoMedia - no media has been set.
299         \li MediaPlayer.Loading - the media is currently being loaded.
300         \li MediaPlayer.Loaded - the media has been loaded.
301         \li MediaPlayer.Buffering - the media is buffering data.
302         \li MediaPlayer.Stalled - playback has been interrupted while the media is buffering data.
303         \li MediaPlayer.Buffered - the media has buffered data.
304         \li MediaPlayer.EndOfMedia - the media has played to the end.
305         \li MediaPlayer.InvalidMedia - the media cannot be played.
306         \li MediaPlayer.UnknownStatus - the status of the media cannot be determined.
307         \endlist
308     */
309     property alias status:          player.status
310
311     /*!
312         \qmlproperty real Video::volume
313
314         This property holds the volume of the audio output, from 0.0 (silent) to 1.0 (maximum volume).
315     */
316     property alias volume:          player.volume
317
318     /*!
319         \qmlproperty bool Video::autoPlay
320
321         This property determines whether the media should begin playback automatically.
322
323         Setting to \c true also sets \l autoLoad to \c true. The default is \c false.
324     */
325     property alias autoPlay:        player.autoPlay
326
327     /*!
328         \qmlsignal Video::paused()
329
330         This signal is emitted when playback is paused.
331     */
332     signal paused
333
334     /*!
335         \qmlsignal Video::stopped()
336
337         This signal is emitted when playback is stopped.
338     */
339     signal stopped
340
341     /*!
342         \qmlsignal Video::playing()
343
344         This signal is emitted when playback is started or continued.
345     */
346     signal playing
347
348     VideoOutput {
349         id: videoOut
350         anchors.fill: video
351         source: player
352     }
353
354     MediaPlayer {
355         id: player
356         onPaused:  video.paused()
357         onStopped: video.stopped()
358         onPlaying: video.playing()
359     }
360
361     /*!
362         \qmlmethod Video::play()
363
364         Starts playback of the media.
365     */
366     function play() {
367         player.play();
368     }
369
370     /*!
371         \qmlmethod Video::pause()
372
373         Pauses playback of the media.
374     */
375     function pause() {
376         player.pause();
377     }
378
379     /*!
380         \qmlmethod Video::stop()
381
382         Stops playback of the media.
383     */
384     function stop() {
385         player.stop();
386     }
387
388     /*!
389         \qmlmethod Video::seek(offset)
390
391         If the \l seekable property is true, seeks the current
392         playback position to \a offset.
393
394         Seeking may be asynchronous, so the \l position property
395         may not be updated immediately.
396
397         \sa seekable, position
398     */
399     function seek(offset) {
400         player.seek(offset);
401     }
402
403 }
404
405 // ***************************************
406 // Documentation for meta-data properties.
407 // ***************************************
408
409 /*!
410     \qmlproperty variant Video::metaData
411
412     This property holds a collection of all the meta-data for the media.
413
414     You can access individual properties like \l {Video::metaData.title}{metaData.title}
415     or \l {Video::metaData.trackNumber} {metaData.trackNumber}.
416 */
417
418 /*!
419     \qmlproperty variant Video::metaData.title
420
421     This property holds the title of the media.
422
423     \sa {QMediaMetaData}
424 */
425
426 /*!
427     \qmlproperty variant Video::metaData.subTitle
428
429     This property holds the sub-title of the media.
430
431     \sa {QMediaMetaData}
432 */
433
434 /*!
435     \qmlproperty variant Video::metaData.author
436
437     This property holds the author of the media.
438
439     \sa {QMediaMetaData}
440 */
441
442 /*!
443     \qmlproperty variant Video::metaData.comment
444
445     This property holds a user comment about the media.
446
447     \sa {QMediaMetaData}
448 */
449
450 /*!
451     \qmlproperty variant Video::metaData.description
452
453     This property holds a description of the media.
454
455     \sa {QMediaMetaData}
456 */
457
458 /*!
459     \qmlproperty variant Video::metaData.category
460
461     This property holds the category of the media
462
463     \sa {QMediaMetaData}
464 */
465
466 /*!
467     \qmlproperty variant Video::metaData.genre
468
469     This property holds the genre of the media.
470
471     \sa {QMediaMetaData}
472 */
473
474 /*!
475     \qmlproperty variant Video::metaData.year
476
477     This property holds the year of release of the media.
478
479     \sa {QMediaMetaData}
480 */
481
482 /*!
483     \qmlproperty variant Video::metaData.date
484
485     This property holds the date of the media.
486
487     \sa {QMediaMetaData}
488 */
489
490 /*!
491     \qmlproperty variant Video::metaData.userRating
492
493     This property holds a user rating of the media in the range of 0 to 100.
494
495     \sa {QMediaMetaData}
496 */
497
498 /*!
499     \qmlproperty variant Video::metaData.keywords
500
501     This property holds a list of keywords describing the media.
502
503     \sa {QMediaMetaData}
504 */
505
506 /*!
507     \qmlproperty variant Video::metaData.language
508
509     This property holds the language of the media, as an ISO 639-2 code.
510
511     \sa {QMediaMetaData}
512 */
513
514 /*!
515     \qmlproperty variant Video::metaData.publisher
516
517     This property holds the publisher of the media.
518
519     \sa {QMediaMetaData}
520 */
521
522 /*!
523     \qmlproperty variant Video::metaData.copyright
524
525     This property holds the media's copyright notice.
526
527     \sa {QMediaMetaData}
528 */
529
530 /*!
531     \qmlproperty variant Video::metaData.parentalRating
532
533     This property holds the parental rating of the media.
534
535     \sa {QMediaMetaData}
536 */
537
538 /*!
539     \qmlproperty variant Video::metaData.ratingOrganization
540
541     This property holds the name of the rating organization responsible for the
542     parental rating of the media.
543
544     \sa {QMediaMetaData}
545 */
546
547 /*!
548     \qmlproperty variant Video::metaData.size
549
550     This property property holds the size of the media in bytes.
551
552     \sa {QMediaMetaData}
553 */
554
555 /*!
556     \qmlproperty variant Video::metaData.mediaType
557
558     This property holds the type of the media.
559
560     \sa {QMediaMetaData}
561 */
562
563 /*!
564     \qmlproperty variant Video::metaData.audioBitRate
565
566     This property holds the bit rate of the media's audio stream in bits per
567     second.
568
569     \sa {QMediaMetaData}
570 */
571
572 /*!
573     \qmlproperty variant Video::metaData.audioCodec
574
575     This property holds the encoding of the media audio stream.
576
577     \sa {QMediaMetaData}
578 */
579
580 /*!
581     \qmlproperty variant Video::metaData.averageLevel
582
583     This property holds the average volume level of the media.
584
585     \sa {QMediaMetaData}
586 */
587
588 /*!
589     \qmlproperty variant Video::metaData.channelCount
590
591     This property holds the number of channels in the media's audio stream.
592
593     \sa {QMediaMetaData}
594 */
595
596 /*!
597     \qmlproperty variant Video::metaData.peakValue
598
599     This property holds the peak volume of the media's audio stream.
600
601     \sa {QMediaMetaData}
602 */
603
604 /*!
605     \qmlproperty variant Video::metaData.sampleRate
606
607     This property holds the sample rate of the media's audio stream in Hertz.
608
609     \sa {QMediaMetaData}
610 */
611
612 /*!
613     \qmlproperty variant Video::metaData.albumTitle
614
615     This property holds the title of the album the media belongs to.
616
617     \sa {QMediaMetaData}
618 */
619
620 /*!
621     \qmlproperty variant Video::metaData.albumArtist
622
623     This property holds the name of the principal artist of the album the media
624     belongs to.
625
626     \sa {QMediaMetaData}
627 */
628
629 /*!
630     \qmlproperty variant Video::metaData.contributingArtist
631
632     This property holds the names of artists contributing to the media.
633
634     \sa {QMediaMetaData}
635 */
636
637 /*!
638     \qmlproperty variant Video::metaData.composer
639
640     This property holds the composer of the media.
641
642     \sa {QMediaMetaData}
643 */
644
645 /*!
646     \qmlproperty variant Video::metaData.conductor
647
648     This property holds the conductor of the media.
649
650     \sa {QMediaMetaData}
651 */
652
653 /*!
654     \qmlproperty variant Video::metaData.lyrics
655
656     This property holds the lyrics to the media.
657
658     \sa {QMediaMetaData}
659 */
660
661 /*!
662     \qmlproperty variant Video::metaData.mood
663
664     This property holds the mood of the media.
665
666     \sa {QMediaMetaData}
667 */
668
669 /*!
670     \qmlproperty variant Video::metaData.trackNumber
671
672     This property holds the track number of the media.
673
674     \sa {QMediaMetaData}
675 */
676
677 /*!
678     \qmlproperty variant Video::metaData.trackCount
679
680     This property holds the number of track on the album containing the media.
681
682     \sa {QMediaMetaData}
683 */
684
685 /*!
686     \qmlproperty variant Video::metaData.coverArtUrlSmall
687
688     This property holds the URL of a small cover art image.
689
690     \sa {QMediaMetaData}
691 */
692
693 /*!
694     \qmlproperty variant Video::metaData.coverArtUrlLarge
695
696     This property holds the URL of a large cover art image.
697
698     \sa {QMediaMetaData}
699 */
700
701 /*!
702     \qmlproperty variant Video::metaData.resolution
703
704     This property holds the dimension of an image or video.
705
706     \sa {QMediaMetaData}
707 */
708
709 /*!
710     \qmlproperty variant Video::metaData.pixelAspectRatio
711
712     This property holds the pixel aspect ratio of an image or video.
713
714     \sa {QMediaMetaData}
715 */
716
717 /*!
718     \qmlproperty variant Video::metaData.videoFrameRate
719
720     This property holds the frame rate of the media's video stream.
721
722     \sa {QMediaMetaData}
723 */
724
725 /*!
726     \qmlproperty variant Video::metaData.videoBitRate
727
728     This property holds the bit rate of the media's video stream in bits per
729     second.
730
731     \sa {QMediaMetaData}
732 */
733
734 /*!
735     \qmlproperty variant Video::metaData.videoCodec
736
737     This property holds the encoding of the media's video stream.
738
739     \sa {QMediaMetaData}
740 */
741
742 /*!
743     \qmlproperty variant Video::metaData.posterUrl
744
745     This property holds the URL of a poster image.
746
747     \sa {QMediaMetaData}
748 */
749
750 /*!
751     \qmlproperty variant Video::metaData.chapterNumber
752
753     This property holds the chapter number of the media.
754
755     \sa {QMediaMetaData}
756 */
757
758 /*!
759     \qmlproperty variant Video::metaData.director
760
761     This property holds the director of the media.
762
763     \sa {QMediaMetaData}
764 */
765
766 /*!
767     \qmlproperty variant Video::metaData.leadPerformer
768
769     This property holds the lead performer in the media.
770
771     \sa {QMediaMetaData}
772 */
773
774 /*!
775     \qmlproperty variant Video::metaData.writer
776
777     This property holds the writer of the media.
778
779     \sa {QMediaMetaData}
780 */
781
782 // The remaining properties are related to photos, and are technically
783 // available but will certainly never have values.
784
785 /*!
786     \qmlproperty variant Video::metaData.cameraManufacturer
787
788     \sa {QMediaMetaData}
789 */
790
791 /*!
792     \qmlproperty variant Video::metaData.cameraModel
793
794     \sa {QMediaMetaData}
795 */
796
797 /*!
798     \qmlproperty variant Video::metaData.event
799
800     \sa {QMediaMetaData}
801 */
802
803 /*!
804     \qmlproperty variant Video::metaData.subject
805
806     \sa {QMediaMetaData}
807 */
808
809 /*!
810     \qmlproperty variant Video::metaData.orientation
811
812     \sa {QMediaMetaData}
813 */
814
815 /*!
816     \qmlproperty variant Video::metaData.exposureTime
817
818     \sa {QMediaMetaData}
819 */
820
821 /*!
822     \qmlproperty variant Video::metaData.fNumber
823
824     \sa {QMediaMetaData}
825 */
826
827 /*!
828     \qmlproperty variant Video::metaData.exposureProgram
829
830     \sa {QMediaMetaData}
831 */
832
833 /*!
834     \qmlproperty variant Video::metaData.isoSpeedRatings
835
836     \sa {QMediaMetaData}
837 */
838
839 /*!
840     \qmlproperty variant Video::metaData.exposureBiasValue
841
842     \sa {QMediaMetaData}
843 */
844
845 /*!
846     \qmlproperty variant Video::metaData.dateTimeDigitized
847
848     \sa {QMediaMetaData}
849 */
850
851 /*!
852     \qmlproperty variant Video::metaData.subjectDistance
853
854     \sa {QMediaMetaData}
855 */
856
857 /*!
858     \qmlproperty variant Video::metaData.meteringMode
859
860     \sa {QMediaMetaData}
861 */
862
863 /*!
864     \qmlproperty variant Video::metaData.lightSource
865
866     \sa {QMediaMetaData}
867 */
868
869 /*!
870     \qmlproperty variant Video::metaData.flash
871
872     \sa {QMediaMetaData}
873 */
874
875 /*!
876     \qmlproperty variant Video::metaData.focalLength
877
878     \sa {QMediaMetaData}
879 */
880
881 /*!
882     \qmlproperty variant Video::metaData.exposureMode
883
884     \sa {QMediaMetaData}
885 */
886
887 /*!
888     \qmlproperty variant Video::metaData.whiteBalance
889
890     \sa {QMediaMetaData}
891 */
892
893 /*!
894     \qmlproperty variant Video::metaData.DigitalZoomRatio
895
896     \sa {QMediaMetaData}
897 */
898
899 /*!
900     \qmlproperty variant Video::metaData.focalLengthIn35mmFilm
901
902     \sa {QMediaMetaData::FocalLengthIn35mmFile}
903 */
904
905 /*!
906     \qmlproperty variant Video::metaData.sceneCaptureType
907
908     \sa {QMediaMetaData}
909 */
910
911 /*!
912     \qmlproperty variant Video::metaData.gainControl
913
914     \sa {QMediaMetaData}
915 */
916
917 /*!
918     \qmlproperty variant Video::metaData.contrast
919
920     \sa {QMediaMetaData}
921 */
922
923 /*!
924     \qmlproperty variant Video::metaData.saturation
925
926     \sa {QMediaMetaData}
927 */
928
929 /*!
930     \qmlproperty variant Video::metaData.sharpness
931
932     \sa {QMediaMetaData}
933 */
934
935 /*!
936     \qmlproperty variant Video::metaData.deviceSettingDescription
937
938     \sa {QMediaMetaData}
939 */
940