|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectoctoshape.osa2.android.StreamPlayer
public final class StreamPlayer
An object which is able to make the Octoshape client play a given stream.
After construction it is recommended to add any listeners needed.
To have a minimal working StreamPlayer
at least use the setListener(StreamPlayerListener)
and
setProblemListener(ProblemListener)
.
After that call initialize(boolean)
or one of the requestPlay...
methods, for instance requestPlay()
.
Field Summary | |
---|---|
static byte |
STATUS_CLOSED
The StreamPlayer is closed. |
static byte |
STATUS_INITIALIZING
The StreamPlayer is currently initializing. |
static byte |
STATUS_PLAY_INITIALIZING
The StreamPlayer is preparing to play, i.e. a requestPlay.. |
static byte |
STATUS_PLAYING
The StreamPlayer has reported a media player URL to be played (via the registered StreamPlayerListener). |
static byte |
STATUS_READY
The StreamPlayer is initialized. |
static byte |
STATUS_UNINITIALIZED
The StreamPlayer is not initialized. |
Method Summary | |
---|---|
void |
close(java.lang.Runnable onComplete)
Closes and disposes the object. |
java.lang.String |
getOctolink()
Gets the octolink set in the constructor. |
byte |
getStatus()
|
static java.lang.String |
getStatusString(byte status)
Returns text representation of a StreamPlayer status |
java.lang.String |
getThumbnailUrlForLatency(int latency)
Returns the URL of the thumbnail closest to the provided argument live latency. |
java.lang.String |
getThumbnailUrlForTimePosition(long octoTime)
Returns the URL of the thumbnail closest to the provided argument octoTime. |
void |
gotID3TextFrame(java.lang.String frameID,
byte[] frameData,
byte encoding,
boolean lastFrame)
Used to pass ID3 frames embedded in the stream to the Octoshape SDK |
void |
gotRawID3Tag(byte[] data)
Used to pass ID3 data embedded in the stream to the Octoshape SDK |
void |
initialize(boolean getInfo)
Will begin initialization of the StreamPlayer . |
void |
requestPlay()
A live stream will play live and an ondemand stream will play from the beginning of the file. |
void |
requestPlayAbort()
This aborts the current playing but allow for one of the other play functions to be called again later. |
void |
requestPlayLiveTimePosition(long startPosition)
This starts to play at a given position. |
void |
requestPlayLiveWithLatency(long latency)
This starts to play with a given latency in addition to live. |
void |
requestPlayOndemandMediaTimePosition(long startPosition)
This starts to play at a given position relative to the start of the file. |
void |
requestPlayOndemandPermilPosition(int permilPosition)
This function only applies to ondemand streams Note that this will call the initialize() method, if that has not already been done. |
void |
requestPlayOndemandTimePosition(long startPosition)
This starts to play at a given position. |
void |
requestTimeInfo(TimeInfoListener timeInfoListener)
Request a TimeInfo object for the currently playing stream. |
void |
requestTimeInfoOnNewFrame(TimeInfoListener timeInfoListener)
Request to receive a TimeInfo object each time the client reaches a new frame in the stream. |
void |
setAuthorization(java.lang.String authInfo,
java.lang.String authHash)
Informs the Octoshape system of obtained authentication. |
void |
setListener(StreamPlayerListener listener)
Setting a listener to listen for when the Octoshape client is ready to play and have provided an URL that a media player can connect to. |
void |
setMultiStreamInfoListener(MultiStreamInfoListener listner)
Setting listener to receive multistream and basestream information for the stream. |
void |
setOctolinkOption(java.lang.String option,
java.lang.String value)
Setting arbitrary low-level Octoshape link option. |
void |
setOpenAttribute(java.lang.String attribute,
java.lang.String value)
Setting arbitrary Low-level open command attribute. |
void |
setPlayAttribute(java.lang.String attribute,
java.lang.String value)
Setting arbitrary Low-level play command attribute. |
void |
setPlayerValidation(java.lang.String method,
java.lang.String playerSecret)
If this stream is configured to require player validation, then the method and secret must be set here. |
void |
setProblemListener(ProblemListener problemListener)
Setting a listener to listen for basic stream problems. |
void |
setStatusChangedListener(StatusChangedListener listener)
Setting a listener to listen for changes to the status. |
void |
setStreamConfigurationListener(StreamConfigurationListener listner)
Setting listener to receive information on how the stream is configured in the Octoshape system. |
void |
setStreamInfoListener(StreamInfoListener listner)
Setting listener to receive stream source information for the stream. |
void |
setStreamSignalListener(StreamSignalListener listener)
Setting a listener to listen for Octoshape stream signals. |
void |
setUMetaDataListener(UMetaDataListener listener)
Setting listener to receive Octoshape u-meta data for the currently playing stream. |
java.lang.String |
toString()
|
Methods inherited from class java.lang.Object |
---|
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Field Detail |
---|
public static final byte STATUS_UNINITIALIZED
Either the initialize() method have never been called, or some problem occurred.
getStatus()
,
setProblemListener(ProblemListener)
,
Constant Field Valuespublic static final byte STATUS_INITIALIZING
getStatus()
,
Constant Field Valuespublic static final byte STATUS_READY
Calling one of the requestPlay methods should fairly quickly result in call to the registered UrlListener.
getStatus()
,
Constant Field Valuespublic static final byte STATUS_PLAY_INITIALIZING
requestPlay..
method has been called,
but the request has not resulted in a media player URL (or a problem) yet.
getStatus()
,
Constant Field Valuespublic static final byte STATUS_PLAYING
getStatus()
,
setListener(StreamPlayerListener)
,
Constant Field Valuespublic static final byte STATUS_CLOSED
The close method have been called, which means that this object can not be used again.
getStatus()
,
close(Runnable)
,
Constant Field ValuesMethod Detail |
---|
public void initialize(boolean getInfo)
StreamPlayer
.
Should be called after setting listeners.
If the StreamPlayer
is already initialized, or currently in the process of initializing, calling this has no effect.
Otherwise the status will go to STATUS_INITIALIZING
, and finally to STATUS_READY
.
The argument getInfo
indicates if stream information that is normally only available
after beginning to play the stream, should be retrieved already during the initialization phase.
Normally we get this information from the Octoshape system right before the StreamPlayer
begins to play for the first time, i.e after calling one of the requestPlay methods, but just before
the callback octoshape.osa2.listeners.StreamPlayerListener#gotUrl(String, long, boolean)
method is called.
This will happen if the argument getInfo
is set to false.
Note that retrieving this information during the initialization phase will incur a slight overhead,
so if this StreamPlayer is to be played right after initialization, then don't set getInfo
to true.
NB: Currently there may be some special cases where setting getInfo
to true has no effect, i.e. where the
information will only be ready after a request to play has been made. This is currently the case for FLV on-demand files.
(This is expected to be fixed in a future release of the Octoshape client protocol module (version 311)).
If the StreamPlayer
should start to play immediately, then calling this method explicitly is not necessary,
and doing so may even slow down the start up of the stream (This is only true when calling with argument
getInfo
set to true).
Note that if the open method of the OctoshapeSystem
has not been called, then the initialization can not proceed.
In this case the status will go to STATUS_INITIALIZING
, but nothing further will happen until
the OctoshapeSystem
is opened, then the initialization will continue.
Note also that the status may change back from READY or PLAYING to INITIALIZING or even to UNINITIALIZED, in rare cases. If it goes to INITIALIZING it means that it will shortly revert to the original READY or PLAYING state. This may happen if the OctoshapeSystem class temporarily losses the socket connection to the Octoshape client.
If a problem arises that can not be automatically fixed, then the StreamPlayer may go to the UNINITIALIZED state. If this happens then an appropriate problem will be given to the problem listener on either the StreamPlayer or the OctoshapeSystem class, depending on if the problem has to do with the OctoshapeSystem connection as such (i.e. concerning all StreamPlayers) or it is this specific to this StreamPlayer.
It is generally recommended to use the problem listeners and not StreamPlayer state changes to programmatically responding to error situations.
StreamPlayerListener
,
MultiStreamInfoListener
,
StreamConfigurationListener
public java.lang.String getOctolink()
public byte getStatus()
STATUS_PLAY_INITIALIZING
,
STATUS_PLAYING
public void setStreamSignalListener(StreamSignalListener listener)
listener
- Will replace any currently set listener. Call with null to remove a listener.public void gotRawID3Tag(byte[] data)
data,
- the unparsed byte data receivedpublic void gotID3TextFrame(java.lang.String frameID, byte[] frameData, byte encoding, boolean lastFrame)
frameID,
- ID3 frame idframeContent,
- ID3 frame contentencoding,
- currently supported encodings are ISO_8859_1 (0x0) and UTF-8 (0x3)lastFrame,
- indicates if this is the last frame within the ID3 tag.public void setListener(StreamPlayerListener listener)
listener
- Will replace any currently set listener. Call with null to remove a listener.public void setProblemListener(ProblemListener problemListener)
When a StreamPlayer
reports a problem it will typically mean that the
stream is no longer playing and that one of the play functions must be
called in order to resume playing.
Problems can occur at any time after calling initialize
.
Problems are reported even if stream stop was expected, (e.g, stopped by the user).
So problems may occur and there is not anything wrong and no error should be reported to the user.
If a problem should trigger a notification to the user is determined by the returned value of {link Problem#getMessage()
.
problemListener
- A ProblemListener
to receive problems as they occurpublic void setMultiStreamInfoListener(MultiStreamInfoListener listner)
listner
- Will replace any currently set listener. Call with null to remove a listener.public void setStreamInfoListener(StreamInfoListener listner)
listner
- Will replace any currently set listener. Call with null to remove a listener.public void setStreamConfigurationListener(StreamConfigurationListener listner)
Normally we get this information from the Octoshape system when the StreamPlayer
begins to play for the first time, i.e after calling one of the requestPlay methods.
Calling initialize(boolean)
with argument true, will
force the information to be retrieved during the initialization phase.
listner
- Will replace any currently set listener. Call with null to remove a listener.StreamConfigurationListener
public void setUMetaDataListener(UMetaDataListener listener)
listener
- public java.lang.String toString()
toString
in class java.lang.Object
public void setAuthorization(java.lang.String authInfo, java.lang.String authHash)
This method sets authorization information for the Octoshape ticket system. See separate documentation of the Octoshape Ticket System for details on how to use tickets.
This method must be called before any calls to initialize(boolean)
or requestPlay methods.
authInfo
- The "authInfo" string described in the Octoshape Ticket System documentation.authHash
- The "authHash" md5 sum as described in the Octoshape Ticket System documentation.public void requestPlayOndemandTimePosition(long startPosition)
Note that this will call the initialize()
method, if that has not already been done. Also if the StreamPlayer
is currently initializing, the play request will be sent as soon as the initialization ends.
startPosition
- an OctoTimeinitialize(boolean)
public void requestPlayOndemandMediaTimePosition(long startPosition)
Note that this will call the initialize()
method, if that has not already been done. Also if the StreamPlayer
is currently initializing, the play request will be sent as soon as the initialization ends.
startPosition
- Time relative to start of file in milliseconds.initialize(boolean)
public void requestPlayOndemandPermilPosition(int permilPosition)
Note that this will call the initialize()
method, if that has not already been done. Also if the StreamPlayer
is currently initializing, the play request will be sent as soon as the initialization ends.
permilPosition
- value from 0 to 1000initialize(boolean)
public void requestPlayLiveTimePosition(long startPosition)
Note that this will call the initialize()
method, if that has not already been done. Also if the StreamPlayer
is currently initializing, the play request will be sent as soon as the initialization ends.
startPosition
- an OctoTimeinitialize(boolean)
public void requestPlayAbort()
This will generate a {'userstop', 'normal'} problem event, unless another play method was called before this playing was finished. Note that there is no reason to call this function because we are going to play a different Octoshape stream: The old stream will automatically be stopped when the new starts. It is possible to play multiple streams concurrently by using special links (not covered by this documentation).
public void requestPlay()
Note that this will call the initialize()
method, if that has not already been done. Also if the StreamPlayer
is currently initializing, the play request will be sent as soon as the initialization ends.
initialize(boolean)
public void requestPlayLiveWithLatency(long latency)
This function only applies to live streams
Note that this will call the initialize()
method, if that has not already been done. Also if the StreamPlayer
is currently initializing, the play request will be sent as soon as the initialization ends.
latency
- The latency according to live, in milliseconds.initialize(boolean)
public void requestTimeInfo(TimeInfoListener timeInfoListener)
TimeInfo
object for the currently playing stream.
If we are not currently playing, then calling this will have no effect. Otherwise the the argument listener will be called one time, when the information is ready.
timeInfoListener
- The listener that will be called when the time information is ready.public void requestTimeInfoOnNewFrame(TimeInfoListener timeInfoListener)
TimeInfo
object each time the client reaches a new frame in the stream.
Currently this only works for live streams.
Replaces any previously set listener.
timeInfoListener
- The listener that will be called on every new frame.public void setPlayAttribute(java.lang.String attribute, java.lang.String value)
This method should not be used unless explicitly being told to do by an Octoshape developer. If an unknown attribute is set, or the value of a known attribute is not given in correct format, the session will close and playing will not be possible.
attribute
- value
- public void setOctolinkOption(java.lang.String option, java.lang.String value)
Note that this method must be called before calling
initialize()
or any of the requestPlay..
methods, for instance
immediately after construction.
This method should not be used unless explicitly being told to do by an Octoshape developer. If an unknown option is set, or the value of a known option is not given in correct format, the session may close and playing may not be possible.
option
- value
- public void setOpenAttribute(java.lang.String attribute, java.lang.String value)
Note that this method must be called before calling
initialize()
or any of the requestPlay..
methods, for instance
immediately after construction.
This method should not be used unless explicitly being told to do by an Octoshape developer. If an unknown option is set, or the value of a known option is not given in correct format, the session may close and playing may not be possible.
attribute
- value
- public void close(java.lang.Runnable onComplete)
This object can no longer be used after calling this method.
public java.lang.String getThumbnailUrlForTimePosition(long octoTime)
This method will return null if this stream is not configured to contain thumbnails, or if
the one of the resolved..
methods of the
StreamPlayerListener
has not been called yet for this stream.
Note that if the provided octotime is not valid for this stream, this method will still return an URL, but that URL will then not reference an actual thumbnail.
octoTime
- The time of the thumbnail to get, in octoTime.
public java.lang.String getThumbnailUrlForLatency(int latency)
This method will return null if this stream is not configured to contain thumbnails, or if
the one of the resolved..
methods of the
StreamPlayerListener
has not been called yet for this stream.
Note that if the provided live latency is not valid for this stream, this method will still return an URL, but that URL will then not reference an actual thumbnail.
This method works by approximating the OctoTime from the given latency, so it may less
precise than the getThumbnailUrlForTimePosition(long)
method.
latency
- The live latency of the thumbnail to get.
public void setPlayerValidation(java.lang.String method, java.lang.String playerSecret)
This method must be called before initializing or playing.
method
- playerSecret
- public void setStatusChangedListener(StatusChangedListener listener)
listener
- getStatus()
public static java.lang.String getStatusString(byte status)
listener
- getStatus()
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |