Publish: Basics

The OT.initPublisher() method initializes and returns a Publisher object. The Publisher object represents the view of a video you publish:

The OT.initPublisher() method takes three parameters:

• targetElement— (Optional) Defines the DOM element that the Publisher video replaces.

• properties— (Optional) A set of properties that customize the Publisher. The properties parameter also includes options to specify an audio and video input device used by the publisher. The properties parameter also includes options for customizing the appearance of view in the HTML page (see Customizing the UI) and select whether to publish audio and video (see Publishing audio or video only).For more publisher options, see the documentation of the properties parameter of the OT.initPublisher() method.

• completionHandler— (Optional) A completion handler that specifies whether the publisher instantiated successfully or with an error.

You can pass this Publisher object into the Session.publish() method to publish a stream to a session.

Before calling Session.publish(), you can use this Publisher object to test the microphone and camera attached to the Publisher.

The insertMode property of the properties parameter of the OT.initPublisher() method specifies how the Publisher object will be inserted in the HTML DOM, in relation to the targetElement parameter. You can set this parameter to one of the following values:

• "replace" — The Publisher object replaces contents of the targetElement. This is the default.
• "after" — The Publisher object is a new element inserted after the targetElement in the HTML DOM. (Both the Publisher and targetElement have the same parent element.)
• "before" — The Publisher object is a new element inserted before the targetElement in the HTML DOM. (Both the Publisher and targetElement have the same parent element.)
• "append" — The Publisher object is a new element added as a child of the targetElement. If there are other child elements, the Publisher is appended as the last child element of the targetElement.

For example, the following code adds a new Publisher object as a child of a publisherContainer DOM element:

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

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

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:

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

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

Note that in sessions that use the Vonage Video 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.

Using a custom video capturer

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

Screen-sharing.

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

Use the OTPublisher object to create a publisher. The view property of the object contains the view of the video you publish:

let publisher = OTPublisher(delegate: self, settings: OTPublisherSettings())!
if let publisherView = publisher.view {
    self.view.addSubview(publisherView)
    publisherView.frame = CGRect(x: 0, y: 0, width: 200, height: 150)
}

Implement the methods of the OTPublisherDelegate protocol in the object you specify as the delegate object. These methods are called when publisher-related events occur.

Pass the Publisher object into the OTSession publish(_:error:) method to publish a stream to a session.

You can set other properties of the OTPublisherSettings object to define custom settings for the publisher:

let publisherSettings = OTPublisherSettings()
publisherSettings.name = "Bob's video"
publisherSettings.audioTrack = false
publisherSettings.videoTrack = true
publisherSettings.cameraResolution = .high
publisherSettings.cameraFrameRate = .rate30FPS
let publisher = OTPublisher(delegate: self, settings: publisherSettings)!

Note that in sessions that use the Vonage Video 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.

Use the OTPublisher object to create a publisher. The view property of the object contains the view of the video you publish:

Implement the methods of the OTPublisherDelegate protocol in the object you specify as the delegate object. These methods are called when publisher-related events occur.

Pass the Publisher object into the [OTSession publish:error] method to publish a stream to a session.

You can set other properties of the OTPublisherSettings object to define custom settings for the publisher:

Note that in sessions that use the Vonage Video 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.

You can create a basic Publisher by calling the Publisher() constructor, passing in the Windows application instance:

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

By default, the Publisher uses the default video capturer, which uses the system's default microphone and camera as the audio an video source for the published stream. This is defined by the VideoCapturer in the Vonage Video SDK.

You can define a specific video capturer object for the publisher to use. This object captures video from a video source (such as a camera), and it has settings for the video (such as the frame rate and resolution).

You can use the VideoCapturer.EnumerateDevices() method to enumerate video capture devices (cameras) on the system. This returns a list of VideoDevice objects. The VideoDevice class includes a number of CreateVideoCapturer() methods to instantiate a VideoCapturer object that uses the video device:

• VideoCapturer.CreateVideoCapturer(format) — Creates a VideoCapturer object using the settings defined by a VideoFormat object.
• VideoCapturer.CreateVideoCapturer(width, height, fps) — Creates a VideoCapturer object with the resolution defined by the width and height parameters and with the frame rate defined by the fps parameter.
• VideoCapturer.CreateVideoCapturer(resolution, fps) — Creates a VideoCapturer object with the resolution defined by the resolution parameter and with the frame rate defined by the fps parameter. The OpenTok.VideoCapturer.Resolution enum defines values used by the resolution parameter: Low (320x240 pixels), Medium (640x480 pixels), and High (1280x720 pixels), and High 1080p (1920x1080 pixels).

The video capturer uses the resolution supported on the system closest to the resolution you specify.

By default, publishers use a default video renderer for Windows Presentation Foundation, which is defined by the VideoRenderer class in the Vonage Video Windows SDK. You can also specify a renderer for the video by creating a class that implements the IVideoRenderer interface. You can use a custom video renderer — see Using a custom video renderer.

The following code creates a Publisher that uses the default system video capturer with the resolution set to 720p (VideoCapturer.Resolution.High) and the frame rate set to 30 frames per second:

Note: In sessions that use the Vonage Video 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 pass in other optional parameters of the Publisher() constructor to define custom settings for the published stream:

• name — The name of the publisher video. The Stream.Name property for a stream published by this publisher will be set to this value (on all clients).
• hasAudioTrack — Whether to include an audio track in the published stream. The default is true.
• hasVideoTrack — Whether to include an audio track in the published stream. The default is true.
• stereo — Whether to enable stereo audio in the published stream. The default is false. Set this to true to publish audio from a stereo microphone.

You can also change the audio source used by the publisher. Or you can create a custom audio driver to be used by all publishers and subscribers.

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.

Note: The OpenTok.Publisher class and the OpenTok.VideoCapturer implement the System.IDisposable interface. Be sure to call the Dispose() method of these objects to release their resources when you no longer need the object (for example, when the Publisher is removed or when the app or window is closing).

Start by creating a structure of type otc_publisher_callbacks:

Use the user_data member of the otc_publisher_callbacks structure to set data you may want to reference in the callback functions. In this example, we set it to a pointer to a char array. But it could be a pointer to an instance of some other type that contains meaningful information.

The other members of the otc_publisher_callbacks structure are each callback functions that are invoked when events related to the published stream occur:

• on_stream_created — Called when the publisher starts streaming to the session.
• on_render_frame — Called each time the publisher is ready to render a new video frame to the stream.
• on_stream_destroyed — Called when the publisher's stream is destroyed.
• on_error — Called when an error occurs in publishing the stream.

All callbacks will not be made on the application or main thread but on an internal thread. The application should return the callback as quickly as possible to avoid blocking the internal thread.

See otc_publisher_callbacks in the OpenTok Linux SDK reference for details on each of the callback functions.

Call the otc_publisher_new() to create an otc_publisher structure, which represents the OpenTok publisher:

The otc_publisher_new() method takes three arguments:

• name — A name (optional) identifying the publisher of the stream.
• capturer — Use this parameter if you want to provide a custom video capturer. If it is set to NULL, the publisher uses the default system camera as the video source.

See Using a custom video capturer to see how to implement a custom video capturer.

• callbacks — The otc_publisher_callbacks publisher callback structure, described above.

Create a custom audio driver to be used by all publishers and subscribers.

You can use a custom video capturer to publish a stream with a customized video source — see Using a custom video capturer.

To publish a stream, add an OTPublisher component as a child of the OTSession object:

The publisher starts streaming when the client connects to the session. The OTPublisher object dispatches a streamCreated event when it starts streaming to the session. It dispatches an error event if there is an error publishing. Set an eventHandlers prop of the OTPublisher component, and set the streamCreated and error properties of that object to callback functions:

Pass the publisher object into the publish() method of a Session object to publish a stream to the session:

The second parameter is a completion handler function that is passed an error object if publishing fails. Otherwise the completion handler function is called with no error passed in.

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

The Publish object dispatches a streamCreated event when it starts streaming to the session:

The Publisher object has an element property, which is set to the HTML DOM element containing it.

You can set the maximum bitrate for a published stream. Setting the maximum bitrate can help to reduce bandwidth consumption when a user is connecting from a metered connection. See this documentation.

Pass the publisher object into the publish(PublisherKit publisher) method of a Session object to publish the stream to the session:

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:

You can set the maximum bitrate for a published stream. Setting the maximum bitrate can help to reduce bandwidth consumption when a user is connecting from a metered connection. See this documentation.

Pass the publisher object into the OTSession publish(_:error:) method of an OTSession object to publish the stream to the session:

var error: OTError?
session.publish(publisher, error: &error)

if let error = error {
    print("publishing failed with error: \(error)");
}

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

The OTPublisherDelegate publisher(_:streamCreated:) message is sent when the publisher starts streaming to the session.

Pass the publisher object into the [OTSession publish:error] method of an OTSession object to publish the stream to the session:

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

The [OTPublisherDelegate publisher:streamCreated:] message is sent when the publisher starts streaming to the session.

You can set the maximum bitrate for a published stream. Setting the maximum bitrate can help to reduce bandwidth consumption when a user is connecting from a metered connection. See this documentation.

Pass the publisher object into the Publish(publisher) method of a Session object to publish the stream to the session:

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

The Publisher sends the StreamCreated event when the publisher starts streaming to the session:

You can set the maximum bitrate for a published stream. Setting the maximum bitrate can help to reduce bandwidth consumption when a user is connecting from a metered connection. See this documentation.

When the application connects to a session, the on_connected() callback function of the otc_session_callbacks struct is called (see Joining a Session). In response to this, you can call the otc_session_publish() function to publish a stream to the OpenTok session:

The otc_session_publish() function takes two arguments:

• The pointer to the otc_session structure.
• The otc_publisher structure.

It returns OTC_SUCCESS when it successfully starts publishing a stream to the session. Or it returns an error, and the otc_error callback is called.

You can set the maximum bitrate for a published stream. Setting the maximum bitrate can help to reduce bandwidth consumption when a user is connecting from a metered connection. See this documentation.

You can stop publisher from streaming to the session by unmounting it (removing it from the parent OTSession component). For example, the following code stops publishing a stream after 30 seconds:

Detecting when a published stream leaves a session

The OTPublisher object dispatches a streamDestroyed event when it stops streaming to the session:

To stop a publisher call the unpublish() method of the Session object:

Note that you can individually stop sending video or audio (while still publishing).

For more information, see Adjusting audio and video.

Detecting when a published stream leaves a session

The Publisher object dispatches a streamDestroyed event when it stops streaming to the session:

The streamDestroyed event is defined by the StreamEvent class. The event includes a reason property, which details why the stream ended. These reasons include "clientDisconnected", "forceDisconnected", "forceUnpublished", or "networkDisconnected". For details, see StreamEvent.

By default, when a Publisher dispatches the streamDestroyed event, the Publisher is destroyed and removed from the HTML DOM. You can prevent this default behavior by calling the preventDefault() method of the StreamEvent object:

You may want to prevent the default behavior, and retain the Publisher, if you want to reuse the Publisher object to publish again to the session.

The Publisher also dispatches a destroyed event when the object has been removed from the HTML DOM. In response to this event, you may choose to adjust (or remove) DOM elements related to the publisher that was removed.

To stop a publisher call the unpublish(PublisherKit publisher) method of the Session object:

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

To stop a publisher call the OTSession unpublish(_:error:) method of the OTSession object:

var error: OTError?
session.unpublish(publisher, error: &error)

if let error = error {
    print("unpublishing failed with error: \(error)");
}

The OTPublisherDelegate publisher(_:streamDestroyed:) message is sent when the publisher stops streaming to the session. When this message is sent, remove the publisher's view from its superview:

publisher.view?.removeFromSuperview();

To stop a publisher call the [OTSession unpublish:error:] method of the OTSession object:

The [OTPublisherDelegate publisher:streamDestroyed:] message is sent when the publisher stops streaming to the session. When this message is sent, remove the publisher's view from its superview:

To stop a publisher call the Unpublish(publisher) method of the Session object:

The Publisher sends the StreamCreated event when the publisher starts streaming to the session:

Call the otc_session_unpublish() function, passing in the otc_session and otc_publisher structs: