source: trunk/doc/src/frameworks-technologies/phonon.qdoc@ 651

/****************************************************************************
**
** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation ([email protected])
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Nokia.
**
** 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.
**
** 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 have questions regarding the use of this file, please contact
** Nokia at [email protected].
** $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