1 | /* This file is part of the KDE project |
2 | Copyright (C) 2005-2008 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 PHONONNAMESPACE_H |
24 | #define PHONONNAMESPACE_H |
25 | |
26 | #include "phonon_export.h" |
27 | |
28 | /** |
29 | * Helper macro that can be used like |
30 | * \code |
31 | * #if (PHONON_VERSION >= PHONON_VERSION_CHECK(4, 4, 0)) |
32 | * \endcode |
33 | */ |
34 | #define PHONON_VERSION_CHECK(major, minor, patch) ((major<<16)|(minor<<8)|(patch)) |
35 | |
36 | /** |
37 | * PHONON_VERSION is (major << 16) + (minor << 8) + patch. |
38 | */ |
39 | #define PHONON_VERSION PHONON_VERSION_CHECK(4, 7, 2) |
40 | |
41 | /** |
42 | * PHONON_VERSION_STR is "major.minor.patch". E.g. "4.2.1" |
43 | */ |
44 | #define PHONON_VERSION_STR "4.7.2" |
45 | |
46 | /** |
47 | * Definitions to disable capture - should end up in the backends and |
48 | * platform plugins, too |
49 | */ |
50 | /* #undef PHONON_NO_CAPTURE */ |
51 | #ifdef PHONON_NO_CAPTURE |
52 | #define PHONON_NO_VIDEOCAPTURE |
53 | #define PHONON_NO_AUDIOCAPTURE |
54 | #endif |
55 | |
56 | |
57 | class QString; |
58 | |
59 | /** |
60 | * \brief The %KDE Multimedia classes |
61 | * |
62 | * In this Namespace you find the classes to access Multimedia functions for |
63 | * audio and video playback. Those classes are not dependent |
64 | * on any specific framework (like they were in pre KDE4 times) but rather use |
65 | * exchangeable backends to do the work. |
66 | * |
67 | * If you want to write a new backend take a look at \ref phonon_backend_development_page. |
68 | * |
69 | * \author Matthias Kretz <kretz@kde.org> |
70 | */ |
71 | namespace Phonon |
72 | { |
73 | PHONON_EXPORT const char *phononVersion(); |
74 | |
75 | /** |
76 | * Enum to identify the media discs supported by MediaObject. |
77 | * |
78 | * \see MediaSource(Phonon::DiscType, const QString &deviceName) |
79 | */ |
80 | enum DiscType { |
81 | NoDisc = -1, /** < No disc was selected. Only used as default value in |
82 | \class MediaSource */ |
83 | Cd = 0, /** < Audio CD */ |
84 | Dvd = 1, /** < Video DVD (no arbitrary data DVDs) */ |
85 | Vcd = 2, /** < Video CD */ |
86 | BluRay = 3 /** < BluRay video disc \since 4.7.0 */ |
87 | }; |
88 | |
89 | /** |
90 | * Provided as keys for MediaObject::metaData for convenience, in addition to the strings defined in |
91 | * the Ogg Vorbis specification. |
92 | */ |
93 | enum MetaData { |
94 | /** |
95 | * The artist generally considered responsible for the work. In popular |
96 | * music this is usually the performing band or singer. For classical |
97 | * music it would be the composer. For an audio book it would be the |
98 | * author of the original text. |
99 | */ |
100 | ArtistMetaData, |
101 | /** |
102 | * The collection name to which this track belongs. |
103 | */ |
104 | AlbumMetaData, |
105 | /** |
106 | * Track/Work name |
107 | */ |
108 | TitleMetaData, |
109 | /** |
110 | * Date the track was recorded |
111 | */ |
112 | DateMetaData, |
113 | /** |
114 | * A short text indication of music genre |
115 | */ |
116 | GenreMetaData, |
117 | /** |
118 | * The track number of this piece if part of a specific larger |
119 | * collection or album |
120 | */ |
121 | TracknumberMetaData, |
122 | /** |
123 | * A short text description of the contents |
124 | */ |
125 | DescriptionMetaData, |
126 | MusicBrainzDiscIdMetaData |
127 | }; |
128 | |
129 | /** |
130 | * The state the media producing object is in at the moment. |
131 | * |
132 | * \see MediaObject |
133 | */ |
134 | enum State { |
135 | /** |
136 | * After construction it might take a while before the Player is |
137 | * ready to play(). Normally this doesn't happen for local |
138 | * files, but can happen for remote files where the asynchronous |
139 | * mimetype detection and prebuffering can take a while. |
140 | */ |
141 | LoadingState, |
142 | /** |
143 | * The Player has a valid media file loaded and is ready for |
144 | * playing. |
145 | */ |
146 | StoppedState, |
147 | /** |
148 | * The Player is playing a media file. |
149 | */ |
150 | PlayingState, |
151 | /** |
152 | * The Player is waiting for data to be able to continue |
153 | * playing. |
154 | */ |
155 | BufferingState, |
156 | /** |
157 | * The Player is currently paused. |
158 | */ |
159 | PausedState, |
160 | /** |
161 | * An unrecoverable error occurred. The Object is unusable in this state. |
162 | */ |
163 | ErrorState |
164 | }; |
165 | |
166 | /** |
167 | * Set's the category your program should be listed in in the mixer. |
168 | * |
169 | * A Jukebox will set this to Music, a VoIP program to Communication, a |
170 | * DVD player to video, and so on. |
171 | * |
172 | * \note These categories can also become useful for an application that |
173 | * controls the volumes automatically, like turning down the music when a call |
174 | * comes in, or turning down the notifications when the media player knows |
175 | * it's playing classical music. |
176 | * |
177 | * \see AudioOutput::setCategory |
178 | */ |
179 | enum Category { |
180 | /** |
181 | * Will make use of the default device. |
182 | */ |
183 | NoCategory = -1, |
184 | /** |
185 | * If the sounds produced are notifications (bing, beep and such) you |
186 | * should use this category. |
187 | */ |
188 | NotificationCategory = 0, |
189 | /** |
190 | * If your application is a music player (like a jukebox or media player |
191 | * playing an audio file). |
192 | */ |
193 | MusicCategory = 1, |
194 | /** |
195 | * If the sound is the audio channel of a video. |
196 | */ |
197 | VideoCategory = 2, |
198 | /** |
199 | * If your applications produces sounds from communication with somebody |
200 | * else (VoIP, voice chat). |
201 | */ |
202 | CommunicationCategory = 3, |
203 | /** |
204 | * Sound produced by a computer game should go into this category. |
205 | */ |
206 | GameCategory = 4, |
207 | /** |
208 | * Sounds produced for accessibility (e.g. Text-To-Speech) |
209 | */ |
210 | AccessibilityCategory = 5, |
211 | /** |
212 | * \internal |
213 | * Holds the largest value of categories. |
214 | */ |
215 | LastCategory = AccessibilityCategory |
216 | }; |
217 | |
218 | /** |
219 | * What capture category does an application adhere to. Mainly |
220 | * used to decide upon what capture device will be used, depending |
221 | * on the global configuration (user preference). |
222 | * |
223 | * \see MediaObject::setVideoCaptureDevice |
224 | * \see MediaObject::setAudioCaptureDevice |
225 | * \see AvCapture |
226 | */ |
227 | enum CaptureCategory { |
228 | /** |
229 | * Will make use of the default device |
230 | */ |
231 | NoCaptureCategory = NoCategory, |
232 | |
233 | /** |
234 | * For applications that use video or audio capture for communication, |
235 | * video conference style. (VoIP, voice chat) |
236 | */ |
237 | CommunicationCaptureCategory = CommunicationCategory, |
238 | |
239 | /** |
240 | * Recording applications, that actually save the data somewhere |
241 | */ |
242 | RecordingCaptureCategory, |
243 | |
244 | /** |
245 | * Voice control. Maybe used for accesibility purpouses too |
246 | */ |
247 | ControlCaptureCategory = AccessibilityCategory |
248 | }; |
249 | |
250 | namespace Capture { |
251 | /** |
252 | * Describes the type of a capture device, audio or video |
253 | */ |
254 | enum DeviceType { |
255 | AudioType, |
256 | VideoType |
257 | }; |
258 | } |
259 | |
260 | /** |
261 | * Tells your program how to recover from an error. |
262 | * |
263 | * \see MediaObject::errorType() |
264 | */ |
265 | enum ErrorType { |
266 | /** |
267 | * No error. MediaObject::errorType() returns this if |
268 | * MediaObject::state() != Phonon::ErrorState. |
269 | */ |
270 | NoError = 0, |
271 | /** |
272 | * Playback should work, and trying with another URL should work. |
273 | */ |
274 | NormalError = 1, |
275 | /** |
276 | * Something important does not work. Your program cannot continue |
277 | * playback or capture or whatever it was trying to do |
278 | * without help from the user. |
279 | */ |
280 | FatalError = 2 |
281 | }; |
282 | |
283 | /** |
284 | * Returns a (translated) string to show to the user identifying the given |
285 | * Category. |
286 | */ |
287 | PHONON_EXPORT QString categoryToString(Category c); |
288 | |
289 | /** |
290 | * Returns a (translated) string to show to the user identifying the given |
291 | * CaptureCategory. |
292 | */ |
293 | PHONON_EXPORT QString categoryToString(CaptureCategory c); |
294 | |
295 | // TODO: naming |
296 | /*enum MediaStreamType { |
297 | Audio = 1, |
298 | Video = 2, |
299 | StillImage = 4, |
300 | Subtitle = 8, |
301 | AllMedia = 0xFFFFFFFF |
302 | }; |
303 | Q_DECLARE_FLAGS(MediaStreamTypes, MediaStreamType)*/ |
304 | |
305 | PHONON_EXPORT QDebug operator <<(QDebug dbg, const Phonon::DiscType &); |
306 | PHONON_EXPORT QDebug operator <<(QDebug dbg, const Phonon::MetaData &); |
307 | PHONON_EXPORT QDebug operator <<(QDebug dbg, const Phonon::State &); |
308 | PHONON_EXPORT QDebug operator <<(QDebug dbg, const Phonon::Category &); |
309 | PHONON_EXPORT QDebug operator <<(QDebug dbg, const Phonon::CaptureCategory &); |
310 | PHONON_EXPORT QDebug operator <<(QDebug dbg, const Phonon::Capture::DeviceType &); |
311 | PHONON_EXPORT QDebug operator <<(QDebug dbg, const Phonon::ErrorType &); |
312 | |
313 | } // namespace Phonon |
314 | //Q_DECLARE_OPERATORS_FOR_FLAGS(Phonon::MediaStreamTypes) |
315 | |
316 | #include <QtCore/QMetaType> |
317 | |
318 | Q_DECLARE_METATYPE(Phonon::State) |
319 | Q_DECLARE_METATYPE(Phonon::ErrorType) |
320 | Q_DECLARE_METATYPE(Phonon::Category) |
321 | Q_DECLARE_METATYPE(Phonon::CaptureCategory) |
322 | |
323 | |
324 | |
325 | // vim: sw=4 ts=4 tw=80 |
326 | #endif // PHONONNAMESPACE_H |
327 | |