FCL/sf/mw/qt: comparison doc/src/frameworks-technologies/phonon.qdoc

equal deleted inserted replaced

-:41300fa6a67c
+:f7bc934e204c
+/****************************************************************************
+**
+** 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&amp;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&amp;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&amp;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
+supported version is 7.0.
+\section1 Deploying Phonon Applications on Windows and Mac OS X
+On Windows and Mac OS X, the Qt backend makes use of the
+\l{QtOpenGL Module}{QtOpenGL} module. You therefore need to deploy
+the QtOpenGL shared library. If this is not what you want, it is
+possible to configure Qt without OpenGL support. In that case, you
+need to run \c configure with the \c -no-opengl option.
+\section1 Work in Progress
+Phonon and its Qt backends, though fully functional for
+multimedia playback, are still under development. Functionality to
+come is the possibility to capture media and more processors for
+both music and video files.
+Another important consideration is to implement support for
+storing media to files; i.e., not playing back media directly.
+We also hope in the future to be able to support direct
+manipulation of media streams. This will give the programmer more
+freedom to manipulate streams than just through processors.
+Currently, the multimedia framework supports one input source. It will be
+possible to include several sources. This is useful in, for example, audio
+mixer applications where several audio sources can be sent, processed and
+output as a single audio stream.
+*/