phonon/Mainpage.dox

   1 /** \file Mainpage.dox
   2     \brief Mainpage of the %Phonon API Documentation.
   3 */
   4 /** \mainpage The Phonon API.
   5
   6 \section phonon_intro Introduction
   7 %Phonon is the Multimedia API for %KDE. You should evaluate whether %Phonon
   8 supplies all you need before looking at frameworks like GStreamer, NMM or Helix.
   9 The range of applications goes from full featured media players and capture
  10 applications to voice/video chats.
  11
  12 \section phonon_overview A Basic Overview
  13 In %Phonon there are two main concepts: MediaProducers and Outputs. They can be
  14 connected using Path objects which also allow the insertion of Effect objects
  15 between producer and output.
  16
  17 \section phonon_tutorial Tutorial
  18 \li \ref phonon_tut1 "a simple audio player"
  19 \li \ref phonon_tut2 "add a playlist"
  20 \li \ref phonon_tut3 "crossfades"
  21 \li \ref phonon_tut4 "show videos"
  22
  23 \section phonon_frontend The Frontend API
  24 \li for simple playback use \ref Phonon::AudioPlayer
  25 \li add ref to overview of frontend objects
  26 \li \ref Phonon "The Phonon namespace"
  27 \li \ref Phonon::MediaObject "The central class for playback functionality (MediaObject)"
  28
  29 \section phonon_backend_development Backend Development
  30 If you want to write a new backend for %Phonon this is for you:
  31 \li \ref phonon_backend_development_page "Phonon Backend Development"
  32
  33
  34
  35
  36
  37
  38
  39
  40
  41
  42
  43
  44
  45
  46 \page phonon_tut1 Phonon Tutorial Part 1: a simple audio player
  47 \code
  48 class Player : public QObject
  49 {
  50   Q_OBJECT
  51   public:
  52     Player( QObject* parent );
  53     void play( const KUrl& url );
  54
  55   private:
  56     Phonon::MediaObject* m_media;
  57     Phonon::AudioPath*   m_audioPath;
  58     Phonon::AudioOutput* m_audioOutput;
  59 };
  60
  61 Player::Player( QObject* parent )
  62   : QObject( parent )
  63   , m_media( new Phonon::MediaObject( this ) )
  64   , m_audioPath( new Phonon::AudioPath( this ) )
  65   , m_audioOutput( new Phonon::AudioOutput( this ) )
  66 {
  67   m_audioOutput->setCategory( Phonon::MusicCategory );
  68   m_media->addAudioPath( m_audioPath );
  69   m_audioPath->addOutput( m_audioOutput );
  70 }
  71
  72 void Player::play( const KUrl& url )
  73 {
  74   m_media->setUrl( url );
  75   m_media->play();
  76 }
  77 \endcode
  78
  79
  80
  81
  82
  83
  84
  85
  86 \page phonon_backend_development_page Phonon Backend Development
  87 The backend is the most important part in %Phonon to provide functionality. This
  88 document will get you started how backends work, how to start development of a
  89 new backend and how to understand existing backend code.
  90
  91 \section phonon_backend_introduction Introduction
  92
  93 The first step is to understand how the %Phonon frontend calls the backend: In
  94 the frontend objects all backend objects are "only" QObjects. But QObject has
  95 powerful introspection capabilities that %Phonon uses to call methods in the
  96 backend. If you're interested look at \ref QMetaObject::invokeMethod. In order
  97 to make sure that a backend is fully operational (there are no abstract classes
  98 that tell the backend developer what method signatures are wrong or what
  99 methods are missing) there are two test programs compiled with kdelibs (if
 100 KDE4_BUILD_TESTS is set in cmake) that inspects the backend.
 101
 102 In short that requires the backend classes to inherit from QObject and to make
 103 all methods that are to be called from the frontend slots or prefixed with
 104 Q_INVOKABLE (the latter doesn't work reliable with Qt 4.1.3 at least, so you
 105 should simply make those methods slots).
 106
 107 \section phonon_backend_classes The Backend Classes
 108
 109 The central class that needs to be implemented is the backend factory class,
 110 throughout this documentation simply called Backend:
 111
 112 \li \ref phonon_Backend "Backend"
 113
 114 \subsection phonon_mediaproducingclasses The classes producing media data (sources)
 115
 116 \li \ref Phonon::MediaProducerInterface "common methods/signals for media producing classes"
 117 \li \ref phonon_AvCapture "AvCapture"
 118 \li \ref phonon_ByteStream "ByteStream"
 119 \li \ref phonon_MediaObject "MediaObject"
 120
 121 \subsection phonon_pathclasses The path classes
 122
 123 \li \ref phonon_AudioPath "AudioPath"
 124 \li \ref phonon_VideoPath "VideoPath"
 125
 126 \subsection phonon_outputclasses The output classes
 127 \li \ref phonon_AudioDataOutput "AudioDataOutput"
 128 \li \ref phonon_AudioOutput "AudioOutput"
 129 \li \ref phonon_VideoDataOutput "VideoDataOutput"
 130 \li \ref phonon_VideoWidget "VideoWidget"
 131
 132 \subsection phonon_EffectClasses The effect classes
 133
 134 \li \ref phonon_AudioEffect "AudioEffect"
 135 \li \ref phonon_BrightnessControl "BrightnessControl"
 136 \li \ref phonon_VideoEffect "VideoEffect"
 137 \li \ref phonon_Visualization "Visualization"
 138 \li \ref phonon_VolumeFaderEffect "VolumeFaderEffect"
 139
 140
 141 */
 142 // DOXYGEN_REFERENCES = kdecore kdeui kio
 143 // DOXYGEN_SET_EXPAND_AS_DEFINED = PHONON_OBJECT PHONON_HEIR
 144 // DOXYGEN_SET_HIDE_SCOPE_NAMES = YES
 145 // DOXYGEN_SET_HIDE_FRIEND_COMPOUNDS = YES
 146 // DOXYGEN_SET_PROJECT_NAME = Phonon
 147 // DOXYGEN_SET_EXCLUDE += kcm DESIGN
 148 // vim: tw=80