Contents

• Properties
• Public Functions
• Public Slots
• Signals
• Detailed Description

Detailed Description

TheMediaObject class provides an interface for media playback.

The media object manages aMediaSource, which supplies the media object with multimedia content, e.g., from a file. A playback in Phonon is always started by calling the play() function.

The state of play (play, pause, stop, seek) is controlled by the media object, and you can also query the current state(). It keeps track of the playback position in the media stream, and emits the 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 stateChanged() signal. The description of theState enum gives a description of the different states.

Beforeplay() is called, the media object should be connected tooutput 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: theAudioOutput for audio content andVideoWidget for video content. If aMediaSource contains both audio and video, both nodes need to be connected to the media object.

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

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.

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

You can also make use of the aboutToFinish() signal, which is guaranteed to be emitted in time for altering the queue.

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

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 emitaboutToFinish() - shortly before the playback has finished - and thenfinished(). ThestateChanged() signal will also be emitted withPausedState, 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 tofinished() 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 theLoadingState. The data is queried by string keys - which should follow the Ogg Vorbis specificationhttp://xiph.org/vorbis/doc/v-comment.html - or by using theMetaData 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 withErrorState. The severity of the error can be queried by theErrorType. With aNormalError, it might be possible to continue the playback, for instance, if only audio playback fails for a media source which also has video. AFatalError 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 byerrorString().

Property Documentation

prefinishMark :qint32

This property holds the time when the prefinishMarkReached signal is emitted before playback ends.

This property specifies the time in milliseconds theprefinishMarkReached() signal is emitted before the playback finishes. A value of0 disables the signal. The signal is only emitted for the last source in themedia queue.

Defaults to0 (disabled).

Warning: For some media data the total time cannot be determined accurately, therefore the accuracy of theprefinishMarkReached signal can be bad sometimes. Still, it is better to use this method than to look attotalTime() andcurrentTime() to emulate the behavior because the backend might have more information available than your application does throughtotalTime() andcurrentTime().

Access functions:

See alsoprefinishMarkReached().

tickInterval :qint32

This property holds the time interval in milliseconds between two ticks.

Thetick() 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 to0 the tick signal gets disabled.

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

Defaults to0 (disabled).

Warning: The back-end is free to choose a different tick interval close to what you asked for. This means that the following codemay 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<=2producer->tickInterval());

Access functions:

See alsotick().

transitionTime :qint32

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

Access functions:

Member Function Documentation

MediaObject::~MediaObject()

Destroys theMediaObject.

[signal]void MediaObject::aboutToFinish()

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

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

See alsoenqueue(),prefinishMark, andprefinishMarkReached().

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

Provides information about the status of the buffer.

When aMediaObject is in theBufferingState, 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 inBufferingState:

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

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

[slot]void MediaObject::clear()

Stops and removes all playing and enqueued media sources.

See alsosetCurrentSource().

void MediaObject::clearQueue()

Clears the queue of media sources.

See alsoqueue() andenqueue().

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 withsetCurrentSource() or taken from the mediaqueue() when a media source has finished playing.

See alsosetCurrentSource().

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

Emitted when theMediaObject fetches a newMediaSource from thequeue() and before it enters theLoadingState for the new source. The media object will take a new source from thequeue() when it has finished the playback of thecurrent 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 alsotick(),totalTime(), andremainingTime().

void MediaObject::enqueue(constMediaSource & source)

Appendssource to the queue.

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

See alsoaboutToFinish(),setQueue(), andclearQueue().

void MediaObject::enqueue(constQList<MediaSource> & sources)

Appends multiplesources to the queue.

See alsosetQueue() andclearQueue().

void MediaObject::enqueue(constQList<QUrl> & urls)

Appends the URLs inurls to the media source queue.

The function will createMediaSources from theQUrls, and append these to the queue.

See alsosetQueue() andclearQueue().

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 thestateChanged() signal is emitted withErrorState.

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 alsoPhonon::ErrorState andstateChanged().

ErrorType MediaObject::errorType() const

Tells your program what to do about the last error that occurred. Use this function after receiving astateChanged() signal withErrorState.

See alsoPhonon::ErrorType,Phonon::ErrorState, andstateChanged().

[signal]void MediaObject::finished()

Emitted when the object has finished playback. It is not emitted if you callstop(),pause() or load(). It is emitted only when the current media source has finished playing and the mediaqueue() is empty, or when afatal 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 alsocurrentSourceChanged(),aboutToFinish(), andprefinishMarkReached().

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 thehasVideoChanged() 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;}

Returnstrue if the media contains video data; otherwise, returnsfalse.

See alsohasVideoChanged().

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

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

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

hasVideo is true when the stream contains video and adding aVideoWidget will show a video, and false if there is no video data in the stream and adding aVideoWidget 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. ThehasVideoChanged() 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;}

Returnstrue if the current media may be seeked; otherwise, returnsfalse.

See alsoseekableChanged().

QStringList MediaObject::metaData(constQString & key) const

Returns the strings associated with the givenkey.

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

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

See alsometaDataChanged().

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

Returns all meta data in a multi map.

See alsometaDataChanged().

[signal]void MediaObject::metaDataChanged()

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

You can get the new meta data with themetaData methods.

See alsometaData(),currentSourceChanged(),stateChanged(), andPhonon::State.

[slot]void MediaObject::pause()

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

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

See alsoplay(),stop(), andstateChanged().

[slot]void MediaObject::play()

Requests playback of the media data to start.

Playback starts when thestateChanged() signal is emitted withPlayingState.

If the media object is already in aPlayingState, nothing happens.

See alsostop(),pause(), andstateChanged().

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

Emitted when there are onlymsecToEnd 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 alsosetPrefinishMark(),prefinishMark(),aboutToFinish(), andfinished().

QList<MediaSource> MediaObject::queue() const

Returns the queued media sources.

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

See alsosetQueue() andenqueue().

qint64 MediaObject::remainingTime() const

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

Returns the remaining time in milliseconds.

See alsototalTime(),currentTime(), andtotalTimeChanged().

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

Requests a seek to thetime indicated, specified in milliseconds.

You can only seek ifstate() isPlayingState,BufferingState orPausedState.

The call is asynchronous, socurrentTime 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 classSeekSlider.

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

See alsoSeekSlider andtick().

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

This signal is emitted when the media object's ability to seek in the media stream changes.isSeekable is true if it is possible toseek(); 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 checkisSeekable() after setting a new media source, and then let this signal tell you when seeking is possible. That way you don't have to pollisSeekable().

void MediaObject::setCurrentSource(constMediaSource & source)

Set the media source theMediaObject should use.

After the media object receives a new source, it will enter theLoadingState. When it is ready to play, it enters theStoppedState unless another state has been requested, e.g., by callingplay().

source is theMediaSource object to the media data. You can just as well use aQUrl orQString (for a local file) here.

We show an example:

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

See alsocurrentSource() andMediaSource.

void MediaObject::setQueue(constQList<MediaSource> & sources)

Set thesources to play when the current source has finished.

This function will overwrite the current queue.

See alsoclearQueue() andenqueue().

void MediaObject::setQueue(constQList<QUrl> & urls)

Set theurls to play when the current media has finished.

This function overwrites the current queue.

See alsoclearQueue() andenqueue().

State MediaObject::state() const

Returns the currentPhonon::State of the object.

See alsoPhonon::State andstateChanged().

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

This signal is emitted when the state of theMediaObject has changed. Theoldstate andnewstate 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.

[slot]void MediaObject::stop()

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

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

See alsoplay(),pause(), andstateChanged().

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

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

See alsotickInterval.

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

See alsototalTimeChanged().

[signal]void 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 thetotalTime 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 alsototalTime().