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
57class 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 */
71namespace 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
318Q_DECLARE_METATYPE(Phonon::State)
319Q_DECLARE_METATYPE(Phonon::ErrorType)
320Q_DECLARE_METATYPE(Phonon::Category)
321Q_DECLARE_METATYPE(Phonon::CaptureCategory)
322
323
324
325// vim: sw=4 ts=4 tw=80
326#endif // PHONONNAMESPACE_H
327