|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.trolltech.qt.QSignalEmitter
com.trolltech.qt.QtJambiObject
com.trolltech.qt.core.QObject
com.trolltech.qt.phonon.MediaObject
public class MediaObject
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.
The following code example is written in c++.
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()
.
Phonon::MediaSource
, Phonon::AudioOutput
, VideoWidget
, Music Player Example, Phonon Overview, Phonon::VideoPlayer
, and Phonon::createPlayer()
.
Nested Class Summary |
---|
Nested classes/interfaces inherited from class com.trolltech.qt.QSignalEmitter |
---|
QSignalEmitter.Signal0, QSignalEmitter.Signal1, QSignalEmitter.Signal2, QSignalEmitter.Signal3, QSignalEmitter.Signal4, QSignalEmitter.Signal5, QSignalEmitter.Signal6, QSignalEmitter.Signal7, QSignalEmitter.Signal8, QSignalEmitter.Signal9 |
Field Summary | |
---|---|
QSignalEmitter.Signal0 |
aboutToFinish
Emitted before the playback of the whole queue stops. |
QSignalEmitter.Signal1 |
bufferStatus
Provides information about the status of the buffer. |
QSignalEmitter.Signal1 |
currentSourceChanged
Emitted when the MediaObject makes a transition to the next MediaSource in the queue. |
QSignalEmitter.Signal0 |
finished
Emitted when the object has finished playback. |
QSignalEmitter.Signal1 |
hasVideoChanged
Emitted whenever the return value of hasVideo() changes. |
QSignalEmitter.Signal0 |
metaDataChanged
This signal is emitted when the media object has resolved new meta data. |
QSignalEmitter.Signal1 |
prefinishMarkReached
Emitted when there are only msecToEnd milliseconds left for playback. |
QSignalEmitter.Signal1 |
seekableChanged
Emitted whenever the return value of isSeekable() changes. |
QSignalEmitter.Signal2 |
stateChanged
This signal is emitted when the state of the MediaObject has changed. |
QSignalEmitter.Signal1 |
tick
This signal is emitted in intervals defined by the tickInterval property. |
QSignalEmitter.Signal1 |
totalTimeChanged
This signal is emitted as soon as the total time of the media file is known or has changed. |
Method Summary | |
---|---|
void |
clearQueue()
Clears the queue of sources. |
MediaSource |
currentSource()
Returns the current media source. |
long |
currentTime()
Returns the current time (in milliseconds), i.e., position in the media stream, of the file currently being played. |
void |
enqueue(java.util.List sources)
Appends multiple sources to the queue. |
void |
enqueue(MediaSource source)
Appends one source to the queue. |
void |
enqueueUrls(java.util.List urls)
Appends the URLs in urls to the media source queue. |
java.lang.String |
errorString()
Returns a human-readable description of the last error that occurred. |
Phonon.ErrorType |
errorType()
Tells your program what to do about the last error that occurred. |
static MediaObject |
fromNativePointer(QNativePointer nativePointer)
|
boolean |
hasVideo()
Check whether the current media source includes a video stream. |
java.util.List |
inputPaths()
Returns the paths that inputs multimedia to this media node. |
boolean |
isSeekable()
Check whether it is possible to seek, i.e., change the playback position in the media stream. |
boolean |
isValid()
Returns true if the backend provides an implementation of this class; otherwise returns false. |
java.util.SortedMap |
metaData()
Returns all meta data in a multi map. |
java.util.List |
metaData(Phonon.MetaData key)
Returns the strings associated with the given key. |
java.util.List |
metaData(java.lang.String key)
Returns the strings associated with the given key. |
java.util.List |
outputPaths()
Returns the paths to which this media node output media. |
void |
pause()
Requests playback to pause, and the media object to enter the PausedState . |
void |
play()
Requests playback of the media data to start. |
int |
prefinishMark()
This property holds Get a signal before playback finishes. |
java.util.List |
queue()
Returns the queued media sources. |
long |
remainingTime()
Get the remaining time (in milliseconds) of the file currently being played. |
void |
seek(long time)
Requests a seek to the time indicated, specified in milliseconds. |
void |
setCurrentSource(MediaSource source)
Set the media source the MediaObject should use. |
void |
setPrefinishMark(int msecToEnd)
This property holds Get a signal before playback finishes. |
void |
setQueue(java.util.List sources)
Set the sources to play when the current source has finished. |
void |
setQueueToUrls(java.util.List urls)
Set the urls to play when the current media has finished. |
void |
setTickInterval(int newTickInterval)
This property holds The time interval in milliseconds between two ticks. |
void |
setTransitionTime(int msec)
This property Defines the time between media sources. |
Phonon.State |
state()
Returns the current Phonon::State of the object. |
void |
stop()
Requests playback to stop, and the media object to enter the StoppedState . |
int |
tickInterval()
This property holds The time interval in milliseconds between two ticks. |
long |
totalTime()
Get the total time (in milliseconds) of the file currently being played. |
int |
transitionTime()
This property Defines the time between media sources. |
Methods inherited from class com.trolltech.qt.core.QObject |
---|
childEvent, children, connectSlotsByName, customEvent, disposeLater, dumpObjectInfo, dumpObjectTree, dynamicPropertyNames, event, eventFilter, findChild, findChild, findChild, findChildren, findChildren, findChildren, findChildren, indexOfProperty, installEventFilter, isWidgetType, killTimer, moveToThread, objectName, parent, properties, property, removeEventFilter, setObjectName, setParent, setProperty, startTimer, timerEvent, toString, userProperty |
Methods inherited from class com.trolltech.qt.QtJambiObject |
---|
dispose, disposed, equals, finalize, reassignNativeResources, tr, tr, tr |
Methods inherited from class com.trolltech.qt.QSignalEmitter |
---|
blockSignals, disconnect, disconnect, signalsBlocked, signalSender, thread |
Methods inherited from class java.lang.Object |
---|
clone, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Methods inherited from interface com.trolltech.qt.QtJambiInterface |
---|
disableGarbageCollection, nativeId, nativePointer, reenableGarbageCollection, setJavaOwnership |
Field Detail |
---|
public final QSignalEmitter.Signal0 aboutToFinish
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.
enqueue()
.
public final QSignalEmitter.Signal1 bufferStatus
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.
public final QSignalEmitter.Signal1 currentSourceChanged
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.
public final QSignalEmitter.Signal0 finished
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.
currentSourceChanged()
, aboutToFinish()
, and prefinishMarkReached()
.
public final QSignalEmitter.Signal1 hasVideoChanged
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
.
public final QSignalEmitter.Signal0 metaDataChanged
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.
metaData()
, currentSourceChanged()
, stateChanged()
, and Phonon::State
.
public final QSignalEmitter.Signal1 prefinishMarkReached
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.
setPrefinishMark()
, prefinishMark()
, aboutToFinish()
, and finished()
.
public final QSignalEmitter.Signal1 seekableChanged
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).
public final QSignalEmitter.Signal2 stateChanged
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.
public final QSignalEmitter.Signal1 tick
public final QSignalEmitter.Signal1 totalTimeChanged
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.
totalTime()
.
Method Detail |
---|
public final void clearQueue()
public final MediaSource currentSource()
setCurrentSource()
.
public final long currentTime()
tick()
, totalTime()
, and remainingTime()
.
public final void enqueue(MediaSource source)
You can use this function to provide the next source after the aboutToFinish()
signal was emitted.
aboutToFinish()
, setQueue()
, and clearQueue()
.
public final void enqueue(java.util.List sources)
setQueue()
, and clearQueue()
.
public final void enqueueUrls(java.util.List urls)
setQueue()
, and clearQueue()
.
public final java.lang.String errorString()
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.
Phonon::ErrorState
, and stateChanged()
.
public final Phonon.ErrorType errorType()
stateChanged()
signal with ErrorState
. Phonon::ErrorType
, Phonon::ErrorState
, and stateChanged()
.
public final boolean hasVideo()
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.
hasVideoChanged()
.
public final java.util.List inputPaths()
outputPaths()
.
public final boolean isSeekable()
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.
seekableChanged()
.
public final boolean isValid()
This does not guarantee that instances of the class works as expected, but that the backend has implemented the functionality for this class. For instance, Qt's GStreamer
backend will return true for instances of the AudioOutput
class, even if there is a problem with GStreamer
and it could not play sound.
public final java.util.SortedMap metaData()
metaDataChanged()
.
public final java.util.List metaData(Phonon.MetaData key)
Same as above except that the keys are defined in the Phonon::MetaData
enum.
metaDataChanged()
.
public final java.util.List metaData(java.lang.String 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"));
public final java.util.List outputPaths()
inputPaths()
.
public final void pause()
PausedState
. If it was paused already, nothing changes. This function is asynchronous and the media might not be paused immediately.
play()
, stop()
, and stateChanged()
.
public final void play()
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.
stop()
, pause()
, and stateChanged()
.
public final int prefinishMark()
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 behavior because the backend might have more information available than your application does through totalTime()
and currentTime()
.
prefinishMarkReached()
.
public final java.util.List queue()
This does list does not include the current source, returned by currentSource()
.
setQueue()
, and enqueue()
.
public final long remainingTime()
Returns the remaining time in milliseconds.
totalTime()
, currentTime()
, and totalTimeChanged()
.
public final void seek(long time)
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
.
SeekSlider
, and tick()
.
public final void setCurrentSource(MediaSource source)
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);
currentSource()
.
public final void setPrefinishMark(int msecToEnd)
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 behavior because the backend might have more information available than your application does through totalTime()
and currentTime()
.
prefinishMarkReached()
.
public final void setQueue(java.util.List sources)
This function will overwrite the current queue.
clearQueue()
, and enqueue()
.
public final void setQueueToUrls(java.util.List urls)
This function overwrites the current queue.
clearQueue()
, and enqueue()
.
public final void setTickInterval(int newTickInterval)
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 <= 2producer->tickInterval());
tick()
.
public final void setTransitionTime(int msec)
A transition time of 0 ms requests gapless playback (sample precise queuing 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 with every backend.
public final Phonon.State state()
Phonon::State
of the object. Phonon::State
, and stateChanged()
.
public final void stop()
StoppedState
. If it was stopped before nothing changes. This function is asynchronous and the media might not be stopped immediately.
play()
, pause()
, and stateChanged()
.
public final int tickInterval()
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 <= 2producer->tickInterval());
tick()
.
public final long totalTime()
Returns the total time in milliseconds.
Warning: The total time is not defined before the media object enters the LoadingState
.
totalTimeChanged()
.
public final int transitionTime()
A transition time of 0 ms requests gapless playback (sample precise queuing 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 with every backend.
public static MediaObject fromNativePointer(QNativePointer nativePointer)
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |