Interface IVideoSocket

Interface to a VideoSocket.

Inherited Members

Namespace: Microsoft.Skype.Bots.Media

Assembly: Microsoft.Skype.Bots.Media.dll

Syntax

public interface IVideoSocket : IDisposable

Properties

MediaType

MediaType of the video socket. This could be Video or Vbss. The MediaType is set after the socket is passed to the CreateMediaConfiguration API

Declaration

MediaType MediaType { get; }

Property Value

Type	Description
MediaType

SocketId

The 0-based ID of the socket. This socket ID is useful to identify a socket in a multiview (ie. more than 1 video socket) call. The same ID is used in the event args of the VideoMediaReceived and VideoSendStatusChanged events that this class may raise. The socket ID property will be present in both single view and multiview cases. The ID maps to the order in which the video sockets are provided to the CreateMediaConfiguration API. Eg., if the collection of IVideoSocket objects in the CreateMediaConfiguration API contains {socketA, socketB, socketC}, the sockets will have the ID mapping of: 0 for socketA, 1 for socketB and 2 for socketC. Before the call to CreateMediaConfiguration, the SocketId has a value of -1.

Declaration

int SocketId { get; }

Property Value

Type	Description
Int32

Methods

GetQualityOfExperienceData()

Get the Quality of Experience (QoE) data for the video socket.

Declaration

VideoQualityOfExperienceData GetQualityOfExperienceData()

Returns

Type	Description
VideoQualityOfExperienceData

Remarks

The bot should fetch the QoE data no more than once every 30 seconds.

RequestKeyFrame()

Allows the application to request for key frame. Only valid for sockets with the ReceiveColorFormat as H264

Declaration

void RequestKeyFrame()

Send(VideoMediaBuffer)

Sends a frame of video media.

Declaration

void Send(VideoMediaBuffer buffer)

Parameters

Type	Name	Description
VideoMediaBuffer	buffer	VideoMediaBuffer containing the frame of video media to send.

Remarks

The application must create a concrete class which derives from the VideoMediaBuffer abstract class. The buffer object passed to the Send method is still potentially in-use after the method returns to the caller. The application must not free the buffer's data until the the buffer object's Dispose() method is invoked by the Media Platform.

The application should be sending up to 30 video frames per second.

The VideoSocket must be enabled to send media via the VideoSocketSettings.StreamDirections property.

SetReceiveBandwidthLimit(UInt32)

Sets the bandwidth limit on the receive stream of the VideoSocket. This is only supported if the socket supports receiving H264 video format. It is recommended to wait for the VideoReceiveStatusChanged event with MediaReceiveStatus Active state during the initial call setup before applying the receive bandwidth limit on the socket. Bandwidth range (in bits per second) for various resolutions and frame rates per media type:

Media type: Video

1000000 - 4000000 1080p at 30 fps

550000 - 2500000 720p at 30 fps

375000 - 1500000 540p at 30 fps

200000 - 800000 360p at 30 fps

150000 - 250000 360p at 15 fps

120000 - 220000 240p at 15 fps

60000 - 200000 180p at 15 fps

20000 - 100000 180p at 7.5 fps

10000 - 25000 180p at 3.75 fps

1000 - 12500 180p at 1.875 fps

Media type: Vbss

Resolution: 1080p

2000000 - 4000000 at 30 fps

600000 - 3000000 at 15 fps

300000 - 700000 at 7.5 fps

150000 - 350000 at 3.75 fps

70000 - 200000 at 1.875 fps

Declaration

void SetReceiveBandwidthLimit(uint bitsPerSecond)

Parameters

Type	Name	Description
UInt32	bitsPerSecond	The receive bitrate

SetSendBandwidthLimit(UInt32)

Sets the bandwidth limit on the send stream of the VideoSocket. This is only supported if the socket supports sending H264 video formats. It is recommended to wait for the VideoSendStatusChanged event with MediaSendStatus Active state during the initial call setup before applying the send bandwidth limit on the socket.

Bandwidth range (in bits per second) for various resolutions and frame rates per media type:

Media type: Video

1000000 - 4000000 1080p at 30 fps

550000 - 2500000 720p at 30 fps

375000 - 1500000 540p at 30 fps

200000 - 800000 360p at 30 fps

150000 - 250000 360p at 15 fps

120000 - 220000 240p at 15 fps

60000 - 200000 180p at 15 fps

20000 - 100000 180p at 7.5 fps

10000 - 25000 180p at 3.75 fps

1000 - 12500 180p at 1.875 fps

Media type: Vbss

Resolution: 1080p

2000000 - 4000000 at 30 fps

600000 - 3000000 at 15 fps

300000 - 700000 at 7.5 fps

150000 - 350000 at 3.75 fps

70000 - 200000 at 1.875 fps

Declaration

void SetSendBandwidthLimit(uint bitsPerSecond)

Parameters

Type	Name	Description
UInt32	bitsPerSecond	The send bitrate

Subscribe(VideoResolution)

Request to receive the video of the peer in a 1:1 call. No need to specify a MediaSourceId. The bot cannot subscribe to a video source unless the VideoReceiveStatusChanged event is raised indicating the VideoSocket's MediaReceiveStatus is Active.

Declaration

void Subscribe(VideoResolution preferredVideoResolution)

Parameters

Type	Name	Description
VideoResolution	preferredVideoResolution	The requested video resolution. The received video frames should have this resolution if the bandwidth constraints and sender capabilities allow, however the bot may receive video frames at a resolution lower than requested.

Subscribe(VideoResolution, UInt32)

Request to receive the video source of a participant in a meeting or group call. The video source must be identified by its MediaSourceId available from the roster. The bot cannot subscribe to a video source unless the VideoReceiveStatusChanged event is raised indicating the VideoSocket's MediaReceiveStatus is Active.

Declaration

void Subscribe(VideoResolution preferredVideoResolution, uint MediaSourceId)

Parameters

Type	Name	Description
VideoResolution	preferredVideoResolution	The requested video resolution. The received video frames should have this resolution if the bandwidth constraints and sender capabilities allow, however the bot may receive video frames at a resolution lower than requested.
UInt32	MediaSourceId	Media source identifier of the video source to be received

Exceptions

Type	Condition
ObjectDisposedException	Thrown if the VideoSocket is disposed.
InvalidOperationException	Thrown if the subscription is invalid.
SkypeMediaException	Thrown if an internal media failure occurs.

Unsubscribe()

Stops the current video subscription on the VideoSocket. The VideoMediaReceived events will stop raising video buffers.

Declaration

void Unsubscribe()

UpdateVideoSendCapability(VideoSendCapability)

Updates the send capabilities (such as SupportedSendVideoFormats or MaxConcurrentSendStreams) of the video socket, allowing the bot to add and remove video formats mid-call.

Declaration

void UpdateVideoSendCapability(VideoSendCapability capability)

Parameters

Type	Name	Description
VideoSendCapability	capability

Events

MediaStreamFailure

This event is raised if there is a network connection failure with the peer. To recover, the bot will need to start a new call or rejoin the meeting.

Declaration

event EventHandler<MediaStreamFailureEventArgs> MediaStreamFailure

Event Type

Type	Description
EventHandler<MediaStreamFailureEventArgs>

Remarks

Note: this event can be raised even if there is no active video subscription; i.e., the VideoSocket is "idle" and not receiving media.

MediaStreamQualityChanged

The event is raised if a media stream quality change was detected

Declaration

event EventHandler<VideoMediaStreamQualityChangedEventArgs> MediaStreamQualityChanged

Event Type

Type	Description
EventHandler<VideoMediaStreamQualityChangedEventArgs>

VideoKeyFrameNeeded

If the application has configured the VideoSocket to receive encoded media, this event is raised each time a key frame is needed. Events are serialized, so only one event at a time is raised to the app.

Declaration

event EventHandler<VideoKeyFrameNeededEventArgs> VideoKeyFrameNeeded

Event Type

Type	Description
EventHandler<VideoKeyFrameNeededEventArgs>

VideoMediaReceived

If the application has configured the VideoSocket to receive media, this event is raised each time a frame of video media is received. Once the application has consumed the buffer, it must call the buffer's Dispose() method.

Declaration

event EventHandler<VideoMediaReceivedEventArgs> VideoMediaReceived

Event Type

Type	Description
EventHandler<VideoMediaReceivedEventArgs>

Remarks

The incoming video frame rate is variable. The frame rate can vary between 1.875 frames per second (fps) up to 30 fps. The application must be able to receive up to 30 video buffers per second. Events are serialized, so only one event at a time is raised to the app. The event handler should return as quickly as possible; any time-consuming per-frame processing should be performed asynchronously from the event handler.

VideoReceiveStatusChanged

If the application has configured the VideoSocket to receive media, this event is raised to inform the application when it is ready to receive media. When the status is active the application can subscribe to a video source, when inactive video subscription won't be allowed

Declaration

event EventHandler<VideoReceiveStatusChangedEventArgs> VideoReceiveStatusChanged

Event Type

Type	Description
EventHandler<VideoReceiveStatusChangedEventArgs>

VideoSendStatusChanged

If the application has configured the VideoSocket to send media, this event is raised to inform the application when it may begin sending media and when it should stop. The application cannot send media before receiving a VideoMediaSendStatusChanged event indicating the SendStatus is Active, such media will be discarded.

Declaration

event EventHandler<VideoSendStatusChangedEventArgs> VideoSendStatusChanged

Event Type

Type	Description
EventHandler<VideoSendStatusChangedEventArgs>