MediaObject Class Reference

 #include <Phonon/MediaObject>

     Phonon::MediaObject *mediaObject = new Phonon::MediaObject(this);

     Phonon::VideoWidget *videoWidget = new Phonon::VideoWidget(this);
     Phonon::createPath(mediaObject, videoWidget);

     Phonon::AudioOutput *audioOutput =
         new Phonon::AudioOutput(Phonon::VideoCategory, this);
     Phonon::createPath(mediaObject, audioOutput);
     mediaObject->play();

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

   media->setCurrentSource(":/sounds/startsound.ogg");
   connect(media, SIGNAL(aboutToFinish()), SLOT(enqueueNextSource()));
 }

 void enqueueNextSource()
 {
   media->enqueue("/home/username/music/song.mp3");
 }

 int x = 200;
 media->setTickInterval(x);
 Q_ASSERT(x == producer->tickInterval());

 int x = 200;
 media->setTickInterval(x);
 Q_ASSERT(x >= producer->tickInterval() &&
          x <= 2producer->tickInterval());

Member Function Documentation

MediaObject::~MediaObject ()

Destroys the MediaObject.

void MediaObject::aboutToFinish () [signal]

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.

See also enqueue(), prefinishMark, and prefinishMarkReached().

void MediaObject::bufferStatus ( int percentFilled ) [signal]

Provides information about the status of the buffer.

When a MediaObject is in the BufferingState, it will send this signal regularly. 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:

 progressBar->setRange(0, 100); // this is the default
 connect(media, SIGNAL(bufferStatus(int)), progressBar, SLOT(setValue(int)));

Note that the BufferingState is commonly used when waiting for data over a network connection, but this might not be true for all backends.

void MediaObject::clear () [slot]

Stops and removes all playing and enqueued media sources.

See also setCurrentSource().

void MediaObject::clearQueue ()

Clears the queue of media sources.

See also queue() and enqueue().

MediaSource 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.

See also setCurrentSource().

void MediaObject::currentSourceChanged ( const Phonon::MediaSource & newSource ) [signal]

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

newSource is the source that starts to play at the time the signal is emitted.

qint64 MediaObject::currentTime () const

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

See also tick(), totalTime(), and remainingTime().

void MediaObject::enqueue ( const MediaSource & source )

Appends source to the queue.

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

See also aboutToFinish(), setQueue(), and clearQueue().

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

Appends multiple sources to the queue.

See also setQueue() and clearQueue().

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

Appends the URLs in urls to the media source queue.

The function will create MediaSources from the QUrls, and append these to the queue.

See also setQueue() and clearQueue().

QString 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 ErrorState.

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: 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.

See also Phonon::ErrorState and stateChanged().

ErrorType MediaObject::errorType () const

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

See also Phonon::ErrorType, Phonon::ErrorState, and stateChanged().

void MediaObject::finished () [signal]

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

See also currentSourceChanged(), aboutToFinish(), and prefinishMarkReached().

bool 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.

   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; otherwise, returns false.

See also hasVideoChanged().

void MediaObject::hasVideoChanged ( bool hasVideo ) [signal]

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

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.

bool 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.

   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 current media may be seeked; otherwise, returns false.

See also seekableChanged().

QStringList 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:

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

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"));

QStringList 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.

See also metaDataChanged().

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

Returns all meta data in a multi map.

See also metaDataChanged().

void MediaObject::metaDataChanged () [signal]

This signal is emitted when the media object has resolved new meta data. This will happen before the media object leaves the 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 ErrorState, and connect to the currentSourceChanged() signal.

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

See also metaData(), currentSourceChanged(), stateChanged(), and Phonon::State.

void MediaObject::pause () [slot]

Requests playback to pause, and the media object to enter the PausedState. If it was paused already, nothing changes.

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

See also play(), stop(), and stateChanged().

void MediaObject::play () [slot]

Requests playback of the media data to start.

Playback starts when the stateChanged() signal is emitted with PlayingState.

If the media object is already in a PlayingState, nothing happens.

See also stop(), pause(), and stateChanged().

void MediaObject::prefinishMarkReached ( qint32 msecToEnd ) [signal]

Emitted when there are only 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.

See also setPrefinishMark(), prefinishMark(), aboutToFinish(), and finished().

QList<MediaSource> MediaObject::queue () const

Returns the queued media sources.

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

See also setQueue() and enqueue().

qint64 MediaObject::remainingTime () const

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

Returns the remaining time in milliseconds.

See also totalTime(), currentTime(), and totalTimeChanged().

void MediaObject::seek ( qint64 time ) [slot]

Requests a seek to the 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.

See also SeekSlider and tick().

void MediaObject::seekableChanged ( bool isSeekable ) [signal]

This signal is emitted when the media object's ability to seek in the media stream changes. 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.

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

void 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 LoadingState. When it is ready to play, it enters the StoppedState unless another state has been requested, e.g., by calling play().

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:

 QUrl url("http://www.example.com/music.ogg");
 media->setCurrentSource(url);

See also currentSource() and MediaSource.

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

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

This function will overwrite the current queue.

See also clearQueue() and enqueue().

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

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

This function overwrites the current queue.

See also clearQueue() and enqueue().

State MediaObject::state () const

Returns the current Phonon::State of the object.

See also Phonon::State and stateChanged().

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

This signal is emitted when the state of the MediaObject has changed. The oldstate and 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.

void MediaObject::stop () [slot]

Requests playback to stop, and the media object to enter the StoppedState. If it was stopped before nothing changes.

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

See also play(), pause(), and stateChanged().

void MediaObject::tick ( qint64 time ) [signal]

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

See also tickInterval.

qint64 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 LoadingState.

See also totalTimeChanged().

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

newTotalTime is the length of the media file in milliseconds.

See also totalTime().