.NET Server SDK

The Vonage Video .NET SDK provides methods for:

Generating sessions and tokens for Vonage Video applications that run on the .NET platform. The SDK also includes support for working with Vonage Video archives.
Vonage Video applications that run on the .NET platform
Working with Vonage Video archives
Working with Vonage Video live streaming broadcasts
Working with Vonage Video SIP interconnect
Sending signals to clients connected to a session
Disconnecting clients from sessions
Forcing clients in a session to disconnect or mute published audio

Installation

NuGet (recommended):

Either look for "Vonage" is your package manager, or run the following command using the Package Manager Console:

PM> Install-Package Vonage

Or a terminal:

dotnet add package Vonage

Usage

Initializing

The Vonage packages uses a JWT for Authorization. The SDK handles JWT generation in the background for you, but will require an ApplicationId and PrivateKey as credentials in order to generate the token.

These credentials are loaded from your project settings. For more details on how to do that, feel free to take a look at the Configuration section.

Otherwise, you can initialize the client manually, like below:

using Vonage;
using Vonage.Request;

...
var credentials = Credentials.FromAppIdAndPrivateKeyPath(applicationId, privateKeyPath);
var client = new VonageClient(credentials);
var videoClient = client.VideoClient;

The Video client exposes various functionalities of our Video APIs.

How to handle Video results

Every method will return the response wrapped into a Result<T> Monad, where T is the type of the response.

It contains either a Success state (T) if the operation succeeded or a Failure state (IResultFailure) if something went wrong. The failure contains an error message and can be converted to the according exception. It can represent any kind of issue:

invalid request
failed authentication
failed request
failed data deserialization
etc.

You can use .Match() to provide methods for both states, or you can call .GetSuccessUnsafe to get the response and catch an exception if the process failed. It contains also other methods to manipulate, transform and extract the underlying result.

Mode details and explanations on the repository.

Creating Sessions

To create a Vonage Video Session, call the client's VideoClient.SessionClient.CreateSessionAsync(CreateSessionRequest)method. You can use a default request with all default values, or create a custom one using the .Build() method.

location : An IPv4 address used as a location hint. (default: string.empty)
MediaMode : Specifies whether the session will use the Vonage Video Media Router) (MediaMode.ROUTED) or attempt to transmit streams directly between clients (MediaMode.RELAYED, the default). A routed session is required for some Vonage Video features (such as archiving).
ArchiveMode : Specifies whether the session will be automatically archived (ArchiveMode.ALWAYS) or not (ArchiveMode.MANUAL, the default)

The return value is a Result<CreateSessionResponse> object.

// Create a session that will attempt to transmit streams directly between clients 
Result<CreateSessionRequest> request = CreateSessionRequest.Default;
// Or create a custom request
Result<CreateSessionRequest> request = CreateSessionRequest.Build()
    .WithLocation("192.168.1.1")
    .WithMediaMode(MediaMode.Routed)
    .WithArchiveMode(ArchiveMode.Always)
    .Create();
    
// Send the request to the API
Result<CreateSessionResponse> response = await client.SessionClient.CreateSessionAsync(request);

Generating Tokens

Once a Session is created, you can start generating Tokens for clients to use when connecting to it. You can generate a token by calling the GenerateToken method.

var generator = services.GetRequiredService<IVideoTokenGenerator>(); 
var credentials = ...
var claims = TokenAdditionalClaims.Parse(sessionId); 

var token = generator.GenerateToken(credentials, claims)

Working with Archives

You can only archive sessions that use the Vonage Video Media Router (sessions with the media mode set to routed).

Creating an archive

You can start the recording of a Vonage Video Session using VideoClient.ArchiveClient.CreateArchiveAsync(CreateSessionRequest) method. The return value is a Result<CreateArchiveRequest> object.

Note that you can only start an Archive on a Session that has clients connected.

// Creates an archive with default values.
Result<CreateArchiveRequest> request = CreateArchiveRequest.Build()
    .WithApplicationId(applicationId)
    .WithSessionId(sessionId)
    .Create();
// Or use any optional value on the builder.    
Result<CreateArchiveRequest> request =  CreateArchiveRequest.Build()
    .WithApplicationId(applicationId)
    .WithSessionId(sessionId)
    .WithName("Archive Name")
    .WithRenderResolution(RenderResolution.FullHighDefinitionLandscape)
    .WithArchiveLayout(new Layout(LayoutType.BestFit, string.Empty, LayoutType.Pip))
    .WithOutputMode(OutputMode.Composed)
    .WithStreamMode(StreamMode.Auto)
    .DisableAudio()
    .DisableVideo()
    .Create();

// Send the request to the API
Result<Archive> response = await client.ArchiveClient.CreateArchiveAsync(request);

Here are all the methods you can use on the builder:

WithName allows you to add a name for the archive (to use for identification).
DisableVideo allows you to disable video recording.
DisableAudio allows you to disable audio recording.
WithResolution allows you to set the resolution of the recording. Please note that you cannot specify the resolution when you set the outputMode parameter to OutputMode.INDIVIDUAL.
WithOutputMode allows you to set the output mode on the stream. By default, all streams are recorded to a single ( composed) file. You can record the different streams in the session to individual files (instead of a single composed file) by providing OutputMode.INDIVIDUAL.
WithStreamMode allows you to indicate whether streams are selected automatically or manually.

Stopping an archive

You can stop the recording of a started Archive using the VideoClient.ArchiveClient.StopArchiveAsync(StopArchiveRequest) method.

Result<StopArchiveRequest> request = StopArchiveRequest.Build()
    .WithApplicationId(applicationId)
    .WithArchiveId(archiveId)
    .Create();
Result<Archive> response = await client.ArchiveClient.StopArchiveAsync(request);

Retrieving an archive

You can retrieve an Archive, with all its information, using the VideoClient.ArchiveClient.GetArchiveAsync(GetArchiveRequest) method.

var request = GetArchiveRequest.Build()
    .WithApplicationId(applicationId)
    .WithArchiveId(archiveId)
    .Create();
Result<Archive> response = await client.ArchiveClient.GetArchiveAsync(request);

Deleting an archive

You can delete an archive using the VideoClient.ArchiveClient.DeleteArchiveAsync(DeleteArchiveRequest) method.

var request = DeleteArchiveRequest.Build()
    .WithApplicationId(applicationId)
    .WithArchiveId(archiveId)
    .Create();
Result<Unit> response = await client.ArchiveClient.DeleteArchiveAsync(request);

Retrieving all archives

You can retrieve a list of all the Archives you've created, up to 1000 archives, using the VideoClient.ArchiveClient.GetArchivesAsync(GetArchivesRequest) method.

This request supports pagination using WithCount and WithOffset on the builder.

// Get a list with the first 1000 archives
var request = GetArchivesRequest.Build()
    .WithApplicationId(applicationId)
    .WithSessionId(sessionId)
    .Create();
// Get the first 50 archives
var request = GetArchivesRequest.Build()
    .WithApplicationId(applicationId)
    .WithSessionId(sessionId)
    .WithCount(50)
    .Create();
// Get the next 50 archives
var request = GetArchivesRequest.Build()
    .WithApplicationId(applicationId)
    .WithSessionId(sessionId)
    .WithCount(50)
    .WithOffset(50)
    .Create();
    
Result<GetArchivesResponse> response = await client.ArchiveClient.GetArchivesAsync(request);

Working with Streams

Retrieving a stream

You can retrieve a Stream, with all its information, using the VideoClient.SessionClient.GetStreamAsync(GetStreamRequest) method.

var request = GetStreamRequest.Build()
        .WithApplicationId(applicationId)
        .WithSessionId(sessionId)
        .WithStreamId(streamId)
        .Create();
Result<GetStreamResponse> response = await client.SessionClient.GetStreamAsync(request);

Retrieving all streams

You can retrieve all the streams in a session, using the VideoClient.SessionClient.GetStreamsAsync(GetStreamsRequest) method.

var request = GetStreamsRequest.Build()
        .WithApplicationId(applicationId)
        .WithSessionId(sessionId)
        .Create();
Result<GetStreamsResponse> response = await client.SessionClient.GetStreamsAsync(request);

Force Disconnecting

Your application server can disconnect a client from a Vonage Video session using the VideoClient.ModerationClient.DisconnectConnectionAsync(DisconnectConnectionRequest) method.

var request = DisconnectConnectionRequest.Build()
        .WithApplicationId(applicationId)
        .WithSessionId(sessionId)
        .WithConnectionId(connectionId)
        .Create();
Result<Unit> response = await client.ModerationClient.DisconnectConnectionAsync(request);

Sending Signals

Once a Session is created, you can send signals to everyone in the session or to a specific connection.

The Content parameter is an instance of SignalContent, where you can set type and data.

type (string): The type string for the signal. You can send a maximum of 128 characters, and only the following characters are allowed: A-Z, a-z, numbers (0-9), '-', '_', and '~'.
data (string): The data string for the signal. You can send a maximum of 8kB.

// Send a signal to a specific connection
var request = SendSignalRequest.Build()
    .WithApplicationId(applicationId)
    .WithSessionId(sessionId)
    .WithConnectionId(connectionId)
    .WithContent(new SignalContent("type", "data"))
    .Create();
Result<Unit> response = await client.SignalingClient.SendSignalAsync(request);

// Send a signal to all connections in a session
var request = SendSignalsRequest.Build()
    .WithApplicationId(applicationId)
    .WithSessionId(sessionId)
    .WithContent(new SignalContent("type", "data"))
    .Create();
Result<Unit> response = await client.SignalingClient.SendSignalsAsync(request);

Working with live streaming broadcasts

Starting a broadcast

You can start a live-streaming broadcast of a Vonage Video Session using the VonageClient.BroadcastClient.StartBroadcastsAsync(StartBroadcastRequest) method.

var request = StartBroadcastRequest.Build()
    .WithApplicationId(applicationId)
    .WithSessionId(sessionId)
    .WithLayout(new Layout(LayoutType.BestFit, string.Empty, LayoutType.HorizontalPresentation))
    .WithOutputs(new StartBroadcastRequest.BroadcastOutput())
    .Create();
Result<Broadcast> response = await client.BroadcastClient.StartBroadcastsAsync(request);

Stopping a broadcast

You can stop a broadcast using the VonageClient.BroadcastClient.StopBroadcastsAsync(StopBroadcastRequest) method.

var request = StopBroadcastRequest.Build()
    .WithApplicationId(applicationId)
    .WithBroadcastId(broadcastId)
    .Create();
Result<Broadcast> response = await client.BroadcastClient.StopBroadcastAsync(request);

Also see the documentation for the VonageClient.BroadcastClient.StopBroadcastsAsync(StopBroadcastRequest) and VonageClient.BroadcastClient.GetBroadcastsAsync(GetBroadcastRequest) methods.

Retrieving a broadcast

You can retrieve a broadcast using the VonageClient.BroadcastClient.StopBroadcastsAsync(StopBroadcastRequest) method.

var request = GetBroadcastRequest.Build()
    .WithApplicationId(applicationId)
    .WithBroadcastId(broadcastId)
    .Create();
Result<Broadcast> response = await client.BroadcastClient.GetBroadcastAsync(request);

Retrieving broadcasts

You can retrieve all broadcast using the VonageClient.BroadcastClient.StopBroadcastsAsync(StopBroadcastRequest) method. This method supports pagination too.

var request = GetBroadcastsRequest.Build()
    .WithApplicationId(applicationId)
    .WithSessionId(sessionId)
    .WithCount(50)
    .WithOffset(50)
    .Create();
Result<GetBroadcastsResponse> response = await client.BroadcastClient.GetBroadcastsAsync(request);

SIP

Initiating a SIP call

You can connect a SIP platform to a Vonage Video session using the VonageClient.SipClient.InitiateCallAsync(InitiateCallRequest) method.

var request = InitiateCallRequest.Build()
        .WithApplicationId(applicationId)
        .WithSessionId(sessionId)
        .WithToken(token)
        .WithSipUri(sipUri)
        .Create();
Result<InitiateCallResponse> response = await client.SipClient.InitiateCallAsync(request);

Playing a tone

You can send DTMF digits to all participants an active Vonage Video session, or to a specific client connected to that session.

// Send digits to all participants in the session
var request = PlayToneIntoCallRequest.Build()
        .WithApplicationId(applicationId)
        .WithSessionId(sessionId)
        .WithDigits(digits)
        .Create();
Result<Unit> response = await client.SipClient.PlayToneIntoCallAsync(request);

// Send digits to a specific connection
var request = PlayToneIntoConnectionRequest.Build()
        .WithApplicationId(applicationId)
        .WithSessionId(sessionId)
        .WithConnectionId(connectionId)
        .WithDigits(digits)
        .Create();
Result<Unit> response = await client.SipClient.PlayToneIntoConnectionAsync(request);

Forcing clients in a session to mute published audio

You can force the publisher to stop publishing audio, for a specific stream or all streams in a session.

// Mute all streams in a session, and mark the session as "muted"
var request = MuteStreamsRequest.Build()
        .WithApplicationId(applicationId)
        .WithSessionId(sessionId)
        .WithConfiguration(new MuteStreamsRequest.MuteStreamsConfiguration(true, Array.Empty<string>()))
        .Create();
Result<MuteStreamsResponse> response = await client.ModerationClient.MuteStreamsAsync(request);

// Mute a specific stream
var request = MuteStreamRequest.Build()
        .WithApplicationId(applicationId)
        .WithSessionId(sessionId)
        .WithStreamId(streamId)
        .Create();
Result<MuteStreamResponse> response = await client.ModerationClient.MuteStreamAsync(request);

Requirements

You need an application with Video capabilities enabled. The ApplicationId and the PrivateKey will be required for authentication.

You need a Vonage Video API key and API secret, which you can obtain by logging into your Vonage Video API account.

The Vonage .NET SDK targets netstandard2.0, which is compatible with all supported frameworks.

Release Notes

See the .NET SDK changelog page for details about each release.

Navigation