summaryrefslogtreecommitdiffstats
path: root/examples/multimedia/video/mediaplayer/doc/src/mediaplayer.qdoc
blob: e6ab453461c050fc40a1b8111b3c11297c7f2744 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
// Copyright (C) 2021 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
    \example video/mediaplayer
    \title QML Media Player Example
    \ingroup multimedia_examples
    \ingroup video_examples_qml
    \brief Playing audio and video using Qt Quick.
    \meta {tag} {quick}
    \meta {tag} {player}
    \image qmlmediaplayer.jpg

    This example demonstrates a simple multimedia player that can play
    audio and video files using various codecs.

    \include examples-run.qdocinc

    \section1 Overview
    At its core this is a QML application, see
    \l{Getting Started Programming with Qt Quick} for information specific to
    that. This documentation is focused on how this example utilizes the
    \l{Qt Multimedia QML Types}.

    \image architecture-overview.gif

    \section1 Using MediaPlayer and VideoOutput
    In \c main.qml a MediaPlayer instance is connected to a VideoOutput to
    play back the video:

    \quotefromfile video/mediaplayer/main.qml
    \skipto MediaPlayer
    \printuntil videoOutput: videoOutput

    \c videoOutput is declared like so:

    \skipto VideoOutput {
    \printto MetadataInfo {

    \section1 PlayerMenuBar
    \image PlayerMenuBar.gif
    This QML type handles media selection from a url or local file, exiting the
    application, viewing meta data, and the selection of available video, audio
    or subtitle tracks.

    \quotefromfile video/mediaplayer/PlayerMenuBar.qml
    Accessing the mediaPlayer object is done through properties:
    \skipto required property
    \printuntil TracksInfo subtitleTracksInfo

    \section2 fileDialog
    A FileDialog, \c fileDialog, is created with an \c onAccepted function that
    will stop \c mediaPlayer, load the source by setting the
    \l{MediaPlayer::source}{source} property and then play it automatically:
    \skipto FileDialog
    \printto MenuBar

    This is triggered in the Menu \c File, which is a child of the MenuBar:
    \skipto MenuBar
    \printto }

    \section2 loadUrl
    \image url.png
    While \c urlPopup handles prompting and capturing a url, it is the \c loadUrl
    function that interacts with \c mediaPlayer like so:
    \quotefromfile video/mediaplayer/PlayerMenuBar.qml
    \skipto function loadUrl
    \printto function closeOverlays(){

    \section2 Getting meta data
    \image meta-data.png

    In the declaration of \c mediaPlayer, in \c main.qml, there is the function
    \c updateMetadata():

    \quotefromfile video/mediaplayer/main.qml
    \skipto function updateMetadata(
    \printto }

    It is called in the following places:
    \skipto onMetaDataChanged:
    \printto onActiveTracksChanged: { updateMetadata() }

    Reading MetaData is done by the \c MetadataInfo type's \c read() function
    \quotefromfile video/mediaplayer/MetadataInfo.qml
    \skipto function read(metadata) {
    \printto ListModel

    The information is displayed via an \l[QML]{Overlay} item.

    \section2 Tracks information and control
    \youtube OqosZsDqvzQ
    This is defined in \c TracksInfo.qml and reading available tracks is done in
    a similar way to \c MetadataInfo:
    \quotefromfile video/mediaplayer/TracksInfo.qml
    \skipto function read(metadata
    \printto ListModel

    To set a track, the property \c selectedTrack is set like so:
    \skipto ListView
    \printto Text

    The \c onSelectectedTrackChanged signal, in each relevant \c TracksInfo
    instance in \c main.qml, is what makes changes to \c mediaPlayer like so:
    \quotefromfile video/mediaplayer/main.qml
    \skipto id: audioTracksInfo
    \printuntil audioTracksInfo.selectedTrack

    \section1 playbackControlPanel
    \image playbackControlPanel.gif

    This item has controls for \l{Playback control}, \l{Play Pause Stop},
    \l{Playback rate control} and \l{Playback seek control}.

    \section2 Playback control
    This qml type handles media playback and interacts with the MediaPlayer in
    \c main.qml.

    Here are the property definitions.
    \quotefromfile video/mediaplayer/PlaybackControl.qml
    \skipto required property
    \printto property alias

    Connections:
    \skipuntil Connections
    \printto HoverHandler

    \section2 Play Pause Stop
    \image play-pause-stop.gif
    \l{MediaPlayer::play()}{Play}, \l{MediaPlayer::stop()}{stop} and
    \l{MediaPlayer::pause()}{pause} interactions with the MediaPlayer object
    are done like so:
    \skipto RoundButton
    \printto Item {

    Playback states done using \l{MediaPlayer::playbackState}{playbackstate}
    like so:
    \skipuntil states:
    \printuntil ]


    \section2 Playback seek control

    \youtube sf_yv01UtIw

    Defined in \c PlaybackSeekControl.qml, this component comprises of an item
    with a Text, \c mediaTime, and \l[QML]{Slider}, \c mediaSlider, in a RowLayout.

    \c mediaTime uses MediaPlayer's \l{MediaPlayer::position}{position} property
    like so:
    \quotefromfile video/mediaplayer/PlaybackSeekControl.qml
    \skipto Text {
    \printto Slider

    \c mediaSlider uses the MediaPlayer \l{MediaPlayer::seekable}{seekable},
    \l{MediaPlayer::duration}{duration}, and \l{MediaPlayer::position}{position}
    properties like so:
    \skipto Slider
    \printuntil }

    \section2 Playback rate control
    \youtube nHrBbW0H-pc

    This type is defined in \c PlaybackRateControl.qml like so:

    \quotefromfile video/mediaplayer/PlaybackRateControl.qml
    \skipto Slider
    \printuntil text:

    \section2 Audio control
    \image audio-control.gif
    This type is defined in \c AudioControl.qml, and utilizes the
    \l{AudioOutput::muted}{muted} and \l{AudioOutput::volume}{volume} properties
    of the AudioOutput instantiated within the MediaPlayer, which is
    instantiated in \c{main.qml}.

    \quotefromfile video/mediaplayer/AudioControl.qml
    \skipto required
    \printuntil value: 100.0
*/