Package com.opentok.android

Class SubscriberKit

java.lang.Object
com.opentok.android.SubscriberKit
All Implemented Interfaces:
Observer
Direct Known Subclasses:
Subscriber
public class SubscriberKit extends Object implements Observer
A SubscriberKit (subscriber) object renders media data bound to a Stream The SubscriberKit class lets you set a custom video renderer for the video stream. Create a subclass of SubscriberKit if you are interested in providing your own video processing and rendering implementation. Otherwise, use the 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.

  • Field Details

  • Constructor Details

    • SubscriberKit

      @Deprecated public SubscriberKit(android.content.Context context, Stream stream)
      Deprecated.
      Creates a new subscriber for a given stream. This method is deprecated. Use the SubscriberKit.Builder class to instantiate a SubscriberKit object.
      Parameters:
      context - The android.content.Context for the Subscriber.
      stream - The Stream object corresponding to the stream you will subscribe to.

    • SubscriberKit

      protected SubscriberKit(android.content.Context context, Stream stream, BaseVideoRenderer renderer)
      Creates a new SubscriberKit object for a given stream. If you extend the SubscriberKit class, you can call this constructor from the child class.
      Parameters:
      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.

  • Method Details

    • destroy

      @Deprecated public void destroy()
      Deprecated.
      Manually destroying the object is not safe. From version 2.17.0 on, this method doesn't do anything. Resources will be automatically released by the garbage collector.

    • setSubscriberListener

      public void setSubscriberListener(SubscriberKit.SubscriberListener listener)
      Sets a SubscriberKit.SubscriberListener object to monitor state changes.
      Parameters:
      listener - The SubscriberKit.SubscriberListener that monitors this SubscriberKit instance.

    • setVideoListener

      public void setVideoListener(SubscriberKit.VideoListener listener)
      Sets a SubscriberKit.VideoListener object to monitor when the subscriber starts and stops receiving video.
      Parameters:
      listener - The SubscriberKit.VideoListener instance.

    • setAudioLevelListener

      public void setAudioLevelListener(SubscriberKit.AudioLevelListener listener)
      Binds an SubscriberKit.AudioLevelListener to this SubscriberKit instance to monitor audio level updates.
      Parameters:
      listener - The SubscriberKit.AudioLevelListener that will monitor this instance. Set this to null to disconnect a listener and stop monitoring audio levels.

    • setCaptionsListener

      public void setCaptionsListener(SubscriberKit.CaptionsListener listener)
      Binds a SubscriberKit.CaptionsListener to this SubscriberKit instance to receive captions.
      Parameters:
      listener - The SubscriberKit.CaptionsListener that will monitor this instance. Set this to null to disconnect a listener and stop receiving captions.

    • setAudioVolume

      public void setAudioVolume(double volume)
      Sets the audio volume, between 0 and 100, of the subscriber. If the value is not in this range, it will be clamped to it.
      Parameters:
      volume - The volume of the subscriber.

    • getAudioVolume

      public double getAudioVolume()
      Returns the audio volume, between 0 and 100, of the subscriber.

      The default value is 100.

    • setStreamListener

      public void setStreamListener(SubscriberKit.StreamListener listener)
      Sets up a listener for events related to the subscriber's stream being interrupted and resuming.

    • getSession

      public Session getSession()
      Returns the Session that the subscriber is bound to (by calling the connect() method of the Session object).
      Returns:
      The Session that the subscriber is bound to.

    • getStream

      public Stream getStream()
      Returns the Stream that this instance is bound to. Any media channels on the stream should be available for display/playback with this instance.
      Returns:
      The Stream that this instance is bound to.

    • getSubscribeToAudio

      public boolean getSubscribeToAudio()
      Whether the Subscriber is subscribing to audio or not.
      Returns:
      true if the Subscriber is subscribing to audio; false if it is not.

    • getSubscribeToVideo

      public boolean getSubscribeToVideo()
      Whether the Subscriber is subscribing to audio or not.
      Returns:
      true if the Subscriber is subscribing to audio; false if it is not.

    • getSubscribeToCaptions

      public boolean getSubscribeToCaptions()
      Whether the Subscriber is subscribing to captions or not.
      Returns:
      true if the Subscriber is subscribing to captions; false if it is not. The default value is the captions value of its publisher PublisherKit.setPublishCaptions(boolean).

    • setSubscribeToAudio

      public void setSubscribeToAudio(boolean subscribeToAudio)
      Whether to subscribe to the stream's audio (true) or not (false). Setting this property has no effect if the hasAudio method of the Stream object returns false.
      Parameters:
      subscribeToAudio - Whether to subscribe to the stream's audio (true) or not (false).

    • setSubscribeToVideo

      public void setSubscribeToVideo(boolean subscribeToVideo)
      Whether to subscribe to the stream's video (true) or not (false). Setting this property has no effect if the hasVideo method of the Stream object returns false.
      Parameters:
      subscribeToVideo - Whether to subscribe to the stream's video (true) or not (false).

    • setSubscribeToCaptions

      public void setSubscribeToCaptions(boolean subscribeToCaptions)
      Whether to subscribe to the stream's captions (true) or not (false)..
      Parameters:
      subscribeToCaptions - Whether to subscribe to the stream's captions (true) or not (false).

    • setStyle

      public void setStyle(String key, String value)
      Set a style used by this subscriber.

      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:

      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.

      Parameters:
      key - The style to set.
      value - The value you are setting the style to.

    • setRenderer

      @Deprecated public void setRenderer(BaseVideoRenderer renderer)
      Deprecated.
      Set the video renderer for this subscriber.

      This method is deprecated. Instead, call the SubscriberKit.Builder.renderer(BaseVideoRenderer renderer) method when using the Builder to create the SubscriberKit instance.

    • getRenderer

      public BaseVideoRenderer getRenderer()
      Returns the video renderer for this subscriber.

    • getView

      public android.view.View getView()
      Returns the android.view.View object that contains the Subscriber video.

    • setVideoStatsListener

      public void setVideoStatsListener(SubscriberKit.VideoStatsListener listener)
      Sets up a listener for subscriber video statistics. The listener object implements the SubscriberKit.VideoStatsListener.onVideoStats(SubscriberKit subscriber, SubscriberKit.SubscriberVideoStats stats) method. This method is called periodically to report the following:

      • Total video packets lost
      • Total video packets received
      • Total video bytes received
      See Also:

    • setAudioStatsListener

      public void setAudioStatsListener(SubscriberKit.AudioStatsListener listener)
      Sets up a listener for subscriber audio statistics. The listener object implements the SubscriberKit.AudioStatsListener.onAudioStats(SubscriberKit subscriber, SubscriberKit.SubscriberAudioStats stats) method. This method is called periodically to report the following:

      • Total audio packets lost
      • Total audio packets received
      • Total audio bytes received
      See Also:

    • setPreferredResolution

      public void setPreferredResolution(VideoUtils.Size preferredResolution)
      Sets the preferred resolution for the subscriber's stream.

      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.

      This method only applies when subscribing to a stream that uses the scalable video feature. Scalable video is available:

      • Only in sessions that use the OpenTok Media Router (sessions with the media mode set to routed).
      • Only for streams published by clients that support scalable video (see the documentation for the scalable video feature).

      In streams that do not use scalable video, calling this method has no effect.

      Note: The resolution for scalable video streams automatically adjusts for each subscriber, based on network conditions and CPU usage, even if you do not call this method. Call this method if you want to set a maximum resolution for this subscriber.

      In streams that do not use scalable video, calling this method has no effect.

      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 preferred resolution. The subscriber will use the maximum resolution available, based on conditions.

    • setPreferredFrameRate

      public void setPreferredFrameRate(float preferredFrameRate)
      Sets the preferred frame rate for the subscriber's stream.

      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.

      This method only applies when subscribing to a stream that uses the scalable video feature. Scalable video is available:

      • Only in sessions that use the OpenTok Media Router (sessions with the media mode set to routed).
      • Only for streams published by clients that support scalable video (see the documentation for the scalable video feature).

      In streams that do not use scalable video, calling this method has no effect.

      Note: The frame rate for scalable video streams automatically adjusts for each subscriber, based on network conditions and CPU usage, even if you do not call this method. Call this method if you want to set a maximum frame rate for this subscriber.

      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 preferred 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 preferred frame rate. The subscriber will use the maximum frame rate available, based on conditions.

    • getPreferredResolution

      public VideoUtils.Size getPreferredResolution()
      Returns the preferred resolution for the subscriber's stream. This method only applies to streams published using the scalable video feature. See setPreferredResolution(VideoUtils.Size preferredResolution).

    • setRtcStatsReportListener

      public void setRtcStatsReportListener(SubscriberKit.SubscriberRtcStatsReportListener listener)
      Sets the RTC stats report listener for the subscriber. See getRtcStatsReport().
      Parameters:
      listener - The SubscriberKit.SubscriberRtcStatsReportListener object.

    • getRtcStatsReport

      public void getRtcStatsReport()
      Gets the RTC stats report for the subscriber. This is an asynchronous operation. Call the SubscriberKit#setRtcStatsReportListener(SubscriberRtcStatsReportListener listener) method, and then implement the SubscriberKit.SubscriberRtcStatsReportListener.onRtcStatsReport(SubscriberKit subscriber, String jsonArrayOfReports) method prior to calling this method. When the stats are available, the implementation of the SubscriberKit.SubscriberRtcStatsReportListener.onRtcStatsReport(SubscriberKit subscriber, String jsonArrayOfReports) method is called.

      Also see setAudioStatsListener(SubscriberKit.AudioStatsListener listener), setVideoStatsListener(SubscriberKit.VideoStatsListener listener), and PublisherKit.getRtcStatsReport().

    • onRtcStatsReport

      protected void onRtcStatsReport(String jsonArrayOfReports)
      Called when the subscriber's RTC stats report is available in response to a call to getRtcStatsReport().

      If you extend the SubscriberKit class, you can override this method instead of implementing the onRtcStatsReport() method of the SubscriberKit.SubscriberRtcStatsReportListener interface.

      See onRtcStatsReport(String jsonArrayOfReports).

    • getPreferredFrameRate

      public float getPreferredFrameRate()
      Returns the preferred frame rate for the subscriber's stream. This method only applies to streams published using the scalable video feature. See setPreferredFrameRate(float preferredFrameRate).
      Returns:
      The preferred frame rate for the subscriber stream or -1 if there has been any error retrieving the actual value.

    • onConnected

      protected void onConnected()
      Invoked when the instance has successfully connected to the stream and begins playing media.

      If you extend the SubscriberKit class, you can override this method instead of the onConnected() method of the SubscriberKit.SubscriberListener interface.

    • onDisconnected

      @Deprecated protected void onDisconnected()
      Deprecated.
      From 2.17.0 on, this callback won't be invoked. When a subscriber disconnects from the session, the Session.SessionListener.onStreamDropped(com.opentok.android.Session, com.opentok.android.Stream) callback will be invoked.

    • onError

      protected void onError(OpentokError error)
      Invoked when a subscriber has failed to connect to the OpenTok server.

      If you extend the SubscriberKit class, you can override this method instead of the onError() method of the SubscriberKit.SubscriberListener interface.

      Parameters:
      error - The error.

    • onStreamDisconnected

      protected void onStreamDisconnected()
      Called when the subscriber's stream has been interrupted.

      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.

    • onStreamReconnected

      protected void onStreamReconnected()
      Called when the subscriber's stream has resumed, after the 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.

    • onAudioEnabled

      protected void onAudioEnabled()
      Called when the subscriber's stream has the audio enabled.

      If you extend the SubscriberKit class, you can override this method instead of implementing the onAudioEnabled() method of the SubscriberKit.StreamListener interface.

    • onAudioDisabled

      protected void onAudioDisabled()
      Called when the subscriber's stream audio has been disabled

      If you extend the SubscriberKit class, you can override this method instead of implementing the onAudioDisabled() method of the SubscriberKit.StreamListener interface.

    • onVideoDisabled

      protected void onVideoDisabled(String reason)
      Called when the subscriber stops receiving video. Check the reason parameter for the reason why the video stopped.

      If you extend the SubscriberKit class, you can override this method instead of the onVideoDisabled() method of the SubscriberKit.SubscriberListener interface.

      Parameters:
      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, VIDEO_REASON_QUALITY, or VIDEO_REASON_CODEC_NOT_SUPPORTED.

    • onVideoEnabled

      protected void onVideoEnabled(String reason)
      Called when the subscriber's video stream starts (when there previously was no video) or resumes (after video was disabled). Check the reason parameter for the reason why the video stopped.

      If you extend the SubscriberKit class, you can override this method instead of the onVideoEnabled() method of the SubscriberKit.SubscriberListener interface.

      Parameters:
      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.

    • onVideoDisableWarning

      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. If the quality degrades further, the subscriber disables the video and the 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.

    • onVideoDisableWarningLifted

      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. This method is called after the 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.

    • onVideoDataReceived

      protected void onVideoDataReceived()
      Invoked when an subscriber initially receives video data.

      If you extend the SubscriberKit class, you can override this method instead of the onVideoDataReceived() method of the SubscriberKit.VideoListener interface.

    • attachToSession

      protected void attachToSession(Session session)

    • detachFromSession

      protected void detachFromSession(Session session)

    • onAudioLevelUpdated

      protected void onAudioLevelUpdated(float audioLevel)

    • onCaptionText

      protected void onCaptionText(String text, boolean isFinal)

    • onPause

      public void onPause()
      Do not call directly; call Session.onPause() instead.

    • onResume

      public void onResume()
      Do not call directly; call Session.onResume() instead.

    • update

      public void update(Observable o, Object arg)
      This method is called whenever the observed object is changed. This class implements the Observer interface, so it observes events, such as session pause and session resume events.
      Specified by:
      update in interface Observer
      Parameters:
      o - The observable object.
      arg - An argument passed to the notifyObservers method.

    • finalize

      protected void finalize() throws Throwable
      Called by the garbage collector on an SubscriberKit object when garbage collection determines that there are no more references to the object.
      Overrides:
      finalize in class Object
      Throws:
      Throwable