The OpenTok .NET SDK provides methods for:
Using the Package Manager Console:
PM> Install-Package OpenTok
Download the latest release from the Releases Page.
Unzip the file and place the place the OpenTok.dll
, dependent assemblies, and supporting files into your
own project.
Import the OpenTokSDK
namespace into any files that will be using OpenTok objects. Then initialize an
OpenTokSDK.OpenTok
object using your own API Key and API Secret.
using OpenTokSDK;
// ...
int ApiKey = 000000; // YOUR API KEY
string ApiSecret = "YOUR API SECRET";
var OpenTok = new OpenTok(ApiKey, ApiSecret);
You can decide to add a custom value to the user-agent value passed with every request.
var OpenTok = new OpenTok(ApiKey, ApiSecret);
OpenTok.SetCustomUserAgent(customUserAgent);
If the custom value has been set, the user-agent will comply to the following format: Opentok-DotNet-SDK/{version}/{customValue}
.
To create an OpenTok Session, call the OpenTok
instance's
CreateSession(string location, MediaMode mediaMode, ArchiveMode archiveMode)
or
CreateSessionAsync(string location, MediaMode mediaMode, ArchiveMode archiveMode)
method. Each of the parameters are optional and can be omitted if not needed. They are:
string location
: An IPv4 address used as a location hint. (default: "")
MediaMode mediaMode
: Specifies whether the session will use the OpenTok Media Router
(MediaMode.ROUTED) or attempt to transmit streams directly between clients
(MediaMode.RELAYED, the default)
ArchiveMode archiveMode
: Specifies whether the session will be automatically archived
(ArchiveMode.ALWAYS) or not (ArchiveMode.MANUAL, the default)
The return value is a OpenTokSDK.Session
object. Its Id
property is useful to get an identifier that can be saved to a
persistent store (such as a database).
// Create a session that will attempt to transmit streams directly between clients
var session = OpenTok.CreateSession();
// Store this sessionId in the database for later use:
string sessionId = session.Id;
// Create a session that uses the OpenTok Media Router (which is required for archiving)
var session = OpenTok.CreateSession(mediaMode: MediaMode.ROUTED);
// Store this sessionId in the database for later use:
string sessionId = session.Id;
// Create an automatically archived session:
var session = OpenTok.CreateSession(mediaMode: MediaMode.ROUTED, ArchiveMode.ALWAYS);
// Store this sessionId in the database for later use:
string sessionId = session.Id;
Once a Session is created, you can start generating Tokens for clients to use when connecting to it.
You can generate a token either by calling an OpenTokSDK.OpenTok
instance's
GenerateToken(string sessionId, Role role, double expireTime, string data)
method, or by calling a OpenTokSDK.Session
instance's GenerateToken(Role role, double expireTime, string data)
method after creating it. In the first method, the
sessionId
is required and the rest of the parameters are optional. In the second method, all the parameters are optional.
// Generate a token from a sessionId (fetched from database)
string token = OpenTok.GenerateToken(sessionId);
// Generate a token by calling the method on the Session (returned from CreateSession)
string token = session.GenerateToken();
// Set some options in a token
double inOneWeek = (DateTime.UtcNow.Add(TimeSpan.FromDays(7)).Subtract(new DateTime(1970, 1, 1))).TotalSeconds;
string token = session.GenerateToken(role: Role.MODERATOR, expireTime: inOneWeek, data: "name=Johnny");
You can start the recording of an OpenTok Session using a OpenTokSDK.OpenTok
instance's
StartArchive(sessionId, name, hasVideo, hasAudio, outputMode, resolution)
method. This will return an
OpenTokSDK.Archive
instance. The parameter name
is optional and used to assign a name for the
Archive. Note that you can only start an Archive on a Session that has clients connected.
// A simple Archive (without a name)
var archive = OpenTok.StartArchive(sessionId);
or
// A simple Archive (without a name)
var archive = await OpenTok.StartArchiveAsync(sessionId);
then
// Store this archive ID in the database for later use
Guid archiveId = archive.Id;
You can add a name for the archive (to use for identification) by setting the name
parameter of
the OpenTok.StartArchive()
method.
You can also disable audio or video recording by setting the hasAudio
or hasVideo
parameter of
the OpenTok.StartArchive()
method false
.
You can also set the resolution of the recording to high definition by setting the resolution
parameter of the OpenTok.StartArchive()
method.
Accepted values are "640x480" (SD landscape, the default), "1280x720" (HD landscape), "1920x1080" (FHD landscape), "480x640" (SD portrait), "720x1280" (HD portrait), or "1080x1920" (FHD portrait).
Please note that you cannot specify the resolution
when you set the outputMode
parameter to OutputMode.INDIVIDUAL
.
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 setting the
outputMode
parameter of the OpenTok.StartArchive()
method OutputMode.INDIVIDUAL
.
You can stop the recording of a started Archive using a OpenTokSDK.OpenTok
instance's
StopArchive(String archiveId)
method or using the OpenTokSDK.Archive
instance's Stop()
method.
// Stop an Archive from an archive ID (fetched from database)
var archive = OpenTok.StopArchive(archiveId);
or
var archive = OpenTok.StopArchiveAsync(archiveId);
To get an OpenTokSDK.Archive
instance (and all the information about it) from an archive ID, use the
OpenTokSDK.OpenTok
instance's GetArchive(archiveId)
method.
var archive = OpenTok.GetArchive(archiveId);
or
var archive = OpenTok.GetArchiveAsync(archiveId);
To delete an archive, you can call a OpenTokSDK.OpenTok
instance's DeleteArchive(archiveId)
method or
call the OpenTokSDK.Archive
instance's Delete()
method.
// Delete an archive from an archive ID (fetched from database)
OpenTok.DeleteArchive(archiveId);
// Delete an archive from an Archive instance (returned from GetArchive)
Archive.Delete();
or
// Delete an archive from an archive ID (fetched from database)
OpenTok.DeleteArchiveAsync(archiveId);
// Delete an archive from an Archive instance (returned from GetArchive)
Archive.DeleteAsync();
You can also get a list of all the Archives you've created (up to 1000) with your API Key. This is
done using an OpenTokSDK.OpenTok
instance's ListArchives(int offset, int count)
method. You may optionally
paginate the Archives you receive using the offset and count parameters. This will return an
OpenTokSDK.ArchiveList
object.
// Get a list with the first 50 archives created by the API Key
var archives = OpenTok.ListArchives();
var archives = OpenTok.ListArchivesAsync();
// Get a list of the first 50 archives created by the API Key
var archives = OpenTok.ListArchives(0, 50);
var archives = OpenTok.ListArchivesAsync(0, 50);
// Get a list of the next 50 archives
var archives = OpenTok.ListArchives(50, 50);
var archives = OpenTok.ListArchivesAsync(50, 50);
// Get a list of the first 50 archives created for the given sessionId
var archives = OpenTok.ListArchives(sessionId:sessionId);
var archives = OpenTok.ListArchivesAsync(sessionId:sessionId);
Note that you can also create an automatically archived session, by passing in ArchiveMode.ALWAYS
as the archiveMode
parameter when you call the OpenTok.CreateSession()
method (see "Creating
Sessions," above).
You can get information about a stream by calling the GetStream(sessionId, streamId)
method of the OpenTok
class.
Stream stream = OpenTok.GetStream(sessionId, streamId);
// Stream Properties
stream.Id; // string with the stream ID
stream.VideoType; // string with the video type
stream.Name; // string with the name
stream.LayoutClassList; // list with the layout class list
You can get information about all the streams in a session by calling the ListStreams(sessionId)
method of the OpenTok
class.
StreamList streamList = OpenTok.ListStreams(sessionId);
streamList.Count; // total count
Your application server can disconnect a client from an OpenTok session by calling the ForceDisconnect(sessionId, connectionId)
method of the OpenTok
class.
// Force disconnect a client connection
OpenTok.ForceDisconnect(sessionId, connectionId);
Once a Session is created, you can send signals to everyone in the session or to a specific connection. You can send a signal by calling the Signal(sessionId, signalProperties, connectionId)
method of the OpenTok
class.
The sessionId
parameter is the session ID of the session.
The signalProperties
parameter is an instance of the SignalProperties
class where you can set the data
paramter and the type
parameter.
data
(string) -- The data string for the signal. You can send a maximum of 8kB.type
(string) -- (Optional) The type string for the signal. You can send a maximum of 128 charaacters, and only the following characters are allowed: A-Z, a-z, numbers (0-9), '-', '_', and '~'.The connectionId
parameter is an optional string used to specify the connection ID of a client conencted to the session. If you specify this value, the signal is sent to the specified client. Otherwise, the signal is sent to all clients connected to the session.
string sessionId = "SESSIONID";
SignalProperties signalProperties = new SignalProperties("data", "type");
OpenTok.Signal(sessionId, signalProperties);
string connectionId = "CONNECTIONID";
OpenTok.Signal(sessionId, signalProperties, connectionId);
You can start a live-streaming broadcast of an OpenTok Session using a OpenTokSDK.OpenTok
instance's
StartBroadcast(sessionId, hls, rtmpList, resolution, maxDuration, layout)
method. This returns an
OpenTokSDK.Broadcast
instance.
Also see the documentation for the Opentok.StopBroadcast()
and OpenTok.GetBroadcast()
methods.
You can connect a SIP platform to an OpenTok session using the
Opentok.Dial(sessionId, token, sipUri, options)
or
Opentok.DialAsync(sessionId, token, sipUri, options)
method.
You can send DTMF digits to all participants an active OpenTok session, or to a specific client
connected to that session, using the Opentok.PlayDTMF(sessionId, digits, connectionId)
or
Opentok.PlayDTMFAsync(sessionId, digits, connectionId)
method.
You can force a specific client to disconnect from an OpenTok session using the
Opentok.ForceDisconnect(sessionId, connectionId)
method.
You can force the publisher of a specific stream to stop publishing audio using the
Opentok.ForceMuteStream(sessionId, stream)
or Opentok.ForceMuteStreamAsync(sessionId, stream)
method.
You can force the publisher of all streams in a session ((except for an optional list of streams)
to stop publishing audio using the Opentok.ForceMuteAll(sessionId, excludedStreamIds)
or Opentok.ForceMuteAllAsync(sessionId, excludedStreamIds)
method.
You can then disable the mute state of the session by calling the
Opentok.DisableForceMute(sessionId)
or Opentok.DisableForceMuteAsync(sessionId)
method.
You can start an Experience Composer
render using the Opentok.StartRenderAsync()
method:
string sessionId = "opentok-session-id";
string token = "token-for-opentok-session";
string url = "https://your-render-url/path/";
StartRenderRequest request = new StartRenderRequest(sessionId, token, url);
OpenTok.StartRenderAsync(request);
To stop a renderer, call the Opentok.StopRenderAsync()
method.
To list renderers, call the Opentok.ListRendersAsync()
method.
You can start an Audio Connector stream by calling the OpenTok.StartAudioConnectorAsync(AudioConnectorStartRequest request)
method:
var webSocket = new AudioConnectorStartRequest.WebSocket(
new Uri("wss://service.com/ws-endpoint"),
new []{"streamId-1", "streamId-2"},
new Dictionary<string, string>
{
{"X-CustomHeader-Key1", "headerValue1"},
{"X-CustomHeader-Key2", "headerValue2"},
});
var startRequest = new AudioConnectorStartRequest(sessionId, token, webSocket);
AudioConnector response = await this.OpenTok.StartAudioConnectorAsync(startRequest);
If you would like to adjust the timeouts for Http Requests sent by the client SDK you can by calling OpenTok.SetDefaultRequestTimeout(int timeout) - note timeout is in milliseconds
this.OpenTok = new OpenTok(apiKey, apiSecret);
this.OpenTok.SetDefaultRequestTimeout(2000);
You need an OpenTok API key and API secret, which you can obtain by logging into your Vonage Video API account.
The OpenTok .NET SDK requires .NET Framework 4.5.2 or greater.
NOTE: When using on 4.5.2 TLS 1.2 is not enabled by default. You should use something like the following to force the runtime onto at least TLS 1.2
ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12;
Alternatively, if your application is dependent on a different version of TLS for other APIs, you can alternatively add TLS to the list of supported methods with a bitwise OR:
ServicePointManager.SecurityProtocol |= SecurityProtocolType.Tls12;
See the Releases page for details about each release.
Changes in v3.0.0:
This version requires .NET Framework 4.5.2 or greater.
Changes in v2.2.1:
The default setting for the CreateSession()
method is to create a session with the media mode set
to relayed. In previous versions of the SDK, the default setting was to use the OpenTok Media Router
(media mode set to routed). In a relayed session, clients will attempt to send streams directly
between each other (peer-to-peer); if clients cannot connect due to firewall restrictions, the
session uses the OpenTok TURN server to relay audio-video streams.
Changes in v2.2.0:
This version of the SDK includes support for working with OpenTok archives.
This version of the SDK includes a number of improvements in the API design. These include a number of API changes:
New OpenTok class -- The name of the main class has changed from OpenTokSDK to OpenTok.
In the previous version, the constructor was OpenTokSDK()
.
In v2.2, it is OpenTok(int apiKey, int apiSecret)
.
CreateSession -- In the previous version, there were two methods to create a session:
OpenTokSDK.CreateSession(String location)
and
OpenTokSDK.CreateSession(String location, Dictionary<string, object> options)
.
These methods returned a string (the session ID).
In v2.2, the OpenTok class includes one method, which takes two parameters (both optional):
CreateSession(string location = "", MediaMode mediaMode = MediaMode.ROUTED)
.
The mediaMode
parameter replaces the p2p.preference
setting in the
previous version. The method returns a Session Object.
GenerateToken -- In the previous version, there were two methods:
OpenTokSDK.GenerateToken(string sessionId)
and
OpenTokSDK.GenerateToken(string sessionId, Dictionary<string, object> options)
In v2.2, this is replaced with the following method:
OpenTokSDK.OpenTok.GenerateToken(string sessionId, Role role = Role.PUBLISHER, double expireTime = 0, string data = null)
.
All parameters, except the sessionId
parameter, are optional.
Also, the Session class includes a method for generating tokens:
OpenTokSDK.Session.GenerateToken(Role role = Role.PUBLISHER, double expireTime = 0, string data = null)
.