1/*
2 Copyright (C) 2007 Matthias Kretz <kretz@kde.org>
3 Copyright (C) 2011 Harald Sitter <sitter@kde.org>
4
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Lesser General Public
7 License as published by the Free Software Foundation; either
8 version 2.1 of the License, or (at your option) version 3, or any
9 later version accepted by the membership of KDE e.V. (or its
10 successor approved by the membership of KDE e.V.), Nokia Corporation
11 (or its successors, if any) and the KDE Free Qt Foundation, which shall
12 act as a proxy defined in Section 6 of version 3 of the license.
13
14 This library is distributed in the hope that it will be useful,
15 but WITHOUT ANY WARRANTY; without even the implied warranty of
16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17 Lesser General Public License for more details.
18
19 You should have received a copy of the GNU Lesser General Public
20 License along with this library. If not, see <http://www.gnu.org/licenses/>.
21
22*/
23
24#ifndef PHONON_MEDIACONTROLLER_H
25#define PHONON_MEDIACONTROLLER_H
26
27#include "phonon_export.h"
28#include "objectdescription.h"
29
30#include <QObject>
31#include <QtGlobal>
32
33
34#ifndef QT_NO_PHONON_MEDIACONTROLLER
35
36namespace Phonon
37{
38class MediaControllerPrivate;
39class MediaObject;
40
41/** \class MediaController mediacontroller.h phonon/MediaController
42 * \brief Controls optional features of a media file/device like title, chapter, angle.
43 *
44 * \ingroup Playback
45 * \author Matthias Kretz <kretz@kde.org>
46 */
47class PHONON_EXPORT MediaController : public QObject
48{
49 Q_OBJECT
50 Q_FLAGS(Features)
51 public:
52 enum Feature {
53 /**
54 * In the VOB (DVD) format, it is possible to give several video streams
55 * of the same scene, each of which displays the scene from a different
56 * angle. The DVD viewer can then change between these angles.
57 */
58 Angles = 1,
59 /**
60 * In the VOB format, chapters are points in a single video stream
61 * that can be played and seeked to separately.
62 */
63 Chapters = 2,
64 /**
65 * In the VOB format, navigations are menus to quickly navigate
66 * to content.
67 */
68 Navigations = 3,
69 /**
70 * On a CD, a title is a separate sound track. On DVD, a title is a
71 * separate VOB file (i.e. usually a different video entity).
72 */
73 Titles = 4,
74 /**
75 * Subtitles for videos.
76 */
77 Subtitles = 5,
78 /**
79 * Audio channel/track setting for sources with multiple tracks.
80 * This can be a DVD or a regular file based container such as MKV or MP4.
81 */
82 AudioChannels = 6
83 };
84 Q_DECLARE_FLAGS(Features, Feature)
85
86 enum NavigationMenu {
87 RootMenu, /** < Root/main menu. */
88 TitleMenu, /** < Title Menu to access different titles on the media source.
89 The title menu is usually where one would select
90 the episode of a TV series DVD. It can be equal to
91 the main menu but does not need to be. */
92 AudioMenu, /** < Audio menu for language (and sometimes also subtitle)
93 settings etc. */
94 SubtitleMenu, /** < Subtitle menu. Usually this represents the same menu
95 as AudioMenu or is not present at all (in which case
96 subtitle settings are probably also in the AudioMenu). */
97 ChapterMenu, /** < Chapter menu for chapter selection. */
98 AngleMenu /** < Angle menu. Rarely supported on any media source. */
99 };
100
101 MediaController(MediaObject *parent);
102 ~MediaController() override;
103
104 Features supportedFeatures() const;
105
106 int availableAngles() const;
107 int currentAngle() const;
108
109 int availableChapters() const;
110 int currentChapter() const;
111
112 /**
113 * Translates a NavigationMenu enum to a string you can use in your GUI.
114 * Please note that keyboard shortucts will not be present in the returned
115 * String, therefore it is probably not a good idea to use this function
116 * if you are providing keyboard shortcuts for every other clickable.
117 *
118 * Please note that RootMenu has the string representation "Main Menu" as
119 * root is a rather technical term when talking about menus.
120 *
121 * Example:
122 * \code
123 * QString s = Phonon::MediaController::navigationMenuToString(MenuMain);
124 * // s now contains "Main Menu"
125 * \endcode
126 *
127 * \returns the QString representation of the menu
128 */
129 static QString navigationMenuToString(NavigationMenu menu);
130
131 /**
132 * Get the list of currently available menus for the present media source.
133 *
134 * The list is always ordered by occurrence in the NavgiationMenu enum.
135 * Should you wish to use a different order in your application you will
136 * have to make appropriate changes.
137 *
138 * \returns list of available menus (supported by backend and media source).
139 *
140 * \see navigationMenuToString()
141 */
142 QList<NavigationMenu> availableMenus() const;
143
144 int availableTitles() const;
145 int currentTitle() const;
146
147 bool autoplayTitles() const;
148
149 /**
150 * Returns the selected audio stream.
151 *
152 * \see availableAudioChannels
153 * \see setCurrentAudioChannel
154 */
155 AudioChannelDescription currentAudioChannel() const;
156
157 /**
158 * Returns the selected subtitle stream.
159 *
160 * \see availableSubtitles
161 * \see setCurrentSubtitle
162 */
163 SubtitleDescription currentSubtitle() const;
164
165 /**
166 * Subtitle auto-detection transparently tries to find a subtitle file
167 * for the current MediaSource and will automatically select a possible
168 * match. Detected subtitles are added to the regular subtitle
169 * descriptions, allowing the user to deactivate it manually or switch
170 * to another detected file.
171 *
172 * Matching method depends on the backend in use and may either be
173 * driven by a backend or even subsystem implementation. Consequently
174 * different backends may not give the same results. At any rate all
175 * algorithms are supposed to give as accurate as possible matches.
176 * Should you require reproducible matching across backends you should
177 * deactivate auto-detection entirely and instead do the lookup yourself
178 * and set the desired file using setCurrentSubtitle(QUrl); the file
179 * will still be added to the subtitledescriptions model.
180 *
181 * \note Auto-detection is always activate so long as the backend supports it.
182 *
183 * \returns \c true if subtitles are autodetected, otherwise \c false is
184 * returned.
185 *
186 * \see setSubtitleAutodetect
187 * \since 4.7.0
188 */
189 bool subtitleAutodetect() const;
190
191 /**
192 * Returns the encoding used to render subtitles
193 *
194 * \see setSubtitleEncoding
195 * \since 4.7.0
196 */
197 QString subtitleEncoding() const;
198
199 /**
200 * Returns the font used to render subtitles
201 *
202 * \see setSubtitleFont
203 * \see QApplication::setFont
204 * \since 4.7.0
205 */
206 QFont subtitleFont() const;
207
208 /**
209 * Returns the audio streams that can be selected by the user. The
210 * strings can directly be used in the user interface.
211 *
212 * \see selectedAudioChannel
213 * \see setCurrentAudioChannel
214 */
215 QList<Phonon::AudioChannelDescription> availableAudioChannels() const;
216
217 /**
218 * Returns the subtitle streams that can be selected by the user. The
219 * strings can directly be used in the user interface.
220 *
221 * \see selectedSubtitle
222 * \see setCurrentSubtitle
223 */
224 QList<SubtitleDescription> availableSubtitles() const;
225
226 /**
227 * Selects an audio stream from the media.
228 *
229 * Some media formats allow multiple audio streams to be stored in
230 * the same file. Normally only one should be played back.
231 *
232 * \param stream Description of an audio stream
233 *
234 * \see availableAudioChannels()
235 * \see currentAudioChannel()
236 */
237 void setCurrentAudioChannel(const Phonon::AudioChannelDescription &stream);
238
239 /**
240 * Switches to a menu (e.g. on a DVD).
241 *
242 * \see availableMenus()
243 */
244 void setCurrentMenu(NavigationMenu menu);
245
246 /**
247 * Selects a subtitle stream from the media.
248 *
249 * Some media formats allow multiple subtitle streams to be stored in
250 * the same file. Normally only one should be displayed.
251 *
252 * \param stream description of a subtitle stream
253 *
254 * \see availableSubtitles()
255 * \see currentSubtitle()
256 */
257 void setCurrentSubtitle(const Phonon::SubtitleDescription &stream);
258
259 /**
260 * \brief Selects a subtitle file as subtitle source for the media.
261 *
262 * \note The file will also be added to the model of SubtitleDescriptions,
263 * so you do not need special handling in the UI.
264 *
265 * \see setCurrentSubtitle(const Phonon::SubtitleDescription &stream)
266 */
267 void setCurrentSubtitle(const QUrl &url);
268
269 /**
270 * Sets/Unsets subtitles autodetection.
271 *
272 * Detection is attempted when moving the MediaObject into Playing state.
273 * In order to enable/disable autodetection it must be set before play()
274 * is called. Whether a MediaSource is set on the MediaObject does not
275 * matter, and once detection is set it will remain set that way for
276 * this exact combination of MediaController and MediaObject.
277 *
278 * \note The subtitle autodetection may only be changed in states other
279 * than Playing | Buffering | Paused.
280 *
281 * \see subtitleAutodetect
282 * \since 4.7.0
283 */
284 void setSubtitleAutodetect(bool enable);
285
286 /**
287 * Selects the current encoding used to render subtitles.
288 *
289 * The encoding name must respect the
290 * @link http://www.iana.org/assignments/character-sets
291 * Link text IANA character-sets encoding file @endlink
292 * If no encoding is explicitly set, it defaults to UTF-8.
293 *
294 * \note The subtitle encoding may only be changed in states other
295 * than Playing | Buffering | Paused.
296 * \note Decoding support may vary between backends.
297 *
298 * \see subtitleEncoding
299 * \since 4.7.0
300 */
301 void setSubtitleEncoding(const QString &encoding);
302
303 /**
304 * Selects the current font used to render subtitles.
305 *
306 * If no font is explicitly set, the system default font is used.
307 *
308 * \note The subtitle font may only be changed in states other
309 * than Playing | Buffering | Paused.
310 * \note Non-system fonts can not be used. In particular adding
311 * fonts manually to the QFontDatabase will not make them
312 * available as render fonts.
313 *
314 * \see subtitleFont
315 * \since 4.7.0
316 */
317 void setSubtitleFont(const QFont &font);
318
319 public Q_SLOTS:
320 void setCurrentAngle(int angleNumber);
321 void setCurrentChapter(int chapterNumber);
322
323 /**
324 * Skips to the given title \p titleNumber.
325 *
326 * If it was playing before the title change it will start playback on the new title if
327 * autoplayTitles is enabled.
328 */
329 void setCurrentTitle(int titleNumber);
330 void setAutoplayTitles(bool);
331
332 /**
333 * Skips to the next title.
334 *
335 * If it was playing before the title change it will start playback on the next title if
336 * autoplayTitles is enabled.
337 */
338 void nextTitle();
339
340 /**
341 * Skips to the previous title.
342 *
343 * If it was playing before the title change it will start playback on the previous title if
344 * autoplayTitles is enabled.
345 */
346 void previousTitle();
347
348 Q_SIGNALS:
349 void availableAnglesChanged(int availableAngles);
350 void availableAudioChannelsChanged();
351 void availableChaptersChanged(int availableChapters);
352
353 /**
354 * The available menus changed, this for example emitted when Phonon switches
355 * from a media source without menus to one with menus (e.g. a DVD).
356 *
357 * \param menus is a list of all currently available menus, you should update
358 * GUI representations of the available menus with the new set.
359 *
360 * \see availableMenus()
361 * \see navigationMenuToString()
362 */
363 void availableMenusChanged(QList<NavigationMenu> menus);
364 void availableSubtitlesChanged();
365 void availableTitlesChanged(int availableTitles);
366
367 void angleChanged(int angleNumber);
368 void chapterChanged(int chapterNumber);
369 void titleChanged(int titleNumber);
370
371 protected:
372 MediaControllerPrivate *const d;
373};
374
375Q_DECLARE_OPERATORS_FOR_FLAGS(MediaController::Features)
376
377} // namespace Phonon
378
379Q_DECLARE_METATYPE(Phonon::MediaController::NavigationMenu)
380Q_DECLARE_METATYPE(QList<Phonon::MediaController::NavigationMenu>)
381
382#endif //QT_NO_PHONON_MEDIACONTROLLER
383
384
385#endif // PHONON_MEDIACONTROLLER_H
386

source code of phonon/phonon/mediacontroller.h