Capabilities Example

Files:

• phonon/capabilities/window.cpp
• phonon/capabilities/window.h
• phonon/capabilities/main.cpp
• phonon/capabilities/capabilities.pro

The Backend Capabilities example shows how to check which MIME types, audio devices, and audio effects are available.

Phonon does not implement the multimedia functionality itself, but relies on a backend to manage this. The backends do not manage the hardware directly, but use intermediate technologies: QuickTime on Mac, GStreamer on Linux, and DirectShow (which requires DirectX) on Windows.

The user may add support for new MIME types and effects to these systems, and the systems abilities may also be different. The support for multimedia MIME types, and audio effects in Phonon will therefore vary from system to system.

Backends informs the programmer about current capabilities through an implementation of the Phonon::BackendCapabilities namespace. The backend reports which MIME types can be played back, which audio effects are available, and which sound devices are available on the system. When the capabilities of a backend changes, it will emit the capabilitiesChanged() signal.

The example consists of one class, Window, which displays capabilities information from the current backend used by Phonon.

See the Phonon Overview for a high-level introduction to Phonon.

Window Class Definition

The Window class queries the Phonon backend for its capabilities. The results are presented in a GUI consisting of standard Qt widgets. We will now take a tour of the Phonon related parts of both the definition and implementation of the Window class.

 private slots:
     void updateWidgets();

 private:
     void setupUi();
     void setupBackendBox();

     QGroupBox *backendBox;

     QLabel *devicesLabel;
     QLabel *mimeTypesLabel;
     QLabel *effectsLabel;

     QListWidget *mimeListWidget;
     QListView *devicesListView;
     QTreeWidget *effectsTreeWidget;

We need the slot to notice changes in the backends capabilities.

mimeListWidget and devicesListView lists MIME types and audio devices. The effectsTreeWidget lists audio effects, and expands to show their parameters.

The setupUi() and setupBackendBox() private utility functions create the widgets and lays them out. We skip these functions while discussing the implementation because they do not contain Phonon relevant code.

Window Class Implementation

Our examination starts with a look at the constructor:

 Window::Window()
 {
     setupUi();
     updateWidgets();

     connect(Phonon::BackendCapabilities::notifier(),
             SIGNAL(capabilitiesChanged()), this, SLOT(updateWidgets()));
     connect(Phonon::BackendCapabilities::notifier(),
             SIGNAL(availableAudioOutputDevicesChanged()), SLOT(updateWidgets()));
 }

After creating the user interface, we call updateWidgets(), which will fill the widgets with the information we get from the backend. We then connect the slot to the capabilitiesChanged() and availableAudioOutputDevicesChanged() signals in case the backend's abilities changes while the example is running. The signal is emitted by a Phonon::BackendCapabilities::Notifier object, which listens for changes in the backend.

In the updateWidgets() function, we query the backend for information it has about its abilities and present it in the GUI of Window. We dissect it here:

 void Window::updateWidgets()
 {
     devicesListView->setModel(new QStandardItemModel());
     Phonon::ObjectDescriptionModel<Phonon::AudioOutputDeviceType> *model =
             new Phonon::ObjectDescriptionModel<Phonon::AudioOutputDeviceType>();
     model->setModelData(Phonon::BackendCapabilities::availableAudioOutputDevices());
     devicesListView->setModel(model);

The availableAudioOutputDevicesChanged() function is a member of the Phonon::BackendCapabilities namespace. It returns a list of AudioOutputDevices, which gives us information about a particular device, e.g., a sound card or a USB headset.

Note that AudioOutputDevice and also EffectDescription, which is described shortly, are typedefs of ObjectDescriptionType.

     mimeListWidget->clear();
     QStringList mimeTypes =
             Phonon::BackendCapabilities::availableMimeTypes();
     foreach (QString mimeType, mimeTypes) {
         QListWidgetItem *item = new QListWidgetItem(mimeListWidget);
         item->setText(mimeType);
     }

The MIME types supported are given as strings in a QStringList. We can therefore create a list widget item with the string, and append it to the mimeListWidget, which displays the available MIME types.

     effectsTreeWidget->clear();
     QList<Phonon::EffectDescription> effects =
         Phonon::BackendCapabilities::availableAudioEffects();
     foreach (Phonon::EffectDescription effect, effects) {
         QTreeWidgetItem *item = new QTreeWidgetItem(effectsTreeWidget);
         item->setText(0, tr("Effect"));
         item->setText(1, effect.name());
         item->setText(2, effect.description());

As before we add the description and name to our widget, which in this case is a QTreeWidget. A particular effect may also have parameters, which are inserted in the tree as child nodes of their effect.

         Phonon::Effect *instance = new Phonon::Effect(effect, this);
         QList<Phonon::EffectParameter> parameters = instance->parameters();
         for (int i = 0; i < parameters.size(); ++i) {
                 Phonon::EffectParameter parameter = parameters.at(i);

             QVariant defaultValue = parameter.defaultValue();
             QVariant minimumValue = parameter.minimumValue();
             QVariant maximumValue = parameter.maximumValue();

             QString valueString = QString("%1 / %2 / %3")
                     .arg(defaultValue.toString()).arg(minimumValue.toString())
                     .arg(maximumValue.toString());

             QTreeWidgetItem *parameterItem = new QTreeWidgetItem(item);
             parameterItem->setText(0, tr("Parameter"));
             parameterItem->setText(1, parameter.name());
             parameterItem->setText(2, parameter.description());
             parameterItem->setText(3, QVariant::typeToName(parameter.type()));
             parameterItem->setText(4, valueString);
         }
     }

The parameters are only accessible through an instance of the Effect class. Notice that an effect is created with the effect description.

The EffectParameter contains information about one of an effects parameters. We pick out some of the information to describe the parameter in the tree widget.

The main() function

Because Phonon uses D-Bus on Linux, it is necessary to give the application a name. You do this with setApplicationName().

 int main(int argv, char **args)
 {
     QApplication app(argv, args);
     app.setApplicationName("Phonon Capabilities Example");

     Window window;
     window.show();

     return app.exec();
 }