PublisherKit

public class PublisherKit 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 types: PublisherKit.PublisherKitVideoType, PublisherKit.VideoBitratePreset, PublisherKit.DegradationPreference, PublisherKit.PreferredVideoCodecs, PublisherKit.PublisherListener, PublisherKit.VideoListener, PublisherKit.PublisherRtcStats, PublisherKit.PublisherRtcStatsReportListener, PublisherKit.AudioLevelListener, PublisherKit.VideoLayerStats, PublisherKit.PublisherVideoStats, PublisherKit.PublisherAudioStats, PublisherKit.PublisherMediaLinkStats, PublisherKit.VideoStatsListener, PublisherKit.AudioStatsListener, PublisherKit.MediaLinkStatsListener, PublisherKit.MuteListener, PublisherKit.Builder, PublisherKit.CustomAudioTransformer, PublisherKit.CustomVideoTransformer, PublisherKit.VideoTransformer, PublisherKit.AudioTransformer

Properties

Methods

PublisherKit(builder)

Parameters:

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.

finalize()

Called by the garbage collector when it determines that there are no more references to the PublisherKit object.

See: : - Throws Throwable

getCaptionsInputLanguage() → {String}

Gets the configured captions input language for this publisher.

Returns:

The configured language code, or null if input is not set.

getCapturer() → {BaseVideoCapturer}

Returns the video capturer used by this publisher.

Returns:

BaseVideoCapturer

getDegradationPreference() → {PublisherKit.DegradationPreference}

Gets the preferred policy that the video engine will follow when adjusting frame rate and resolution to limited bandwidth and CPU conditions. See DegradationPreference for a description of the possible values.

Returns:

The current degradation preference.

getMaxVideoBitrate() → {int}

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.

See: : - setMaxVideoBitrate(int maxVideoBitrate)

Returns:

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

getName() → {String}

The stream name. The name appears at the bottom of Subscriber videos.

Returns:

publisher name

getPublishAudio() → {boolean}

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

Returns:

boolean

getPublishCaptions() → {boolean}

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

Returns:

boolean

getPublishVideo() → {boolean}

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

Returns:

boolean

getPublisherVideoType() → {PublisherKit.PublisherKitVideoType}

Returns the type of video for this publisher.

See: : - setPublisherVideoType(PublisherKitVideoType type)

Returns:

PublisherKit.PublisherKitVideoType

getRenderer() → {BaseVideoRenderer}

Returns the video renderer for this publisher.

Returns:

BaseVideoRenderer

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

getSession() → {Session}

Returns the Session bound to this Publisher instance.

See: : - Session#publish(com.opentok.android.PublisherKit)

Returns:

The Session bound to this Publisher instance.

getStream() → {Stream}

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

Returns:

The stream object.

getTargetScalabilityMode() → {String}

Gets the target scalability mode that was explicitly set via setTargetScalabilityMode. Returns the last value passed to the setter, or null if the setter has never been called. This reflects the user's intent, not the mode actually applied (which may differ due to codec-dependent fallback).

This is a beta feature.

Returns:

The target scalability mode set by the caller, or null if not explicitly set.

getVideoBitratePreset() → {PublisherKit.VideoBitratePreset}

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 VideoBitratePreset#VideoBitratePresetCustom.

See: : - setVideoBitratePreset(VideoBitratePreset videoBitratePreset)

Returns:

The active VideoBitratePreset.

getView() → {View}

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

Returns:

View

onAudioLevelUpdated(audioLevel)

Called periodically to report the audio level of the publisher.

Parameters:

onError(error)

Invoked when the publisher fails.

Most errors are fatal: the publisher is automatically dropped and can no longer be used. Some errors are continuable and leave the publisher usable; when an error is non-fatal it is stated in the error description.

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

Parameters:

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.

onPause()

Do not call directly; call Session#onPause() instead.

onRestart()

Restarts publisher resources that were previously released by calling the PublisherKit#onStop() method.

onResume()

Do not call directly; call Session#onResume() instead.

onRtcStatsReport(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.

Parameters:

See: : - PublisherRtcStatsReportListener#onRtcStatsReport(PublisherKit publisher, PublisherRtcStats[] stats)

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 PublisherKit#onRestart() method.

onStreamCreated(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:

onStreamDestroyed(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:

setAudioLevelListener(listener)

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

Parameters:

setAudioStatsListener(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

Parameters:

See: : - setVideoStatsListener(VideoStatsListener listener)

setAudioTransformers(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:

setCaptionsInputLanguage(language)

Sets the preferred captions input language for this publisher.

Parameters:

setCapturer(newCapturer)

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.

Deprecated

Parameters:

setDegradationPreference(degradationPreference)

Gets the preferred policy that the video engine will follow when adjusting frame rate and resolution to limited bandwidth and CPU conditions. See DegradationPreference for a description of the possible values.

Parameters:

setMaxVideoBitrate(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:

See: : - getMaxVideoBitrate() - setVideoBitratePreset(VideoBitratePreset videoBitratePreset) - Publisher Max Bitrate

setMediaLinkStatsListener(listener)

Sets up a listener for publisher media link statistics. The listener object implements the PublisherKit.MediaLinkStatsListener#onMediaLinkStats(PublisherKit, PublisherMediaLinkStats[]) and PublisherKit.MediaLinkStatsListener#onNetworkConditionChanged(PublisherKit, PublisherMediaLinkStats, String) methods.

Parameters:

See: : - setVideoStatsListener(VideoStatsListener listener) - setAudioStatsListener(AudioStatsListener listener)

setMuteListener(listener)

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

Parameters:

setName(name)

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

Deprecated

Parameters:

setPublishAudio(publishAudio)

Toggles publishing of audio on or off, based on the value passed in.

Parameters:

setPublishCaptions(publishCaptions)

Toggles publishing of captioning on or off, based on the value passed in.

Parameters:

setPublishVideo(publishVideo)

Toggles publishing of video on or off, based on the value passed in.

Parameters:

setPublisherListener(listener)

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

Parameters:

setPublisherVideoType(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. 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.

Parameters:

setRenderer(renderer)

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.

Deprecated

Parameters:

setRtcStatsReportListener(listener)

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

Parameters:

setStyle(key, 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:

setTargetScalabilityMode(scalabilityMode)

Sets the target scalability mode (SVC - Scalable Video Coding) for this publisher. The scalability mode controls the number of spatial (resolution) and temporal (frame rate) layers that WebRTC encodes. The mode is applied to the Media Router media path.

This method may be called at any time — it does not require the media path negotiation to have completed. The mode will be applied once the Media Router media path is established.

If a non-SVC codec (VP8, H.264) is negotiated on the Media Router media path, the closest applicable mode is used: spatial layers are forced to 1, preserving the temporal dimension (e.g. L2T2 → L1T2 when VP8 is negotiated).

This is a beta feature.

Parameters:

See: : - Throws IllegalArgumentException — if the requested mode is not a valid scalability mode (i.e. not one of L1T1, L1T2, L1T3, L2T1, L2T2, L2T3, L3T1, L3T2, L3T3).

setVideoBitratePreset(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 VideoBitratePreset#VideoBitratePresetCustom.

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

Parameters:

See: : - getVideoBitratePreset() - setMaxVideoBitrate(int maxVideoBitrate) - Publisher Max Bitrate

setVideoListener(listener)

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

Parameters:

setVideoStatsListener(listener)

Sets up a listener for publisher video statistics. The listener object implements the PublisherKit.VideoStatsListener#onVideoStats(PublisherKit publisher, PublisherKit.PublisherVideoStats[] stats) method and optionally the PublisherKit.VideoStatsListener#onVideoQualityChanged(PublisherKit, PublisherVideoStats, String) method.

Parameters:

See: : - setAudioStatsListener(AudioStatsListener listener)

setVideoTransformers(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:

update(o, 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.

Deprecated

Parameters: