MediaObject Class Reference
(Phonon::MediaObject)
[Phonon module]

Detailed Description

The MediaObject class provides an interface for media playback.

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

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

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

   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;
 }

   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;
 }

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

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