|  | Home · All Classes · Modules

# Phonon.MediaObject Class Reference
[phonon module]

The MediaObject class provides an interface for media playback. More...

Inherits QObject and MediaNode.

### Methods

- __init__ (self, QObject parent = None)
- clearQueue (self)
- MediaSource currentSource (self)
- long currentTime (self)
- enqueue (self, MediaSource source)
- enqueue (self, QList<Phonon::MediaSource> sources)
- enqueue (self, QUrl-list urls)
- QString errorString (self)
- ErrorType errorType (self)
- bool hasVideo (self)
- bool isSeekable (self)
- QStringList metaData (self, QString key)
- QStringList metaData (self, MetaData key)
- QString-QString-list-dict metaData (self)
- pause (self)
- play (self)
- int prefinishMark (self)
- QList<Phonon::MediaSource> queue (self)
- long remainingTime (self)
- seek (self, long time)
- setCurrentSource (self, MediaSource source)
- setPrefinishMark (self, int msecToEnd)
- setQueue (self, QList<Phonon::MediaSource> sources)
- setQueue (self, QUrl-list urls)
- setTickInterval (self, int newTickInterval)
- setTransitionTime (self, int msec)
- State state (self)
- stop (self)
- int tickInterval (self)
- long totalTime (self)
- int transitionTime (self)

### Qt Signals

- void aboutToFinish ()
- void bufferStatus (int)
- void currentSourceChanged (const Phonon::MediaSource&)
- void finished ()
- void hasVideoChanged (bool)
- void metaDataChanged ()
- void prefinishMarkReached (int)
- void seekableChanged (bool)
- void stateChanged (Phonon::State,Phonon::State)
- void tick (PY_LONG_LONG)
- void totalTimeChanged (PY_LONG_LONG)

## Detailed Description

The MediaObject class provides an interface for media playback.

Author: Matthias Kretz <kretz@kde.org>

The media object manages a MediaSource, 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 the State enum gives a description of the different states.

Before play() is called, the media object should be connected to 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 AudioOutput for audio content and VideoWidget for video content. If a MediaSource 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 emit aboutToFinish() - shortly before the playback has finished - and then finished(). The stateChanged() signal will also be emitted with 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 LoadingState. The data is queried by string keys - which should follow the Ogg Vorbis specification http://xiph.org/vorbis/doc/v-comment.html - or by using the 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 ErrorState. The severity of the error can be queried by the ErrorType. With a 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 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().

See also Phonon.MediaSource, Phonon.AudioOutput, VideoWidget, Music Player Example, Phonon Overview, Phonon.VideoPlayer, and Phonon.createPlayer().

## Method Documentation

### MediaObject.__init__ (self, QObject parent = None)

The parent argument, if not None, causes self to be owned by Qt instead of PyQt.

### MediaObject.clearQueue (self)

Clears the queue of sources.

### MediaSource MediaObject.currentSource (self)

Returns the current media source.

See also setCurrentSource().

### long MediaObject.currentTime (self)

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

### MediaObject.enqueue (self, MediaSource source)

Appends one source to the queue.

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

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

### MediaObject.enqueue (self, QList<Phonon::MediaSource> sources)

This is an overloaded member function, provided for convenience.

Appends multiple sources to the queue.

See also setQueue() and clearQueue().

### MediaObject.enqueue (self, QUrl-list urls)

This is an overloaded member function, provided for convenience.

Appends the URLs in urls to the media source queue.

See also setQueue() and clearQueue().

### QString MediaObject.errorString (self)

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

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

### bool MediaObject.hasVideo (self)

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

### bool MediaObject.isSeekable (self)

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 (self, QString key)

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 (self, MetaData key)

This is an overloaded member function, provided for convenience.

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

### QString-QString-list-dict MediaObject.metaData (self)

This is an overloaded member function, provided for convenience.

Returns all meta data in a multi map.

See also metaDataChanged().

### MediaObject.pause (self)

This method is also a Qt slot with the C++ signature `void pause()`.

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

### MediaObject.play (self)

This method is also a Qt slot with the C++ signature `void play()`.

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 or in the error state, nothing happens.

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

### int MediaObject.prefinishMark (self)

### QList<Phonon::MediaSource> MediaObject.queue (self)

Returns the queued media sources.

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

See also setQueue() and enqueue().

### long MediaObject.remainingTime (self)

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

Returns the remaining time in milliseconds.

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

### MediaObject.seek (self, long time)

This method is also a Qt slot with the C++ signature `void seek(PY_LONG_LONG)`.

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.

See also SeekSlider and tick().

### MediaObject.setCurrentSource (self, 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().

### MediaObject.setPrefinishMark (self, int msecToEnd)

### MediaObject.setQueue (self, QList<Phonon::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().

### MediaObject.setQueue (self, QUrl-list urls)

This is an overloaded member function, provided for convenience.

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

This function overwrites the current queue.

See also clearQueue() and enqueue().

### MediaObject.setTickInterval (self, int newTickInterval)

This method is also a Qt slot with the C++ signature `void setTickInterval(int)`.

### MediaObject.setTransitionTime (self, int msec)

### State MediaObject.state (self)

Returns the current Phonon.State of the object.

See also Phonon.State and stateChanged().

### MediaObject.stop (self)

This method is also a Qt slot with the C++ signature `void stop()`.

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

### int MediaObject.tickInterval (self)

### long MediaObject.totalTime (self)

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

### int MediaObject.transitionTime (self)

## Qt Signal Documentation

### void aboutToFinish ()

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 bufferStatus (int)

Provides information 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)));

percentFilled is a number between 0 and 100 telling you how much the buffer is filled.

### void currentSourceChanged (const Phonon::MediaSource&)

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.

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

### void finished ()

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(), and prefinishMarkReached().

### void hasVideoChanged (bool)

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

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.

### void metaDataChanged ()

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 prefinishMarkReached (int)

Emitted when there are only msecToEnd milliseconds left for playback.

msecToEnd The 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(), and finished().

### void seekableChanged (bool)

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

isSeekable is true if the stream is seekable (i.e. calling seek() works), and false if the stream is not seekable (i.e. all calls to seek() will be ignored).

### void stateChanged (Phonon::State,Phonon::State)

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

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 and is specified in milliseconds.

See also tickInterval.

### void totalTimeChanged (PY_LONG_LONG)

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