1/* This file is part of the KDE project
2 Copyright (C) 2004-2007 Matthias Kretz <kretz@kde.org>
3
4 This library is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Lesser General Public
6 License as published by the Free Software Foundation; either
7 version 2.1 of the License, or (at your option) version 3, or any
8 later version accepted by the membership of KDE e.V. (or its
9 successor approved by the membership of KDE e.V.), Nokia Corporation
10 (or its successors, if any) and the KDE Free Qt Foundation, which shall
11 act as a proxy defined in Section 6 of version 3 of the license.
12
13 This library is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 Lesser General Public License for more details.
17
18 You should have received a copy of the GNU Lesser General Public
19 License along with this library. If not, see <http://www.gnu.org/licenses/>.
20
21*/
22
23#ifndef Phonon_VIDEOPLAYER_H
24#define Phonon_VIDEOPLAYER_H
25
26#include "phonon_export.h"
27#include "phononnamespace.h"
28#include "mediasource.h"
29#include <QWidget>
30
31
32#ifndef QT_NO_PHONON_VIDEOPLAYER
33
34namespace Phonon
35{
36class VideoPlayerPrivate;
37class MediaObject;
38class AudioOutput;
39class VideoWidget;
40
41/** \class VideoPlayer videoplayer.h phonon/VideoPlayer
42 * \short Playback class for simple tasks.
43 *
44 * With %VideoPlayer you can get results quickly and easily. You can do the standard
45 * playback tasks like play, pause and stop, but also set a playback volume and
46 * seek (there's no guarantee that the seek will work, though).
47 *
48 * Keep in mind that when the %VideoPlayer instance is deleted the playback will
49 * stop.
50 *
51 * A play and forget code example:
52 * \code
53 * VideoPlayer *player = new VideoPlayer(parentWidget);
54 * connect(player, SIGNAL(finished()), player, SLOT(deleteLater()));
55 * player->play(url);
56 * \endcode
57 *
58 * \ingroup Playback
59 * \ingroup PhononVideo
60 * \author Matthias Kretz <kretz@kde.org>
61 */
62class PHONON_EXPORT VideoPlayer : public QWidget
63{
64 Q_OBJECT
65 public:
66 /**
67 * Constructs a new %VideoPlayer instance.
68 *
69 * \param category The category used for the audio output device.
70 * \param parent The QObject parent.
71 */
72 explicit VideoPlayer(Phonon::Category category, QWidget *parent = nullptr);
73
74 /**
75 * Constructs a new video widget with a \p parent
76 * using Phonon::VideoCategory as its category.
77 *
78 * \param parent The QObject parent.
79 */
80 VideoPlayer(QWidget *parent = nullptr);
81
82 /**
83 * On destruction the playback is stopped, also the audio output is
84 * removed so that the desktop mixer will not show the application
85 * anymore. If you need a persistent audio output don't use
86 * %VideoPlayer but MediaObject, VideoPath and VideoOutput.
87 */
88 ~VideoPlayer() override;
89
90 /**
91 * Get the total time (in milliseconds) of the file currently being played.
92 */
93 qint64 totalTime() const;
94 /**
95 * Get the current time (in milliseconds) of the file currently being played.
96 */
97 qint64 currentTime() const;
98 /**
99 * This is the current volume of the output as voltage factor.
100 *
101 * 1.0 means 100%, 0.5 means 50% voltage/25% power, 0.0 means 0%
102 */
103 float volume() const;
104
105 /**
106 * \returns \c true if it is currently playing
107 * \returns \c false if it is currently stopped or paused
108 */
109 bool isPlaying() const;
110 /**
111 * \returns \c true if it is currently paused
112 * \returns \c false if it is currently playing or stopped
113 */
114 bool isPaused() const;
115
116 /**
117 * getter for the MediaObject.
118 */
119 MediaObject *mediaObject() const;
120
121 /**
122 * getter for the AudioOutput.
123 */
124 AudioOutput *audioOutput() const;
125
126 /**
127 * getter for the VideoWidget.
128 */
129 VideoWidget *videoWidget() const;
130
131 public Q_SLOTS:
132 /**
133 * Starts preloading the media data and fill audiobuffers in the
134 * backend.
135 *
136 * When there's already a media playing (or paused) it will be stopped
137 * (the finished signal will not be emitted).
138 */
139 void load(const Phonon::MediaSource &source);
140
141 /**
142 * Play the media at the given URL. Starts playback as fast as possible.
143 * This can take a considerable time depending on the URL and the
144 * backend.
145 *
146 * If you need low latency between calling play() and the sound actually
147 * starting to play on your output device you need to use MediaObject
148 * and be able to set the URL before calling play(). Note that
149 * \code
150 * audioPlayer->load(url);
151 * audioPlayer->play();
152 * \endcode
153 * doesn't make a difference: the application should be idle between the
154 * load and play calls so that the backend can start preloading the
155 * media and fill audio buffers.
156 */
157 void play(const Phonon::MediaSource &source);
158
159 /**
160 * Continues playback of a paused media. Restarts playback of a stopped
161 * media.
162 */
163 void play();
164 /**
165 * Pauses the playback.
166 */
167 void pause();
168 /**
169 * Stops the playback.
170 */
171 void stop();
172
173 /**
174 * Seeks to the requested time. Note that the backend is free to ignore
175 * the seek request if the media source isn't seekable.
176 *
177 * \param ms Time in milliseconds from the start of the media.
178 */
179 void seek(qint64 ms);
180 /**
181 * Sets the volume of the output as voltage factor.
182 *
183 * 1.0 means 100%, 0.5 means 50% voltage/25% power, 0.0 means 0%
184 */
185 void setVolume(float volume);
186
187 Q_SIGNALS:
188 /**
189 * This signal is emitted when the playback finished.
190 */
191 void finished();
192
193 protected:
194 bool event(QEvent *) override;
195 VideoPlayerPrivate *const d;
196};
197
198} //namespace Phonon
199
200#endif //QT_NO_PHONON_VIDEOPLAYER
201
202
203#endif // Phonon_VIDEOPLAYER_H
204// vim: sw=4 ts=4 tw=80
205

source code of phonon/phonon/videoplayer.h