Phonon::MediaObject

Phonon::MediaObject Class Reference

#include <phonon/MediaObject>

Inheritance diagram for Phonon::MediaObject:

Properties

qint32 prefinishMark
 
qint32 tickInterval
 
qint32 transitionTime
 
- Properties inherited from QObject
 objectName
 

Signals

void aboutToFinish ()
 
void bufferStatus (int percentFilled)
 
void currentSourceChanged (const Phonon::MediaSource &newSource)
 
void finished ()
 
void hasVideoChanged (bool hasVideo)
 
void metaDataChanged ()
 
void prefinishMarkReached (qint32 msecToEnd)
 
void seekableChanged (bool isSeekable)
 
void stateChanged (Phonon::State newstate, Phonon::State oldstate)
 
void tick (qint64 time)
 
void totalTimeChanged (qint64 newTotalTime)
 

Public Slots

void clear ()
 
void pause ()
 
void play ()
 
void seek (qint64 time)
 
void setTickInterval (qint32 newTickInterval)
 
void stop ()
 

Public Member Functions

 MediaObject (const MediaSource &, QObject *parent)
 
 ~MediaObject () override
 
void clearQueue ()
 
bool closePort (const Port &)
 
MediaSource currentSource () const
 
QList< SubStreamDescription > currentSubStreams (MediaStreamType=AllMedia)
 
qint64 currentTime () const
 
QList< DecoderParameter > decoderParameters (const Port &port)
 
QWidgetdecoderParameterWidget (const Port &port)
 
void enqueue (const MediaSource &source)
 
void enqueue (const QList< MediaSource > &sources)
 
void enqueue (const QList< QUrl > &urls)
 
QString errorString () const
 
ErrorType errorType () const
 
bool hasVideo () const
 
bool isPortValid (const Port &p)
 
bool isSeekable () const
 
QStringList metaData (const QString &key) const
 
QStringList metaData (Phonon::MetaData key) const
 
QMultiMap< QString, QStringmetaData () const
 
Port openPort (MediaStreamType type, const char *format=0)
 
qint32 prefinishMark () const
 
QList< MediaSourcequeue () const
 
qint64 remainingTime () const
 
bool selectSubstream (SubStreamDescription, const Port &port=Port())
 
void setCurrentSource (const MediaSource &source)
 
void setPrefinishMark (qint32 msecToEnd)
 
void setQueue (const QList< MediaSource > &sources)
 
void setQueue (const QList< QUrl > &urls)
 
void setTransitionTime (qint32 msec)
 
State state () const
 
qint32 tickInterval () const
 
qint64 totalTime () const
 
qint32 transitionTime () const
 
- Public Member Functions inherited from QObject
 QObject (QObject *parent)
 
bool blockSignals (bool block)
 
const QObjectListchildren () const const
 
QMetaObject::Connection connect (const QObject *sender, const char *signal, const char *method, Qt::ConnectionType type) const const
 
void deleteLater ()
 
void destroyed (QObject *obj)
 
bool disconnect (const char *signal, const QObject *receiver, const char *method) const const
 
bool disconnect (const QObject *receiver, const char *method) const const
 
void dumpObjectInfo ()
 
void dumpObjectInfo () const const
 
void dumpObjectTree ()
 
void dumpObjectTree () const const
 
QList< QByteArraydynamicPropertyNames () const const
 
virtual bool event (QEvent *e)
 
virtual bool eventFilter (QObject *watched, QEvent *event)
 
findChild (const QString &name, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QString &name, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QRegExp &regExp, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QRegularExpression &re, Qt::FindChildOptions options) const const
 
bool inherits (const char *className) const const
 
void installEventFilter (QObject *filterObj)
 
bool isWidgetType () const const
 
bool isWindowType () const const
 
void killTimer (int id)
 
virtual const QMetaObjectmetaObject () const const
 
void moveToThread (QThread *targetThread)
 
QString objectName () const const
 
void objectNameChanged (const QString &objectName)
 
QObjectparent () const const
 
QVariant property (const char *name) const const
 
 Q_CLASSINFO (Name, Value)
 
 Q_DISABLE_COPY (Class)
 
 Q_DISABLE_COPY_MOVE (Class)
 
 Q_DISABLE_MOVE (Class)
 
 Q_EMIT Q_EMIT
 
 Q_ENUM (...)
 
 Q_ENUM_NS (...)
 
 Q_ENUMS (...)
 
 Q_FLAG (...)
 
 Q_FLAG_NS (...)
 
 Q_FLAGS (...)
 
 Q_GADGET Q_GADGET
 
 Q_INTERFACES (...)
 
 Q_INVOKABLE Q_INVOKABLE
 
 Q_NAMESPACE Q_NAMESPACE
 
 Q_NAMESPACE_EXPORT (EXPORT_MACRO)
 
 Q_OBJECT Q_OBJECT
 
 Q_PROPERTY (...)
 
 Q_REVISION Q_REVISION
 
 Q_SET_OBJECT_NAME (Object)
 
 Q_SIGNAL Q_SIGNAL
 
 Q_SIGNALS Q_SIGNALS
 
 Q_SLOT Q_SLOT
 
 Q_SLOTS Q_SLOTS
 
qFindChild (const QObject *obj, const QString &name)
 
QList< T > qFindChildren (const QObject *obj, const QRegExp &regExp)
 
QList< T > qFindChildren (const QObject *obj, const QString &name)
 
qobject_cast (QObject *object)
 
qobject_cast (const QObject *object)
 
 QT_NO_NARROWING_CONVERSIONS_IN_CONNECT QT_NO_NARROWING_CONVERSIONS_IN_CONNECT
 
void removeEventFilter (QObject *obj)
 
void setObjectName (const QString &name)
 
void setParent (QObject *parent)
 
bool setProperty (const char *name, const QVariant &value)
 
bool signalsBlocked () const const
 
int startTimer (int interval, Qt::TimerType timerType)
 
int startTimer (std::chrono::milliseconds time, Qt::TimerType timerType)
 
QThreadthread () const const
 

Additional Inherited Members

- Static Public Member Functions inherited from QObject
QMetaObject::Connection connect (const QObject *sender, const char *signal, const QObject *receiver, const char *method, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, Functor functor)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, const QObject *context, Functor functor, Qt::ConnectionType type)
 
bool disconnect (const QMetaObject::Connection &connection)
 
bool disconnect (const QObject *sender, const char *signal, const QObject *receiver, const char *method)
 
bool disconnect (const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method)
 
bool disconnect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method)
 
QString tr (const char *sourceText, const char *disambiguation, int n)
 
QString trUtf8 (const char *sourceText, const char *disambiguation, int n)
 
- Public Attributes inherited from QObject
typedef QObjectList
 
- Protected Member Functions inherited from QObject
virtual void childEvent (QChildEvent *event)
 
virtual void connectNotify (const QMetaMethod &signal)
 
virtual void customEvent (QEvent *event)
 
virtual void disconnectNotify (const QMetaMethod &signal)
 
bool isSignalConnected (const QMetaMethod &signal) const const
 
int receivers (const char *signal) const const
 
QObjectsender () const const
 
int senderSignalIndex () const const
 
virtual void timerEvent (QTimerEvent *event)
 

Detailed Description

Interface for media playback of a given URL.

This class is the most important class in Phonon. Use it to open a media file at an arbitrary location, a CD or DVD or to stream media data from the application to the backend.

This class controls the state (play, pause, stop, seek) and you can use it to get a lot of information about the media data.

Notice that most functions of this class are asynchronous. That means if you call play() the object only starts playing when the stateChanged() signal tells you that the object changed into PlayingState. The states you can expect are documented for those methods.

A common usage example is the following:

media = new MediaObject(this);
connect(media, SIGNAL(finished()), SLOT(slotFinished());
media->setCurrentSource("/home/username/music/filename.ogg");
media->play();

If you want to play more than one media file (one after another) you can either tell MediaObject about all those files

media->setCurrentSource(":/sounds/startsound.ogg");
media->enqueue("/home/username/music/song.mp3");
media->enqueue(":/sounds/endsound.ogg");

or provide the next file just in time:

media->setCurrentSource(":/sounds/startsound.ogg");
connect(media, SIGNAL(aboutToFinish()), SLOT(enqueueNextSource()));
}
void enqueueNextSource()
{
media->enqueue("/home/username/music/song.mp3");
}

This integration is opt-in only and can be enabled by setting the PlaybackTracking property to true:

media->setProperty("PlaybackTracking", true);

This kind of information is normally used to provide a universal history view to the user, such as what songs were played when, regardless of the media player. This is in addition to any emails read, IM conversations, websites viewed, etc.

Author
Matthias Kretz kretz[email protected]@kde[email protected].org

Definition at line 93 of file mediaobject.h.

Property Documentation

qint32 Phonon::MediaObject::prefinishMark
readwrite

Get a signal before playback finishes.

This property specifies the time in milliseconds the prefinishMarkReached signal is emitted before the playback finishes. A value of 0 disables the signal.

Defaults to 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 behaviour because the backend might have more information available than your application does through totalTime and currentTime.
See also
prefinishMarkReached

Definition at line 136 of file mediaobject.h.

qint32 Phonon::MediaObject::tickInterval
readwrite

The time interval in milliseconds between two ticks.

The tick interval is the time that elapses between the emission of two tick signals. If you set the interval to 0 the tick signal gets disabled.

Defaults to 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 may fail:
int x = 200;
media->setTickInterval(x);
Q_ASSERT(x == producer->tickInterval());
On the other hand the following is guaranteed:
int x = 200;
media->setTickInterval(x);
Q_ASSERT(x >= producer->tickInterval() &&
x <= 2 * producer->tickInterval());
See also
tick

Definition at line 163 of file mediaobject.h.

qint32 Phonon::MediaObject::transitionTime
readwrite

Defines the time between media sources.

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

A transition time of 0 ms requests gapless playback (sample precise queueing of the next source).

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

Defaults to 0 (gapless playback).

Warning
This feature might not work reliably on every platform.

Definition at line 115 of file mediaobject.h.

Constructor & Destructor Documentation

PHONON_OBJECT_IMPL Phonon::MediaObject::~MediaObject ( )
override

Destroys the MediaObject.

Definition at line 51 of file mediaobject.cpp.

Member Function Documentation

void Phonon::MediaObject::aboutToFinish ( )
signal

Emitted before the playback of the whole queue stops.

When this signal is emitted you still have time to provide the next MediaSource (using enqueue()) so that playback continues.

This signal can be used to provide the next MediaSource just in time for the transition still to work.

See also
enqueue
void Phonon::MediaObject::bufferStatus ( int  percentFilled)
signal

Tells about the status of the buffer.

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

progressBar->setRange(0, 100); // this is the default
connect(media, SIGNAL(bufferStatus(int)), progressBar, SLOT(setValue(int)));
Parameters
percentFilledA number between 0 and 100 telling you how much the buffer is filled.
void Phonon::MediaObject::clear ( )
slot

Stops and removes all playing and enqueued media sources.

See also
setCurrentSource

Definition at line 257 of file mediaobject.cpp.

void Phonon::MediaObject::clearQueue ( )

Clears the queue of sources.

Definition at line 309 of file mediaobject.cpp.

MediaSource Phonon::MediaObject::currentSource ( ) const

Returns the current media source.

See also
setCurrentSource

Definition at line 223 of file mediaobject.cpp.

void Phonon::MediaObject::currentSourceChanged ( const Phonon::MediaSource newSource)
signal

Emitted when the MediaObject makes a transition to the next MediaSource in the queue().

In other words, it is emitted when an individual MediaSource is finished.

Parameters
newSourceThe source that starts to play at the time the signal is emitted.
qint64 Phonon::MediaObject::currentTime ( ) const

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

Returns
The current time in milliseconds.
See also
tick
QWidget* Phonon::MediaObject::decoderParameterWidget ( const Port &  port)

Returns 0 if there are no parameters for the given port/decoder.

media = new MediaObject;
media->setCurrentSource("/music/file.ogg");
output = new AudioOutput(Phonon::Music);
Path path(media, output);
QWidget *w = media->decoderParameterWidget(path.sourcePort());
if (w) {
w->setParent(this);
// or
// w->show();
}
void Phonon::MediaObject::enqueue ( const MediaSource source)

Appends one source to the queue.

Use this function to provide the next source just in time after the aboutToFinish signal was emitted.

See also
aboutToFinish
setQueue
clearQueue

Definition at line 284 of file mediaobject.cpp.

void Phonon::MediaObject::enqueue ( const QList< MediaSource > &  sources)

Appends multiple sources to the queue.

See also
setQueue
clearQueue

Definition at line 295 of file mediaobject.cpp.

void Phonon::MediaObject::enqueue ( const QList< QUrl > &  urls)

Appends multiple sources to the queue.

See also
setQueue
clearQueue

Definition at line 302 of file mediaobject.cpp.

QString Phonon::MediaObject::errorString ( ) const

Returns a human-readable description of the last error that occurred.

Definition at line 132 of file mediaobject.cpp.

ErrorType Phonon::MediaObject::errorType ( ) const

Tells your program what to do about the error.

See also
Phonon::ErrorType

Definition at line 146 of file mediaobject.cpp.

void Phonon::MediaObject::finished ( )
signal

Emitted when the object has finished playback.

It is not emitted if you call stop(), pause() or load(), but only on end-of-queue or a critical error.

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.
See also
currentSourceChanged
aboutToFinish
prefinishMarkReached
bool Phonon::MediaObject::hasVideo ( ) const

Check whether the media data includes a video stream.

Warning
This information cannot be known immediately. It is best to also listen to the hasVideoChanged signal.
connect(media, SIGNAL(hasVideoChanged(bool)), hasVideoChanged(bool));
media->setCurrentSource("somevideo.avi");
media->hasVideo(); // returns false;
}
void hasVideoChanged(bool b)
{
// b == true
media->hasVideo(); // returns true;
}
Returns
true if the media contains video data. false otherwise.
See also
hasVideoChanged
void Phonon::MediaObject::hasVideoChanged ( bool  hasVideo)
signal

Emitted whenever the return value of hasVideo() changes.

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().

Parameters
hasVideotrue The stream contains video and adding a VideoWidget will show a video. false There is no video data in the stream and adding a VideoWidget will show an empty (black) VideoWidget.
bool Phonon::MediaObject::isSeekable ( ) const

Check whether the current media may be seeked.

Warning
This information cannot be known immediately. It is best to also listen to the seekableChanged signal.
connect(media, SIGNAL(seekableChanged(bool)), seekableChanged(bool));
media->setCurrentSource("somevideo.avi");
media->isSeekable(); // returns false;
}
void seekableChanged(bool b)
{
// b == true
media->isSeekable(); // returns true;
}
Returns
true when the current media may be seeked. false otherwise.
See also
seekableChanged()
QStringList Phonon::MediaObject::metaData ( const QString key) const

Returns the strings associated with the given key.

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

Therefore the following should work with every backend:

A typical usage looks like this:

setMetaArtist (media->metaData("ARTIST" ));
setMetaAlbum (media->metaData("ALBUM" ));
setMetaTitle (media->metaData("TITLE" ));
setMetaDate (media->metaData("DATE" ));
setMetaGenre (media->metaData("GENRE" ));
setMetaTrack (media->metaData("TRACKNUMBER"));
setMetaComment(media->metaData("DESCRIPTION"));

For Audio CDs you can query

metaData("MUSICBRAINZ_DISCID");

to get a DiscID hash that you can use with the MusicBrainz service: http://musicbrainz.org/doc/ClientHOWTO

Definition at line 183 of file mediaobject.cpp.

QStringList Phonon::MediaObject::metaData ( Phonon::MetaData  key) const

Returns the strings associated with the given key.

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

Definition at line 160 of file mediaobject.cpp.

QMultiMap< QString, QString > Phonon::MediaObject::metaData ( ) const

Returns all meta data.

Definition at line 189 of file mediaobject.cpp.

void Phonon::MediaObject::metaDataChanged ( )
signal

This signal is emitted whenever the audio/video data that is being played is associated with new meta data.

E.g. for radio streams this happens when the next song is played.

You can get the new meta data with the metaData methods.

void Phonon::MediaObject::pause ( )
slot

Requests playback to pause.

If it was paused before nothing changes. If the media cannot be paused, some backends will internally call stop instead of pause.

Possible states right after this call:
  • PlayingState
  • PausedState
  • StoppedState
  • ErrorState

Definition at line 108 of file mediaobject.cpp.

void Phonon::MediaObject::play ( )
slot

Requests playback of the media data to start.

Playback only starts when stateChanged() signals that it goes into PlayingState, though.

Possible states right after this call:
  • BufferingState
  • PlayingState
  • ErrorState

Definition at line 100 of file mediaobject.cpp.

void Phonon::MediaObject::prefinishMarkReached ( qint32  msecToEnd)
signal

Emitted when there are only msecToEnd milliseconds left for playback.

Parameters
msecToEndThe remaining time until the playback queue finishes.
Warning
This signal is not emitted when there is another source in the queue. It is only emitted when the queue is empty.
See also
setPrefinishMark
prefinishMark
aboutToFinish
finished
QList< MediaSource > Phonon::MediaObject::queue ( ) const

Returns the queued media sources.

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

Definition at line 264 of file mediaobject.cpp.

qint64 Phonon::MediaObject::remainingTime ( ) const

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

Returns
The remaining time in milliseconds.

Definition at line 210 of file mediaobject.cpp.

void Phonon::MediaObject::seek ( qint64  time)
slot

Requests a seek to the time indicated.

You can only seek if state() == 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.

Parameters
timeThe time in milliseconds where to continue playing.
Possible states right after this call:
  • BufferingState
  • PlayingState
  • ErrorState
See also
SeekSlider

Definition at line 124 of file mediaobject.cpp.

void Phonon::MediaObject::seekableChanged ( bool  isSeekable)
signal

Emitted whenever the return value of isSeekable() changes.

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

Parameters
isSeekabletrue if the stream is seekable (i.e. calling seek() works) false if the stream is not seekable (i.e. all calls to seek() will be ignored)
void Phonon::MediaObject::setCurrentSource ( const MediaSource source)

Set the media source the MediaObject should use.

Parameters
sourceThe MediaSource object to the media data. You can just as well use a QUrl or QString (for a local file) here. Setting an empty (invalid) source, will stop and remove the current source.
QUrl url("http://www.example.com/music.ogg");
media->setCurrentSource(url);
See also
currentSource

Definition at line 229 of file mediaobject.cpp.

void Phonon::MediaObject::setQueue ( const QList< MediaSource > &  sources)

Set the MediaSources to play when the current media has finished.

This function will overwrite the current queue.

See also
clearQueue
enqueue

Definition at line 270 of file mediaobject.cpp.

void Phonon::MediaObject::setQueue ( const QList< QUrl > &  urls)

Set the MediaSources to play when the current media has finished.

This function overwrites the current queue.

See also
clearQueue
enqueue

Definition at line 277 of file mediaobject.cpp.

void Phonon::MediaObject::setTickInterval ( qint32  newTickInterval)
slot

Sets the tick interval in milliseconds.

Parameters
newTickIntervalthe new tick interval in milliseconds.
See also
tickInterval
Phonon::State Phonon::MediaObject::state ( ) const

Get the current state.

Returns
The state of the object.
See also
State
stateChanged

Definition at line 69 of file mediaobject.cpp.

void Phonon::MediaObject::stateChanged ( Phonon::State  newstate,
Phonon::State  oldstate 
)
signal

Emitted when the state of the MediaObject has changed.

Parameters
newstateThe state the Player is in now.
oldstateThe state the Player was in before.
void Phonon::MediaObject::stop ( )
slot

Requests playback to stop.

If it was stopped before nothing changes.

Possible states right after this call:
  • the state it was in before (e.g. PlayingState)
  • StoppedState
  • ErrorState

Definition at line 116 of file mediaobject.cpp.

void Phonon::MediaObject::tick ( qint64  time)
signal

This signal gets emitted every tickInterval milliseconds.

Parameters
timeThe position of the media file in milliseconds.
See also
setTickInterval, tickInterval
qint32 Phonon::MediaObject::tickInterval ( ) const

The time interval in milliseconds between two ticks.

The tick interval is the time that elapses between the emission of two tick signals.

Returns
the tick interval in milliseconds
qint64 Phonon::MediaObject::totalTime ( ) const

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

Returns
The total time in milliseconds.
Note
The total time may change throughout playback as more accurate calculations become available, so it is recommended to connect and use the totalTimeChanged signal whenever possible unless best precision is not of importance.
Warning
The total time is undefined until the MediaObject entered the PlayingState. A valid total time is always indicated by emission of the totalTimeChanged signal.
See also
totalTimeChanged

Definition at line 201 of file mediaobject.cpp.

void Phonon::MediaObject::totalTimeChanged ( qint64  newTotalTime)
signal

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. Initially the totalTime function can not return useful information. You have to wait for this signal to know the real total time.

This signal may appear at any given point after a MediaSource was set. Namely in the LoadingState, BufferingState, PlayingState or PausedState.

Note
When changing the currentSource there is no signal emission until a reasonable value for the new source has been calculated.
Parameters
newTotalTimeThe length of the media file in milliseconds.
See also
totalTime

The documentation for this class was generated from the following files:
This file is part of the KDE documentation.
Documentation copyright © 1996-2020 The KDE developers.
Generated on Fri Jul 3 2020 23:06:07 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.