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:
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:
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), High
(1280x720 pixels), and High1080p
(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 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:
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).
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.");
}
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.");
}
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:
ConnectionId
— The connection ID of the client subscribing to the streamSubscriberId
— The subscriber ID of the client subscribing to the streamThese two properties are undefined for a publisher in a routed session.
To get more detailed stream statistics, 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.
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.