1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the documentation of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 /*!

    43     \example phonon/qmusicplayer

    44     \title Music Player Example

    45 

    46     The Music Player Example shows how to use Phonon - the multimedia

    47     framework that comes with Qt - to create a simple music player.

    48     The player can play music files, and provides simple playback

    49     control, such as pausing, stopping, and resuming the music.

    50 

    51     \image musicplayer.png

    52 

    53     The player has a button group with the play, pause, and stop

    54     buttons familiar from most music players. The top-most slider

    55     controls the position in the media stream, and the bottom slider

    56     allows adjusting the sound volume. 

    57 

    58     The user can use a file dialog to add music files to a table,

    59     which displays meta information about the music - such as the

    60     title, album, and artist. Each row contains information about a

    61     single music file; to play it, the user selects that row and

    62     presses the play button. Also, when a row is selected, the files

    63     in the table are queued for playback.

    64 

    65     Phonon offers playback of sound using an available audio device,

    66     e.g., a sound card or an USB headset. For the implementation, we

    67     use two objects: a \l{Phonon::}{MediaObject}, which controls the

    68     playback, and an \l{Phonon::}{AudioOutput}, which can output the

    69     audio to a sound device. We will explain how they cooperate when

    70     we encounter them in the code. For a high-level introduction to

    71     Phonon, see its \l{Phonon Overview}{overview}.

    72 

    73     The API of Phonon is implemented through an intermediate

    74     technology on each supported platform: DirectShow, QuickTime, and

    75     GStreamer. The sound formats supported may therefore vary from

    76     system to system. We do not in this example try to determine which

    77     formats are supported, but let Phonon report an error if the user

    78     tries to play an unsupported sound file.

    79 

    80     Our player consists of one class, \c MainWindow, which both

    81     constructs the GUI and handles the playback. We will now go

    82     through the parts of its definition and implementation that

    83     concerns Phonon.

    84 

    85     \section1 MainWindow Class Definition

    86 

    87     Most of the API in \c MainWindow is private, as is often the case

    88     for classes that represent self-contained windows. We list Phonon

    89     objects and slots we connect to their signals; we take a closer

    90     look at them when we walk through the \c MainWindow

    91     implementation.

    92 

    93     \snippet examples/phonon/qmusicplayer/mainwindow.h 2

    94 

    95     We use the \l{Phonon::}{SeekSlider} to move the current playback

    96     position in the media stream, and the \l{Phonon::}{VolumeSlider}

    97     controls the sound volume. Both of these widgets come ready made

    98     with Phonon.  We use another \l{Phonon::}{MediaObject},

    99     metaInformationProvider, to get the meta information from the

   100     music files. More on this later.

   101 

   102     \snippet examples/phonon/qmusicplayer/mainwindow.h 1

   103 

   104     The \l{Phonon::}{MediaObject} informs us of the state of the playback and

   105     properties of the media it is playing back through a series of

   106     signals. We connect the signals we need to slots in \c MainWindow.

   107     The \c tableClicked() slot is connected to the table, so that we

   108     know when the user requests playback of a new music file, by

   109     clicking on the table.

   110 

   111     \section1 MainWindow Class Implementation

   112 

   113     The \c MainWindow class handles both the user interface and

   114     Phonon. We will now take a look at the code relevant for Phonon.

   115     The code required for setting up the GUI is explained elsewhere.

   116 

   117     We start with the constructor:

   118 

   119     \snippet examples/phonon/qmusicplayer/mainwindow.cpp 0

   120 

   121     We start by instantiating our media and audio output objects.

   122     As mentioned, the media object knows how to playback

   123     multimedia (in our case sound files) while the audio output

   124     can send it to a sound device.

   125 

   126     For the playback to work, the media and audio output objects need

   127     to get in contact with each other, so that the media object can

   128     send the sound to the audio output. Phonon is a graph based

   129     framework, i.e., its objects are nodes that can be connected by

   130     paths. Objects are connected using the \c createPath() function,

   131     which is part of the Phonon namespace.

   132 

   133     \snippet examples/phonon/qmusicplayer/mainwindow.cpp 1

   134 

   135     We also connect signals of the media object to slots in our \c

   136     MainWindow. We will examine them shortly.

   137 

   138     \snippet examples/phonon/qmusicplayer/mainwindow.cpp 2

   139 

   140     Finally, we call private helper functions to set up the GUI.

   141     The \c setupUi() function contains code for setting up the seek

   142     , and volume slider. We move on to \c setupUi():

   143 

   144     \snippet examples/phonon/qmusicplayer/mainwindow.cpp 3

   145     \dots

   146     \snippet examples/phonon/qmusicplayer/mainwindow.cpp 4

   147 

   148     After creating the widgets, they must be supplied with the

   149     \l{Phonon::}{MediaObject} and \l{Phonon::}{AudioOutput} objects

   150     they should control.  

   151 

   152     In the \c setupActions(), we connect the actions for the play,

   153     pause, and stop tool buttons, to slots of the media object.

   154 

   155     \snippet examples/phonon/qmusicplayer/mainwindow.cpp 5

   156 

   157     We move on to the slots of \c MainWindow, starting with \c

   158     addFiles(): 

   159 

   160     \snippet examples/phonon/qmusicplayer/mainwindow.cpp 6

   161 

   162     In the \c addFiles() slot, we add files selected by the user to

   163     the \c sources list. We then set the first source selected on the

   164     \c metaInformationProvider \l{Phonon::}{MediaObject}, which will

   165     send a state changed signal when the meta information is resolved;

   166     we have this signal connected to the \c metaStateChanged() slot.

   167 

   168     The media object informs us of state changes by sending the \c

   169     stateChanged() signal. The \c stateChanged() slot is connected

   170     to this signal.

   171 

   172     \snippet examples/phonon/qmusicplayer/mainwindow.cpp 9

   173 

   174     The \l{Phonon::MediaObject::}{errorString()} function gives a

   175     description of the error that is suitable for users of a Phonon

   176     application. The two values of the \l{Phonon::}{ErrorState} enum

   177     helps us determine whether it is possible to try to play the same

   178     file again.

   179 

   180     \snippet examples/phonon/qmusicplayer/mainwindow.cpp 10

   181 

   182     We update the GUI when the playback state changes, i.e., when it

   183     starts, pauses, stops, or resumes.

   184 

   185     The media object will report other state changes, as defined by the

   186     \l{Phonon::}{State} enum.

   187 

   188     The \c tick() slot is connected to a \l{Phonon::}{MediaObject} signal which is

   189     emitted when the playback position changes:

   190 

   191     \snippet examples/phonon/qmusicplayer/mainwindow.cpp 11

   192 

   193     The \c time is given in milliseconds.

   194 

   195     When the table is clicked on with the mouse, \c tableClick()

   196     is invoked:

   197 

   198     \snippet examples/phonon/qmusicplayer/mainwindow.cpp 12

   199 

   200     Since we stop the media object, we first check whether it is

   201     currently playing. \c row contains the row in the table that was

   202     clicked upon; the indices of \c sources follows the table, so we

   203     can simply use \c row to find the new source.

   204 

   205     \snippet examples/phonon/qmusicplayer/mainwindow.cpp 13

   206 

   207     When the media source changes, we simply need to select the

   208     corresponding row in the table.

   209 

   210     \snippet examples/phonon/qmusicplayer/mainwindow.cpp 14

   211 

   212     When \c metaStateChanged() is invoked, \c

   213     metaInformationProvider has resolved the meta data for its current

   214     source. A \l{Phonon::}{MediaObject} will do this before

   215     entering \l{Phonon::}{StoppedState}. Note that we could also

   216     have used the \l{Phonon::MediaObject::}{metaDataChanged()} signal for

   217     this purpose.

   218 

   219     Some of the meta data is then chosen to be displayed in the

   220     music table. A file might not contain the meta data requested,

   221     in which case an empty string is returned.

   222 

   223     \snippet examples/phonon/qmusicplayer/mainwindow.cpp 15

   224 

   225     If we have media sources in \c sources of which meta information

   226     is not resolved, we set a new source on the \c

   227     metaInformationProvider, which will invoke \c metaStateChanged()

   228     again.

   229 

   230     We move on to the \c aboutToFinish() slot:

   231 

   232     \snippet examples/phonon/qmusicplayer/mainwindow.cpp 16

   233 

   234     When a file is finished playing, the Music Player will move on and

   235     play the next file in the table. This slot is connected to the

   236     \l{Phonon::}{MediaObject}'s

   237     \l{Phonon::MediaObject::}{aboutToFinish()} signal, which is

   238     guaranteed to be emitted while there is still time to enqueue

   239     another file for playback.

   240 

   241     \section1 The main() function.

   242 

   243     Phonon requires that the application has a name; it is set with

   244     \l{QCoreApplication::}{setApplicationName()}. This is because

   245     D-Bus, which is used by Phonon on Linux systems, demands this.

   246 

   247     \snippet examples/phonon/qmusicplayer/main.cpp 1

   248 */