diff options
author | Nicholas Bennett <nicholas.bennett@qt.io> | 2022-02-15 22:33:40 +0200 |
---|---|---|
committer | Qt Cherry-pick Bot <cherrypick_bot@qt-project.org> | 2022-03-18 12:06:09 +0000 |
commit | 9547ba8f75b3d4edcfe62f533ce3ef567440d589 (patch) | |
tree | 942f1bb70b411711186f21f7c8cec4b6d8773ce6 /examples | |
parent | 372b0d8c0bcc715b7030d0310719538ddb35c210 (diff) |
Docs: Update QML Mediaplayer Example Documentation
Added a step through of the code and added images and animations to
support the explanations.
Large videos were uploaded to YouTube and embedded.
Task-number: QTBUG-100512
Change-Id: Ie79de8e7af7908d8f2728c2af273ed5f4ae51a65
Reviewed-by: Lars Knoll <lars.knoll@qt.io>
(cherry picked from commit 29eb3cc4d8a00f889b989730d65f8b7d074bef6a)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
Diffstat (limited to 'examples')
13 files changed, 168 insertions, 6 deletions
diff --git a/examples/multimedia/video/mediaplayer/doc/images/OqosZsDqvzQ.jpg b/examples/multimedia/video/mediaplayer/doc/images/OqosZsDqvzQ.jpg Binary files differnew file mode 100644 index 000000000..a53e85803 --- /dev/null +++ b/examples/multimedia/video/mediaplayer/doc/images/OqosZsDqvzQ.jpg diff --git a/examples/multimedia/video/mediaplayer/doc/images/PlayerMenuBar.gif b/examples/multimedia/video/mediaplayer/doc/images/PlayerMenuBar.gif Binary files differnew file mode 100644 index 000000000..779713332 --- /dev/null +++ b/examples/multimedia/video/mediaplayer/doc/images/PlayerMenuBar.gif diff --git a/examples/multimedia/video/mediaplayer/doc/images/architecture-overview.gif b/examples/multimedia/video/mediaplayer/doc/images/architecture-overview.gif Binary files differnew file mode 100644 index 000000000..b85ce61c5 --- /dev/null +++ b/examples/multimedia/video/mediaplayer/doc/images/architecture-overview.gif diff --git a/examples/multimedia/video/mediaplayer/doc/images/audio-control.gif b/examples/multimedia/video/mediaplayer/doc/images/audio-control.gif Binary files differnew file mode 100644 index 000000000..5ac07ccc2 --- /dev/null +++ b/examples/multimedia/video/mediaplayer/doc/images/audio-control.gif diff --git a/examples/multimedia/video/mediaplayer/doc/images/meta-data.png b/examples/multimedia/video/mediaplayer/doc/images/meta-data.png Binary files differnew file mode 100644 index 000000000..a96b8f7e1 --- /dev/null +++ b/examples/multimedia/video/mediaplayer/doc/images/meta-data.png diff --git a/examples/multimedia/video/mediaplayer/doc/images/nHrBbW0H-pc.jpg b/examples/multimedia/video/mediaplayer/doc/images/nHrBbW0H-pc.jpg Binary files differnew file mode 100644 index 000000000..2d530a46d --- /dev/null +++ b/examples/multimedia/video/mediaplayer/doc/images/nHrBbW0H-pc.jpg diff --git a/examples/multimedia/video/mediaplayer/doc/images/play-pause-stop.gif b/examples/multimedia/video/mediaplayer/doc/images/play-pause-stop.gif Binary files differnew file mode 100644 index 000000000..355f7af86 --- /dev/null +++ b/examples/multimedia/video/mediaplayer/doc/images/play-pause-stop.gif diff --git a/examples/multimedia/video/mediaplayer/doc/images/playbackControlPanel.gif b/examples/multimedia/video/mediaplayer/doc/images/playbackControlPanel.gif Binary files differnew file mode 100644 index 000000000..c71e577d7 --- /dev/null +++ b/examples/multimedia/video/mediaplayer/doc/images/playbackControlPanel.gif diff --git a/examples/multimedia/video/mediaplayer/doc/images/qmlmediaplayer.jpg b/examples/multimedia/video/mediaplayer/doc/images/qmlmediaplayer.jpg Binary files differindex c8fbbca25..94e9c04a0 100644 --- a/examples/multimedia/video/mediaplayer/doc/images/qmlmediaplayer.jpg +++ b/examples/multimedia/video/mediaplayer/doc/images/qmlmediaplayer.jpg diff --git a/examples/multimedia/video/mediaplayer/doc/images/sf_yv01UtIw.jpg b/examples/multimedia/video/mediaplayer/doc/images/sf_yv01UtIw.jpg Binary files differnew file mode 100644 index 000000000..ab7342d5d --- /dev/null +++ b/examples/multimedia/video/mediaplayer/doc/images/sf_yv01UtIw.jpg diff --git a/examples/multimedia/video/mediaplayer/doc/images/url.png b/examples/multimedia/video/mediaplayer/doc/images/url.png Binary files differnew file mode 100644 index 000000000..7bd4ff9f4 --- /dev/null +++ b/examples/multimedia/video/mediaplayer/doc/images/url.png diff --git a/examples/multimedia/video/mediaplayer/doc/qmlmediaplayer.qdocconf b/examples/multimedia/video/mediaplayer/doc/qmlmediaplayer.qdocconf new file mode 100644 index 000000000..bb1eab7da --- /dev/null +++ b/examples/multimedia/video/mediaplayer/doc/qmlmediaplayer.qdocconf @@ -0,0 +1,7 @@ +HTML.extraimages += images/OqosZsDqvzQ.jpg \ + images/sf_yv01UtIw.jpg \ + images/nHrBbW0H-pc.jpg + +qhp.QtMultimedia.extraFiles += images/OqosZsDqvzQ.jpg \ + images/sf_yv01UtIw.jpg \ + images/nHrBbW0H-pc.jpg diff --git a/examples/multimedia/video/mediaplayer/doc/src/mediaplayer.qdoc b/examples/multimedia/video/mediaplayer/doc/src/mediaplayer.qdoc index 6afae93f3..9ddf91bc3 100644 --- a/examples/multimedia/video/mediaplayer/doc/src/mediaplayer.qdoc +++ b/examples/multimedia/video/mediaplayer/doc/src/mediaplayer.qdoc @@ -32,17 +32,172 @@ \ingroup video_examples_qml \brief Playing audio and video using Qt Quick. \meta {tag} {quick} - + \meta {tag} {player} \image qmlmediaplayer.jpg - \e{QML Media Player} demonstrates a simple multimedia player that can play - audio and or video files using various codecs. + This example demonstrates a simple multimedia player that can play + audio and video files using various codecs. \include examples-run.qdocinc - The example uses the QML MediaPlayer object connected to a VideoOutput to - play back the video. + \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 multimedia/video/mediaplayer/main.qml + \skipto MediaPlayer + \printuntil videoOutput: videoOutput + + \c videoOutput is declared like so: - The example shows usage of some advanced features such as selection of audio + \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 multimedia/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 multimedia/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 multimedia/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 multimedia/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 multimedia/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 multimedia/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 multimedia/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{Slider}, \c mediaSlider, in a RowLayout. + + \c mediaTime uses MediaPlayer's \l{MediaPlayer::position}{position} property + like so: + \quotefromfile multimedia/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 multimedia/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{MediaPlayer::muted}{muted} and \l{MediaPlayer::volume}{volume} properties + of MediaPlayer. + + \quotefromfile multimedia/video/mediaplayer/AudioControl.qml + \skipto required + \printuntil value: 100.0 */ |