public class SubscriberKit
extends java.lang.Object
Subscriber
class,
which includes a pre-built video processor and renderer.
The stream property references the stream that you have subscribed to. The SubscriberKit class includes methods that let you disable and enable local audio and video playback for the subscribed stream.
Modifier and Type | Class and Description |
---|---|
static interface |
SubscriberKit.AudioLevelListener
Monitors changes in the audio level of the subscriber.
|
static interface |
SubscriberKit.AudioStatsListener
Defines the listener object for getting subscriber audio statistcs.
|
static class |
SubscriberKit.Builder
Used to build a
SubscriberKit object. |
static interface |
SubscriberKit.StreamListener
Monitors when the subscriber's stream is interrupted and resumes.
|
static class |
SubscriberKit.SubscriberAudioStats
Defines audio statistics for a subscriber.
|
static interface |
SubscriberKit.SubscriberListener
Monitors state changes of a
SubscriberKit instance. |
static class |
SubscriberKit.SubscriberVideoStats
Defines video statistics for a subscriber.
|
static interface |
SubscriberKit.VideoListener
Monitors when the subscriber starts and stops receiving video data.
|
static interface |
SubscriberKit.VideoStatsListener
Defines the listener object for getting subscriber video statistcs.
|
Modifier and Type | Field and Description |
---|---|
protected SubscriberKit.AudioLevelListener |
audioLevelListener |
static float |
NO_PREFERRED_FRAMERATE
Defines a reset value to passed into the
setPreferredFrameRate(float preferredFrameRate) method. |
static VideoUtils.Size |
NO_PREFERRED_RESOLUTION
Defines a reset value to passed into the
setPreferredResolution(VideoUtils.Size preferredResolution)
method. |
protected BaseVideoRenderer |
renderer |
protected Session |
session |
protected Stream |
stream |
protected SubscriberKit.StreamListener |
streamListener |
protected SubscriberKit.SubscriberListener |
subscriberListener |
static java.lang.String |
VIDEO_REASON_PUBLISH_VIDEO
The video event was caused by the stream's publisher starting or stopping
the video stream.
|
static java.lang.String |
VIDEO_REASON_QUALITY
The video event was caused by a change to the video stream quality.
|
static java.lang.String |
VIDEO_REASON_SUBSCRIBE_TO_VIDEO
The video event was caused by a call to the
setSubscribeToVideo(boolean subscribeToVideo)
method. |
protected SubscriberKit.VideoListener |
videoListener |
Modifier | Constructor and Description |
---|---|
|
SubscriberKit(android.content.Context context,
Stream stream)
Deprecated.
|
protected |
SubscriberKit(android.content.Context context,
Stream stream,
BaseVideoRenderer renderer)
Creates a new subscriber for a given stream.
|
Modifier and Type | Method and Description |
---|---|
protected void |
attachToSession(Session session) |
void |
destroy()
Releases this object, including all hardware and UI resources bound to it.
|
protected void |
detachFromSession(Session session) |
protected void |
finalize() |
float |
getPreferredFrameRate()
Returns the preferred frame rate for the subscriber's stream.
|
VideoUtils.Size |
getPreferredResolution()
Returns the preferred resolution for the subscriber's stream.
|
BaseVideoRenderer |
getRenderer()
Returns the video renderer for this subscriber.
|
Session |
getSession()
Returns the
Session that the subscriber is bound to (by calling
the connect() method of the Session object). |
Stream |
getStream()
Returns the
Stream that this instance is bound to. |
boolean |
getSubscribeToAudio()
Whether the Subscriber is subscribing to audio or not.
|
boolean |
getSubscribeToVideo()
Whether the Subscriber is subscribing to audio or not.
|
android.view.View |
getView()
Returns the android.view.View object that contains the Subscriber video.
|
protected void |
onConnected()
Invoked when the instance has successfully connected to the stream and begins playing
media.
|
protected void |
onDisconnected()
Invoked when the instance has successfully destroyed.
|
protected void |
onError(OpentokError error)
Invoked when a subscriber has failed to connect to the OpenTok server.
|
protected void |
onStreamDisconnected()
Called when the subscriber's stream has been interrupted.
|
protected void |
onStreamReconnected()
Called when the subscriber's stream has resumed, after the
onStreamDisconnected() method is called. |
protected void |
onVideoDataReceived()
Invoked when an subscriber initially receives video data.
|
protected void |
onVideoDisabled(java.lang.String reason)
Called when the subscriber stops receiving video.
|
protected void |
onVideoDisableWarning()
Called when the OpenTok Media Router determines that the stream quality has
degraded and the video will be disabled if the quality degrades further.
|
protected void |
onVideoDisableWarningLifted()
Called when the OpenTok Media Router determines that the stream quality has
improved to the point at which the video being disabled is not an immediate
risk.
|
protected void |
onVideoEnabled(java.lang.String reason)
Called when the subscriber's video stream starts (when there previously
was no video) or resumes (after video was disabled).
|
void |
setAudioLevelListener(SubscriberKit.AudioLevelListener listener)
Binds an
SubscriberKit.AudioLevelListener to this SubscriberKit instance to monitor audio
level updates. |
void |
setAudioStatsListener(SubscriberKit.AudioStatsListener listener)
Sets up a listener for subscriber audio statistics.
|
void |
setPreferredFrameRate(float preferredFrameRate)
Sets the preferred frame rate for the subscriber's stream.
|
void |
setPreferredResolution(VideoUtils.Size preferredResolution)
Sets the preferred resolution for the subscriber's stream.
|
void |
setRenderer(BaseVideoRenderer renderer)
Deprecated.
|
void |
setStreamListener(SubscriberKit.StreamListener listener)
Sets up a listener for events related to the subscriber's stream being interrupted and
resuming.
|
void |
setStyle(java.lang.String key,
java.lang.String value)
Set a style used by this subscriber.
|
void |
setSubscriberListener(SubscriberKit.SubscriberListener listener)
Sets a
SubscriberKit.SubscriberListener object to monitor state changes. |
void |
setSubscribeToAudio(boolean subscribeToAudio)
Whether to subscribe to the stream's audio (
true ) or not (false ). |
void |
setSubscribeToVideo(boolean subscribeToVideo)
Whether to subscribe to the stream's video (
true ) or not (false ). |
void |
setVideoListener(SubscriberKit.VideoListener listener)
Sets a
SubscriberKit.VideoListener object to monitor when the subscriber starts
and stops receiving video. |
void |
setVideoStatsListener(SubscriberKit.VideoStatsListener listener)
Sets up a listener for subscriber video statistics.
|
public static final java.lang.String VIDEO_REASON_PUBLISH_VIDEO
method.
,
method.
,
Constant Field Valuespublic static final java.lang.String VIDEO_REASON_SUBSCRIBE_TO_VIDEO
setSubscribeToVideo(boolean subscribeToVideo)
method.public static final java.lang.String VIDEO_REASON_QUALITY
This reason is only used in sessions that have the media mode set to
"routed". (See
The
OpenTok Media Router and media modes.
This feature of the OpenTok Media Router has a subscriber drop the video
stream when the video stream quality degrades, and the
SubscriberKit.VideoListener.onVideoDisabled(SubscriberKit, String)
method is
called.
When conditions improve, the video stream resumes, and the
SubscriberKit.VideoListener.onVideoEnabled(SubscriberKit, String)
method is
called.
When the video stream is dropped, the subscriber continues to receive the audio stream, if there is one.
method.
,
method.
,
Constant Field Valuespublic static final VideoUtils.Size NO_PREFERRED_RESOLUTION
setPreferredResolution(VideoUtils.Size preferredResolution)
method. Pass in this value to reset the subscriber to have no prefered resolution.
The subscriber will use the maximum resolution available, based on conditions.
This only applies to streams streams published using the scalable video feature.
public static final float NO_PREFERRED_FRAMERATE
setPreferredFrameRate(float preferredFrameRate)
method. Pass in
this value to reset the subscriber to have no prefered frame rate. The subscriber
will use the maximum frame rate available, based on conditions.
This only applies to streams streams published using the scalable video feature.
protected Stream stream
protected Session session
protected SubscriberKit.SubscriberListener subscriberListener
protected SubscriberKit.VideoListener videoListener
protected SubscriberKit.AudioLevelListener audioLevelListener
protected SubscriberKit.StreamListener streamListener
protected BaseVideoRenderer renderer
@Deprecated public SubscriberKit(android.content.Context context, Stream stream)
SubscriberKit.Builder
class to instantiate a SubscriberKit
object.context
- The android.content.Context
for the Subscriber.stream
- The Stream object corresponding to the stream you will subscribe to.protected SubscriberKit(android.content.Context context, Stream stream, BaseVideoRenderer renderer)
SubscriberKit
class,
you can call this constructor to instantiate a subscriber object.context
- The
android.content.Context for the Subscriber.stream
- The Stream object corresponding to the stream you will subscribe to.renderer
- The renderer for the subscriber.public void destroy()
public void setSubscriberListener(SubscriberKit.SubscriberListener listener)
SubscriberKit.SubscriberListener
object to monitor state changes.listener
- The SubscriberKit.SubscriberListener
that monitors this SubscriberKit instance.public void setVideoListener(SubscriberKit.VideoListener listener)
SubscriberKit.VideoListener
object to monitor when the subscriber starts
and stops receiving video.listener
- The SubscriberKit.VideoListener
instance.public void setAudioLevelListener(SubscriberKit.AudioLevelListener listener)
SubscriberKit.AudioLevelListener
to this SubscriberKit instance to monitor audio
level updates.listener
- The SubscriberKit.AudioLevelListener
that will monitor this instance. Set
this to null to disconnect a listener and stop monitoring audio levels.public void setStreamListener(SubscriberKit.StreamListener listener)
public Session getSession()
Session
that the subscriber is bound to (by calling
the connect()
method of the Session object).Session
that the subscriber is bound to.public Stream getStream()
Stream
that this instance is bound to.
Any media channels on the stream should be available for
display/playback with this instance.Stream
that this instance is bound to.public boolean getSubscribeToAudio()
public boolean getSubscribeToVideo()
public void setSubscribeToAudio(boolean subscribeToAudio)
true
) or not (false
).
Setting this property has no effect if the hasAudio
method of the Stream object
returns false
.subscribeToAudio
- Whether to subscribe to the stream's audio (true
) or
not (false
).public void setSubscribeToVideo(boolean subscribeToVideo)
true
) or not (false
).
Setting this property has no effect if the hasVideo
method of the Stream object
returns false
.subscribeToVideo
- Whether to subscribe to the stream's video (true
) or
not (false
).protected void finalize() throws java.lang.Throwable
finalize
in class java.lang.Object
java.lang.Throwable
public void setStyle(java.lang.String key, java.lang.String value)
By default, there is only one pre-defined style key:
BaseVideoRenderer.STYLE_VIDEO_SCALE
. You can set a value for this key
to determine the scaling of the video. The following values are supported:
BaseVideoRenderer.STYLE_VIDEO_FILL
— The video scales to fill the entire
area of the renderer, with cropping as needed.
BaseVideoRenderer.STYLE_VIDEO_FIT
— The video shrinks, as needed,
so that the entire video is visible, with pillarboxing (the default setting).
Calling this method is equivalent to calling getRenderer().setStyle()
. However,
if you extend this class, you can override this method to support other styles and behaviors.
key
- The style to set.value
- The value you are setting the style to.@Deprecated public void setRenderer(BaseVideoRenderer renderer)
renderer
- The video renderer for this subscriber to use.public BaseVideoRenderer getRenderer()
public android.view.View getView()
protected void onConnected()
If you extend the SubscriberKit class, you can override this method instead of the
onConnected()
method of the SubscriberKit.SubscriberListener interface.
protected void onDisconnected()
If you extend the SubscriberKit class, you can override this method instead of the
onDisconnected()
method of the SubscriberKit.SubscriberListener interface.
protected void onStreamDisconnected()
In response to this method being called, you may want to provide a user interface notification, to let the user know that the audio-video stream is temporarily disconnected and the app is trying to reconnect to the stream.
If the client reconnects to the stream, the onStreamReconnected()
method is called.
Otherwise, the onDisconnected()
method is called.
If you extend the SubscriberKit class, you can override this method instead of implementing
the onDisconnected()
method of the SubscriberKit.StreamListener interface.
protected void onStreamReconnected()
onStreamDisconnected()
method is called.
If you extend the SubscriberKit class, you can override this method instead of implementing
the onReconnected()
method of the SubscriberKit.StreamListener interface.
protected void onVideoDisabled(java.lang.String reason)
If you extend the SubscriberKit class, you can override this method instead of the
onVideoDisabled()
method of the SubscriberKit.SubscriberListener interface.
reason
- The reason that the video track was disabled. This value is
set to one of the following values:
VIDEO_REASON_PUBLISH_VIDEO
VIDEO_REASON_SUBSCRIBE_TO_VIDEO
, or
VIDEO_REASON_QUALITY
.protected void onVideoEnabled(java.lang.String reason)
If you extend the SubscriberKit class, you can override this method instead of the
onVideoEnabled()
method of the SubscriberKit.SubscriberListener interface.
reason
- The reason that the video track started or resumed. This value
is set to one of the following values:
VIDEO_REASON_PUBLISH_VIDEO
VIDEO_REASON_SUBSCRIBE_TO_VIDEO
, or
VIDEO_REASON_QUALITY
.protected void onVideoDisableWarning()
onVideoDisabled(String reason)
method is called. If the stream quality
improves, the onVideoDisableWarningLifted()
method is called.
This feature is only available in sessions that use the OpenTok Media Router (sessions with the media mode set to routed), not in sessions with the media mode set to relayed. (See The OpenTok Media Router and media modes).
This method is mainly called when connection quality degrades.
If you extend the SubscriberKit class, you can override this method instead of the
onVideoDisableWarning()
method of the SubscriberKit.SubscriberListener
interface.
protected void onVideoDisableWarningLifted()
onVideoDisableWarning()
method is called.
This feature is only available in sessions that use the OpenTok Media Router (sessions with the media mode set to routed), not in sessions with the media mode set to relayed. (See The OpenTok Media Router and media modes.)
This method is mainly called when connection quality improves.
If you extend the SubscriberKit class, you can override this method instead of
the onVideoDisableWarningLifted()
method of the
SubscriberKit.SubscriberListener interface.
protected void onVideoDataReceived()
If you extend the SubscriberKit class, you can override this method instead of the
onVideoDataReceived()
method of the SubscriberKit.VideoListener interface.
protected void onError(OpentokError error)
If you extend the SubscriberKit class, you can override this method instead of the
onError()
method of the SubscriberKit.SubscriberListener interface.
error
- The error.public void setVideoStatsListener(SubscriberKit.VideoStatsListener listener)
SubscriberKit.VideoStatsListener.onVideoStats(SubscriberKit subscriber,
SubscriberKit.SubscriberVideoStats stats)
method. This method is called periodically to report
the following:
public void setAudioStatsListener(SubscriberKit.AudioStatsListener listener)
SubscriberKit.AudioStatsListener.onAudioStats(SubscriberKit subscriber,
SubscriberKit.SubscriberAudioStats stats)
method. This method is called periodically to report
the following:
protected void attachToSession(Session session)
protected void detachFromSession(Session session)
public void setPreferredResolution(VideoUtils.Size preferredResolution)
Limiting the video resolution and frame rate (see
setPreferredFrameRate(float preferredFrameRate)
) reduces the network
and CPU usage on the subscribing client. You may want to use lower resolution based on the
dimensions of subscriber's video in the app. You may want to use a lower frame rate or
resolution for subscribers to a stream that is less important (and smaller) than other
streams.
Not every resolution is available to a subscriber. When you set the preferred
resolution, the OpenTok Android SDK picks the best resolution available that
matches your constraints. The resolutions available depend on the maximum
width and height the Publisher sets for the stream, which are returned by the
Stream.getVideoWidth()
and Stream.getVideoHeight()
methods
for the Stream object. Each of the resolutions available for a stream will use the same
aspect ratio.
Pass in SubscriberKit.NO_PREFERRED_RESOLUTION
to reset the subscriber
to have no prefered resolution. The subscriber will use the maximum resolution
available, based on conditions.
public void setPreferredFrameRate(float preferredFrameRate)
Limiting the frame rate and video resolution (see
setPreferredResolution(VideoUtils.Size preferredResolution)
)
reduces the network and
CPU usage on the subscribing client. You may want to use lower resolution based on the
dimensions of subscriber's video in the app. You may want to use a lower frame rate or
resolution for subscribers to a stream that is less important (and smaller) than other
streams.
The frame rates available are based on the value of the maximum frame rate available for the stream. When you set the preferred frame rate for the subscriber, the OpenTok Android SDK picks the best frame rate available that is closest to the prefered frame rate, based on the client's bandwidth and CPU constraints.
The actual frame rates available depend, dynamically, on network and CPU resources available to the publisher.
Pass in SubscriberKit.NO_PREFERRED_FRAMERATE
to reset the subscriber
to have no prefered frame rate. The subscriber will use the maximum frame rate
available, based on conditions.
public VideoUtils.Size getPreferredResolution()
setPreferredResolution(VideoUtils.Size preferredResolution)
.public float getPreferredFrameRate()
setPreferredFrameRate(float preferredFrameRate)
.