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