source: trunk/doc/src/phonon-api.qdoc@ 321

/*
    This file is part of the KDE project
    Copyright (C) 2005-2007 Matthias Kretz <[email protected]>
    Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
   Contact: Qt Software Information ([email protected])

    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.
*/


/*!
    \enum Phonon::DiscType
    Enum to identify the media discs supported by MediaObject.

    \value NoDisc
    No disc was selected. This is only useful as a return value from
    MediaSource::diskType().
    \value Cd Identifies Audio CDs.
    \value Dvd Identifies DVDs (not arbitrary data DVDs, only movie DVDs).
    \value Vcd Identifies Video CDs.

    \sa MediaSource, MediaObject
*/

/*!
    \enum Phonon::MetaData

    Provided as keys for Phonon::MediaObject::metaData(). The enum
    values matches strings defined in the Ogg Vorbis specification

    \value ArtistMetaData
    \value AlbumMetaData
    \value TitleMetaData
    \value DateMetaData
    \value GenreMetaData
    \value TracknumberMetaData
    \value DescriptionMetaData
    \value MusicBrainzDiscIdMetaData
*/

/*!
    \enum Phonon::State
    \since 4.4

    The state enum describes the different states a media object can
    take. Several functions of \l{Phonon::}{MediaObject} are
    asynchronous, so even if a you have requested a state change
    through a function call, e.g., through
    \l{Phonon::MediaObject::}{play()}, you cannot be sure that the
    change has taken place before you receive the
    \l{Phonon::MediaObject::}{stateChanged()} signal. 

    A media object can at any time change into any state, regardless
    of the state it previously had. \omit In the
    \l{Phonon::}{MediaObject} class description explains the typical
    state changes in the life of a media object. \endomit

    \value LoadingState
    After construction it might take a while before the media object
    is ready to \l{Phonon::MediaObject::}{play()}. This state is
    commonly used by backends to initialize the \l{Phonon
    Overview}{media graph} and loading the source. When
    the object leaves the loading state, it will enter the
    StoppedState unless an error occurred or another state is
    requested through a function call, e.g.,
    \l{Phonon::}{MediaObject::play()}.

    \value StoppedState
    In the stopped state, the media object is ready to play its
    current media source. The current
    \l{MediaObject::seek()}{position} in the media stream is then 0.

    \value PlayingState
    The media object is playing back its media source.

    \value BufferingState
    The Player is waiting for data to be able to start or continue
    playing. This state is commonly used to wait for media data over a
    network connection.

    \value PausedState
    The media player has currently paused its playback, i.e., it
    stops playing but keeps the current playback position in the
    stream.

    \value ErrorState
    When a media object enters the error state a problem with the
    playback has occurred. The possible errors are grouped into
    two categories by Phonon::ErrorType, and the type can be
    queried through \l{Phonon::MediaObject::}{errorType()}. A
    \l{Phonon::}{FatalError} implies that the playback
    cannot continue, but one can still try with a new media
    source. With a \l{Phonon::}{NormalError} it might
    be possible to continue playback, and a media object may
    therefore change state from the ErrorState.

    \sa MediaObject
*/

/*!
    \enum Phonon::Category

    Sets the category your program should be listed in in the mixer.

    \value NoCategory
    Will make use of the default device.
    \value NotificationCategory
    If the sounds produced are notifications (ping, beep and such) you
    should use this category.
    \value MusicCategory
    If your application is a music player (like a jukebox or media player
    playing an audio file).
    \value VideoCategory
    If the sound is the audio channel of a video.
    \value CommunicationCategory
    If your applications produces sounds from communication with somebody
    else (VoIP, voice chat).
    \value GameCategory
    Sound produced by a computer game should go into this category.
    \value AccessibilityCategory
    Sounds produced for accessibility (e.g., Text-To-Speech)
    \omitvalue LastCategory
    Holds the largest value of categories.
    \omitvalue AccessibilityCategory

    A Jukebox will set this to Music, a VoIP program to Communication, a
    DVD player to video, and so on.

    \note These categories can also become useful for an application that
    controls the volumes automatically, like turning down the music when a call
    comes in, or turning down the notifications when the media player knows
    it's playing classical music.
*/

/*!
    \enum Phonon::ErrorType

    This enum describes the severity when an error has occurred during
    playback.

    After a media object has entered the \l{Phonon::}{ErrorState}, one
    can query the type of error from
    \l{Phonon::}{MediaObject::errorType()}. Note that you should query
    the error when receiving the
    \l{Phonon::}{MediaObject::stateChanged()} signal, because the
    error type will be lost if the media object leaves the error
    state.    

    \value NoError No error. MediaObject::errorType() returns this if
    MediaObject::state() != Phonon::ErrorState.

    \value NormalError An error has occurred with the playback of the current
    source. It might be possible to continue playback, for instance, if only the
    audio stream in a video cannot be played back. The media object will then
    leave the error state again.

    \value FatalError. Something important does not work. Your program cannot continue
    the playback of the current source, but it might be possible to try another.

    \sa MediaObject::errorType()
*/

/*!
    \fn QString Phonon::categoryToString(Category c)

    Returns a (translated) string to show to the user identifying the given
    Category (\a c).
*/

/*!
    \enum Phonon::ObjectDescriptionType
    \relates Phonon::ObjectDescription

    This enum defines the type of information that is contained in a
    \l{Phonon::}{ObjectDescription} object.

    \value AudioOutputDeviceType An audio output device (\l{Phonon::}{AudioOutputDevice}).
    This can be soundcards (with different drivers),
    sound servers, or other virtual outputs like playback on a different
    computer on the network.

    \value EffectType An audio effect (\l{Phonon::}{EffectDescription}).
    \omitvalue SubtitleType 
    \omitvalue AudioCaptureDeviceType 
    \omitvalue AudioChannelType 
*/

/*!
    \typedef Phonon::AudioOutputDevice
    \relates Phonon::ObjectDescription    

    This typedef of \l{Phonon::}{ObjectDescription} describes an audio output
    device, such as soundcards (with different drivers), sound servers, or other
    virtual outputs like playback on a different computer on the network.

    \omit
    For Hardware devices the backend should use libkaudiodevicelist
    (AudioDevice and AudioDeviceEnumerator) which will list removable
    devices even when they are unplugged and provide a unique identifier
    that can make backends use the same identifiers.
    \endomit

    A list of available devices is given by the backend with
    Backendcapabilities::availableAudioOutputDevices()

    \snippet doc/src/snippets/phononobjectdescription.cpp 1

*/

/*!
    \fn Phonon::phononVersion()
    \inmodule Phonon
    \since 4.5
    
    Returns the Phonon version.
*/

/*!
    \class Phonon::ObjectDescription
    \inmodule Phonon
    \inheaderfile Phonon/ObjectDescription
    \since 4.4
    \brief The ObjectDescription class provides information about Phonon objects.

    Phonon currently uses this class to describe audio effects and
    audio output devices - using the typedefs AudioOutputDevice and
    EffectDescription. The type of an ObjectDescription is also
    described through the \l{Phonon::}{ObjectDescriptionType} enum.
    Objects of the same \l{Phonon::ObjectDescriptionType}{type} are
    uniquely identified by an index().

    The class gives a description() and a name() of the object, both
    of which are strings appropriate for end users of a Phonon
    application. You can also check whether the device or effect
    described is \l{isValid()}{valid}. This does not guarantee that
    the device or effect functions as expected, but that the
    ObjectDescription describes an existing device or effect.

    Audio output devices and effect descriptions are used to select
    the audio output device to be used for playback and to create
    effects; we show examples of this in the snippet below. The
    available descriptions can be fetched with
    \l{Phonon::BackendCapabilities::}{availableAudioOutputDevices()}
    and \l{Phonon::BackendCapabilities::}{availableAudioEffects()}
    static functions in the Phonon::BackendCapabilities namespace

    \snippet doc/src/snippets/phononobjectdescription.cpp 0

    Other types of ObjectDescriptions might be possible in the future,
    e.g., descriptions of audio capture devices, such as microphones.

    \omit Not implemented yet.
    Need a new paragraph on that some descriptions 'belong
    together', such as chained audio effects.

    Some parts give the end user choices, e.g. what source to capture
    audio from. These choices are described by the name and
    description methods of this class and identified with the id
    method. Subclasses then define additional information like which
    audio and video choices belong together.  \endomit

    \sa Phonon::AudioOutputDevice, Phonon::EffectDescription, {Capabilities Example}, {Phonon Module}
*/

/*!
    \fn Phonon::ObjectDescription::ObjectDescription()
    \brief constructs a new object description.
    \internal
*/

/*!
    \fn Phonon::ObjectDescription::ObjectDescription (int index, const QHash<QByteArray, QVariant> & properties)
    \internal
*/

/*!
    \fn Phonon::ObjectDescription::ObjectDescription(const QExplicitlySharedDataPointer<ObjectDescriptionData> &dd)
    \internal
*/

/*!
    \fn static inline ObjectDescription<T> Phonon::ObjectDescription::fromIndex(int index)
    \internal

    \omit Currently indices are not unique for all ObjectDescription types, making
    the behavior of this function undefined. \endomit

    Returns a new description object that describes the
    device/effect/codec/...  with the given \a index.
*/

/*!
    \fn inline bool Phonon::ObjectDescription::operator==(const ObjectDescription &otherDescription) const

    Returns \c true if this ObjectDescription describes the same
    object as \a otherDescription; otherwise, returns \c false.
*/

/*!
    \fn inline bool Phonon::ObjectDescription::operator!=(const ObjectDescription &otherDescription) const
    Returns \c false if this ObjectDescription describes the same
    as \a otherDescription; otherwise, returns \c true.
*/

/*!
    \fn inline QString Phonon::ObjectDescription::name() const

    Returns a string appropriate for a user to select between
    object descriptions, e.g., from a QComboBox.

    \sa description()
*/

/*!
    \fn inline QString Phonon::ObjectDescription::description() const

    Returns a more extensive description than the name() function.

    For example, in the case of \l{Phonon::}{AudioOutputDevice}s, this
    text should make clear which sound source is described; this is
    sometimes hard to describe or understand from just the name.

    The text is appropriate to present to an end user in for example
    tool tips of items, with the name()'s as text, in a QComboBox.

*/

/*!
    \fn inline QVariant Phonon::ObjectDescription::property(const char *name) const

    Returns the property named \a name. A property can be used for
    extended information, such as the manufacturer of a sound card. The
    information will usually be given as text.

    If the property is not set an invalid QVariant is returned.

    Qt's backends do not use properties at the time of this writing.

    \sa propertyNames()
*/

/*!
    \fn inline QList<QByteArray> Phonon::ObjectDescription::propertyNames() const

    Properties can be used for extended information about a
    ObjectDescription, e.g., a manufacturer of a sound card. The
    information will usually be given text.

    This function returns all names that return valid data when
    property() is called.

    Currently, Qt backends do not use properties for their object
    descriptions. 

    \sa property()
*/

/*!
    \fn inline bool Phonon::ObjectDescription::isValid() const

    Returns true if the device or effect described exists. 

    An ObjectDescription that is invalid, will also have an
    index() of -1.

    \sa index()
*/

/*!
    \fn inline int Phonon::ObjectDescription::index() const

    Returns a unique identifier for this ObjectDescription. Used
    internally to distinguish between the descriptions.

    Notice that the identifiers are only unique to the type of
    description, e.g., \l{Phonon::}{AudioOutputDevice} or
    \l{Phonon::}{EffectDescription}.
*/

/*!
    \class Phonon::ObjectDescriptionPrivate
    \inmodule Phonon
    \since 4.4
    \internal

*/

/*!
    \class Phonon::StreamInterface
    \inmodule Phonon
    \since 4.4
    \brief Backend interface to handle media streams (AbstractMediaStream).
    \internal
*/

/*!
    \fn virtual Phonon::StreamInterface::~StreamInterface()
*/

/*!
    \fn virtual void Phonon::StreamInterface::writeData(const QByteArray &data) = 0
    \internal
*/

/*!
    \fn virtual void Phonon::StreamInterface::endOfData() = 0
    \internal
*/

/*!
    \fn virtual void Phonon::StreamInterface::setStreamSize(qint64 newSize) = 0
    \internal
*/

/*!
    \fn virtual void Phonon::StreamInterface::setStreamSeekable(bool s) = 0
    \internal
*/

/*!
    \fn void Phonon::StreamInterface::connectToSource(const MediaSource &mediaSource)
    \internal
*/

/*!
    \fn void Phonon::StreamInterface::needData()
    \internal
*/

/*!
    \fn void Phonon::StreamInterface::enoughData()
    \internal
*/

/*!
    \fn void Phonon::StreamInterface::seekStream(qint64)
    \internal
*/

/*!
    \fn void Phonon::StreamInterface::reset()
    \internal
*/

/*!
    \fn Phonon::StreamInterface::StreamInterface()
    \internal
    \omit
    For subclasses.
    \endomit
*/

/*!
    \class StreamInterfacePrivate
    \inmodule Phonon
    \internal
*/

/*!
    \class Phonon::AbstractVideoOutput
    \inmodule Phonon
    \internal
    \since 4.4
    \brief The AbstractVideoOutput class is the common base class for all video output classes.

    \sa VideoWidget
*/

/*!
    \namespace Phonon::Experimental
    \internal
*/

/*!
    \fn Phonon::AbstractVideoOutput::AbstractVideoOutput(AbstractVideoOutputPrivate &d)
    \internal

    Constructor that is called from derived classes.

    \param parent Standard QObject parent.
*/

/*!
    \class Phonon::AbstractVideoOutputPrivate
    \inmodule Phonon
    \internal
    \since 4.4
*/

/*!
    \class Phonon::VolumeFaderEffect
    \inmodule Phonon
    \internal
    \since 4.4

    This effect differs from gradually changing the output volume in that
    a dedicated effect can change the volume in the smallest possible
    steps while every other volume control will make more or less
    noticeable steps.

    \sa AudioOutput::volume()
*/

/*!
    \property Phonon::VolumeFaderEffect::volume

    This is the current volume of the output as voltage factor.
    Setting this property changes the volume immediately.

    1.0 means 100%, 0.5 means 50% voltage/25% power, 0.0 means 0%

    \sa volumeDecibel
*/

/*!
    \property Phonon::VolumeFaderEffect::volumeDecibel

    This is the current volume of the output in decibel.
    Setting this property changes the volume immediately.

    0 dB means no change in volume, -6dB means an attenuation of the
    voltage to 50% and an attenuation of the power to 25%, -inf dB means
    silence.

    \sa volume
*/

/*!
    \property Phonon::VolumeFaderEffect::fadeCurve

    This property holds the fade curve to be used for the fadeIn(), fadeOut()
    and fadeTo() slots.

    Defaults to Fade3Decibel.

    \sa FadeCurve
*/

/*!
    \enum Phonon::VolumeFaderEffect::FadeCurve
    Determines the curve of the volume change.

    \value Fade3Decibel Crossfade curve/fast fade out.
    This is the default fade curve.
    \value Fade6Decibel Linear fade out.
    \value Fade9Decibel Slow fade out.
    \value Fade12Decibel A more extreme version of the -9dB fade.

    \bold{Notes:}

    \c Fade3Decibel is often the best fade for a crossfade, as after half
    of the time the volume reached -3dB. This means that half the
    possible power (which is proportional to the square of the
    voltage) is reached. Summed, the maximum power of two audio
    signals fading with a -3dB curve will always be equal.

    For fading in or out the -3dB curve is too abrupt in the end.

    With a -6dB fade curve, a volume of -6dB is reached after half of
    the fading time. -6dB is equal to half of the voltage meaning
    that the voltage multiplier changes linearly from the start
    of the fade to the end.

    With the \c Fade9Decibel fade, a volume of -9dB is reached after
    half of the fade time, so the fade is fast in the beginning and
    slow at the end. This is a good fade for ending music.
*/

/*!
    \fn void Phonon::VolumeFaderEffect::fadeIn(int fadeTime)

    Tells the Fader to change the volume from the current volume to 100%
    in \a fadeTime milliseconds.

    Short for \c fadeTo(1.0, fadeTime).

    \param fadeTime the fade duration in milliseconds

    \sa fadeTo(), volume
*/

/*!
    \fn void Phonon::VolumeFaderEffect::fadeOut(int fadeTime)

    Tells the Fader to change the volume from the current volume to 0%
    in \a fadeTime milliseconds.
    Short for \c fadeTo(0.0, fadeTime).

    \param fadeTime the fade duration in milliseconds

    \sa fadeTo
*/

/*!
    \fn void Phonon::VolumeFaderEffect::fadeTo(float volume, int fadeTime)

    Tells the Fader to change the volume from the current value to
    \a volume in \a fadeTime milliseconds.

    \sa fadeIn(), fadeOut()
*/

/*!
    \class Phonon::VolumeFaderEffectPrivate
    \inmodule Phonon
    \since 4.4
    \internal
*/

/*!
    \class Phonon::VolumeFaderInterface
    \inmodule Phonon
    \since 4.4
    \internal
*/

/*!
    \fn virtual Phonon::VolumeFaderInterface::~VolumeFaderInterface()
    \internal
*/

/*!
    \fn virtual float Phonon::VolumeFaderInterface::volume() const
    \internal
*/

/*!
    \fn virtual void Phonon::VolumeFaderInterface::setVolume(float)
    \internal
*/

/*!
    \fn virtual Phonon::VolumeFaderEffect::FadeCurve Phonon::VolumeFaderInterface::fadeCurve() const
    \internal
*/

/*!
    \fn virtual void Phonon::VolumeFaderInterface::setFadeCurve(Phonon::VolumeFaderEffect::FadeCurve)
    \internal
*/

/*!
    \fn virtual void Phonon::VolumeFaderInterface::fadeTo(float, int)
    \internal
*/

/*!
    \class Phonon::AbstractMediaStream
    \inmodule Phonon
    \internal
    \since 4.4
    \brief The AbstractMediaStream class is the base class for custom media data streams.
    \inheaderfile Phonon/AbstractMediaStream

    This class is subclassed to provide custom data streams for
    \l{Phonon::}{MediaSource}s.

    The \l{Phonon::}{MediaSource} knows how to handle the most common
    media sources, such as files and CD. If you need to fetch
    multimedia from other sources, you can reimplement this class,
    which can be used by a \l{Phonon::}{MediaSource}.

    When a backend needs more data from the stream, needData() will be
    called. You must then use writeData() to write the data to the
    backend. You can either write one time and wait for a new
    needData() call, or continue to write data until you receive an
    enoughData() call. When the stream is at its end, call endOfData()
    instead of writeData().

    Before the custom stream is passed to a \l{Phonon::}{MediaSource},
    setStreamSize() needs to be called, and also setStreamSeekable()
    (if the stream is seekable). A good place to do this work is in
    the constructor. A seekable stream must also reimplement
    seekStream().

    We show two examples. The first writes data repeatedly until it
    receives the enoughData() call, while the second only writes once
    and waits for a new needData() call.

    Example where data is written repeatedly.

    \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 0

    Example where data is written once:

    \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 1

    \sa Phonon::MediaSource, Phonon::MediaObject 

*/

/*!
    \fn Phonon::AbstractMediaStream::AbstractMediaStream(QObject *parent = 0)
    \internal

    Constructs an AbstractMediaStream object with the given \a parent.

*/

/*!
    \fn qint64 Phonon::AbstractMediaStream::streamSize() const

    Returns the stream size that was set with setStreamSize().

    A negative value means that the length of the stream cannot be known.

    Defaults to 0.

    \sa setStreamSize()
*/

/*!
    \fn void Phonon::AbstractMediaStream::setStreamSize(qint64 size)

    Sets the \a size of the stream in number of bytes.

    A negative value means that the length of the stream cannot be known.

    Defaults to 0.

    This function has to be called. A backend will not call needData()
    until the stream size is set.

    \sa streamSize()

*/

/*!
    \fn bool Phonon::AbstractMediaStream::streamSeekable() const

    Returns whether your data stream is set as seekable.

    Defaults to \c false.

    \sa setStreamSeekable()

*/

/*!
    \fn void Phonon::AbstractMediaStream::setStreamSeekable(bool s)

    Sets whether your data stream is seekable. \a s should be true if
    the stream is seekable; otherwise false.

    Defaults to \c false.

    If you set this to \c true you have to implement the seekStream()
    function.

    \sa streamSeekable()
*/

/*!
    \fn void Phonon::AbstractMediaStream::writeData(const QByteArray &data)

    Sends the media \a data to the backend for decoding.

    Use this function to send data to the backend after needData() has
    been called.

    If your stream is a push stream, data should be written until the
    enoughData() function is called. For a pull stream, write data
    once before the call to needData() function returns.

    If the data is depleted, call endOfData() instead of writeData().

    \warning Don't call this function before the first needData() is emitted.

    \sa needData(), endOfData()

*/

/*!
    \fn void Phonon::AbstractMediaStream::endOfData()

    Tells the backend that the media data stream is at its end.

    \warning Don't call this function before the first needData() is emitted.

    \sa writeData(), needData()
*/

/*!
    \fn void Phonon::AbstractMediaStream::error(Phonon::ErrorType errorType, const QString &errorString)

    If an I/O error occurs you should call this function to make
    MediaObject go into ErrorState. \c errorType classifies the error,
    while \a errorString is a textual description of the error suitable
    for users of Phonon applications.

    \sa MediaObject::errorType(), MediaObject::errorString()
*/

/*!
    \fn virtual void Phonon::AbstractMediaStream::reset() = 0

    Reimplement this function to reset the stream. Subsequent calls to writeData should start
    from the first position of the data unless a seek is requested.

    The function is necessary for the case where a non-seekable MediaStream is
    played more than once. For a seekable stream the implementation can simply call
    \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 2

    \sa writeData(), needData()
*/

/*!
    \fn virtual void Phonon::AbstractMediaStream::needData() = 0

    Reimplement this function to be notified when the backend needs data.

    When this function is called you should write data to the backend
    (See writeData()).

    \sa writeData(), endOfData(), enoughData()
*/

/*!
    \fn virtual void Phonon::AbstractMediaStream::enoughData()

    If your stream is a push stream, reimplement this function to be
    notified when the backend has enough data and your stream object
    may take a break.

    This method is important for pushing data to the backend in order
    to not fill the backend buffer unnecessarily.

    \sa needData()
*/

/*!
    \fn virtual void Phonon::AbstractMediaStream::seekStream(qint64 offset)

    Reimplement this function if your stream is seekable.

    When this function is called the next call to writeData has to be at the
    requested \a offset.

    \warning Do not call the parent implementation.

    \sa setStreamSeekable(), streamSeekable(), needData()
*/

/*!
    \class Phonon::BackendInterface
    \inmodule Phonon
    \since 4.4
    \brief Main Backend class interface
    \internal

    This interface defines the main factory of the backend. The createObject() function creates all the
    objects needed by the frontend.

    The objectDescriptionIndexes and objectDescriptionProperties functions return information about
    available devices, effects and codecs.

    An implementation could look like this:
    \snippet snippets/phonon/samplebackend/main.cpp snippet

*/

/*!
    \fn virtual Phonon::BackendInterface::~BackendInterface()
    \internal

    Silence gcc's warning.
*/

/*!
    \enum Phonon::BackendInterface::Class
    \internal

    Classes that the createObject() function has to handle.

    \value MediaObjectClass Request to return a \c MediaObject object.
    \value VolumeFaderEffectClass Request to return a \c VolumeFaderEffect
    object.
    \value AudioOutputClass Request to return an \c AudioOutput object.
    \value AudioDataOutputClass Request to return an \c AudioDataOutput object.
    \value VisualizationClass Request to return a \c Visualization object.
    \value VideoDataOutputClass Request to return a \c VideoDataOutput object.
    \value EffectClass Request to return a \c Effect object.
    Takes an additional int that specifies the effect ID.
    \value VideoWidgetClass Request to return a \c VideoWidget object.
*/

/*!
    \fn virtual QObject *Phonon::BackendInterface::createObject(Class c, QObject *parent, const QList<QVariant> &args = QList<QVariant>()) = 0
    \internal

    Returns a new instance of the requested class.

    \param c The requested class.
    \param parent The parent object.
    \param args Additional arguments (documented in Class).
*/


/*!
    \fn virtual QList<int> Phonon::BackendInterface::objectDescriptionIndexes(ObjectDescriptionType type) const = 0
    \internal

    Returns the unique identifiers for the devices/effects/codecs of the given \a type.

    \param type see ObjectDescriptionType
*/

/*!
    \fn virtual QHash<QByteArray, QVariant> Phonon::BackendInterface::objectDescriptionProperties(ObjectDescriptionType type, int index) const = 0
    \internal

    Given a unique identifier that was returned from objectDescriptionIndexes this function
    returns a hash mapping property names to values.

    The property "name" must always be present. All other properties are optional.

    \table
    \header \o Property \o Description
    \row \o name \o The name of the device/effect/codec/...
    \row \o description \o A text explaining what this device/effect/codec/... is/can do
    \row \o icon \o An icon name (using the freedesktop naming scheme) or a QIcon for this
    device/effect/codec/...
    \row \o available \o A bool telling whether the device is present or unplugged.
    \endtable

    \param type see ObjectDescriptionType
    \param index The unique identifier that is returned from objectDescriptionIndexes
*/

/*!
    \fn virtual bool Phonon::BackendInterface::startConnectionChange(QSet<QObject *>) = 0;
    \internal

    When this function is called the nodes given in the parameter list should
    not lose any signal data when connections are changed.
*/

/*!
    \fn virtual bool Phonon::BackendInterface::connectNodes(QObject *, QObject *) = 0
    \internal

    Defines a signal connection between the two given nodes.
*/

/*!
    \fn virtual bool Phonon::BackendInterface::disconnectNodes(QObject *, QObject *) = 0
    \internal

    Cuts a signal connection between the two given nodes.
*/

/*!
    \fn virtual bool Phonon::BackendInterface::endConnectionChange(QSet<QObject *>) = 0
    \internal

    When this function is called the nodes given in the parameter list may lose
    signal data when a port is not connected.
*/

/*!
    \fn virtual QStringList Phonon::BackendInterface::availableMimeTypes() const = 0
    \internal

    Returns all available MIME types.
*/

/*!
    \class Phonon::MediaSource
    \inmodule Phonon
    \inheaderfile Phonon/MediaSource
    \since 4.4
    \brief The MediaSource class provides multimedia data for media objects.

    The MediaSource class manages a source of multimedia content, such
    as a music or video file, of which data is given to a
    \l{Phonon::}{MediaObject}.

    The media source knows how fetch its data from several sources,
    e.g., from files, a QIODevice, or a CD. The possible source types
    are described by the \l{MediaSource::}{Type} enum. The type of the
    source is set by the media source itself, and is dependent on the
    constructor used to create it. Note that it is possible to provide
    data from any source by implementing a QIODevice.

    The class has several functions to acquire information about the
    source it manages, e.g., fileName() and url(). The return from
    these functions are dependent on the type() of the media source.

    Normally, a programmer does not need to be concerned with media
    sources. It's constructors are implicit, so one can, for instance,
    send an URL or filename directly to the constructors of the
    \l{Phonon::}{MediaObject}.

    \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 3

    A MediaSource object cannot be reused for another multimedia
    source. It is possible to play the same source again, and also
    stop and start a non-seekable media source, such as a radio
    stream, with the same MediaSource object.

    \section1 Qt Backends

    Currently, Qt's backends support files in local and remote
    locations. Support for other sources, such as CD/DVD, are planned
    for the future.

    \sa MediaObject, {Phonon Module}
*/

/*!
    \enum Phonon::MediaSource::Type

    Identifies the type of media described by the MediaSource object.

    \value Invalid The MediaSource object does not describe any valid source.
    \value LocalFile The MediaSource object describes a local file.
    \value Url The MediaSource object describes an URL, which can be either a
    local file or a file on the network.
    \value Disc The MediaSource object describes a disc, e.g., a CD.
    \value Stream The MediaSource object describes a data stream.
                  This is the type used for \l{QIODevice}s. Note
                  that a stream opened with a QUrl, will still be of the Url type.

    \sa MediaSource::type()
*/

/*!
    \fn Phonon::MediaSource::MediaSource()
    \internal

    Creates an invalid MediaSource object.

    \sa Invalid
*/

/*!
    \fn Phonon::MediaSource::MediaSource(const QString &fileName)

    Creates a MediaSource object for the file specified by \a
    fileName.  You can also use this constructor with \l{The Qt
    Resource System}{Qt resources}

    \omit
    \param fileName file name of a local media file or a Qt resource that was compiled in.
    \endomit
*/

/*!
    \fn Phonon::MediaSource::MediaSource(const QUrl &url)

    Creates a MediaSource object for a the URL specified by \a url.
    
    If the multimedia content you would like to play back is on a
    remote network location, you should use this constructor; though,
    it also possible to specify an URL to a local file.

    \sa QUrl
*/


/*!
    \fn Phonon::MediaSource::MediaSource(Phonon::DiscType discType, const QString &deviceName = QString())

    Creates a MediaSource object for the type of disc specified by \a discType in the named
    device referred to by \a deviceName.

    \note \a deviceName is a platform dependent device name. It can be useful to specify this
    if the computer has more than one CD drive. On KDE, it is recommended to use the Solid
    hardware discovery framework to retrieve the device name in a portable way.
*/

/*!
    \fn Phonon::MediaSource::MediaSource(AbstractMediaStream *stream)
    \internal
    Creates a MediaSource object for a data stream.

    Your application can provide the media data by subclassing AbstractMediaStream and
    passing a pointer to that object. Phonon will never delete the \a stream.

    \param stream The AbstractMediaStream subclass to provide the media data.

    \sa setAutoDelete
*/

/*!
    \fn Phonon::MediaSource::MediaSource(QIODevice *ioDevice)

    Creates a MediaSource object for the QIODevice specified by \a ioDevice.

    This constructor can be very handy in the combination of
    QByteArray and QBuffer.

    If you need to fetch multimedia data from a source that is not
    supported by MediaSource, you should subclass QIODevice and use
    this MediaSource constructor. It is important that you reimplement
    QIODevice::isSequential(), as it is used by MediaSource to
    determine if the media source is seekable.

    \a ioDevice is an arbitrary readable QIODevice subclass. If the device is not opened
    MediaSource will open it as QIODevice::ReadOnly.

    \note Sequential devices can also be used, but MediaObject::isSeekable() will
    return false as a result.

    \sa setAutoDelete()
*/

/*!
    \fn Phonon::MediaSource::MediaSource(MediaSourcePrivate &)
    \internal
*/

/*!
    \fn Phonon::MediaSource::~MediaSource()

    Destroys the MediaSource object. You should never delete a
    MediaSource yourself, the MediaObject will handle this.

*/

/*!
    \fn Phonon::MediaSource::MediaSource(const MediaSource &other)

    Constructs a copy of the \a other media source.

    This constructor is fast thanks to explicit sharing.
*/

/*!
    \fn MediaSource &Phonon::MediaSource::operator=(const MediaSource &other)

    Assigns the \a other media source to this media source and returns a
    reference to it.

    This operation is fast thanks to explicit sharing.
*/

/*!
    \fn bool Phonon::MediaSource::operator==(const MediaSource &other) const

    Returns true if this media source is equal to the \a other media source;
    otherwise returns false.
*/

/*!
    \fn void Phonon::MediaSource::setAutoDelete(bool enable)

    If \a enable is true, the media source will take ownership of the
    object passed in the \l{Phonon::}{MediaSource}'s constructor
    object that was passed in the constructor; otherwise, the
    programmer is responsible for deletion of this object.

    This setting is false by default. If you enable it, you should
    only access the stream or device as long as you keep the media
    source object around. As long as you keep the media source
    wrapping the stream or device, the object will not get deleted.

    \sa autoDelete()
*/

/*!
    \fn bool Phonon::MediaSource::autoDelete() const

    Returns the setting of the auto-delete option. The default is
    false.

    \sa setAutoDelete()
*/

/*!
    \fn Type Phonon::MediaSource::type() const

    Returns the type of the MediaSource (depends on the constructor
    that was used).

    \sa Type
*/

/*!
    \fn QString Phonon::MediaSource::fileName() const

    Returns the file name of the MediaSource if type() ==
    LocalFile; otherwise, returns QString().

    \sa type()
*/

/*!
    \fn QUrl Phonon::MediaSource::url() const
    Returns the URL of the MediaSource if type() == URL or type() == LocalFile;
    otherwise returns QUrl().

    \sa type()
*/

/*!
    \fn Phonon::DiscType Phonon::MediaSource::discType() const
    Returns the disc type of the MediaSource if type() == Disc; otherwise
    returns NoDisc.

    \sa type()
*/

/*!
    \fn QString Phonon::MediaSource::deviceName() const

    Returns the device name of the MediaSource if type() == Disc; otherwise
    returns QString().

    \sa type()
*/

/*!
    \fn AbstractMediaStream *Phonon::MediaSource::stream() const
    \internal
    Returns the media stream of the MediaSource if type() == Stream; otherwise
    returns 0.
    QIODevices are handled as streams, too.
*/

/*!
    \class Phonon::MediaSourcePrivate
    \inmodule Phonon
    \since 4.4
    \internal
*/

/*!
    \class Phonon::SeekSlider
    \inmodule Phonon
    \inheaderfile Phonon/SeekSlider
    \since 4.4
    \brief The SeekSlider class provides a slider for seeking to positions in media streams.

    The SeekSlider connects to a \l{Phonon::}{MediaObject}, and
    controls the seek position in the object's media stream.

    The slider will connect to the necessary signals to keep track of
    the sliders maximum, minimum, and current values. It will also
    disable itself for non-seekable streams, and update the media
    object when the current value of the slider changes.

    Here follows a typical example of SeekSlider usage:

    \snippet doc/src/snippets/seekslider.cpp 0

    \sa Phonon::VolumeSlider, Phonon::VideoWidget, {Music Player Example}, {Phonon Module}

*/

/*!
    \property Phonon::SeekSlider::iconVisible
    \brief whether the icon next to the slider is visible

    By default the icon is visible if the platform provides an icon; else
    it's hidden.

*/

/*!
    \property Phonon::SeekSlider::tracking
    \brief whether slider tracking is enabled

    If tracking is enabled (the default), the media seeks
    while the slider is being dragged. If tracking is
    disabled, the media seeks only when the user
    releases the slider.
*/

/*!
    \property Phonon::SeekSlider::pageStep
    \brief the page step interval

    The larger of two natural steps that a slider provides and
    typically corresponds to the user pressing PageUp or PageDown.

    Defaults to 5 seconds.
*/

/*!
    \property Phonon::SeekSlider::singleStep
    \brief the single step interval

    The smaller of two natural steps that a slider provides and
    typically corresponds to the user pressing an arrow key.

    Defaults to 0.5 seconds.
*/

/*!
    \property Phonon::SeekSlider::orientation
    \brief the orientation of the slider

    The orientation must be Qt::Vertical or Qt::Horizontal (the default).
*/

/*!
    \property Phonon::SeekSlider::iconSize
    \brief the icon size used for the mute button/icon.

    The default size is defined by the GUI style.
*/

/*!
    \fn explicit Phonon::SeekSlider::SeekSlider(QWidget *parent = 0)

    Constructs a seek slider widget with the given \a parent.
*/

/*!
    \fn explicit Phonon::SeekSlider::SeekSlider(MediaObject *media, QWidget *parent = 0)

    Constructs a seek slider widget for the specified \a media with the
    given \a parent.
*/

/*!
    \fn Phonon::SeekSlider::~SeekSlider()
    Destroys the seek slider.
*/

/*!
    \fn Phonon::MediaObject *Phonon::SeekSlider::mediaObject() const

    Return the media object this SeekSlider controls.
*/

/*!
    \class Phonon::SeekSliderPrivate
    \inmodule Phonon
    \since 4.4
    \internal
*/

/*!
    \fn void Phonon::SeekSlider::setMediaObject(MediaObject *media)

    Sets the media object to be controlled by this slider to the \a media specified.
*/

/*!
    \class Phonon::VideoPlayer
    \inmodule Phonon
    \inheaderfile Phonon/VideoPlayer
    \since 4.4
    \brief The VideoPlayer widget is used to perform playback of video.

    With VideoPlayer you can get results quickly and easily. You can
    do the standard playback tasks like play(), pause(), and stop(),
    but also set a playback volume and seek - if the media and backend
    supports seeking.

    VideoPlayer is provided for convenience and removes the need to
    create a media graph with a \l{Phonon::}{MediaObject},
    \l{Phonon::}{AudioOutput}, and \l{Phonon::}{VideoWidget}. If
    you need functionality not supported by the player, you can build
    this \l{Building Graphs}{graph} yourself.

    Keep in mind that when the VideoPlayer instance is deleted the
    playback will stop.

    Note also that most of the functions in this class are
    asynchronous. For instance, a media source may not play
    immediately after you call the play() function.

    A play and forget code example:
    \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 4

    \sa {Phonon Module}, MediaObject
*/

/*!
    \fn Phonon::VideoPlayer::VideoPlayer(QWidget *parent = 0)
    
    Constructs a new video widget with a \a parent using
    Phonon::VideoCategory as its category.

    \param parent The QObject parent.
*/

/*!
    \fn Phonon::VideoPlayer::VideoPlayer(Phonon::Category category, QWidget *parent = 0)

    Constructs a new VideoPlayer instance with the specified \a
    parent.

    \a category is the category used for the audio output device.
*/

/*!
    \fn Phonon::VideoPlayer::~VideoPlayer()

    On destruction the playback is stopped, also the audio output is
    removed so that the desktop mixer will not show the application
    anymore. If you need a persistent audio output don't use
    VideoPlayer but MediaObject, VideoPath and VideoOutput.
*/

/*!
    \fn qint64 Phonon::VideoPlayer::totalTime() const

    Get the total time (in milliseconds) of the file currently being played.
*/

/*!
    \fn qint64 Phonon::VideoPlayer::currentTime() const

    Get the current time (in milliseconds) of the file currently being played.
*/

/*!
    \fn float Phonon::VideoPlayer::volume() const

    This is the current volume of the output as voltage factor.

    1.0 means 100%, 0.5 means 50% voltage/25% power, 0.0 means 0%
*/

/*!
    \fn bool Phonon::VideoPlayer::isPlaying() const

    Returns true if it is currently playing; otherwise returns false if it
    is currently stopped or paused
*/

/*!
    \fn bool Phonon::VideoPlayer::isPaused() const

    Returns true if it is currently paused; otherwise returns false if it
    is currently playing or stopped.
*/

/*!
    \fn void Phonon::VideoPlayer::load(const Phonon::MediaSource &source)

    Starts pre-loading the media data from the specified \a source and
    filling audio buffers in the backend.

    When there's already a media playing (or paused) it will be stopped
    (the finished signal will not be emitted).

    \sa MediaObject::setCurrentSource()
*/

/*!
    \fn void Phonon::VideoPlayer::play(const Phonon::MediaSource &source)

    Plays the media from the given \a source. Starts playback as fast as
    possible.
    This can take a considerable time depending on the URL and the
    backend.

    If you need low latency between calling play() and the sound actually
    starting to play on your output device you need to use MediaObject
    and be able to set the URL before calling play(). Note that
    \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 5
    doesn't make a difference: the application should be idle between the
    load and play calls so that the backend can start preloading the
    media and fill audio buffers.
*/

/*!
    \fn void Phonon::VideoPlayer::play()

    Continues playback of paused media. Restarts playback of a stopped
    (or newly loaded) media.

    \sa MediaObject::play(), play()
*/

/*!
    \fn void Phonon::VideoPlayer::pause()

    Pauses the playback.

    \sa MediaObject::pause()
*/

/*!
    \fn void Phonon::VideoPlayer::stop()

    Stops the playback.

    \sa MediaObject::stop()
*/

/*!
    \fn void Phonon::VideoPlayer::seek(qint64 ms)

    Seeks to the requested time. Note that the backend is free to
    ignore the seek request if the media source isn't seekable; you
    can check this by asking the media object of the VideoPlayer.

    \snippet doc/src/snippets/videomedia.cpp 0

    The \a ms parameter is the time in milliseconds from the start of
    the media.

    The call is asynchronous, so currentTime() can still be the old
    value right after this method was called. If all you need is a
    slider that shows the current position and allows the user to
    seek, use the class SeekSlider.

    \sa MediaObject::seek(), MediaObject::isSeekable(), mediaObject()
*/

/*!
    \fn void Phonon::VideoPlayer::setVolume(float volume)

    Sets the \a volume of the output as voltage factor.

    1.0 means 100%, 0.5 means 50% voltage/25% power, 0.0 means 0%
*/

/*!
    \fn MediaObject *Phonon::VideoPlayer::mediaObject() const

    Returns the media object being used by the player.

    The media object can be accessed directly instead of using the
    \l{VideoPlayer}s convenience functions, e.g., play() and stop().
    It is also possible to give the object to other Phonon widgets,
    e.g., a \l{Phonon::}{SeekSlider} or a \l{Phonon::}{VolumeSlider}.

    \sa Phonon::SeekSlider, Phonon::MediaObject
*/

/*!
    \fn AudioOutput *Phonon::VideoPlayer::audioOutput() const

    Returns the audio output object being used by the player.

*/

/*!
    \fn VideoWidget *Phonon::VideoPlayer::videoWidget() const

    Returns the video widget being used by the player.
*/

/*!
    \fn void Phonon::VideoPlayer::finished()

    This signal is emitted when the playback finished.

*/

/*!
    \class Phonon::VideoWidgetPrivate
    \inmodule Phonon
    \since 4.4
    \internal
*/

/*!
    \class Phonon::MediaObject
    \inmodule Phonon
    \inheaderfile Phonon/MediaObject
    \since 4.4
    \brief The MediaObject class provides an interface for media playback.


    The media object manages a \l{Phonon::}{MediaSource}, which
    supplies the media object with multimedia content, e.g., from a
    file. A playback in Phonon is always started by calling the
    \l{Phonon::MediaObject::}{play()} function.

    The state of play (play, pause, stop, seek) is controlled by the
    media object, and you can also query the current
    \l{Phonon::MediaObject::}{state()}. It keeps track of the playback
    position in the media stream, and emits the
    \l{Phonon::MediaObject::}{tick()} signal when the current position
    in the stream changes.

    Notice that most functions of this class are asynchronous, so you
    cannot rely on that a state is entered after a function call
    before you receive the \l{Phonon::MediaObject::}{stateChanged()}
    signal. The description of the \l{Phonon::}{State} enum gives a
    description of the different states.

    Before play() is called, the media object should be connected to
    \l{Sinks}{output nodes}, which outputs the media to the
    underlying hardware. The output nodes required are dependent on
    the contents of the multimedia file that is played back. Phonon
    has currently two output nodes: the \l{Phonon::}{AudioOutput} for
    audio content and \l{Phonon::}{VideoWidget} for video content.  If
    a \l{Phonon::}{MediaSource} contains both audio and video, both
    nodes need to be connected to the media object.

    \snippet snippets/phonon.cpp 4
    \snippet snippets/phonon.cpp 5 

    The media object can queue sources for playback. When it has
    finished to play one source, it will start playing the next in the
    queue; the new source is then removed from the queue. The
    queue can be altered at any time. 

    \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 7

    You can also make use of the
    \l{Phonon::MediaObject::}{aboutToFinish()} signal, which is
    guaranteed to be emitted in time for altering the queue.

    \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 8

    When playback is finishing, i.e., when a media source has been
    played to the end and the queue is empty, several signals are
    emitted. First, the media object will emit aboutToFinish() -
    shortly before the playback has finished - and then finished().
    The stateChanged() signal will also be emitted with
    \l{Phonon::}{PausedState}, which is the state the media object
    takes when the playback is finished. If you wish to enter another
    state, you can connect a slot to finished() and set a new state
    there.

    The media object resolves the meta information, such as title,
    artist, and album. The meta data is not resolved immediately after
    a new source is provided, but will be resolved before the object
    leaves the \l{Phonon::}{LoadingState}. The data is queried by
    string keys - which should follow the Ogg Vorbis specification
    \l http://xiph.org/vorbis/doc/v-comment.html - or by using the
    \l{Phonon::}{MetaData} enum. The data available will depend on the
    type and content of the individual media files.  metaDataChanged()
    will be emitted when the media object has resolved new meta data.

    Errors encountered during playback and loading of media sources
    are reported by emitting a state changed signal with
    \l{Phonon::}{ErrorState}. The severity of the error can be queried
    by the \l{Phonon::}{ErrorType}. With a \l{Phonon::}{NormalError},
    it might be possible to continue the playback, for instance, if
    only audio playback fails for a media source which also has video.
    A \l{Phonon::}{FatalError} indicates that Phonon cannot continue
    playback of the current source, but it is possible to try with a
    different one. A user readable error message is given by
    errorString().

    \sa Phonon::MediaSource, Phonon::AudioOutput, VideoWidget,
    {Music Player Example}, {Phonon Overview}, Phonon::VideoPlayer,
    Phonon::createPlayer(), {Phonon Module}

*/

/*!
    \property Phonon::MediaObject::transitionTime
    \brief Defines the time between playback of two media sources
    in the media queue.

    A positive transition time defines a gap of silence between queued
    media sources.

    A transition time of 0 ms requests gapless playback (i.e., the
    next source in the media queue starts immediately after the
    playback of the current source finishes).

    A negative transition time defines a crossfade between the queued
    media sources.

    Defaults to 0 (gapless playback).

    \warning This feature might not work reliably with every
             backend.
*/

/*!
    \property Phonon::MediaObject::prefinishMark
    \brief the time when the prefinishMarkReached signal is emitted before playback ends.

    This property specifies the time in milliseconds the
    prefinishMarkReached() signal is emitted before the playback
    finishes. A value of \c 0 disables the signal. The signal is only
    emitted for the last source in the \l{queue()}{media queue}.

    Defaults to \c 0 (disabled).

    \warning For some media data the total time cannot be determined
    accurately, therefore the accuracy of the prefinishMarkReached signal
    can be bad sometimes. Still, it is better to use this method than to
    look at totalTime() and currentTime() to emulate the behavior
    because the backend might have more information available than your
    application does through totalTime() and currentTime().

    \sa prefinishMarkReached()
*/

/*!
    \property Phonon::MediaObject::tickInterval
    \brief The time interval in milliseconds between two ticks.

    The tick() signal is emitted continuously during playback.
    The tick interval is the time that elapses between the emission of two tick signals.
    If you set the interval to \c 0 the tick signal gets disabled.

    The tick() signal can, for instance, be used to update widgets
    that show the current position in the playback of a media source.

    Defaults to \c 0 (disabled).

    \warning The back-end is free to choose a different tick interval close
    to what you asked for. This means that the following code \c may fail:
    \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 9
    On the other hand the following is guaranteed:
    \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 10

    \sa tick()
*/

/*!
    \fn Phonon::MediaObject::~MediaObject()

    Destroys the MediaObject.
*/

/*!
    \fn State Phonon::MediaObject::state() const

    Returns the current Phonon::State of the object.

    \sa Phonon::State, stateChanged()
*/

/*!
    \fn bool Phonon::MediaObject::hasVideo() const

    Check whether the current media source includes a video stream.

    \warning This information is not resolved immediately after a
    media object gets a new source. Listen to the hasVideoChanged()
    signal instead.

    \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 11

    Returns \c true if the media contains video data; otherwise,
    returns  \c false.

    \sa hasVideoChanged()
*/

/*!
    \fn bool Phonon::MediaObject::isSeekable() const

    Check whether it is possible to seek, i.e., change the
    playback position in the media stream.

    \warning This information is not solved immediately after the
    media object gets a new media source. The hasVideoChanged() signal
    is emitted after this information is available.

    \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 12

    Returns \c true if the current media may be seeked; otherwise,
    returns \c false.

    \sa seekableChanged()
*/

/*!
    \fn QStringList Phonon::MediaObject::metaData(const QString &key) const

    Returns the strings associated with the given \a key.

    Backends should use the keys specified in the Ogg Vorbis
    documentation: \l http://xiph.org/vorbis/doc/v-comment.html

    Therefore the following should work with every backend:

    Note that meta data is not resolved before the \c
    metaDataChanged() signal is emitted.

    A typical usage looks like this:

    \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 13
*/

/*!
    \fn QStringList Phonon::MediaObject::metaData(Phonon::MetaData key) const

    Returns the strings associated with the given \a key.

    Same as above except that the keys are defined in the
    Phonon::MetaData enum.

    \sa metaDataChanged()
*/

/*!
    \fn QMultiMap<QString, QString> Phonon::MediaObject::metaData() const

    Returns all meta data in a multi map. 

    \sa metaDataChanged()
*/

/*!
    \fn QString Phonon::MediaObject::errorString() const

    Returns a human-readable description of the last error that occurred.
    The strings given may vary between backends.

    The error description can be used to give a message to the user -
    and the developer - when the stateChanged() signal is emitted with
    \l{Phonon::}{ErrorState}.

    \section1 Qt Backends

    On Windows, Qt fetches its error messages from the DirectShow
    backend.  This usually includes an error number, which can be
    looked up in the DirectShow documentation:
    \l{http://msdn.microsoft.com/archive/default.asp?url=/archive/en-us/dx81_c/directx_cpp/htm/errorandsuccesscodes.asp}.

    On Linux and Mac, the error strings are not fetched directly from
    the backend, but are created in the backend.

    \sa Phonon::ErrorState, stateChanged()
*/

/*!
    \fn ErrorType Phonon::MediaObject::errorType() const

    Tells your program what to do about the last error that occurred.
    Use this function after receiving a stateChanged() signal with
    \l{Phonon::}{ErrorState}.

    \sa Phonon::ErrorType, Phonon::ErrorState, stateChanged()
*/

/*!
    \fn MediaSource Phonon::MediaObject::currentSource() const

    Returns the current media source, i.e., the media source that is
    being played back. The current source is either set with
    setCurrentSource() or taken from the media queue() when a media
    source has finished playing.

    \sa setCurrentSource()
*/

/*!
    \fn void Phonon::MediaObject::setCurrentSource(const MediaSource &source)

    Set the media source the MediaObject should use.

    After the media object receives a new source, it will enter the
    \l{Phonon::}{LoadingState}. When it is ready to play, it
    enters the \l{Phonon::}{StoppedState} unless another state
    has been requested, e.g., by calling play().

    \a source is the MediaSource object to the media data. You can
    just as well use a QUrl or QString (for a local file) here.

    We show an example:

    \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 14

    \sa currentSource()
*/

/*!
    \fn QList<MediaSource> Phonon::MediaObject::queue() const

    Returns the queued media sources.

    This does list does not include the current source,
    returned by currentSource().

    \sa enqueue()
*/

/*!
    \fn void Phonon::MediaObject::setQueue(const QList<MediaSource> &sources)

    Set the \a sources to play when the current source has finished.

    This function will overwrite the current queue.

    \sa clearQueue(), enqueue()
*/

/*!
    \fn void Phonon::MediaObject::setQueue(const QList<QUrl> &urls)

    Set the \a urls to play when the current media has finished.

    This function overwrites the current queue.

    \sa clearQueue(), enqueue()
*/

/*!
    \fn void Phonon::MediaObject::enqueue(const MediaSource &source)

    Appends \a source to the queue.

    You can use this function to provide the next source after the
    aboutToFinish() signal has been emitted.

    \sa aboutToFinish(), setQueue(), clearQueue()
*/

/*!
    \fn void Phonon::MediaObject::enqueue(const QList<MediaSource> &sources)

    Appends multiple \a sources to the queue.

    \sa setQueue(), clearQueue()
*/

/*!
    \fn void Phonon::MediaObject::enqueue(const QList<QUrl> &urls)

    Appends the URLs in \a urls to the media source queue. 

    The function will create \l{MediaSource}s from the \l{QUrl}s, and
    append these to the queue.

    \sa setQueue(), clearQueue()
*/

/*!
    \fn void Phonon::MediaObject::clearQueue()

    Clears the queue of media sources.
    
    \sa queue(), enqueue()
*/

/*!
    \fn qint64 Phonon::MediaObject::currentTime() const

    Returns the current time (in milliseconds), i.e., position in the
    media stream, of the file currently being played.

    \sa tick(), totalTime(), remainingTime()
*/

/*!
    \fn qint64 Phonon::MediaObject::totalTime() const

    Get the total time (in milliseconds) of the file currently being played.

    Returns the total time in milliseconds.

    \warning The total time is not defined before the media object
             enters the \l{Phonon::}{LoadingState}.

    \sa totalTimeChanged()
*/

/*!
    \fn qint64 Phonon::MediaObject::remainingTime() const

    Get the remaining time (in milliseconds) of the file currently being played.

    Returns the remaining time in milliseconds.

    \sa totalTime(), currentTime(), totalTimeChanged()
*/

/*!
    \fn void Phonon::MediaObject::play()

    Requests playback of the media data to start.

    Playback starts when the stateChanged() signal is emitted with
    \l{Phonon::}{PlayingState}.

    If the media object is already in a
    \l{Phonon::}{PlayingState}, nothing happens.

    \sa stop(), pause(), stateChanged()
*/

/*!
    \fn void Phonon::MediaObject::pause()

    Requests playback to pause, and the media object to enter the
    \l{Phonon::}{PausedState}. If it was paused already, nothing
    changes.

    This function is asynchronous and the media might not be paused
    immediately.

    \sa play(), stop(), stateChanged()
*/

/*!
    \fn void Phonon::MediaObject::stop()

    Requests playback to stop, and the media object to enter the
    \l{Phonon::}{StoppedState}. If it was stopped before
    nothing changes.

    This function is asynchronous and the media might not be
    stopped immediately.

    \sa play(), pause(), stateChanged()
*/

/*!
    \fn void Phonon::MediaObject::seek(qint64 time)

    Requests a seek to the \a time indicated, specified in milliseconds.

    You can only seek if state() is PlayingState, BufferingState or PausedState.

    The call is asynchronous, so currentTime can still be the old
    value right after this method was called. If all you need is a
    slider that shows the current position and allows the user to
    seek, use the class SeekSlider.

    If the current source of the media object is not seekable, calls
    to this functions do nothing.

    \sa SeekSlider, tick()
*/

/*!
    \fn void Phonon::MediaObject::stateChanged(Phonon::State newstate, Phonon::State oldstate)

    This signal is emitted when the state of the MediaObject has changed.
    The \a oldstate and \a newstate parameters indicate the previous
    state and current state of the media object.

    If you are only interested in the new state of the media object, you can
    connect this signal to a slot that accepts only one State argument.
*/

/*!
    \fn void Phonon::MediaObject::tick(qint64 time)

    This signal is emitted in intervals defined by the
    \l{tickInterval} property. The current position of the media
    object in the stream is given by the \a time parameter. The \a
    time is specified in milliseconds.

    \sa tickInterval
*/

/*!
    \fn void Phonon::MediaObject::metaDataChanged()

    This signal is emitted when the media object has resolved new meta
    data. This will happen before the media object leaves the
    \l{Phonon::}{LoadingState} after a new source has been set.

    This signal is not emitted when the media object removes the
    current data, i.e., when a new source is set or an error has
    occurred. If you need to know this, you can listen for the
    \l{Phonon::}{ErrorState}, and connect to the
    \l{Phonon::MediaObject::}{currentSourceChanged()} signal.

    You can get the new meta data with the metaData methods.
    
    \sa metaData(), currentSourceChanged(), stateChanged(), Phonon::State
*/

/*!
    \fn void Phonon::MediaObject::seekableChanged(bool isSeekable)

    This signal is emitted when the media object's ability to seek in
    the media stream changes. \a isSeekable is true if it is possible
    to seek(); otherwise, it is false.

    Change in the ability to seek in the stream usually happens when
    the current source changes or when an error occurs.

    \omit Emitted whenever the return value of isSeekable()
    changes. \endomit

    Normally you'll check isSeekable() after setting a new media
    source, and then let this signal tell you when seeking is
    possible. That way you don't have to poll isSeekable().
*/

/*!
    \fn void Phonon::MediaObject::hasVideoChanged(bool hasVideo)

    Emitted whenever the return value of hasVideo() changes, i.e., 
    the media source being played back contains video.

    Normally you'll check hasVideo() first and then let this signal
    tell you whether video is available now or not. That way you
    don't have to poll hasVideo().

    \a hasVideo is true  when the stream contains video and adding a
    VideoWidget will show a video, and false if there is no video data
    in the stream and adding a VideoWidget will show an empty (black)
    VideoWidget.
*/

/*!
    \fn void Phonon::MediaObject::bufferStatus(int percentFilled)

    Provides information about the status of the buffer.

    When a MediaObject is in the \l{Phonon::}{BufferingState}, it will
    send this signal regularly. \a percentFilled is a number between 0
    and 100 telling you how much the buffer is filled.

    You can use this signal to show a progress bar to the user when
    in BufferingState:

    \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 15

    Note that the \l{Phonon::}{BufferingState} is commonly used when
    waiting for data over a network connection, but this might not be
    true for all backends.
*/

/*!
    \fn void Phonon::MediaObject::finished()

    Emitted when the object has finished playback.  It is not emitted
    if you call stop(), pause() or load(). It is emitted only when the
    current media source has finished playing and the media queue() is
    empty, or when a \l{Phonon::FatalError}{fatal error} occurs.

    \warning This signal is not emitted when the current source has
    finished and there's another source in the queue. It is only
    emitted when the queue is empty.

    \sa currentSourceChanged(), aboutToFinish(), prefinishMarkReached()
*/

/*!
    \fn void Phonon::MediaObject::currentSourceChanged(const Phonon::MediaSource &newSource)

    Emitted when the MediaObject fetches a new MediaSource from the
    queue() and before it enters the \l{Phonon::}{LoadingState} for
    the new source. The media object will take a new source from the
    queue() when it has finished the playback of the
    \l{currentSource()}{current source}.

    \a newSource is the source that starts to play at the time the
    signal is emitted.
*/

/*!
    \fn void Phonon::MediaObject::aboutToFinish()

    Emitted before the playback of the whole queue ends. When this
    signal is emitted you still have time to enqueue() a new
    MediaSource, so that playback continues.

    If you need a signal to be emitted at a specific time before
    playback is finished, you should use the prefinishMarkReached()
    signal instead.

    \sa enqueue(), prefinishMark, prefinishMarkReached()
*/

/*!
    \fn void Phonon::MediaObject::prefinishMarkReached(qint32 msecToEnd)

    Emitted when there are only \a msecToEnd milliseconds left
    of playback.

    \warning This signal is not emitted when there is another source
    in the queue.  It is only emitted when the queue is empty.

    \sa setPrefinishMark(), prefinishMark(), aboutToFinish(), finished()
*/

/*!
    \fn void Phonon::MediaObject::totalTimeChanged(qint64 newTotalTime)

    This signal is emitted as soon as the total time of the media file is
    known or has changed. For most non-local media data the total
    time of the media can only be known after some time. At that time the
    totalTime function can not return useful information. You have
    to wait for this signal to know the real total time.

    \a newTotalTime is the length of the media file in milliseconds.

    \sa totalTime()
*/

/*!
    \fn MediaObject *Phonon::createPlayer(Phonon::Category category, const MediaSource &source = MediaSource())

    Convenience function to create a MediaObject and AudioOutput
    connected by a path. The \l{Phonon::}{MediaObject} return will
    have \a source set as its current source and the specified \a
    category.

*/

/*!
    \class Phonon::MediaObjectPrivate
    \inmodule Phonon
    \since 4.4
    \internal
*/

/*!
    \namespace Phonon::BackendCapabilities
    \inmodule Phonon
    \since 4.4
    \brief The BackendCapabilities namespace contains functions to describe the capabilities of the multimedia backend.

*/

/*!
    \class Phonon::BackendCapabilitiesPrivate
    \inmodule Phonon
    \since 4.4
    \internal
*/

/*!
    \class Phonon::BackendCapabilities::Notifier
    \since 4.4
    \inmodule Phonon
    \inheaderfile Phonon/BackendCapabilities

    Notifications about backend capabilities.
*/

/*!
    \fn void Phonon::BackendCapabilities::Notifier::capabilitiesChanged()

    This signal is emitted if the capabilities have changed. This can
    happen if the user has requested a backend change.
*/

/*!
    \fn void Phonon::BackendCapabilities::Notifier::availableAudioOutputDevicesChanged()

    This signal is emitted when audio output devices were plugged or
    unplugged.

    Check BackendCapabilities::availableAudioOutputDevices to get the
    current list of available devices.
*/

/*!
    \fn Notifier *Phonon::BackendCapabilities::notifier()

    Use this function to get a QObject pointer to connect to the capabilitiesChanged signal.

    \return a pointer to a QObject.

    The capabilitiesChanged signal is emitted if the capabilities have changed. This can
    happen if the user has requested a backend change.

    To connect to this signal do the following:
    \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 16

    \sa Notifier::capabilitiesChanged()
*/

/*!
    \fn QStringList Phonon::BackendCapabilities::availableMimeTypes()

    Returns a list of mime types that the Backend can decode.

    \sa isMimeTypeAvailable()
*/

/*!
    \fn bool Phonon::BackendCapabilities::isMimeTypeAvailable(const QString &mimeType)

    Often all you want to know is whether one given MIME type can be
    decoded by the backend. Use this method in favor of
    availableMimeTypes() as it can give you a negative answer without
    having a backend loaded.

    Returns true if the given \a mimeType is supported by the backend;
    otherwise, returns false.

    \sa availableMimeTypes()
*/

/*!
    \fn QList<AudioOutputDevice> Phonon::BackendCapabilities::availableAudioOutputDevices()

    Returns the audio output devices the backend supports.

    \return A list of AudioOutputDevice objects that give a name and
            description for every supported audio output device.
*/

/*!
    \fn QList<EffectDescription> Phonon::BackendCapabilities::availableAudioEffects()

    Returns descriptions for the audio effects the backend supports.

    \return A list of AudioEffectDescription objects that give a name and
    description for every supported audio effect.
*/

/*!
    \internal
    \class ObjectDescriptionModelData
    \internal
    \inmodule Phonon
    \brief Data class for models for ObjectDescription objects.
*/

/*!
    \typedef Phonon::EffectDescription
    \relates Phonon::ObjectDescription

    EffectDescription gives a description of an \l{Processors}{audio
    effect}. It is a typedef of the \l{Phonon::}{ObjectDescription}
    class. Please see its class description for details.

    EffectDescription is used to create audio \l{Phonon::}{Effect}s,
    which can be inserted into a media graph, altering an audio
    stream.

    \sa Phonon::ObjectDescription, {Capabilities Example}, {Media
    Player}

*/