Documentation
Free API Key

.NET SDK V3 to V4 Migration Guide

Migrating from Deepgram .NET SDK v3 to the Deepgram .NET SDK v4

Suggest Edits

📘

This guide is for users with experience using the Deepgram .NET SDK v3 who want to migrate to the Deepgram .NET SDK v4. This is not an end-to-end guide, but a reference for people using our existing .NET SDK to migrate to our newest version.

Notable Changes

  • Significant Restructure of the .NET SDK
  • Improved Implementation for Live, PreRecorded, and Manage Clients
  • Implements Text-to-Speech API
  • Implements Intelligence APIs for PreRecorded and Text (Summary, Intent, Topic, Sentiment)
  • Support for self-hosted/on-prem (previously not supported)
  • Improved and Independent Timeout Capabilities per API Call
  • Verbosity Logging Levels for Troubleshooting
  • Custom Header and Query Parameters for API calls
  • Better Error Handling
  • Support for future products (APIs)

Migration Guide

This section of the migration guide focuses on the SDK's PreRecorded and Live Clients. It will allow you to transition to the latest version of the SDK.

Installation

# The latest version will definitely be newer than version 4.0.0 listed below
# Visit https://www.nuget.org/packages/Deepgram for the latest version available.
dotnet add package Deepgram

Transcription: Pre-Recorded

There are two methods for transcribing Pre-Recorded audio:

  • Using a local file on the file system
  • Providing a URL pointing to an supported audio file

Local File Transcription

Transcribe a local file on the same filesystem as the app is running.

var credentials = new Credentials(DEEPGRAM_API_KEY);

var deepgramClient = new DeepgramClient(credentials);

using (FileStream fs = File.OpenRead("path\\to\\file"))
{
    var response = await deepgramClient.Transcription.Prerecorded.GetTranscriptionAsync(
        new StreamSource(
            fs,
            "audio/wav"),
        new PrerecordedTranscriptionOptions()
        {
            Model = "nova-2",
        });
}

// Set "DEEPGRAM_API_KEY" environment variable to your Deepgram API Key
var deepgramClient = ClientFactory.CreateListenRESTClient();

var audioData = File.ReadAllBytes(@"Bueller-Life-moves-pretty-fast.wav");
var response = await deepgramClient.TranscribeFile(
  audioData,
  new PreRecordedSchema()
  {
    Model = "nova-2",
  });

Console.WriteLine(JsonSerializer.Serialize(response, options));

URL File Transcription

Transcribe a remote file by sending a publicly accessible URL.

var credentials = new Credentials("YOUR API KEY");
var deepgramClient = new DeepgramClient(credentials);

var response = await deepgramClient.Transcription.Prerecorded.GetTranscriptionAsync(
  new UrlSource("https://dpgr.am/bueller.wav"),
  new PrerecordedTranscriptionOptions(){
    Tier = "nova-2",
  }
);

Console.WriteLine(JsonConvert.SerializeObject(response));

// Set "DEEPGRAM_API_KEY" environment variable to your Deepgram API Key
var deepgramClient = ClientFactory.CreateListenRESTClient();

var response = await deepgramClient.TranscribeUrl(
  new UrlSource("https://dpgr.am/bueller.wav"),
  new PreRecordedSchema()
  {
    Model = "nova-2",
  });

Console.WriteLine(JsonSerializer.Serialize(response, options));

Transcription: Live

The Live Client abstracts the underlying WebSocket implementation from the user for greater usability. This in turn only requires that you deal with higher-level functions like Connect(), Send(), Stop() methods.

var credentials = new Credentials(DEEPGRAM_API_KEY);

var deepgramClient = new DeepgramClient(credentials);

using (var deepgramLive = deepgramClient.CreateLiveTranscriptionClient())
{
    deepgramLive.TranscriptReceived += HandleTranscriptReceived;

    // Connection opened so start sending audio.
    async void HandleConnectionOpened(object? sender, ConnectionOpenEventArgs e)
    {
        byte[] buffer;

        using (FileStream fs = File.OpenRead("path\\to\\file"))
        {
            buffer = new byte[fs.Length];
            fs.Read(buffer, 0, (int)fs.Length);
        }

        var chunks = buffer.Chunk(1000);

        foreach (var chunk in chunks)
        {
            deepgramLive.SendData(chunk);
            await Task.Delay(50);
        }

        await deepgramLive.FinishAsync();
    }

    void HandleTranscriptReceived(object? sender, TranscriptReceivedEventArgs e)
    {
        if (e.Transcript.IsFinal && e.Transcript.Channel.Alternatives.First().Transcript.Length > 0) {
            var transcript = e.Transcript;
            Console.WriteLine($"[Speaker: {transcript.Channel.Alternatives.First().Words.First().Speaker}] {transcript.Channel.Alternatives.First().Transcript}");
        }
    }

    var options = new LiveTranscriptionOptions()
  	{
      Model = "nova-2"
    };
    await deepgramLive.StartConnectionAsync(options);

    while (deepgramLive.State() == WebSocketState.Open) { }
}

// Set "DEEPGRAM_API_KEY" environment variable to your Deepgram API Key
var liveClient = ClientFactory.CreateListenWebSocketClient();

// Subscribe to the EventResponseReceived event
liveClient.Subscribe(new EventHandler<ResultResponse>((sender, e) =>
{
	Console.WriteLine($"Speaker: {e.Channel.Alternatives[0].Transcript}\n");
}));

// Start the connection
var liveSchema = new LiveSchema()
{
  Model = "nova-2",
};
await liveClient.Connect(liveSchema);

// Send some audio data
var audioData = File.ReadAllBytes(@"preamble.wav");
liveClient.Send(audioData);

Management API

Below is a transition guide for using the Manage APIs.

Get all projects for a user

var result = await deepgramClient.Projects.ListProjectsAsync();

var result = await manageClient.GetProjects();

See our API reference for more info.

Get a project

var result = await deepgramClient.Projects.ListProjectAsync(projectId);

var result = await manageClient.GetProject(projectId);

See our API reference for more info.

Update a project

var project = new Project()
{
    Project = "projectId string",
    Name = "New name for Project"
}
var result = await deepgramClient.Projects.UpdateProjectAsync(project);

var updateOptions = new ProjectSchema()
{
  Name = "My TEST RENAME Example"
};

var result = await manageClient.UpdateProject(projectId, updateOptions);

See our API reference for more info.

Delete a project

var result = await deepgramClient.Projects.DeleteProjectAsync(projectId);

var result = await manageClient.DeleteProject(projectId);

See our API reference for more info.

Get all project key details

var result = await deepgramClient.Keys.ListKeysAsync(projectId);

 var result = await manageClient.GetKeys(myId);

See our API reference for more info.

Get a project key

var result = await deepgramClient.Keys.GetKeyAsync(projectId,keyId);

var result = await manageClient.GetKey(projectId, keyId);

See our API reference for more info.

Create a project key

var scopes = new string[]{"admin","member"};
var result = await deepgramClient.Keys.CreateKeyAsync(projectId,comment,scopes);

var createKey = new KeySchema()
{
  Comment = "MyTestKey",
  Scopes = new List<string> { "member" },
};

var result = await manageClient.CreateKey(projectId, createKey);

See our API reference for more info.

Delete a project key

var result = await deepgramClient.Keys.DeleteKeyAsync(projectId, keyId);

var result = await manageClient.DeleteKey(projectId, keyId);

See our API reference for more info.

Get all project members

var result = await deepgramClient.Projects.GetMembersScopesAsync(projectId,memberId);

var result = memberClient.GetMembers(projectId);

See our API reference for more info.

Remove a project member

var result = await deepgramClient.Projects.RemoveMemberAsync(projectId,memberId);

var result = manageClient.RemoveMember(projectId, memberId);

See our API reference for more info.

Get all scopes for a project member

var result = await deepgramClient.Keys. GetMemberScopesAsync(projectId,memberId);

var result = await manageClient.GetMemberScopes(projectId, memberId);

See our API reference for more info.

Update a scope for a project member

var scopeOptions = new UpdateScopeOption(){Scope = "admin"};
var result = await deepgramClient.Keys.UpdateScopeAsync(projectId,memberId,scopeOptions);

var scopeUpdate = new MemberScopeSchema()
{
  Scope = "admin"
};
var result = await manageClient.UpdateMemberScope(projectId, memberId, scopeUpdate);

See our API reference for more info.

Get all usage requests for a project

var listAllRequestOptions = new listAllRequestOptions()
{
     StartDateTime = DateTime.Now
};
var result = await deepgramClient.Usage.ListAllRequestsAsync(projectId,listAllRequestOptions);

var requestsOptions = new UsageRequestsSchema();
var result = await manageClient.GetUsageRequests(projectId, requestsOptions);

See our API reference for more info.

Get a usage request for a project

var result = await deepgramClient.Usage.GetUsageRequestAsync(projectId,requestId);

var result = await manageClient.GetUsageRequest(projectId, requestId);

See our API reference for more info.

Get the project usage summary

var getUsageSummmaryOptions = new GetUsageSummmaryOptions()
{
    StartDateTime = DateTime.Now
}
var result = await deepgramClient.Usage.GetUsageSummaryAsync(projectId,getUsageSummmaryOptions);

var summaryOptions = new UsageSummarySchema();
var result = await manageClient.GetUsageSummary(projectId, summaryOptions);

See our API reference for more info.

Get project usage fields

var getUsageFieldsOptions = new getUsageFieldsOptions()
{
    StartDateTime = Datetime.Now
}
var result = await deepgramClient.Usage.GetUsageFieldsAsync(projectId,getUsageFieldsOptions);

var fieldsOptions = new UsageFieldsSchema();
var result = await manageClient.GetUsageFields(projectId, fieldsOptions);

See our API reference for more info.

New to v4

[NOTICE] There were several APIs that were previously unavailable in v3 of the .NET SDK but that are now available in the v4 release. These included:

  • Self-hosted (on-prem) APIs
  • Manage APIs for Balances and Invitations
  • Intelligence APIs (SITS) for Text and Audio
  • Text-to-Speech

Please refer to the examples in the examples folder at the root of the .NET SDK repository for implementation details.

Updated 5 months ago