Show / Hide Table of Contents

    Interface IVideoSocket

    Interface to a VideoSocket.

    Inherited Members
    IDisposable.Dispose()
    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>
    Back to top Copyright (c) Microsoft Corporation. All rights reserved.