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