Package com.opentok.android

Class SubscriberKit

  • All Implemented Interfaces:
    java.util.Observer
    Direct Known Subclasses:
    Subscriber
    public class SubscriberKit
extends java.lang.Object
implements java.util.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.

    • Constructor Detail

      • 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 Detail

      • 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.

      • 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​(java.lang.String key,
                     java.lang.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.

      • 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.

      • 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.

      • onRtcStatsReport

        protected void onRtcStatsReport​(java.lang.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.

      • 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​(java.lang.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​(java.lang.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​(java.lang.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​(java.util.Observable o,
                   java.lang.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 java.util.Observer
        Parameters:
        o - The observable object.
        arg - An argument passed to the notifyObservers method.

      • finalize

        protected void finalize()
                 throws java.lang.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 java.lang.Object
        Throws:
        java.lang.Throwable