1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
|
/****************************************************************************
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** No Commercial Usage
** This file contains pre-release code and may not be distributed.
** You may use this file in accordance with the terms and conditions
** contained in the either Technology Preview License Agreement or the
** Beta Release License Agreement.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 2.1 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 2.1 requirements
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
**
** In addition, as a special exception, Nokia gives you certain
** additional rights. These rights are described in the Nokia Qt LGPL
** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
** package.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 3.0 as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL included in the
** packaging of this file. Please review the following information to
** ensure the GNU General Public License version 3.0 requirements will be
** met: http://www.gnu.org/copyleft/gpl.html.
**
** If you are unsure which license is appropriate for your use, please
** contact the sales department at http://www.qtsoftware.com/contact.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\example phonon/musicplayer
\title Music Player Example
The Music Player Example shows how to use Phonon - the multimedia
framework that comes with Qt - to create a simple music player.
The player can play music files, and provides simple playback
control, such as pausing, stopping, and resuming the music.
\image musicplayer.png
The player has a button group with the play, pause, and stop
buttons familiar from most music players. The top-most slider
controls the position in the media stream, and the bottom slider
allows adjusting the sound volume.
The user can use a file dialog to add music files to a table,
which displays meta information about the music - such as the
title, album, and artist. Each row contains information about a
single music file; to play it, the user selects that row and
presses the play button. Also, when a row is selected, the files
in the table are queued for playback.
Phonon offers playback of sound using an available audio device,
e.g., a sound card or an USB headset. For the implementation, we
use two objects: a \l{Phonon::}{MediaObject}, which controls the
playback, and an \l{Phonon::}{AudioOutput}, which can output the
audio to a sound device. We will explain how they cooperate when
we encounter them in the code. For a high-level introduction to
Phonon, see its \l{Phonon Overview}{overview}.
The API of Phonon is implemented through an intermediate
technology on each supported platform: DirectShow, QuickTime, and
GStreamer. The sound formats supported may therefore vary from
system to system. We do not in this example try to determine which
formats are supported, but let Phonon report an error if the user
tries to play an unsupported sound file.
Our player consists of one class, \c MainWindow, which both
constructs the GUI and handles the playback. We will now go
through the parts of its definition and implementation that
concerns Phonon.
\section1 MainWindow Class Definition
Most of the API in \c MainWindow is private, as is often the case
for classes that represent self-contained windows. We list Phonon
objects and slots we connect to their signals; we take a closer
look at them when we walk through the \c MainWindow
implementation.
\snippet examples/phonon/musicplayer/mainwindow.h 2
We use the \l{Phonon::}{SeekSlider} to move the current playback
position in the media stream, and the \l{Phonon::}{VolumeSlider}
controls the sound volume. Both of these widgets come ready made
with Phonon. We use another \l{Phonon::}{MediaObject},
metaInformationProvider, to get the meta information from the
music files. More on this later.
\snippet examples/phonon/musicplayer/mainwindow.h 1
The \l{Phonon::}{MediaObject} informs us of the state of the playback and
properties of the media it is playing back through a series of
signals. We connect the signals we need to slots in \c MainWindow.
The \c tableClicked() slot is connected to the table, so that we
know when the user requests playback of a new music file, by
clicking on the table.
\section1 MainWindow Class Implementation
The \c MainWindow class handles both the user interface and
Phonon. We will now take a look at the code relevant for Phonon.
The code required for setting up the GUI is explained elsewhere.
We start with the constructor:
\snippet examples/phonon/musicplayer/mainwindow.cpp 0
We start by instantiating our media and audio output objects.
As mentioned, the media object knows how to playback
multimedia (in our case sound files) while the audio output
can send it to a sound device.
For the playback to work, the media and audio output objects need
to get in contact with each other, so that the media object can
send the sound to the audio output. Phonon is a graph based
framework, i.e., its objects are nodes that can be connected by
paths. Objects are connected using the \c createPath() function,
which is part of the Phonon namespace.
\snippet examples/phonon/musicplayer/mainwindow.cpp 1
We also connect signals of the media object to slots in our \c
MainWindow. We will examine them shortly.
\snippet examples/phonon/musicplayer/mainwindow.cpp 2
Finally, we call private helper functions to set up the GUI.
The \c setupUi() function contains code for setting up the seek
, and volume slider. We move on to \c setupUi():
\snippet examples/phonon/musicplayer/mainwindow.cpp 3
\dots
\snippet examples/phonon/musicplayer/mainwindow.cpp 4
After creating the widgets, they must be supplied with the
\l{Phonon::}{MediaObject} and \l{Phonon::}{AudioOutput} objects
they should control.
In the \c setupActions(), we connect the actions for the play,
pause, and stop tool buttons, to slots of the media object.
\snippet examples/phonon/musicplayer/mainwindow.cpp 5
We move on to the slots of \c MainWindow, starting with \c
addFiles():
\snippet examples/phonon/musicplayer/mainwindow.cpp 6
In the \c addFiles() slot, we add files selected by the user to
the \c sources list. We then set the first source selected on the
\c metaInformationProvider \l{Phonon::}{MediaObject}, which will
send a state changed signal when the meta information is resolved;
we have this signal connected to the \c metaStateChanged() slot.
The media object informs us of state changes by sending the \c
stateChanged() signal. The \c stateChanged() slot is connected
to this signal.
\snippet examples/phonon/musicplayer/mainwindow.cpp 9
The \l{Phonon::MediaObject::}{errorString()} function gives a
description of the error that is suitable for users of a Phonon
application. The two values of the \l{Phonon::}{ErrorState} enum
helps us determine whether it is possible to try to play the same
file again.
\snippet examples/phonon/musicplayer/mainwindow.cpp 10
We update the GUI when the playback state changes, i.e., when it
starts, pauses, stops, or resumes.
The media object will report other state changes, as defined by the
\l{Phonon::}{State} enum.
The \c tick() slot is connected to a \l{Phonon::}{MediaObject} signal which is
emitted when the playback position changes:
\snippet examples/phonon/musicplayer/mainwindow.cpp 11
The \c time is given in milliseconds.
When the table is clicked on with the mouse, \c tableClick()
is invoked:
\snippet examples/phonon/musicplayer/mainwindow.cpp 12
Since we stop the media object, we first check whether it is
currently playing. \c row contains the row in the table that was
clicked upon; the indices of \c sources follows the table, so we
can simply use \c row to find the new source.
\snippet examples/phonon/musicplayer/mainwindow.cpp 13
When the media source changes, we simply need to select the
corresponding row in the table.
\snippet examples/phonon/musicplayer/mainwindow.cpp 14
When \c metaStateChanged() is invoked, \c
metaInformationProvider has resolved the meta data for its current
source. A \l{Phonon::}{MediaObject} will do this before
entering \l{Phonon::}{StoppedState}. Note that we could also
have used the \l{Phonon::MediaObject::}{metaDataChanged()} signal for
this purpose.
Some of the meta data is then chosen to be displayed in the
music table. A file might not contain the meta data requested,
in which case an empty string is returned.
\snippet examples/phonon/musicplayer/mainwindow.cpp 15
If we have media sources in \c sources of which meta information
is not resolved, we set a new source on the \c
metaInformationProvider, which will invoke \c metaStateChanged()
again.
We move on to the \c aboutToFinish() slot:
\snippet examples/phonon/musicplayer/mainwindow.cpp 16
When a file is finished playing, the Music Player will move on and
play the next file in the table. This slot is connected to the
\l{Phonon::}{MediaObject}'s
\l{Phonon::MediaObject::}{aboutToFinish()} signal, which is
guaranteed to be emitted while there is still time to enqueue
another file for playback.
\section1 The main() function.
Phonon requires that the application has a name; it is set with
\l{QCoreApplication::}{setApplicationName()}. This is because
D-Bus, which is used by Phonon on Linux systems, demands this.
\snippet examples/phonon/musicplayer/main.cpp 1
*/
|
