Suggestions

close search

Add Messaging, Voice, and Authentication to your apps with Vonage Communications APIs

Visit the Vonage API Developer Portal

Publishing streams — Android

Once you have connected to a session, you can publish a stream that other clients connected to the session can view.

This topic includes the following sections:

Initializing a Publisher object

A Publisher object is used to capture an audio-video stream from the device's microphone and camera for use in an OpenTok session.

For a basic publisher, use the Publisher.Builder class to instantiate a Publisher object. Pass in the Android application context for the publisher: 

mPublisher = new Publisher.Builder(context)
  .build();

Add a listener object for basic publisher-related events by calling the setPublisherListener(PublisherKit.PublisherListener listener) method of the Publisher object: 

mPublisher.setPublisherListener(this);

Implement the methods of the PublisherKit.PublisherListener interface in the object you specify as the event listener object. These methods are called when publisher-related events occur.

The getView() method of the Publisher object returns the view of the video you publish. Add it as a subview of an android.view.ViewGroup object to display it in the app: 

mPublisherViewContainer.addView(mPublisher.getView());

Pass the Publisher object into the Session.publish() method to publish a stream to a session. See Publishing a stream.

You can call other methods of the Publisher.Builder object to define custom settings for the publisher: 

mPublisher = new Publisher.Builder(context)
  .name("Bob")
  .audioTrack(true)
  .frameRate(CameraCaptureFrameRate.FPS_7)
  .resolution(CameraCaptureResolution.LOW)
  .videoTrack(false)
  .capturer(mCapturer)
  .renderer(mRenderer)
  .build();

Note that in sessions that use the OpenTok Media Router (sessions with the media mode set to routed), lowering the frame rate proportionally reduces the bandwidth the stream uses. However, in sessions that have the media mode set to relayed, lowering the frame rate does not reduce the stream's bandwidth.

You can use a custom video capturer to publish a stream with a customized video source — see Using a custom video capturer. You can also use the custom video capturer to publish a screen-sharing stream — see Screen-sharing.

You can also use a customized audio source for the published stream — see Using a custom audio driver.

Previewing the publisher's video before streaming

Note that, by default, the view of the Publisher contains the video of the publisher when the publisher starts streaming to the session. To see a preview of the video before the Publisher starts streaming, call the startPreview() method of the Publisher object: 

mPublisher.startPreview();

If you call the startPreview() method, you must call the destroy() method of the Publisher to remove the Publisher's view (and the video), when the publisher stops streaming (when the onStreamDestroyed(PublisherKit publisher, Stream stream) method of the PublisherListener is called).

Note: The startPreview() method does not connect the audio input to the publisher. To get a preview of the audio before the publisher starts streaming to the session, use a custom audio driver.

Publishing a stream

Once you create a Publisher object (See Initializing a Publisher object), you can pass it into the publish(PublisherKit publisher) method of a Session object to publish the stream to the session: 

mSession.publish(mPublisher);

This code assumes that mSession is a Session object, and that the client has connected to the session. For more information, see Joining a Session.

The PublisherKit.PublisherListener.onStreamCreated(PublisherKit publisher, Stream stream) method is called when the publisher starts streaming to the session: 

@Override
public void onStreamCreated(publisher, stream) {
   // The publisher started streaming.
}

Stopping a publisher from streaming

You can stop publisher from streaming to the session by calling the unpublish(PublisherKit publisher) method of the Session object: 

    mSession.unpublish(mPublisher);

The PublisherKit.PublisherListener.onStreamDestroyed(PublisherKit publisher, Stream stream) method is called when the publisher stops streaming to the session: 

@Override
public void onStreamDestroyed(publisher, stream) {
   // The publisher stopped streaming.
}

Getting statistics about a publisher's stream

To register callbacks methods for periodic reports of audio and video statistics for a publisher, call the PublisherKit.setAudioStatsListener(listener) and PublisherKit.setVideoStatsListener(listener) methods. Pass in objects that implement the PublisherKit.AudioStatsListener and PublisherKit.VideoStatsListener interfaces.

The implementations of the PublisherKit.AudioStatsListener.onAudioStats(publisher, stats) and PublisherKit.VideoStatsListener.onVideoStats(publisher, stats) methods are called periodically to report audio and video statistics for the publisher. Each method is passed in two objects: the publisher and an array of stats objects. For a publisher in a routed session (one that uses the OpenTok Media Router), the stats array includes one object, defining the statistics for the single audio or video media stream that is sent to the OpenTok Media Router. In a relayed session, the stats array includes an object for each subscriber to the published stream. The stats object includes the following properties:

Additionally, for a publisher in a relayed session, each object in the array contains the following two properties:

These two properties are undefined for a publisher in a routed session.

To get more detailed stream statics, use the PublisherKit.getRtcStatsReport() method. This provides RTC stats reports for the media stream. This is an asynchronous operation. Call the PublisherKit.setRtcStatsReportListener(PublisherKit.PublisherRtcStatsReportListener listener) method, and then implement the PublisherKit.PublisherRtcStatsReportListener.onRtcStatsReport(PublisherKit publisher, PublisherKit.PublisherRtcStats[] stats) method prior to calling PublisherKit.getRtcStatsReport(). When the stats are available, the implementation of the PublisherKit.PublisherRtcStatsReportListener.onRtcStatsReport(PublisherKit publisher, PublisherKit.PublisherRtcStats[] stats) method is called. An array of PublisherRtcStats objects is passed into that method. The PublisherRtcStats object includes a jsonArrayOfReports property. This is a JSON array of RTC stats reports, which are similar to the format of the RtcStatsReport object implemented in web browsers (see these Mozilla docs). Also see this W3C documentation.

Testing a publisher's stream

You can publish a test stream and check its audio and video statistics to determine the type of stream (such as high-resolution or audio-only) supported by your connection.

To get statistics for a stream published by the local client, you must use a session that uses the OpenTok Media Router (sessions with the media mode set to routed). You can then use the SubscriberKit.setAudioStatsListener(AudioStatsListener listener) and SubscriberKit.setVideoStatsListener(VideoStatsListener listener) methods of the Subscriber object to get audio and video statistics for the stream you publish. See this topic for more information.

The opentok-network-test repo includes sample code for showing how to use statistics of a test stream before publishing to a session.