Deepgram.Unstable.SDK.Builds 4.0.0-alpha.3

Deepgram .NET SDK

Official .NET SDK for Deepgram. Power your apps with world-class speech and Language AI models.

This SDK only supports hosted usage of api.deepgram.com.

• Deepgram .NET SDK
• Getting an API Key
• Documentation
• Installation
• Targeted Frameworks
• Configuration
  • Default
  • Notes regarding Cors
  • Examples
• Creating A Rest Client
  • Default Client Creation
• Examples
• Transcription
  • Remote File
    • UrlSource
  • Local files
    • PrerecordedSchema
  • CallBackAsync Methods
  • Live Audio
    • LiveSchema
• Projects
  • Get Projects
  • Get Project
  • Update Project
  • Delete Project
  • Leave Project
• Keys
  • List Keys
  • Get Key
  • Create Key
  • Delete Key
• Members
  • Get Members
  • Remove Member
• Scopes
  • Get Member Scopes
  • Update Scope
• Invitations
  • List Invites
  • Send Invite
  • Delete Invite
  • Leave Project
• Usage
  • Get All Requests
    • ListAllRequestOptions
  • Get Request
  • Summarize Usage
    • GetUsageSummaryOptions
  • Get Fields
    • GetUsageFieldsOptions
• Balances
  • Get Balances
  • Get Balance
• OnPrem
  • List Credentials
  • Get Credentials
  • Remove Credentials
  • Create Credentials
• Logging
• Development and Contributing
• Testing
• Getting Help

Getting an API Key

🔑 To access the Deepgram API you will need a free Deepgram API Key.

Documentation

Complete documentation of the .NET SDK can be found on the Deepgram Docs.

You can learn more about the full Deepgram API at https://developers.deepgram.com.

Installation

To install the C# SDK using NuGet:

Run the following command from your terminal in your projects directory:

dotnet add package Deepgram

Or use the Nuget package Manager.

Right click on project and select manage nuget packages

Targeted Frameworks

• 8.0.x
• 7.0.x
• 6.0.x

Configuration

Add to you ServiceCollection class

Default

for default implementation add

    services.AddDeepgram(string apikey):

With

Notes Regarding CORS

deepgram api does not support COR requests

Examples

Creating a Client

To create rest clients to communitcate with the deepgram apis, instantiate them directly. When creating a restclient you need to pass in the apikey and a HttpClientFactory

Default Client Creation

If you need to customize the url or set optional headers then you can when creating a client passing in a instance of DeepgramClientOptions.

var manageClient = new ManageClient(deepgramClientOptions,httpClientFactory);

DeepgramClientOptions

Property	Value	Description
BaseAddress	string?	url of server, include protocol
Headers	Dictionary<string, string>?	any headers that you want to add
ApiKey	string	REQUIRED apikey for authorization

UserAgent & Authorization headers are added internally

Timeout can also be set by callling the RestClients SetTimeout(Timespan)

Examples

To quickly get started with examples for prerecorded and streaming, run the files in the example folder. See the README in that folder for more information on getting started.

Transcription

Remote File

for available options see PrerecordedSchema

var client = new PrerecordedClient(apiKey,HttpClientFactory);
var response = await client.TranscribeUrlAsync(
    new UrlSource("https://static.deepgram.com/examples/Bueller-Life-moves-pretty-fast.wav"),
    new PrerecordedSchema()
    {
        Punctuate = true
    });

UrlSource

Property	Value	Description
Url	string	Url of the file to transcribe

Local files

There are 2 overloads for local files you can pass either a byte[] or a stream

var deepgramClientOptions = new DeepgramClientOptions("apikey");
var client = new PrerecordedClient(deepgramClientOptions,HttpClientFactory);
var response = await client.TranscribeFileAsync(
    stream,
     new PrerecordedSchema()
    {
        Punctuate = true
    });

CallBackAsync Methods

TranscibeFileCallBackAsync and TranscibeUrlCallBackAsync are the methods to use if you want to use a CallBack url you can either pass the the CallBack in the method or by setting the CallBack proeprty in the PrerecordedSchema, but NOT in both

PrerecordedSchema

Property	Value Type	reason for	Possible values
Model	string	AI model used to process submitted audio
Version	string	Version of the model to use
Language	string	BCP-47 language tag that hints at the primary spoken language
Tier	string	Level of model you would like to use in your request
Punctuate	bool	Indicates whether to add punctuation and capitalization to the transcript
ProfanityFilter	bool	Indicates whether to remove profanity from the transcript
Redact	List<string>	Indicates whether to redact sensitive information	pci, numbers, ssn
Diarize	bool	Indicates whether to recognize speaker changes
MultiChannel	bool	Indicates whether to transcribe each audio channel independently
Alternatives	int	Maximum number of transcript alternatives to return
Numerals	bool	Indicates whether to convert numbers from written format
SmartFormat	bool	Indicates whether to use Smart Format on the transcript
Search	List<string>	Terms or phrases to search for in the submitted audio
Replace	List<string>	Terms or phrases to search for in the submitted audio and replace
Callback	string	Callback URL to provide if you would like your submitted audio to be processed asynchronously
Keywords	List<string>	Keywords to which the model should pay particular attention to boosting or suppressing to help it understand context
Utterances	bool	Indicates whether Deepgram will segment speech into meaningful semantic units
DetectLanguage	bool	Indicates whether to detect the language of the provided audio
Paragraphs	bool	Indicates whether Deepgram will split audio into paragraphs
UtteranceSplit	decimal	Length of time in seconds of silence between words that Deepgram will use when determining
Summarize	object	Indicates whether Deepgram should provide summarizations of sections of the provided audio
DetectEntities	bool	Indicates whether Deepgram should detect entities within the provided audio
DetectTopics	bool	Indicates whether Deepgram should detect topics within the provided audio
Tag	List<string>

Live Audio

The example below demonstrates sending a pre-recorded audio to simulate a real-time stream of audio. In a real application, this type of audio is better handled using the pre-recorded transcription.

using Deepgram.CustomEventArgs;
using Deepgram.Models;
using System.Net.WebSockets;

var deepgramClientOptions = new DeepgramClientOptions("apikey");
var deepgramClient = new LiveClient(deepgramClientOptions);

using (var deepgramLive = deepgramClient.CreateLiveTranscriptionClient())
{
    deepgramLive.ConnectionOpened += HandleConnectionOpened;
    deepgramLive.ConnectionClosed += HandleConnectionClosed;
    deepgramLive.ConnectionError += HandleConnectionError;
    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.Send(chunk);
            await Task.Delay(50);
        }
    }

    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}");
        }
    }

    void HandleConnectionClosed(object? sender, ConnectionClosedEventArgs e)
    {
        Console.Write("Connection Closed");
    }

    void HandleConnectionError(object? sender, ConnectionErrorEventArgs e)
    {
        Console.WriteLine(e.Exception.Message);
    }

    var options = new LiveTranscriptionOptions() { Punctuate = true, Diarize = true, Encoding = Deepgram.Common.AudioEncoding.Linear16 };
    await deepgramLive.Connect(options);

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

LiveSchema

Property	Type	Description	Possible values
Model	string	AI model used to process submitted audio
Version	string	Version of the model to use
Language	string	BCP-47 language tag that hints at the primary spoken language
Tier	string	Level of model you would like to use in your request
Punctuate	bool	Indicates whether to add punctuation and capitalization to the transcript
ProfanityFilter	bool	Indicates whether to remove profanity from the transcript
Redact	List<string>	Indicates whether to redact sensitive information	pci, numbers, ssn
Diarize	bool	Indicates whether to recognize speaker changes
MultiChannel	bool	Indicates whether to transcribe each audio channel independently
Numerals	bool	Indicates whether to convert numbers from written format
SmartFormat	bool	Indicates whether to use Smart Format on the transcript
Search	List<string>	Terms or phrases to search for in the submitted audio
Replace	List<string>	Terms or phrases to search for in the submitted audio and replace
Callback	string	Callback URL to provide if you would like your submitted audio to be processed asynchronously
Keywords	List<string>	Keywords to which the model should pay particular attention to boosting or suppressing to help it understand context
InterimResults	bool	Indicates whether the streaming endpoint should send you updates to its transcription as more audio becomes available
EndPointing	string	Indicates whether Deepgram will detect whether a speaker has finished speaking
Channels	int	Number of independent audio channels contained in submitted streaming audio
SampleRate	int	Sample rate of submitted streaming audio. Required (and only read) when a value is provided for encoding
Tag	List<string>

Projects

projectId and memberId are of type string

Get Projects

Returns all projects accessible by the API key.

    var result = await manageClient.GetProjectsAsync();

See our API reference for more info.

Get Project

Retrieves a specific project based on the provided projectId.

var result = await manageClient.GetProject(projectId);

See our API reference for more info.

Update Project

Update a project.

var updateProjectSchema = new ProjectSchema()
{
    Company = "Acme",
    Name = "Mega Speech inc"
}
var result = await manageClient.UpdateProjectAsync(projectid,updateProjectSchema);

ProjectSchema Type

Property Name	Type	Description
Name	string	Name of the project
Company	string	Name of the company associated with the Deepgram project

See our API reference for more info.

Delete Project

Delete a project.

manageClient.DeleteProject(projectId);

Leave Project

Leave a project.

var result = await manageClient.LeaveProjectAsync(projectId);

See our API reference for more info.

Keys

projectId,keyId and comment are of typestring

List Keys

Retrieves all keys associated with the provided project_id.

var result = await manageClient.GetProjectAsync(projectId);

See our API reference for more info.

Get Key

Retrieves a specific key associated with the provided project_id.

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

See our API reference for more info.

Create Key

Creates an API key with the provided scopes.

var createProjectKeyWithExpirationSchema = new createProjectKeyWithExpirationSchema
    {
        Scopes= new List<string>{"admin","member"},
        Comment = "Yay a new key",
        Tags = new List<string> {"boss"}
        Expiration = DateTime.Now.AddDays(7);
};
var result = await manageClient.CreateProjectKey(projectId,createProjectKeyWithExpirationSchema);

Required - Scopes, Comment You can set ExpirationDate or TimeToLive or neither, but you cannot set both

See our API reference for more info.

KeySchema

Property	Type	Required	Description
Scopes	List<string>	*	scopes for key
Comment	DateTime	*	comment description of key
Tags	List<string>		Tag for key
ExpirationDate	string		Specfic data for key to expire
TimeToLiveInSeconds	string		time to live in seconds

Delete Key

Deletes a specific key associated with the provided project_id.

manageClient.DeleteKey(projectId, keyId);

See our API reference for more info.

Members

projectId and memberId are of typestring

Get Members

Retrieves account objects for all of the accounts in the specified project_id.

var result = await manageClient.GetMembersAsync(projectId);

See our API reference for more info.

Remove Member

Removes member account for specified member_id.

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

See our API reference for more info.

Scopes

projectId and memberId are of typestring

Get Member Scopes

Retrieves scopes of the specified member in the specified project.

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

See our API reference for more info.

Update Scope

Updates the scope for the specified member in the specified project.

var scopeOptions = new UpdateProjectMemeberScopeSchema(){Scope = "admin"};
var result = await manageClient.UpdateProjectMemberScopeAsync(projectId,memberId,scopeOptions);

See our API reference for more info.

Invitations

List Invites

Retrieves all invitations associated with the provided project_id.

var result = await manageClient.GetProjectInvitesAsync(projectId);

See our API reference for more info.

Send Invite

Sends an invitation to the provided email address.

var inviteSchema = new InviteSchema()
{
    Email = "awesome@person.com",
    Scope = "fab"
}
var result = manageClient.SendProjectInviteAsync(projectId,inviteSchema)

See our API reference for more info.

Delete Invite

Removes the specified invitation from the project.

 manageClient.DeleteProjectInvite(projectId,emailOfInvite)

See our API reference for more info.

Usage

projectId and requestId typestring

Get All Requests

Retrieves all requests associated with the provided projectId based on the provided options.

var UsageRequestsSchema = new UsageRequestsSchema ()
{
     Start = DateTime.Now.AddDays(-7);
};
var result = await manageClient.ListAllRequestsAsync(projectId,UsageRequestsSchema);

UsageRequestsSchema

Property	Type	Description
Start	DateTime	Start date of the requested date range
End	DateTime	End date of the requested date range	required
Limit	int	number of results per page
Status	string	status of requests to search for

See our API reference for more info.

Get Request

Retrieves a specific request associated with the provided projectId.

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

See our API reference for more info.

Summarize Usage

Retrieves usage associated with the provided project_id based on the provided options.

var getProjectUsageSummarySchema = new GetProjectUsageSummarySchema ()
{
    StartDateTime = DateTime.Now
}
var result = await manageClient.GetProjectUsageSummaryAsync(projectId,getProjectUsageSummarySchema);

GetProjectUsageSummarySchema

Property	Value	Description
Start	DateTime	Start date of the requested date range
End	DateTime	End date of the requested date range
Accessor	string
Model	string
MultiChannel	bool
InterimResults	bool
Punctuate	bool
Ner	bool
Utterances	bool
Replace	bool
ProfanityFilter	bool
Keywords	bool
DetectTopics	bool
Diarize	bool
Search	bool
Redact	bool
Alternatives	bool
Numerals	bool
SmartFormat	bool

See our API reference for more info.

Get Fields

Lists the features, models, tags, languages, and processing method used for requests in the specified project.

var getProjectUsageFieldsSchema = new UsageFieldsSchema()
{
    Start = Datetime.Now
}
var result = await manageClient.GetProjectUsageFieldsAsync(projectId,getProjectUsageFieldsSchema);

UsageFieldsSchema

Property	Value	Description
Start	DateTime	Start date of the requested date range
End	DateTime	End date of the requested date range

See our API reference for more info.

Balances

Get Balances

Get balances associated with project

var result = await manageClient.GetProjectBalancesAsync(projectId)

Get Balance

Get Balance associated with id

var result = await manageClient.GetProjectBalanceAsync(projectId,balanceId)

OnPrem

OnPremClient methods

List Credentials

list credenetials

var result = onPremClient.ListCredentialsAsync(projectId);

Get Credentials

get the credentials associated with the credentials id

var result = onPremClient.GetCredentialsASync(projectId,credentialsId);

Remove Credentials

remove credentials associated with the credentials id

var result = onPremClient.DeleteCredentialsASync(projectId,credentialsId);

Create Credentials

var createOnPremCredentialsSchema = new CredentialsSchema()
 {
    Comment = "my new credentials",
    Scopes = new  List<string>{"team fab"},
    Provider = "Acme credential provider"
 }
var result = onPremClientCreateCredentialsAsync(string projectId,  createOnPremCredentialsSchema)

CredentialsSchema

Property	Value	Description
Comment	string?	comment to associate with credentials
Scopes	List<string>?	scopes for the credentials
Provider	string?	provider for the credentials

Logging

The Library uses Microsoft.Extensions.Logging to preform all of its logging tasks. To configure logging for your app simply create a new ILoggerFactory and call the LogProvider.SetLogFactory() method to tell the Deepgram library how to log. For example, to log to the console with Serilog, you'd need to install the Serilog package with dotnet add package Serilog and then do the following:

using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Configuration;
using Deepgram.Logger;
using Serilog;

var log = new LoggerConfiguration()
    .MinimumLevel.Debug()
    .WriteTo.Console(outputTemplate: "{Timestamp:HH:mm} [{Level}]: {Message}\n")
    .CreateLogger();
var factory = new LoggerFactory();
factory.AddSerilog(log);
LogProvider.SetLogFactory(factory);

The sdk will generate loggers with the cateroryName of the client being used for example to get the logger for the ManageClient you would call

LogProvider.GetLogger(nameof(ManageClient));

Development and Contributing

Interested in contributing? We ❤️ pull requests!

To make sure our community is safe for all, be sure to review and agree to our Code of Conduct. Then see the Contribution guidelines for more information.

Testing

The test suite is located within Deepgram.Tests/. Run all tests with the following command from the top-level repository:

dotnet test

Upon completion, a summary is printed:

Passed!  - Failed:     0, Passed:    69, Skipped:     0, Total:    69, Duration: 906 ms - Deepgram.Tests.dll (net7.0)

Getting Help

We love to hear from you so if you have questions, comments or find a bug in the project, let us know! You can either:

• Open an issue in this repository
• Join the Deepgram Github Discussions Community
• Join the Deepgram Discord Community