diff options
Diffstat (limited to 'doc/src/phonon.qdoc')
| -rw-r--r-- | doc/src/phonon.qdoc | 643 |
1 files changed, 0 insertions, 643 deletions
diff --git a/doc/src/phonon.qdoc b/doc/src/phonon.qdoc deleted file mode 100644 index 611812d..0000000 --- a/doc/src/phonon.qdoc +++ /dev/null @@ -1,643 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** 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 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 and the \l{Phonon Overview} for an introductory tour of its - features. -*/ - -/*! - \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: Nokia Corporation (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 -*/ |