Package com.opentok.android

Class PublisherKit

  • All Implemented Interfaces:
    java.util.Observer
    Direct Known Subclasses:
    Publisher
    public class PublisherKit
extends java.lang.Object
implements java.util.Observer
    A publisher captures an audio-video stream from the sources you specify. You can then publish the audio-video stream to an OpenTok session by calling the Session.publish(PublisherKit publisher) method.

    Create a subclass of PublisherKit if you are interested in providing your own video capturing and rendering implementation. Otherwise, use the Publisher class, which includes a pre-built video capturer and renderer.

    • Constructor Detail

      • PublisherKit

        @Deprecated
protected PublisherKit​(android.content.Context context,
                       java.lang.String name,
                       boolean audioTrack,
                       boolean videoTrack,
                       BaseVideoCapturer capturer,
                       BaseVideoRenderer renderer)
        Deprecated.
        Creates a new PublisherKit instance. If you extend the PublisherKit class, you can call this constructor to instantiate a publisher object.

        Use the Session.publish(PublisherKit publisher) method to start streaming from this publisher into a session.

        The getView() method returns the android.view.View object containing the published video.

        Publishers cannot be reused. Instantiate a new PublisherKit object each time you want to publish a new stream.

        Parameters:
        context - The android.content.Context for the Publisher.
        name - The name of the publisher video. The Stream.getName() method for a published by this publisher will return this value (on all clients).
        audioTrack - Whether to include an audio track in the published stream.
        videoTrack - Whether to include a video track in the published stream.
        capturer - The video capturer for the publisher.
        renderer - The video renderer for the publisher.
        See Also:
        setPublisherListener(PublisherKit.PublisherListener listener)

      • PublisherKit

        @Deprecated
protected PublisherKit​(android.content.Context context,
                       java.lang.String name,
                       boolean audioTrack,
                       int maxAudioBitRate,
                       boolean videoTrack,
                       BaseVideoCapturer capturer,
                       BaseVideoRenderer renderer,
                       boolean enableOpusDtx,
                       boolean scalableScreenshare)
        Deprecated.
        Creates a new PublisherKit object. If you extend the PublisherKit class, you can call this constructor from the child class.
        Parameters:
        context - The android.content.Context for the Publisher.
        name - The name of the publisher video. The Stream.getName() method for a published by this publisher will return this value (on all clients).
        audioTrack - Whether to include an audio track in the published stream.
        maxAudioBitRate - The desired bitrate of the audio, in bits per second.
        videoTrack - Whether to include a video track in the published stream.
        capturer - The video capturer for the publisher.
        renderer - The video renderer for the publisher.
        scalableScreenshare - Whether to allow use of scalable video for a publisher that has the videoType set to PublisherKitVideoTypeScreen (true) or not (false, the default).

      • PublisherKit

        protected PublisherKit​(android.content.Context context,
                       java.lang.String name,
                       boolean audioTrack,
                       int maxAudioBitRate,
                       boolean videoTrack,
                       BaseVideoCapturer capturer,
                       BaseVideoRenderer renderer,
                       boolean enableOpusDtx,
                       boolean scalableScreenshare,
                       boolean subscriberAudioFallback,
                       boolean publisherAudioFallback)
        Creates a new PublisherKit object. If you extend the PublisherKit class, you can call this constructor from the child class.
        Parameters:
        context - The android.content.Context for the Publisher.
        name - The name of the publisher video. The Stream.getName() method for a published by this publisher will return this value (on all clients).
        audioTrack - Whether to include an audio track in the published stream.
        maxAudioBitRate - The desired bitrate of the audio, in bits per second.
        videoTrack - Whether to include a video track in the published stream.
        capturer - The video capturer for the publisher.
        renderer - The video renderer for the publisher.
        scalableScreenshare - Whether to allow use of scalable video for a publisher that has the videoType set to PublisherKitVideoTypeScreen (true) or not (false, the default).
        subscriberAudioFallback - Whether the stream will use the subscriber audio-fallback feature (true) or not
        publisherAudioFallback - Whether the stream will use the publisher audio-fallback feature (true) or not

      • PublisherKit

        @Deprecated
public PublisherKit​(android.content.Context context,
                    java.lang.String name,
                    boolean audioTrack,
                    boolean videoTrack)
        Deprecated.
        Creates a new PublisherKit instance. This method is deprecated. Use the PublisherKit.Builder class to instantiate a PublisherKit object.

        Use the Session.publish(PublisherKit publisher) method to start streaming from this publisher into a session.

        This version of the constructor adds parameters that let you exclude the audio track or video track from the published stream. Creating a Publisher without an audio track or video track can save CPU resources.

        The getView() method returns the android.view.View object containing the published video.

        Publishers cannot be reused.

        Parameters:
        context - The android.content.Context for the Publisher.
        name - The name of the publisher video. The Stream.getName() method for a stream published by this publisher will return this value (on all clients).
        audioTrack - Whether to include an audio track in the published stream.
        videoTrack - Whether to include a video track in the published stream.

    • Method Detail

      • onPause

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

      • onResume

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

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

      • setPublishVideo

        public void setPublishVideo​(boolean publishVideo)
        Toggles publishing of video on or off, based on the value passed in.
        Parameters:
        publishVideo - Whether to publish video (true) or not ( false).

      • setPublishAudio

        public void setPublishAudio​(boolean publishAudio)
        Toggles publishing of audio on or off, based on the value passed in.
        Parameters:
        publishAudio - Whether to publish audio (true) or not ( false).

      • setPublishCaptions

        public void setPublishCaptions​(boolean publishCaptions)
        Toggles publishing of captioning on or off, based on the value passed in.
        Parameters:
        publishCaptions - Whether to publish captions (true) or not ( false).

      • setPublisherVideoType

        public void setPublisherVideoType​(PublisherKit.PublisherKitVideoType type)
        Specifies the type of video for this stream. Set this to one of the following values:

        • PublisherKitVideoType.PublisherKitVideoTypeScreen — Optimizes the video encoding for screen sharing. It is recommended to use a low frame rate (5 frames per second or lower) with this video type. When using the screen video type in a session that uses the OpenTok Media Server, you should call the setAudioFallbackEnabled(boolean enabled) method and pass in false before calling the Session.publish(com.opentok.android.PublisherKit) method; this disables the audio-only fallback feature, so that the video does not drop out in subscribers. See The OpenTok Media Router and media modes.
        • PublisherKitVideoType.PublisherKitVideoTypeCamera — This is the default setting, which you should use when using a camera as the video source.

      • getName

        public java.lang.String getName()
        The stream name. The name appears at the bottom of Subscriber videos.
        Returns:
        publisher name

      • getPublishVideo

        public boolean getPublishVideo()
        Whether the Publisher is publishing video (true) or not ( false).

      • getPublishAudio

        public boolean getPublishAudio()
        Whether the Publisher is publishing audio (true) or not ( false).

      • getPublishCaptions

        public boolean getPublishCaptions()
        Whether the Publisher is publishing captions (true) or not ( false).

      • getStream

        public Stream getStream()
        Returns the stream object corresponding the the Publisher's stream.
        Returns:
        The stream object.

      • setVideoTransformers

        public void setVideoTransformers​(@NonNull
                                 java.util.ArrayList<PublisherKit.VideoTransformer> videoTransformers)
        Sets a list of video transformers to this publisher's video stream. If the list is empty, calling this method resets the transformers. The array can be composed by Vonage video transformers provided by ml-library or custom transfomers (see this developer guide). Note: Media transformers are not supported on all devices or Android versions. See this documentation.
        Parameters:
        videoTransformers - The list of video transformers, in the order to be applied to the stream.

      • setAudioTransformers

        public void setAudioTransformers​(java.util.ArrayList<PublisherKit.AudioTransformer> audioTransformers)
        Sets a list of audio transformers to this publisher's audio stream. If the list is empty, calling this method resets the transformers. The array can be composed of Vonage audio transformers provided by ml-library or custom transfomers (see this developer guide). Note: Media transformers are not supported on all devices or Android versions. See this documentation. .
        Parameters:
        audioTransformers - The list of audio transformers, in the order to be applied to the stream.

      • setStyle

        public void setStyle​(java.lang.String key,
                     java.lang.String value)
        Sets a style for the video renderer used by this publisher.

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

      • getCapturer

        public BaseVideoCapturer getCapturer()
        Returns the video capturer used by this publisher.

      • getView

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

      • setAudioFallbackEnabled

        @Deprecated
public void setAudioFallbackEnabled​(boolean enabled)
        Deprecated.
        Whether the stream will use the subscriber audio-fallback feature (true) or not (false). The audio-fallback feature is available in sessions that use the the OpenTok Media Router. With the audio-fallback feature enabled (the default), when the OpenTok Media Router determines that a stream's quality has degraded significantly for a specific subscriber, it disables the video in that subscriber in order to preserve audio quality.

        The default setting is true (the audio-fallback feature is enabled). To turn off the audio-fallback feature, call this method (and pass in false) before calling the Session.publish(com.opentok.android.PublisherKit) method.

        See Also:
        SubscriberKit.VideoListener.onVideoDisabled(SubscriberKit subscriber, String reason), the OpenTok Media Router and media modes

      • getAudioFallbackEnabled

        @Deprecated
public boolean getAudioFallbackEnabled()
        Deprecated.
        Whether the stream uses the subscriber audio-fallback feature (true) or not (false).
        See Also:
        setAudioFallbackEnabled(boolean enabled)

      • onStreamCreated

        protected void onStreamCreated​(Stream stream)
        Invoked when the publisher's stream is created.

        If you extend the PublisherKit class, you can override this method instead of the onStreamCreated() method of the PublisherKit.PublisherListener interface.

        Parameters:
        stream - The stream that that is created.

      • onStreamDestroyed

        protected void onStreamDestroyed​(Stream stream)
        Invoked when the publisher's stream is destroyed.

        If you extend the PublisherKit class, you can override this method instead of the onStreamDestroyed() method of the PublisherKit.PublisherListener interface.

        Parameters:
        stream - The stream that that is destroyed.

      • onError

        protected void onError​(OpentokError error)
        Invoked when the publisher fails.

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

        Parameters:
        error - The error that invoked this callback.

      • onAudioLevelUpdated

        protected void onAudioLevelUpdated​(float audioLevel)
        Called periodically to report the audio level of the publisher.
        Parameters:
        audioLevel - The audio level, from 0 to 1.0. Adjust this value logarithmically for use in a user interface visualization (such as a volume meter).

      • onMuteForced

        protected void onMuteForced()
        Invoked when a moderator has forced this publisher to mute audio.

        If you extend the PublisherKit class, you can override this method instead of the onMuteForced() method of the PublisherKit.MuteListener interface.

      • 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 the 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 when it determines that there are no more references to the PublisherKit object.
        Overrides:
        finalize in class java.lang.Object
        Throws:
        java.lang.Throwable

      • onStop

        public void onStop()
        Releases resources tied to the publisher. Calling this method causes the publisher to stop capturing, and then it releases the camera. To reuse the publisher after calling this method, call the onRestart() method.

      • onRestart

        public void onRestart()
        Restarts publisher resources that were previously released by calling the onStop() method.