diff options
Diffstat (limited to 'doc/src/phonon.qdoc')
| -rw-r--r-- | doc/src/phonon.qdoc | 642 |
1 files changed, 642 insertions, 0 deletions
diff --git a/doc/src/phonon.qdoc b/doc/src/phonon.qdoc new file mode 100644 index 0000000..e86ccf6 --- /dev/null +++ b/doc/src/phonon.qdoc @@ -0,0 +1,642 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (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 either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** 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.0, 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 are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page phonon-overview.html + \title Phonon Overview + \ingroup multimedia + + \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 + 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. +*/ + +/*! + \namespace Phonon + \brief The Phonon namespace contains classes and functions for multimedia applications. + \since 4.4 + + This namespace contains classes to access multimedia functions for + audio and video playback. Those classes are not dependent on any specific + framework, but rather use exchangeable backends to do the work. + + See the \l{Phonon Module} page for general information about the + framework. +*/ + +/*! + \page phonon-module.html + \module Phonon + \title Phonon Module + \contentspage Qt's Modules + \previouspage QtXmlPatterns + \nextpage Qt3Support + \ingroup modules + + \brief The Phonon module contains namespaces and classes for multimedia functionality. + + \generatelist{classesbymodule Phonon} + + Phonon is a cross-platform multimedia framework that enables the use of + audio and video content in Qt applications. The \l{Phonon Overview} + document provides an introduction to the architecture and features included + in Phonon. The \l{Phonon} namespace contains a list of all classes, functions + and namespaces provided by the module. + + Applications that use Phonon's classes need to + be configured to be built against the Phonon module. + The following declaration in a \c qmake project file ensures that + an application is compiled and linked appropriately: + + \snippet doc/src/snippets/code/doc_src_phonon.qdoc 1 + + The Phonon module is part of the \l{Qt Full Framework Edition} and the + \l{Open Source Versions of Qt}. + + \section1 Qt Backends + + Qt Backends are currently developed for Phonon version 4.1. The Phonon + project has moved on and introduced new features that the Qt Backends do not + implement. We have chosen not to document the part of Phonon that we do not + support. Any class or function not appearing in our documentation can be + considered unsupported. + + \section1 License Information + + Qt Commercial Edition licensees that wish to distribute applications that + use the Phonon module need to be aware of their obligations under the + GNU Lesser General Public License (LGPL). + + Developers using the Open Source Edition can choose to redistribute + the module under the appropriate version of the GNU LGPL; version 2.1 + for applications and libraries licensed under the GNU GPL version 2, + or version 3 for applications and libraries licensed under the GNU + GPL version 2. + + \legalese + This file is part of the KDE project + + Copyright (C) 2005-2007 Matthias Kretz <kretz@kde.org> \BR + Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). + Contact: Qt Software Information (qt-info@nokia.com) + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Library General Public + License version 2 as published by the Free Software Foundation. + + This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Library General Public License for more details. + + You should have received a copy of the GNU Library General Public License + along with this library; see the file COPYING.LIB. If not, write to + the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, + Boston, MA 02110-1301, USA. + \endlegalese +*/ |