Suggestions

close search

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

Visit the Vonage API Developer Portal

Publishing streams — Windows

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 systems's microphone and camera for use in an OpenTok session. You can also use a Publisher to publish a screen-sharing video stream.

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

publisher = new Publisher(Context.Instance);
publisher.Error += Publisher_Error;

private void Publisher_Error(object sender, Publsher.ErrorEventArgs e)
{
    Console.WriteLine("Publisher error:" + e.ErrorCode);
}

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

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 OpenTok 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:

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 OpenTok 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: 

var devices = VideoCapturer.EnumerateDevices();
var selectedDevice = devices[0];
capturer = selectedDevice.CreateVideoCapturer(VideoCapturer.Resolution.High,
             VideoCapturer.VideoCapturer.FrameRate.Fps30);
publisher = new Publisher(Context.Instance, renderer: publisherVideoRenderer, capturer: capturer);
publisher.Error += Publisher_Error;

private void Publisher_Error(object sender, Publsher.ErrorEventArgs e)
{
    Console.WriteLine("Publisher error:" + e.ErrorCode);
}

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

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

Publishing a stream

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

session.Publish(publisher);

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: 

publisher.StreamCreated += Publisher_StreamCreated;
session.Publish(publisher);
private void Publisher_StreamCreated(object sender, Publisher.StreamEventArgs e)
{
    Console.WriteLine("The publisher started streaming.");
}

Stopping a publisher from streaming

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

session.unpublish(mPublisher);

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

publisher.StreamCreated += Publisher_StreamDestroyed;
session.Publish(publisher);
private void Publisher_StreamDestroyed(object sender, Publisher.StreamEventArgs e)
{
    Console.WriteLine("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, set an event handler for the Publisher AudioStatsUpdated and VideoUpdated events.

These events are sent periodically to report audio and video statistics for the publisher. The event handlers for these are passed in an array of AudioNetworkStats and VideoNetworkStats 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 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 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 Publisher.GetRtcStatsReport() method. This provides RTC stats reports for the media stream. This is an asynchronous operation. When the stats are available, the RtcStatsReport event is sent. The RtcStatsReportArgs object includes an array of PublisherRtcStats objects, which includes a JsonArrayOfReports property. This is a JSON array of RTC stats reports, which are similar to the format 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.

You can then subscribe to the stream and use the Subscriber.AudioStatsUpdated and Subscriber.VideoStatsUpdated events to get audio and video statistics for the stream you publish.