|  | Home · All Classes · Main Classes · Grouped Classes · Modules · Functions |

# Music Player Example

Files:

- phonon/musicplayer/mainwindow.cpp
- phonon/musicplayer/mainwindow.h
- phonon/musicplayer/main.cpp
- phonon/musicplayer/musicplayer.pro

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.

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 MediaObject, which controls the playback, and an 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 overview.

The API of Phonon is implemented through an intermediate technology on each supported platform: DirectSound, DirectShow, 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, `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.

## MainWindow Class Definition

When we include the necessary headers in our header file, we also, for convenience, include the Phonon namespace.

     using namespace Phonon;

     class MainWindow : public QMainWindow
     {

Most of the API in `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 `MainWindow` implementation.

         SeekSlider *seekSlider;
         MediaObject *mediaObject;
         AudioOutput *audioOutput;
         VolumeSlider *volumeSlider;
         QList<MediaSource> sources;

We use the `SeekSlider` to move the current playback position in the media stream, and the `VolumeSlider` controls the sound volume. Both of these widgets come ready made with Phonon.

         void stateChanged(Phonon::State newState, Phonon::State oldState);
         void tick(qint64 time);
         void sourceChanged(const MediaSource &source);
         void tableClicked(int row, int column);

The `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 `MainWindow`. The `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.

## MainWindow Class Implementation

The `MainWindow` class handles both the user interface and Phonon. We will now take a look at the functions that deal with Phonon and their code. The code required for setting up the GUI is explained elsewhere.

We start with the constructor:

     MainWindow::MainWindow()
     {
         audioOutput = new AudioOutput(Phonon::MusicCategory);
         mediaObject = new MediaObject(this);

         mediaObject->setTickInterval(1000);

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 `createPath()` function, which is part of the Phonon namespace.

         createPath(mediaObject, audioOutput);

We also connect signals of the media object to slots in our `MainWindow`. We will examine them shortly.

         setupActions();
         setupMenus();
         setupUi();
         timeLcd->display("00:00");
     }

Finally, we call private helper functions to set up the GUI. The `setupUi()` function contains code for setting up the seek , and volume slider. We move on to `setupUi()`:

     void MainWindow::setupUi()
     {
         ...
         seekSlider = new SeekSlider(this);
         seekSlider->setMediaObject(mediaObject);

         volumeSlider = new VolumeSlider(this);
         volumeSlider->setAudioOutput(audioOutput);

After creating the widgets, they must be supplied with the MediaObject and AudioOutput objects they should control.

In the `setupActions()`, we connect the actions for the play, pause, and stop tool buttons, to slots of the media object.

         connect(playAction, SIGNAL(triggered()), mediaObject, SLOT(play()));
         connect(pauseAction, SIGNAL(triggered()), mediaObject, SLOT(pause()) );
         connect(stopAction, SIGNAL(triggered()), mediaObject, SLOT(stop()));

We move on to the the slots of `MainWindow`, starting with `addFiles()`, which is connected to the table.

         MediaObject metaProvider(this);
         connect(&metaProvider, SIGNAL(stateChanged(Phonon::State, Phonon::State)),
                 this, SLOT(stateChanged(Phonon::State, Phonon::State)));

We create a local media object; meta information in music files are resolved by a `MediaObject`. We connect the object to our `stateChanged()` slot because the object will signal us with Phonon::ErrorState if an error occurs.

         QStringList files = QFileDialog::getOpenFileNames(this,
                             tr("Select Music Files"), ".");

         if (files.isEmpty())
             return;

         foreach (QString string, files) {
             MediaSource source(string);

             metaProvider.setCurrentSource(source);
             metaProvider.pause();

             QMap <QString, QString> metaData = metaProvider.metaData();

             QString title = metaData.value("TITLE");
             if (title == "")
                     title = string;

             QTableWidgetItem *titleItem = new QTableWidgetItem(title);
             titleItem->setFlags(titleItem->flags() ^ Qt::ItemIsEditable);
             QTableWidgetItem *artistItem = new QTableWidgetItem(metaData.value("ARTIST"));
             artistItem->setFlags(artistItem->flags() ^ Qt::ItemIsEditable);
             QTableWidgetItem *albumItem = new QTableWidgetItem(metaData.value("ALBUM"));
             albumItem->setFlags(albumItem->flags() ^ Qt::ItemIsEditable);
             QTableWidgetItem *yearItem = new QTableWidgetItem(metaData.value("DATE"));
             yearItem->setFlags(yearItem->flags() ^ Qt::ItemIsEditable);

We create MediaSources for each file the user has selected and set them on the media object. Note that the media object does not resolve the information when the source is supplied, but after it enters the Phonon::PausedState. We therefore call pause(). The media object will also emit metaDataChanged() after it has resolved the meta data.

After creating QTableWidgetItems with the meta data, we insert the items into the table (we have omitted that code here).

             sources.append(source);
         }
         if (musicTable->selectedItems().isEmpty()) {
                 musicTable->selectRow(0);
                 mediaObject->setCurrentSource(sources.at(0));
                 enqueueFrom(0);
         } else {
             mediaObject->clearQueue();
             enqueueFrom(sources.indexOf(mediaObject->currentSource()));
         }

When the items are added to the table, we need to append the new media source to the `sources` list, which we use to enqueue the sources in the media object and update the table. Finally, we update the media objects' queue. The `enqueueFrom()` function does this for us.

The media object informs us of state changes by sending the `stateChanged()` signal. The `stateChanged()` slot is connected to this signal.

     void MainWindow::stateChanged(Phonon::State newState, Phonon::State /* oldState */)
     {
         switch (newState) {
             case Phonon::ErrorState:
                 if (mediaObject->errorType() == Phonon::FatalError) {
                     QMessageBox::warning(this, tr("Fatal Error"),
                     mediaObject->errorString() + tr("\n\nTerminating Program"));
                     this->close();
                 } else {
                     QMessageBox::warning(this, tr("Error"),
                     mediaObject->errorString());
                 }
                 break;

The errorString() function gives a description of the error that is suitable for users of a Phonon application. The two values of the ErrorState enum helps us determine whether it is possible to try another media source.

             case Phonon::PlayingState:
                     playAction->setEnabled(false);
                     pauseAction->setEnabled(true);
                     stopAction->setEnabled(true);
                     break;
             case Phonon::StoppedState:
                     stopAction->setEnabled(false);
                     playAction->setEnabled(true);
                     pauseAction->setEnabled(false);
                     timeLcd->display("00:00");
                     break;
             case Phonon::PausedState:
                     pauseAction->setEnabled(false);
                     stopAction->setEnabled(true);
                     playAction->setEnabled(true);
                     break;

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 State enum.

The `tick()` slot is connected to a MediaObject signal which is emitted when the playback position changes:

     void MainWindow::tick(qint64 time)
     {
         QTime displayTime(0, (time / 60000) % 60, (time / 1000) % 60);

         timeLcd->display(displayTime.toString("mm:ss"));
     }

The `time` is given in milliseconds.

When the table is clicked on with the mouse, `tableClick()` is invoked:

     void MainWindow::tableClicked(int row, int /* column */)
     {
         bool wasPlaying = mediaObject->state() == Phonon::PlayingState;

         mediaObject->stop();
         mediaObject->clearQueue();

         mediaObject->setCurrentSource(sources[row]);
         enqueueFrom(row);

         if (wasPlaying)
             mediaObject->play();
         else
             mediaObject->stop();
     }

Since we stop the media object, we first check whether it is currently playing. `row` contains the row in the table that was clicked upon; the indices of `sources` follows the table, so we can simply use `row` to find the new source.

     void MainWindow::sourceChanged(const MediaSource &source)
     {
         musicTable->selectRow(sources.indexOf(source));
         timeLcd->display("00:00");
     }

When the media source changes, we simply need to select the corresponding row in the table.

     void MainWindow::enqueueFrom(int row)
     {
         mediaObject->setCurrentSource(sources[row]);
         for (int i = 1; i < sources.size(); ++i) {
             mediaObject->enqueue(sources[(i+row) % sources.size()]);
         }
     }

The `enqueueFrom()` function sets up the media object's queue when the user changes the source, by clicking on the table or adding new files.

## The main() function.

Phonon requires that the application has a name; it is set with setApplicationName(). This is because D-Bus, which is used by Phonon on Linux systems, demands this.

     int main(int argv, char **args)
     {
         QApplication app(argv, args);
         app.setApplicationName("Music Player");
         app.setQuitOnLastWindowClosed(true);

         MainWindow window;
         window.show();

         return app.exec();
     }