Suggestions

close search

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

Visit the Vonage API Developer Portal

Adjusting audio and video — Windows

You can make audio and video adjustments to published and subscribed streams:

Publishing audio or video only

You can toggle audio and video on or off, by set the PublishAudio and PublishVideo properties of the Publisher object. For example, the following code turns audio off:

publisher.PublishAudio = false;

Publishing in a voice-only session

To set up a voice-only session, set the hasVideoTrack parameter of the Publisher() constructor to false and set the the capturer perameter to null when you instantiate each Publisher object in the session. For example, the following code creates a publisher for a voice-only session:

mPublisher = new Publisher(Context.Instance, renderer: publisherVideoRenderer, capturer: null, hasVideo: false);

Selecting the camera used by a publisher

Call the VideoCapturer.EnumerateDevices to get a list of VideoDevice objects, representing the video devices (usually cameras) available on the system. You can then use one of the CreateVideoCapturer() methods of a VideoDevice object to create a video capturer that uses the device as the video source. You can then use that video capturer when instantiating a Publisher object:

var devices = VideoCapturer.EnumerateDevices();
var selectedDevice = devices[0];
capturer = selectedDevice.CreateVideoCapturer(VideoCapturer.Resolution.High);
publisher = new Publisher(Context.Instance, renderer: publisherVideo, capturer: capturer);

The VideoDevice class includes Name and Id properties to identify the video device.

Mirroring the local display of a publisher's video

You can set the MirrorOnLocalRender property of the VideoCaptureSettings object to have the publisher's locally rendered video mirrored (true) or not (false). Set this property in the implementation of the GetCaptureSettings() method of the custom video capturer for the Publisher object. See Using a custom video capturer.

This setting only affects the rendered video in the publisher's client application. It has no effect on the video in subscribing clients.

Switching the audio source used by publishers

You can easily change the audio input source (microphone) used by publishers. Call the static AudioDevice.EnumerateInputAudioDevices() method to get a list of AudioDevice.InputAudioDevice objects, representing available input devices. Call the AudioDevice.SetInputAudioDevice(audioInput) method to set the audio input device used by publishers.

Setting the resolution and frame rate for a video

You can set the resolution and frame rate for a publisher's stream by configuring the VideoCapturer object you use when you instantiate the Publisher object.

Note: See the 1080p developer guide for considerations about using 1080p resolution.

There a a number of ways to instantiate a VideoCapturer object. One is to call the OpenTok.VideoCapturer.EnumerateDevices() method to obtain a list of available video devices. Then use one of CreateVideoCapturer() methods of the device you select to instantiate a VideoCapturer object. For example, 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);

If the selected video device does not support the selected resolution or frame rate, the video capturer will use the closest available settings.

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.

Using a custom video capturer

Use VideoCapturer.EnumerateDevices() to get a list of available video devices (cameras). Use one of the CreateVideoCapturer() methods of the VideoDevice class to instantiate a VideoCapturer object based on the video device.

The OpenTok Windows SDK includes a IVideoCapturer interface that you can use to define custom video capturer. Create custom classes that implements thes IVideoCapturer interface to create a custom video capturer. Pass an instance of the custom video capturer class into the Publisher()instantiate the Publisher object.

The OpenTok Windows SDK calls the Start(IVideoFrameConsumer frameConsumer) method of the video capturer object to start capturing video from the custom video capturer. The SDK includes a IVideoFrameConsumer interface that define the video frame consumer for a custom capturer.

The OpenTok Windows SDK calls the Consume(VideoFrame frame) method of the custom video frame consumer object when there is a new video frame to render. The VideoFrame class, defined in the OpenTok Windows SDK, includes a VideoFrame class represents the video frame.

You can use a custom video capturer to publish a screen-sharing stream. For more information, and to see a code example, see Screen-sharing.

You can also use a custom video renderer for videos.

Using a custom audio driver

By default, the OpenTok Windows SDK uses the device microphone to capture audio to transmit to a published stream. And it uses the and speakers (or headphones) to play back audio from a subscribed stream. You can implement a custom audio driver to read and write audio data for subscribers and publishers. Create an implementation the IAudioDevice interface and its methods. The IAudioDevice.InitAudio(AudioDevice.AudioBus audioBus) method is called when the AudioDevice is initialized. Use the AudioBus object, passed into that method, to read write audio data, with its ReadRenderData(buffer, numberOfSamples) and WriteCaptureData(buffer, numberOfSamples) methods.

Additionally, you can implement the IAudioDeviceExtension interface. When a CustomAudioDevice implementing this interface is assigned via AudioDevice.SetCustomAudioDevice(), the implementation includes additional methods (for enumerating devices, selecting a specific device, or subscribing to notifications), which be wired internally to the custom audio device implementation instead of the default static one.

The MMAudioDevice class, included in the SDK, implements this interface using the Windows mmdeviceapi.h interface:

readonly MMAudioDevice audioDevice;
    
...

audioDevice = new MMAudioDevice(dispatcher);
AudioDevice.SetCustomAudioDevice(context, audioDevice);

/* Subscribe to notifications: */
audioDevice.InputDeviceAdded += AudioInputDeviceAdded;
audioDevice.InputDeviceRemoved += AudioInputDeviceRemoved;
audioDevice.DefaultInputDeviceChanged += AudioDefaultInputDeviceChanged;

/* Alternatively, you can use the following code to subscribe to
notifications and yield the same result: */
AudioDevice.Notifications notifications = new AudioDevice.Notifications(dispatcher);
notifications.InputDeviceAdded += AudioInputDeviceAdded;
notifications.InputDeviceRemoved += AudioInputDeviceRemoved;
notifications.DefaultInputDeviceChanged += AudioDefaultInputDeviceChanged;

/* Call methods */
audioDevice.SetInputAudioDevice(myInputAudioDevice.Id);

/* Alternatively, you can use the static methods in AudioDevice and yield the same result: */
AudioDevice.SetInputAudioDevice(myInputAudioDevice);

Reducing audio bandwidth with Opus DTX

Opus DTX (Discontinuous Transmission) is an audio codec that can reduce the bandwidth usage when a participant is not speaking. This can be useful in large sessions with many audio participants.

You enable Opus DTX by setting the OpusDtx property of the Publisher.Builder object you use when creating a Publisher) to true.

For more information, see this Vonage Video API knowledge base article.

Setting the audio volume for a subscriber

You can individually set the audio volume for each subscriber by calling the Subscriber.AudioVolume property.

Subscribing to audio or video only

By default, a Subscriber object is initialized to subscribe to audio and video, if they are available.

You can toggle audio on or off by setting the SubscribeToAudio property of the Subscriber object:

subscriber.SubscribeToAudio = false; // audio off
subscriber.SubscribeToAudio = true;  // audio on

You toggle video on or off by setting the SubscribeToVideo property of the Subscriber object:

subscriber.SubscribeToVideo = false; // video off
subscriber.SubscribeToVideo = true;  // video on

Note however that you can only subscribe to audio or video if the client publishing the stream includes audio or video. For example, setting SubscribeToVideo to true will have no effect if the client publishing the stream is publishing audio only.

Detecting whether a stream has audio or video

You can check the HasAudio and HasVideo properties of a Stream object to see if it has audio or video

if (!stream.HasAudio) {
	// You may want to adjust the user interface
}
if (!stream.HasVideo) {
	// You may want to adjust the user interface
}

For example, when you subscribe to a stream, you may want to adjust the user interface based on whether the stream has audio or video. For example, you may want to indicate to the user whether a stream has audio or not; or you may not want to display a subscriber's view if a stream does not have video.