File indexing completed on 2024-04-21 04:43:16
0001 /* 0002 Copyright (C) 2007 Matthias Kretz <kretz@kde.org> 0003 Copyright (C) 2011 Harald Sitter <sitter@kde.org> 0004 0005 This library is free software; you can redistribute it and/or 0006 modify it under the terms of the GNU Lesser General Public 0007 License as published by the Free Software Foundation; either 0008 version 2.1 of the License, or (at your option) version 3, or any 0009 later version accepted by the membership of KDE e.V. (or its 0010 successor approved by the membership of KDE e.V.), Nokia Corporation 0011 (or its successors, if any) and the KDE Free Qt Foundation, which shall 0012 act as a proxy defined in Section 6 of version 3 of the license. 0013 0014 This library is distributed in the hope that it will be useful, 0015 but WITHOUT ANY WARRANTY; without even the implied warranty of 0016 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 0017 Lesser General Public License for more details. 0018 0019 You should have received a copy of the GNU Lesser General Public 0020 License along with this library. If not, see <http://www.gnu.org/licenses/>. 0021 0022 */ 0023 0024 #ifndef PHONON_MEDIACONTROLLER_H 0025 #define PHONON_MEDIACONTROLLER_H 0026 0027 #include "phonon_export.h" 0028 #include "objectdescription.h" 0029 0030 #include <QObject> 0031 #include <QtGlobal> 0032 0033 0034 #ifndef QT_NO_PHONON_MEDIACONTROLLER 0035 0036 namespace Phonon 0037 { 0038 class MediaControllerPrivate; 0039 class MediaObject; 0040 0041 /** \class MediaController mediacontroller.h phonon/MediaController 0042 * \brief Controls optional features of a media file/device like title, chapter, angle. 0043 * 0044 * \ingroup Playback 0045 * \author Matthias Kretz <kretz@kde.org> 0046 */ 0047 class PHONON_EXPORT MediaController : public QObject 0048 { 0049 Q_OBJECT 0050 Q_FLAGS(Features) 0051 public: 0052 enum Feature { 0053 /** 0054 * In the VOB (DVD) format, it is possible to give several video streams 0055 * of the same scene, each of which displays the scene from a different 0056 * angle. The DVD viewer can then change between these angles. 0057 */ 0058 Angles = 1, 0059 /** 0060 * In the VOB format, chapters are points in a single video stream 0061 * that can be played and seeked to separately. 0062 */ 0063 Chapters = 2, 0064 /** 0065 * In the VOB format, navigations are menus to quickly navigate 0066 * to content. 0067 */ 0068 Navigations = 3, 0069 /** 0070 * On a CD, a title is a separate sound track. On DVD, a title is a 0071 * separate VOB file (i.e. usually a different video entity). 0072 */ 0073 Titles = 4, 0074 /** 0075 * Subtitles for videos. 0076 */ 0077 Subtitles = 5, 0078 /** 0079 * Audio channel/track setting for sources with multiple tracks. 0080 * This can be a DVD or a regular file based container such as MKV or MP4. 0081 */ 0082 AudioChannels = 6 0083 }; 0084 Q_DECLARE_FLAGS(Features, Feature) 0085 0086 enum NavigationMenu { 0087 RootMenu, /** < Root/main menu. */ 0088 TitleMenu, /** < Title Menu to access different titles on the media source. 0089 The title menu is usually where one would select 0090 the episode of a TV series DVD. It can be equal to 0091 the main menu but does not need to be. */ 0092 AudioMenu, /** < Audio menu for language (and sometimes also subtitle) 0093 settings etc. */ 0094 SubtitleMenu, /** < Subtitle menu. Usually this represents the same menu 0095 as AudioMenu or is not present at all (in which case 0096 subtitle settings are probably also in the AudioMenu). */ 0097 ChapterMenu, /** < Chapter menu for chapter selection. */ 0098 AngleMenu /** < Angle menu. Rarely supported on any media source. */ 0099 }; 0100 0101 MediaController(MediaObject *parent); 0102 ~MediaController() override; 0103 0104 Features supportedFeatures() const; 0105 0106 int availableAngles() const; 0107 int currentAngle() const; 0108 0109 int availableChapters() const; 0110 int currentChapter() const; 0111 0112 /** 0113 * Translates a NavigationMenu enum to a string you can use in your GUI. 0114 * Please note that keyboard shortucts will not be present in the returned 0115 * String, therefore it is probably not a good idea to use this function 0116 * if you are providing keyboard shortcuts for every other clickable. 0117 * 0118 * Please note that RootMenu has the string representation "Main Menu" as 0119 * root is a rather technical term when talking about menus. 0120 * 0121 * Example: 0122 * \code 0123 * QString s = Phonon::MediaController::navigationMenuToString(MenuMain); 0124 * // s now contains "Main Menu" 0125 * \endcode 0126 * 0127 * \returns the QString representation of the menu 0128 */ 0129 static QString navigationMenuToString(NavigationMenu menu); 0130 0131 /** 0132 * Get the list of currently available menus for the present media source. 0133 * 0134 * The list is always ordered by occurrence in the NavgiationMenu enum. 0135 * Should you wish to use a different order in your application you will 0136 * have to make appropriate changes. 0137 * 0138 * \returns list of available menus (supported by backend and media source). 0139 * 0140 * \see navigationMenuToString() 0141 */ 0142 QList<NavigationMenu> availableMenus() const; 0143 0144 int availableTitles() const; 0145 int currentTitle() const; 0146 0147 bool autoplayTitles() const; 0148 0149 /** 0150 * Returns the selected audio stream. 0151 * 0152 * \see availableAudioChannels 0153 * \see setCurrentAudioChannel 0154 */ 0155 AudioChannelDescription currentAudioChannel() const; 0156 0157 /** 0158 * Returns the selected subtitle stream. 0159 * 0160 * \see availableSubtitles 0161 * \see setCurrentSubtitle 0162 */ 0163 SubtitleDescription currentSubtitle() const; 0164 0165 /** 0166 * Subtitle auto-detection transparently tries to find a subtitle file 0167 * for the current MediaSource and will automatically select a possible 0168 * match. Detected subtitles are added to the regular subtitle 0169 * descriptions, allowing the user to deactivate it manually or switch 0170 * to another detected file. 0171 * 0172 * Matching method depends on the backend in use and may either be 0173 * driven by a backend or even subsystem implementation. Consequently 0174 * different backends may not give the same results. At any rate all 0175 * algorithms are supposed to give as accurate as possible matches. 0176 * Should you require reproducible matching across backends you should 0177 * deactivate auto-detection entirely and instead do the lookup yourself 0178 * and set the desired file using setCurrentSubtitle(QUrl); the file 0179 * will still be added to the subtitledescriptions model. 0180 * 0181 * \note Auto-detection is always activate so long as the backend supports it. 0182 * 0183 * \returns \c true if subtitles are autodetected, otherwise \c false is 0184 * returned. 0185 * 0186 * \see setSubtitleAutodetect 0187 * \since 4.7.0 0188 */ 0189 bool subtitleAutodetect() const; 0190 0191 /** 0192 * Returns the encoding used to render subtitles 0193 * 0194 * \see setSubtitleEncoding 0195 * \since 4.7.0 0196 */ 0197 QString subtitleEncoding() const; 0198 0199 /** 0200 * Returns the font used to render subtitles 0201 * 0202 * \see setSubtitleFont 0203 * \see QApplication::setFont 0204 * \since 4.7.0 0205 */ 0206 QFont subtitleFont() const; 0207 0208 /** 0209 * Returns the audio streams that can be selected by the user. The 0210 * strings can directly be used in the user interface. 0211 * 0212 * \see selectedAudioChannel 0213 * \see setCurrentAudioChannel 0214 */ 0215 QList<Phonon::AudioChannelDescription> availableAudioChannels() const; 0216 0217 /** 0218 * Returns the subtitle streams that can be selected by the user. The 0219 * strings can directly be used in the user interface. 0220 * 0221 * \see selectedSubtitle 0222 * \see setCurrentSubtitle 0223 */ 0224 QList<SubtitleDescription> availableSubtitles() const; 0225 0226 /** 0227 * Selects an audio stream from the media. 0228 * 0229 * Some media formats allow multiple audio streams to be stored in 0230 * the same file. Normally only one should be played back. 0231 * 0232 * \param stream Description of an audio stream 0233 * 0234 * \see availableAudioChannels() 0235 * \see currentAudioChannel() 0236 */ 0237 void setCurrentAudioChannel(const Phonon::AudioChannelDescription &stream); 0238 0239 /** 0240 * Switches to a menu (e.g. on a DVD). 0241 * 0242 * \see availableMenus() 0243 */ 0244 void setCurrentMenu(NavigationMenu menu); 0245 0246 /** 0247 * Selects a subtitle stream from the media. 0248 * 0249 * Some media formats allow multiple subtitle streams to be stored in 0250 * the same file. Normally only one should be displayed. 0251 * 0252 * \param stream description of a subtitle stream 0253 * 0254 * \see availableSubtitles() 0255 * \see currentSubtitle() 0256 */ 0257 void setCurrentSubtitle(const Phonon::SubtitleDescription &stream); 0258 0259 /** 0260 * \brief Selects a subtitle file as subtitle source for the media. 0261 * 0262 * \note The file will also be added to the model of SubtitleDescriptions, 0263 * so you do not need special handling in the UI. 0264 * 0265 * \see setCurrentSubtitle(const Phonon::SubtitleDescription &stream) 0266 */ 0267 void setCurrentSubtitle(const QUrl &url); 0268 0269 /** 0270 * Sets/Unsets subtitles autodetection. 0271 * 0272 * Detection is attempted when moving the MediaObject into Playing state. 0273 * In order to enable/disable autodetection it must be set before play() 0274 * is called. Whether a MediaSource is set on the MediaObject does not 0275 * matter, and once detection is set it will remain set that way for 0276 * this exact combination of MediaController and MediaObject. 0277 * 0278 * \note The subtitle autodetection may only be changed in states other 0279 * than Playing | Buffering | Paused. 0280 * 0281 * \see subtitleAutodetect 0282 * \since 4.7.0 0283 */ 0284 void setSubtitleAutodetect(bool enable); 0285 0286 /** 0287 * Selects the current encoding used to render subtitles. 0288 * 0289 * The encoding name must respect the 0290 * @link http://www.iana.org/assignments/character-sets 0291 * Link text IANA character-sets encoding file @endlink 0292 * If no encoding is explicitly set, it defaults to UTF-8. 0293 * 0294 * \note The subtitle encoding may only be changed in states other 0295 * than Playing | Buffering | Paused. 0296 * \note Decoding support may vary between backends. 0297 * 0298 * \see subtitleEncoding 0299 * \since 4.7.0 0300 */ 0301 void setSubtitleEncoding(const QString &encoding); 0302 0303 /** 0304 * Selects the current font used to render subtitles. 0305 * 0306 * If no font is explicitly set, the system default font is used. 0307 * 0308 * \note The subtitle font may only be changed in states other 0309 * than Playing | Buffering | Paused. 0310 * \note Non-system fonts can not be used. In particular adding 0311 * fonts manually to the QFontDatabase will not make them 0312 * available as render fonts. 0313 * 0314 * \see subtitleFont 0315 * \since 4.7.0 0316 */ 0317 void setSubtitleFont(const QFont &font); 0318 0319 public Q_SLOTS: 0320 void setCurrentAngle(int angleNumber); 0321 void setCurrentChapter(int chapterNumber); 0322 0323 /** 0324 * Skips to the given title \p titleNumber. 0325 * 0326 * If it was playing before the title change it will start playback on the new title if 0327 * autoplayTitles is enabled. 0328 */ 0329 void setCurrentTitle(int titleNumber); 0330 void setAutoplayTitles(bool); 0331 0332 /** 0333 * Skips to the next title. 0334 * 0335 * If it was playing before the title change it will start playback on the next title if 0336 * autoplayTitles is enabled. 0337 */ 0338 void nextTitle(); 0339 0340 /** 0341 * Skips to the previous title. 0342 * 0343 * If it was playing before the title change it will start playback on the previous title if 0344 * autoplayTitles is enabled. 0345 */ 0346 void previousTitle(); 0347 0348 Q_SIGNALS: 0349 void availableAnglesChanged(int availableAngles); 0350 void availableAudioChannelsChanged(); 0351 void availableChaptersChanged(int availableChapters); 0352 0353 /** 0354 * The available menus changed, this for example emitted when Phonon switches 0355 * from a media source without menus to one with menus (e.g. a DVD). 0356 * 0357 * \param menus is a list of all currently available menus, you should update 0358 * GUI representations of the available menus with the new set. 0359 * 0360 * \see availableMenus() 0361 * \see navigationMenuToString() 0362 */ 0363 void availableMenusChanged(QList<NavigationMenu> menus); 0364 void availableSubtitlesChanged(); 0365 void availableTitlesChanged(int availableTitles); 0366 0367 void angleChanged(int angleNumber); 0368 void chapterChanged(int chapterNumber); 0369 void titleChanged(int titleNumber); 0370 0371 protected: 0372 MediaControllerPrivate *const d; 0373 }; 0374 0375 Q_DECLARE_OPERATORS_FOR_FLAGS(MediaController::Features) 0376 0377 } // namespace Phonon 0378 0379 Q_DECLARE_METATYPE(Phonon::MediaController::NavigationMenu) 0380 Q_DECLARE_METATYPE(QList<Phonon::MediaController::NavigationMenu>) 0381 0382 #endif //QT_NO_PHONON_MEDIACONTROLLER 0383 0384 0385 #endif // PHONON_MEDIACONTROLLER_H