OpenTok .NET SDK
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
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);
To create an OpenTok Session, call the
CreateSession(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
GenerateToken(string sessionId, Role role, double expireTime, string data) method, or by calling a
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 option. 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");
Working with Archives
You can start the recording of an OpenTok Session using a
StartArchive(sessionId, name, hasVideo, hasAudio, outputMode) 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); // 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
You can also disable audio or video recording by setting the
hasVideo parameter of
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
You can stop the recording of a started Archive using a
StopArchive(String archiveId) method or using the
// Stop an Archive from an archive ID (fetched from database) var archive = OpenTok.StopArchive(archiveId);
To get an
OpenTokSDK.Archive instance (and all the information about it) from an archive ID, use the
var archive = OpenTok.GetArchive(archiveId);
To delete an archive, you can call a
DeleteArchive(archiveId) method or
// 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();
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
ListArchives(int offset, int count) method. You may optionally
paginate the Archives you receive using the offset and count parameters. This will return an
// Get a list with the first 1000 archives created by the API Key var archives = OpenTok.ListArchives(); // Get a list of the first 50 archives created by the API Key var archives = OpenTok.ListArchives(0, 50); // Get a list of the next 50 archives var archives = OpenTok.ListArchives(50, 50);
Note that you can also create an automatically archived session, by passing in
archiveMode parameter when you call the
OpenTok.CreateSession() method (see "Creating
There are two sample applications included with the SDK. To get going as fast as possible, clone the whole repository and follow the Walkthroughs:
Reference documentation is available at https://www.tokbox.com/opentok/libraries/server/dot-net/reference/ and in the docs directory of the SDK.
You need an OpenTok API key and API secret, which you can obtain at https://dashboard.tokbox.com.
The OpenTok .NET SDK requires .NET Framework 3.5 or greater.
See the Releases page for details about each release.
Important changes since v2.2.0
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, 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
mediaModeparameter replaces the
p2p.preferencesetting in the previous version. The method returns a Session Object.
GenerateToken -- In the previous version, there were two methods:
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
sessionIdparameter, 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).
Development and Contributing
See https://support.tokbox.com/ for all our support options.
Find a bug? File it on the Issues page. Hint: test cases are really helpful!