/****************************************************************************

**

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

** All rights reserved.

** 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 Technology Preview License Agreement accompanying

** this package.

**

** 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.1, included in the file LGPL_EXCEPTION.txt in this package.

**

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

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

**

**

**

**

**

**

**

**

** $QT_END_LICENSE$

**

****************************************************************************/

/*!

    \page phonon-overview.html

    \title Phonon Overview

    \ingroup frameworks-technologies

    \tableofcontents

    \section1 Introduction

    Qt uses the Phonon multimedia framework to provide functionality

    for playback of the most common multimedia formats. The media can

    be read from files or streamed over a network, using a QURL to a

    file.

    In this overview, we take a look at the main concepts of Phonon.

    We also explain the architecture, examine the

    core API classes, and show examples on how to use the classes

    provided.

    \section1 Architecture

    Phonon has three basic concepts: media objects, sinks, and paths.

    A media object manages a media source, for instance, a music file;

    it provides simple playback control, such as starting, stopping,

    and pausing the playback. A sink outputs the media from Phonon,

    e.g., by rendering video on a widget, or by sending audio to a

    sound card. Paths are used to connect Phonon objects, i.e., a

    media object and a sink, in a graph - called a media graph in

    Phonon.

    As an example, we show a media graph for an audio stream:

    \image conceptaudio.png

    The playback is started and managed by the media object, which

    send the media stream to any sinks connected to it by a path. The

    sink then plays the stream back, usually though a sound card.

    \omit Not sure if this goes here, or anywhere...

    All nodes in the graph are synchronized by the framework,

    meaning that if more than one sink is connected to the same

    media object, the framework will handle the synchronization

    between the sinks; this happens for instance when a media

    source containing video with sound is played back. More on

    this later.

    \endomit

    \section2 Media Objects

    The media object, an instance of the \l{Phonon::}{MediaObject}

    class, lets you start, pause, and stop the playback of a media

    stream, i.e., it provided basic control over the playback. You may

    think of the object as a simple media player.

    The media data is provided by a media source, which is

    kept by the media object. The media source is a separate

    object - an instance of \l{Phonon::}{MediaSource} - in Phonon, and

    not part of the graph itself. The source will supply the media

    object with raw data. The data can be read from files and streamed

    over a network. The contents of the source will be interpreted by

    the media object.

    A media object is always instantiated with the default constructor

    and then supplied with a media source. Concrete code examples are

    given later in this overview.

    As a complement to the media object, Phonon also provides

    \l{Phonon::}{MediaController}, which provides control over

    features that are optional for a given media. For instance, for

    chapters, menus, and titles of a VOB (DVD) file will be features

    managed by a \l{Phonon::}{MediaController}.

    \section2 Sinks

    A sink is a node that can output media from the graph, i.e., it

    does not send its output to other nodes. A sink is usually a

    rendering device.

    The input of sinks in a Phonon media graph comes from a

    \l{Phonon::}{MediaObject}, though it might have been processed

    through other nodes on the way.

    While the \l{Phonon::}{MediaObject} controls the playback, the

    sink has basic controls for manipulation of the media. With an

    audio sink, for instance, you can control the volume and mute the

    sound, i.e., it represents a virtual audio device. Another example

    is the \l{Phonon::}{VideoWidget}, which can render video on a

    QWidget and alter the brightness, hue, and scaling of the video.

    As an example we give an image of a graph used for playing back a

    video file with sound.

    \image conceptvideo.png

    \section2 Processors

    Phonon does not allow manipulation of media streams directly,

    i.e., one cannot alter a media stream's bytes programmatically

    after they have been given to a media object. We have other nodes

    to help with this: processors, which are placed in the graph on

    the path somewhere between the media object and its sinks. In

    Phonon, processors are of the \l{Phonon::}{Effect} class.

    When inserted into the rendering process, the  processor will

    alter the media stream, and will be active as long as it is part

    of the graph. To stop, it needs to be removed.

    \omit \image conceptprocessor.png \endomit

    The \c {Effect}s may also have controls that affect how the media

    stream is manipulated. A processor applying a depth effect to

    audio, for instance, can have a value controlling the amount of

    depth. An \c Effect can be configured at any point in time.

    \section1 Playback

    In some common cases, it is not necessary to build a graph

    yourself.

    Phonon has convenience functions for building common graphs. For

    playing an audio file, you can use the

    \l{Phonon::}{createPlayer()} function. This will set up the

    necessary graph and return the media object node; the sound can

    then be started by calling its \l{Phonon::MediaObject::}{play()}

    function.

    \snippet snippets/phonon.cpp 0

    We have a similar solution for playing video files, the

    \l{Phonon::}{VideoPlayer}.

    \snippet snippets/phonon.cpp 1

    The VideoPlayer is a widget onto which the video will be drawn. 

    The \c .pro file for a project needs the following line to be added:

    \snippet doc/src/snippets/code/doc_src_phonon.qdoc 0

    Phonon comes with several widgets that provide functionality

    commonly associated with multimedia players - notably SeekSlider

    for controlling the position of the stream, VolumeSlider for

    controlling sound volume, and EffectWidget for controlling the

    parameters of an effect. You can learn about them in the API

    documentation.

    \section1 Building Graphs

    If you need more freedom than the convenience functions described

    in the previous section offers you, you can build the graphs

    yourself. We will now take a look at how some common graphs are

    built. Starting a graph up is a matter of calling the

    \l{Phonon::MediaObject::}{play()} function of the media object.

    If the media source contains several types of media, for instance, a

    stream with both video and audio, the graph will contain two

    output nodes: one for the video and one for the audio. 

    We will now look at the code required to build the graphs discussed

    previously in the \l{Architecture} section. 

    \section2 Audio

    When playing back audio, you create the media object and connect

    it to an audio output node - a node that inherits from

    AbstractAudioOutput. Currently, AudioOutput, which outputs audio

    to the sound card, is provided.

    The code to create the graph is straight forward:

    \snippet snippets/phonon.cpp 2

    Notice that the type of media an input source has is resolved by

    Phonon, so you need not be concerned with this. If a source

    contains multiple media formats, this is also handled

    automatically.

    The media object is always created using the default constructor

    since it handles all multimedia formats.

    The setting of a Category, Phonon::MusicCategory in this case,

    does not affect the actual playback; the category can be used by

    KDE to control the playback through, for instance, the control

    panel.

    \omit Not sure about this

    Users of KDE can often also choose to send sound with the

    CommunicationCategory, e.g., given to VoIP, to their headset,

    while sound with MusicCategory is sent to the sound card.

    \endomit

    The AudioOutput class outputs the audio media to a sound card,

    that is, one of the audio devices of the operating system. An

    audio device can be a sound card or a intermediate technology,

    such as \c DirectShow on windows. A default device will be chosen

    if one is not set with \l{Phonon::AudioOutput::}{setOutputDevice()}.

    The AudioOutput node will work with all audio formats supported by

    the back end, so you don't need to know what format a specific

    media source has.

    For a an extensive example of audio playback, see the \l{Music

    Player Example}{Phonon Music Player}.

    \section3 Audio Effects

    Since a media stream cannot be manipulated directly, the backend

    can produce nodes that can process the media streams. These nodes

    are inserted into the graph between a media object and an output

    node.

    Nodes that process media streams inherit from the Effect class.

    The effects available depends on the underlying system. Most of

    these effects will be supported by Phonon. See the \l{Querying

    Backends for Support} section for information on how to resolve

    the available effects on a particular system.

    We will now continue the example from above using the Path

    variable \c path to add an effect. The code is again trivial:

    \snippet snippets/phonon.cpp 3

    Here we simply take the first available effect on the system.

    The effect will start immediately after being inserted into the

    graph if the media object is playing. To stop it, you have to

    detach it again using \l{Phonon::Path::}{removeEffect()} of the Path.

    \section2 Video

    For playing video, VideoWidget is provided. This class functions

    both as a node in the graph and as a widget upon which it draws

    the video stream. The widget will automatically choose an available

    device for playing the video, which is usually a technology

    between the Qt application and the graphics card, such as \c

    DirectShow on Windows.

    The video widget does not play the audio (if any) in the media

    stream. If you want to play the audio as well, you will need

    an AudioOutput node. You create and connect it to the graph as

    shown in the previous section.

    The code for creating this graph is given below, after which

    one can play the video with \l{Phonon::MediaObject::}{play()}.

    \snippet snippets/phonon.cpp 4

    The VideoWidget does not need to be set to a Category, it is

    automatically classified to \l{Phonon::}{VideoCategory}, we only

    need to assure that the audio is also classified in the same

    category.

    The media object will split files with different media content

    into separate streams before sending them off to other nodes in

    the graph. It is the media object that determines the type of

    content appropriate for nodes that connect to it.

    \omit This section is from the future

    \section2 Multiple Audio Sources and Graph Outputs

    In this section, we take a look at a graph that contains multiple

    audio sources in addition to video. We have a video camera with

    some embarrassing home footage from last weekend's party, a

    microphone with which we intend to add commentary, and an audio

    music file to set the correct mood. It would be an advantage to

    write the graph output to a file for later viewing, but since this

    is not yet supported by Qt backends, we will play it back

    directly.

    <image of party graph>

    <code>

    <code walkthrough>

    \endomit

    \section1 Backends

    The multimedia functionality is not implemented by Phonon itself,

    but by a back end - often also referred to as an engine. This

    includes connecting to, managing, and driving the underlying

    hardware or intermediate technology. For the programmer, this

    implies that the media nodes, e.g., media objects, processors, and

    sinks, are produced by the back end. Also, it is responsible for

    building the graph, i.e., connecting the nodes.

    The backends of Qt use the media systems DirectShow (which

    requires DirectX) on Windows, QuickTime on Mac, and GStreamer on

    Linux. The functionality provided on the different platforms are

    dependent on these underlying systems and may vary somewhat, e.g.,

    in the media formats supported.

    Backends expose information about the underlying system. It can

    tell which media formats are supported, e.g., \c AVI, \c mp3, or

    \c OGG.

    A user can often add support for new formats and filters to the

    underlying system, by, for instance, installing the DivX codex. We

    can therefore not give an exact overview of which formats are

    available with the Qt backends.

    \omit Not sure I want a separate section for this

    \section2 Communication with the Backends

    We cooperate with backends through static functions in the

    Phonon namespace. We have already seen some of these functions

    in code examples. Their two main responsibilities are creating

    graph nodes and supplying information about the capabilities

    of the various nodes. The nodes uses the backend internally

    when created, so it is only connecting them in the graph that

    you need to use the backend directly.

    The main functions for graph building are:

    \list

        \o createPath(): This function creates a path between to

                         nodes, which it takes as arguments.

        \o 

    \endlist

    For more detailed information, please consult the API

    documentation.

    \endomit

    \section2 Querying Backends for Support

    As mentioned, Phonon depends on the backend to provide its

    functionality. Depending on the individual backend, full support

    of the API may not be in place. Applications therefore need to

    check with the backend if functionality they require is

    implemented. In this section, we take look at how this is done.

    The backend provides the

    \l{Phonon::BackendCapabilities::}{availableMimeTypes()} and

    \l{Phonon::BackendCapabilities::}{isMimeTypeAvailable()} functions

    to query which MIME types the backend can produce nodes for. The

    types are listed as strings, which for any type is equal for any

    backend or platform.

    The backend will emit a signal -

    \l{Phonon::BackendCapabilities::}{Notifier::capabilitiesChanged()}

    - if its abilities have changed. If the available audio devices

    have changed, the

    \l{Phonon::BackendCapabilities::}{Notifier::availableAudioOutputDevicesChanged()}

    signal is emitted instead.

    To query the actual audio devices possible, we have the

    \l{Phonon::BackendCapabilities::}{availableAudioOutputDevices()} as

    mentioned in the \l{#Sinks}{Sinks} section. To query information

    about the individual devices, you can examine its \c name(); this

    string is dependent on the operating system, and the Qt backends

    does not analyze the devices further.

    The sink for playback of video does not have a selection of

    devices. For convenience, the \l{Phonon::}{VideoWidget} is both a

    node in the graph and a widget on which the video output is

    rendered. To query the various video formats available, use

    \l{Phonon::BackendCapabilities::}{isMimeTypeAvailable()}.  To add

    it to a path, you can use the Phonon::createPath() as usual. After

    creating a media object, it is also possible to call its

    \l{Phonon::MediaObject::}{hasVideo()} function.

    See also the \l{Capabilities Example}.

    \section1 Installing Phonon

    When running the Qt configure script, you will be notified whether

    Phonon support is available on your system. As mentioned

    previously, to use develop and run Phonon applications, you also

    need to link to a backend, which provides the multimedia

    functionality.

    Note that Phonon applications will compile and run without a

    working backend, but will, of course, not work as expected.

    The following sections explains requirements for each backend.

    \section2 Windows

    On Windows, building Phonon requires DirectX and DirectShow

    version 9 or higher. You'll need additional SDKs you can download

    from Microsoft.

    \section3 Windows XP and later Windows versions

    If you develop for Windows XP and up, you should download the Windows SDK

    \l{http://www.microsoft.com/downloads/details.aspx?FamilyID=e6e1c3df-a74f-4207-8586-711ebe331cdc&DisplayLang=en}{here}.

    Before building Qt, just call the script: \c {C:\Program Files\Microsoft SDKs\Windows\v6.1\Bin\setenv.cmd}

    \note Visual C++ 2008 already contains the Windows SDK and doesn't

    need that package and has already the environment set up for a

    smooth compilation of phonon.

    \section3 Earlier Windows versions than Windows XP

    If you want to support previous Windows versions, you should download and install the Platform SDK. You find it

    \l{http://www.microsoft.com/downloads/details.aspx?FamilyId=0BAF2B35-C656-4969-ACE8-E4C0C0716ADB&displaylang=en}{here}.

    \note The platform SDK provided with Visual C++ is not

    complete and

    you'll need this one to have DirectShow 9.0 support. You can download the DirectX SDK

    \l{http://www.microsoft.com/downloads/details.aspx?familyid=09F7578C-24AA-4E0A-BF91-5FEC24C8C7BF&displaylang=en}{here}.

    \section3 Setting up the environment

    Once the SDKs are installed, please make sure to set your

    environment variables LIB and INCLUDE correctly. The paths to the

    include and lib directory of the SDKs should appear first.

    Typically, to setup your environment, you would execute the

    following script:

    \code

        Set DXSDK_DIR=C:\Program Files\Microsoft DirectX SDK (February 2007)

        %DXSDK_DIR%\utilities\bin\dx_setenv.cmd

        C:\program files\Microsoft Platform SDK\setenv.cmd

    \endcode

    If your environment is setup correctly, executing configure.exe on

    your Qt installation should automatically activate Phonon.

    \warning The MinGW version of Qt does not support building the

             Qt backend.

    \section2 Linux

    The Qt backend on Linux uses GStreamer (minimum version is 0.10),

    which must be installed on the system. At a minimum, you need the

    GStreamer library and base plugins, which provides support for \c

    .ogg files. The package names may vary between Linux

    distributions; on Mandriva, they have the following names:

    \table

        \header

            \o Package

            \o Description

        \row

            \o libgstreamer0.10_0.10

            \o The GStreamer base library.

        \row

            \o libgstreamer0.10_0.10-devel

            \o Contains files for developing applications with

               GStreamer.

        \row

            \o libgstreamer-plugins-base0.10

            \o Contains the basic plugins for audio and video

               playback, and will enable support for \c ogg files.

        \row

            \o libgstreamer-plugins-base0.10-devel

            \o Makes it possible to develop applications using the

               base plugins.

    \endtable

    \omit Should go in troubleshooting (in for example README)

    alsasink backend for GStreamer

    \table

        \header

            \o Variable

            \o Description

        \row

            \o PHONON_GST_AUDIOSINK

            \o Sets the audio sink to be used. Possible values are

               ... alsasink.

        \row

            \o PHONON_GSTREAMER_DRIVER

            \o Sets the driver for GStreamer. This driver will

               usually be configured automatically when

               installing.

        \row

            \o PHONON_GST_VIDEOWIDGET

            \o This variable can be set to the name of a widget to

               use as the video widget??

        \row

            \o PHONON_GST_DEBUG

            \o Phonon will give debug information while running if

               this variable is set to a number between 1 and 3.

        \row

            \o PHONON_TESTURL

            \o ...

    \endtable

    \endomit

    \section2 Mac OS X

    On Mac OS X, Qt uses QuickTime for its backend. The minimum