Package com.opentok.android

Class PublisherKit

java.lang.Object

com.opentok.android.PublisherKit

All Implemented Interfaces:

Observer

Direct Known Subclasses:

Publisher

public class PublisherKit
extends Object
implements 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.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	PublisherKit.AudioLevelListener	Monitors changes in the audio level of the publisher.
static interface	PublisherKit.AudioStatsListener	Defines the listener object for getting publisher audio statistics.
class	PublisherKit.AudioTransformer	A transformer for an audio stream.
static class	PublisherKit.Builder	Used to build a PublisherKit object.
static interface	PublisherKit.CustomAudioTransformer	Defines a custom transformer for an audio stream, to be passed into the PublisherKit.AudioTransformer constructor.
static interface	PublisherKit.CustomVideoTransformer	Defines a custom transformer for a video stream, to be passed into the PublisherKit.VideoTransformer constructor.
static interface	PublisherKit.MuteListener	Monitors when a moderator has forced this publisher to mute audio.
static final class	PublisherKit.PreferredVideoCodecs	Defines codec preferences for video publishing.
static class	PublisherKit.PublisherAudioStats	Defines audio statistics for a publisher.
static enum	PublisherKit.PublisherKitVideoType	Defines values for the setPublisherVideoType(PublisherKitVideoType type) method.
static interface	PublisherKit.PublisherListener	Monitors when a publisher starts and stops streaming to the session.
static class	PublisherKit.PublisherRtcStats	Represents RTC statistics for a media stream published by the publisher.
static interface	PublisherKit.PublisherRtcStatsReportListener	Defines the listener object for getting publisher RTC stats reports.
static class	PublisherKit.PublisherVideoStats	Defines video statistics for a publisher.
static enum	PublisherKit.VideoBitratePreset	Defines values for the setVideoBitratePreset(VideoBitratePreset preset) method.
static interface	PublisherKit.VideoListener	Monitors when the publisher starts and stops receiving video data.
static interface	PublisherKit.VideoStatsListener	Defines the listener object for getting publisher video statistics.
class	PublisherKit.VideoTransformer	A transformer for a video stream.

Field Summary

Fields

Modifier and Type	Field	Description
protected PublisherKit.AudioLevelListener	audioLevelListener
protected PublisherKit.AudioStatsListener	audioStatsListener
protected BaseVideoCapturer	capturer
protected android.content.Context	context
protected android.os.Handler	handler
protected PublisherKit.MuteListener	muteListener
protected PublisherKit.PublisherListener	publisherListener
protected BaseVideoRenderer	renderer
protected PublisherKit.PublisherRtcStatsReportListener	rtcStatsReportListener
protected PublisherKit.VideoListener	videoListener
protected PublisherKit.VideoStatsListener	videoStatsListener

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	PublisherKit(PublisherKit.Builder builder)

Method Summary

Modifier and Type	Method	Description
void	destroy()	Releases this object, including all hardware and UI resources bound to it, if it cannot be released by the garbage collector.
protected void	finalize()	Called by the garbage collector when it determines that there are no more references to the PublisherKit object.
boolean	getAudioFallbackEnabled()	Deprecated.
BaseVideoCapturer	getCapturer()	Returns the video capturer used by this publisher.
int	getMaxVideoBitrate()	Gets the maximum video bitrate for the publisher's video stream, in bits per second.
String	getName()	The stream name.
boolean	getPublishAudio()	Whether the Publisher is publishing audio (true) or not ( false).
boolean	getPublishCaptions()	Whether the Publisher is publishing captions (true) or not ( false).
PublisherKit.PublisherKitVideoType	getPublisherVideoType()	Returns the type of video for this publisher.
boolean	getPublishVideo()	Whether the Publisher is publishing video (true) or not ( false).
BaseVideoRenderer	getRenderer()	Returns the video renderer for this publisher.
void	getRtcStatsReport()	Gets the RTC stats report for the publisher.
Session	getSession()	Returns the Session bound to this Publisher instance.
Stream	getStream()	Returns the stream object corresponding the the Publisher's stream.
PublisherKit.VideoBitratePreset	getVideoBitratePreset()	Gets the currently active video bitrate preset for the publisher's stream.
android.view.View	getView()	Returns the android.view.View object that contains the Publisher video.
protected void	onAudioLevelUpdated(float audioLevel)	Called periodically to report the audio level of the publisher.
protected void	onError(OpentokError error)	Invoked when the publisher fails.
protected void	onMuteForced()	Invoked when a moderator has forced this publisher to mute audio.
void	onPause()	Do not call directly; call Session.onPause() instead.
void	onRestart()	Restarts publisher resources that were previously released by calling the onStop() method.
void	onResume()	Do not call directly; call Session.onResume() instead.
protected void	onRtcStatsReport(PublisherKit.PublisherRtcStats[] stats)	Called when the publisher's RTC stats report is available in response to a call to getRtcStatsReport().
void	onStop()	Releases resources tied to the publisher.
protected void	onStreamCreated(Stream stream)	Invoked when the publisher's stream is created.
protected void	onStreamDestroyed(Stream stream)	Invoked when the publisher's stream is destroyed.
void	setAudioFallbackEnabled(boolean enabled)	Deprecated.
void	setAudioLevelListener(PublisherKit.AudioLevelListener listener)	Binds an PublisherKit.AudioLevelListener to this PublisherKit instance to monitor audio level updates.
void	setAudioStatsListener(PublisherKit.AudioStatsListener listener)	Sets up a listener for publisher audio statistics.
void	setAudioTransformers(ArrayList<PublisherKit.AudioTransformer> audioTransformers)	Sets a list of audio transformers to this publisher's audio stream.
void	setCapturer(BaseVideoCapturer newCapturer)	Deprecated.
void	setMaxVideoBitrate(int maxVideoBitrate)	Sets the maximum video bitrate for the publisher's video stream, in bits per second.
void	setMuteListener(PublisherKit.MuteListener listener)	Sets a PublisherKit.MuteListener object to monitor when a moderator forces this publisher to mute audio.
void	setName(String name)	Deprecated.
void	setPublishAudio(boolean publishAudio)	Toggles publishing of audio on or off, based on the value passed in.
void	setPublishCaptions(boolean publishCaptions)	Toggles publishing of captioning on or off, based on the value passed in.
void	setPublisherListener(PublisherKit.PublisherListener listener)	Binds a PublisherKit.PublisherListener to this Publisher instance to monitor state changes.
void	setPublisherVideoType(PublisherKit.PublisherKitVideoType type)	Specifies the type of video for this stream.
void	setPublishVideo(boolean publishVideo)	Toggles publishing of video on or off, based on the value passed in.
void	setRenderer(BaseVideoRenderer renderer)	Deprecated.
void	setRtcStatsReportListener(PublisherKit.PublisherRtcStatsReportListener listener)	Sets the RTC stats report listener the subscriber.
void	setStyle(String key, String value)	Sets a style for the video renderer used by this publisher.
void	setVideoBitratePreset(PublisherKit.VideoBitratePreset videoBitratePreset)	Sets a video bitrate preset strategy for the publisher's video stream.
void	setVideoListener(PublisherKit.VideoListener listener)	Sets a PublisherKit.VideoListener object to monitor when the publisher starts and stops sending video.
void	setVideoStatsListener(PublisherKit.VideoStatsListener listener)	Sets up a listener for publisher video statistics.
void	setVideoTransformers(ArrayList<PublisherKit.VideoTransformer> videoTransformers)	Sets a list of video transformers to this publisher's video stream.
void	update(Observable o, Object arg)	Deprecated.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

handler

protected android.os.Handler handler

publisherListener

protected PublisherKit.PublisherListener publisherListener

audioLevelListener

protected PublisherKit.AudioLevelListener audioLevelListener

videoStatsListener

protected PublisherKit.VideoStatsListener videoStatsListener

audioStatsListener

protected PublisherKit.AudioStatsListener audioStatsListener

muteListener

protected PublisherKit.MuteListener muteListener

rtcStatsReportListener

protected PublisherKit.PublisherRtcStatsReportListener rtcStatsReportListener

context

protected android.content.Context context

renderer

protected BaseVideoRenderer renderer

capturer

protected BaseVideoCapturer capturer

videoListener

protected PublisherKit.VideoListener videoListener

Constructor Details

PublisherKit

protected PublisherKit(PublisherKit.Builder builder)

Method Details

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

public void destroy()

Releases this object, including all hardware and UI resources bound to it, if it cannot be released by the garbage collector. Resources are generally safely released by the garbage collector, and you do not need to call this method. However, this can happen at any time at the VM discretion, which might not be the desired behavior in some cases. This method allows manually releasing resources for scenarios where immediateness is desired:

• An app wants to publish again but needs to have access to the camera immediately after unpublishing.
• An app wants to make sure that the audio device is released immediately after unpublishing.

After you have called this method, you cannot reuse the publisher.

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

setName

@Deprecated
public void setName(String name)

Deprecated.

Set the name for this stream. The name appears at the bottom of the publisher video and at the bottom of subscriber videos associated with the published stream. You can set this name after initializing the publisher and before the PublisherKit.PublisherListener.onStreamCreated(PublisherKit publisher, Stream stream) method is called. Setting the property after the PublisherKit.PublisherListener.onStreamCreated(PublisherKit publisher, Stream stream) method is called has no effect on the name displayed for the stream.

The default name is "" (an empty string).

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

getSession

public Session getSession()

Returns the Session bound to this Publisher instance.

Returns:

The Session bound to this Publisher instance.

See Also:

• Session.publish(com.opentok.android.PublisherKit)

getStream

public Stream getStream()

Returns the stream object corresponding the the Publisher's stream.

Returns:

The stream object.

getPublisherVideoType

public PublisherKit.PublisherKitVideoType getPublisherVideoType()

Returns the type of video for this publisher.

See Also:

• setPublisherVideoType(PublisherKitVideoType type)

getMaxVideoBitrate

public int getMaxVideoBitrate()

Gets the maximum video bitrate for the publisher's video stream, in bits per second.

Returns the currently configured upper limit. If no manual bitrate has been set, or if a bitrate preset is active, the value is 0.

Returns:

The maximum video bitrate in bits per second, or 0 if unset or using a preset.

See Also:

• setMaxVideoBitrate(int maxVideoBitrate)

setMaxVideoBitrate

public void setMaxVideoBitrate(int maxVideoBitrate)

Sets the maximum video bitrate for the publisher's video stream, in bits per second.

This method applies an explicit upper limit to the publisher’s video bitrate. Setting the value to 0 clears any manual cap and reverts to the default preset-based adaptive bitrate behavior with no explicit limit.

Parameters:

maxVideoBitrate - The maximum video bitrate in bits per second, between 5,000 and 10,000,000.

See Also:

• getMaxVideoBitrate()
• setVideoBitratePreset(VideoBitratePreset videoBitratePreset)
• Publisher Max Bitrate

getVideoBitratePreset

public PublisherKit.VideoBitratePreset getVideoBitratePreset()

Gets the currently active video bitrate preset for the publisher's stream.

Returns the preset strategy in use. If a custom bitrate has been manually set using setMaxVideoBitrate(int), this method returns PublisherKit.VideoBitratePreset.VideoBitratePresetCustom.

Returns:

The active PublisherKit.VideoBitratePreset.

See Also:

• setVideoBitratePreset(VideoBitratePreset videoBitratePreset)

setVideoBitratePreset

public void setVideoBitratePreset(PublisherKit.VideoBitratePreset videoBitratePreset)

Sets a video bitrate preset strategy for the publisher's video stream.

Preset configurations balance video quality and bandwidth usage with predefined strategies. Preset settings and manual bitrate settings are mutually exclusive. Setting the setMaxVideoBitrate(int) method overrides any preset and automatically changes the active preset to PublisherKit.VideoBitratePreset.VideoBitratePresetCustom.

Note: The PublisherKit.VideoBitratePreset.VideoBitratePresetCustom value cannot be set directly.

Parameters:

videoBitratePreset - The PublisherKit.VideoBitratePreset to apply.

See Also:

• getVideoBitratePreset()
• setMaxVideoBitrate(int maxVideoBitrate)
• Publisher Max Bitrate

setPublisherListener

public void setPublisherListener(PublisherKit.PublisherListener listener)

Binds a PublisherKit.PublisherListener to this Publisher instance to monitor state changes.

Parameters:

listener - The PublisherKit.PublisherListener that will monitor this instance, or null to disconnect a listener.

setAudioLevelListener

public void setAudioLevelListener(PublisherKit.AudioLevelListener listener)

Binds an PublisherKit.AudioLevelListener to this PublisherKit instance to monitor audio level updates.

Parameters:

listener - The PublisherKit.AudioLevelListener that will monitor this instance. Set this to null to disconnect a listener and stop monitoring audio levels.

setRtcStatsReportListener

public void setRtcStatsReportListener(PublisherKit.PublisherRtcStatsReportListener listener)

Sets the RTC stats report listener the subscriber. See getRtcStatsReport().

Parameters:

listener - The PublisherKit.PublisherRtcStatsReportListener object.

setVideoTransformers

public void setVideoTransformers(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.

setVideoListener

public void setVideoListener(PublisherKit.VideoListener listener)

Sets a PublisherKit.VideoListener object to monitor when the publisher starts and stops sending video.

Parameters:

listener - The PublisherKit.VideoListener instance.

setAudioTransformers

public void setAudioTransformers(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(String key,
 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:

• 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. If you do not set this style the default setting is BaseVideoRenderer.STYLE_VIDEO_FIT.

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.

Sets the video renderer for this publisher.

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

getRenderer

public BaseVideoRenderer getRenderer()

Returns the video renderer for this publisher.

getCapturer

public BaseVideoCapturer getCapturer()

Returns the video capturer used by this publisher.

setCapturer

@Deprecated
public void setCapturer(BaseVideoCapturer newCapturer)

Deprecated.

Sets the video capturer for this publisher.

This method is deprecated. Instead, call the PublisherKit.Builder.capturer(BaseVideoCapturer capturer) method when using the builder to create the PublisherKit instance.

getView

public android.view.View getView()

Returns the android.view.View object that contains the Publisher video.

setVideoStatsListener

public void setVideoStatsListener(PublisherKit.VideoStatsListener listener)

Sets up a listener for publisher video statistics. The listener object implements the PublisherKit.VideoStatsListener.onVideoStats(PublisherKit publisher, PublisherKit.PublisherVideoStats[] stats) method. This method is called periodically to report the following:

• Total video packets lost
• Total video packets sent
• Total video bytes sent

See Also:

• setAudioStatsListener(AudioStatsListener listener)

setAudioStatsListener

public void setAudioStatsListener(PublisherKit.AudioStatsListener listener)

Sets up a listener for publisher audio statistics. The listener object implements the PublisherKit.AudioStatsListener.onAudioStats(PublisherKit publisher, PublisherKit.PublisherAudioStats[] stats) method. This method is called periodically to report the following:

• Total audio packets lost
• Total audio packets sent
• Total audio bytes sent

See Also:

• setVideoStatsListener(VideoStatsListener listener)

setMuteListener

public void setMuteListener(PublisherKit.MuteListener listener)

Sets a PublisherKit.MuteListener object to monitor when a moderator forces this publisher to mute audio.

Parameters:

listener - The PublisherKit.MuteListener instance.

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)

getRtcStatsReport

public void getRtcStatsReport()

Gets the RTC stats report for the publisher. This is an asynchronous operation. Call the setRtcStatsReportListener(PublisherKit.PublisherRtcStatsReportListener listener) method, and then implement the PublisherKit.PublisherRtcStatsReportListener.onRtcStatsReport(PublisherKit publisher, PublisherKit.PublisherRtcStats[] stats) method prior to calling this method. When the stats are available, the implementation of the PublisherKit.PublisherRtcStatsReportListener.onRtcStatsReport(PublisherKit publisher, PublisherKit.PublisherRtcStats[] stats) method is called.

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

onRtcStatsReport

protected void onRtcStatsReport(PublisherKit.PublisherRtcStats[] stats)

Called when the publisher's RTC stats report is available in response to a call to getRtcStatsReport().

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

See Also:

• PublisherKit.PublisherRtcStatsReportListener.onRtcStatsReport(PublisherKit publisher, PublisherRtcStats[] stats)

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

@Deprecated
public void update(Observable o,
 Object arg)

Deprecated.

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 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 when it determines that there are no more references to the PublisherKit object.

Overrides:

finalize in class Object

Throws:

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.