diff --git a/examples/LivestreamApi/Program.cs b/examples/LivestreamApi/Program.cs index 5811afa..4775543 100644 --- a/examples/LivestreamApi/Program.cs +++ b/examples/LivestreamApi/Program.cs @@ -33,7 +33,7 @@ public static async Task Main(string[] args) transcriptionApi.OnErrorReceived += (connection, errorEventArgs) => { - Console.WriteLine(errorEventArgs.Error); + Console.WriteLine(errorEventArgs.Exception); return Task.CompletedTask; }; diff --git a/src/AsyncEvents/AsyncEvent.cs b/src/AsyncEvents/AsyncEvent.cs index 4700736..2ea35e1 100644 --- a/src/AsyncEvents/AsyncEvent.cs +++ b/src/AsyncEvents/AsyncEvent.cs @@ -5,8 +5,15 @@ namespace DeepgramSharp.AsyncEvents /// public abstract class AsyncEvent { + /// + /// The name of the event. + /// public string Name { get; } + /// + /// Initializes a new instance of the class. + /// + /// The name of the event. protected internal AsyncEvent(string name) => Name = name; } } diff --git a/src/DeepgramClient.cs b/src/DeepgramClient.cs index 856a018..789ce94 100644 --- a/src/DeepgramClient.cs +++ b/src/DeepgramClient.cs @@ -10,6 +10,9 @@ namespace DeepgramSharp { + /// + /// Represents the Deepgram API. + /// public sealed class DeepgramClient { internal static readonly JsonSerializerOptions DefaultJsonSerializerOptions = new(JsonSerializerDefaults.Web) @@ -19,11 +22,24 @@ public sealed class DeepgramClient private static readonly string _defaultUserAgent = $"DeepgramSharp/{typeof(DeepgramClient).Assembly.GetCustomAttribute()?.InformationalVersion ?? "0.1.0"}"; + /// + /// The base URI to use for requests. + /// public Uri BaseUri { get; init; } + + /// + /// The to used for transcribing prerecorded audio. + /// public DeepgramPreRecordedApi PreRecordedApi { get; init; } internal readonly ILogger Logger; private readonly AuthenticationHeaderValue _authenticationHeader; + /// + /// Creates a new and connects to the Deepgram prerecorded API. + /// + /// The API key to use for requests. + /// The URI to use for requests. Overwrites the default Uri, . + /// The to use for logging. public DeepgramClient(string apiKey, Uri? baseUri = null, ILogger? logger = null) { ArgumentException.ThrowIfNullOrWhiteSpace(apiKey, nameof(apiKey)); @@ -33,6 +49,12 @@ public DeepgramClient(string apiKey, Uri? baseUri = null, ILogger + /// Creates a new and connects to the Deepgram livestream API. + /// + /// The options to use for the livestream. + /// A to use for the request. + /// A connected to the Deepgram livestream API. public async ValueTask CreateLivestreamAsync(DeepgramLivestreamOptionCollection? options = null, CancellationToken cancellationToken = default) { DeepgramLivestreamApi api = new(this, BaseUri); diff --git a/src/DeepgramLivestreamApi.cs b/src/DeepgramLivestreamApi.cs index 0e84961..f746d17 100644 --- a/src/DeepgramLivestreamApi.cs +++ b/src/DeepgramLivestreamApi.cs @@ -13,6 +13,9 @@ namespace DeepgramSharp { + /// + /// Represents a connection to the Deepgram livestream API. + /// public sealed class DeepgramLivestreamApi(DeepgramClient client, Uri? baseUri = null) : IDisposable { private sealed class AuthenticatedMessageInvoker : HttpMessageInvoker @@ -49,22 +52,48 @@ public override HttpResponseMessage Send(HttpRequestMessage request, Cancellatio Type = DeepgramPayloadType.CloseStream.ToString() }, DeepgramClient.DefaultJsonSerializerOptions); - // Metadata + /// + /// Raised when the livestream receives metadata from the Deepgram API. + /// public event AsyncEventHandler OnMetadataReceived { add => _metadataReceived.Register(value); remove => _metadataReceived.Unregister(value); } private readonly AsyncEvent _metadataReceived = new("METADATA_RECEIVED", EverythingWentWrongErrorHandler); + /// + /// Raised when the livestream receives a transcription from the Deepgram API. + /// public event AsyncEventHandler OnTranscriptionReceived { add => _transcriptionReceived.Register(value); remove => _transcriptionReceived.Unregister(value); } private readonly AsyncEvent _transcriptionReceived = new("TRANSCRIPTION_RECEIVED", EverythingWentWrongErrorHandler); + /// + /// Raised when an error occurs within the Deepgram API. + /// public event AsyncEventHandler OnErrorReceived { add => _errorReceived.Register(value); remove => _errorReceived.Unregister(value); } private readonly AsyncEvent _errorReceived = new("ERROR_RECEIVED", EverythingWentWrongErrorHandler); + /// + /// Raised when the livestream is closed by the Deepgram API. + /// public event AsyncEventHandler OnClosed { add => _closed.Register(value); remove => _closed.Unregister(value); } private readonly AsyncEvent _closed = new("CLOSED", EverythingWentWrongErrorHandler); + /// + /// The to use for requests. + /// public DeepgramClient Client { get; init; } = client ?? throw new ArgumentNullException(nameof(client)); + + /// + /// The URI to use for requests. + /// public Uri BaseUri { get; init; } = baseUri ?? DeepgramRoutes.LivestreamUri; + + /// + /// The underlying used for communication with the Deepgram API. + /// public ClientWebSocket WebSocket { get; init; } = new(); + + /// + /// The current state of the . + /// public WebSocketState State => WebSocket.State; private readonly SemaphoreSlim _semaphore = new(1, 1); @@ -72,6 +101,11 @@ public override HttpResponseMessage Send(HttpRequestMessage request, Cancellatio private DateTimeOffset _lastKeepAlive = DateTimeOffset.Now; private bool _isDisposed; + /// + /// Connects to the Deepgram livestream API. + /// + /// The options to use for the connection. + /// A to use for the connection. public async ValueTask ConnectAsync(DeepgramLivestreamOptionCollection? options = null, CancellationToken cancellationToken = default) { if (WebSocket.State == WebSocketState.Open) @@ -88,6 +122,12 @@ await WebSocket.ConnectAsync(new UriBuilder(BaseUri) _ = ReceiveTranscriptionLoopAsync(); } + /// + /// Sends audio to the Deepgram livestream API. + /// + /// A containing the raw audio to send. + /// A to use for the request. + /// A representing the asynchronous operation. public async ValueTask SendAudioAsync(ReadOnlyMemory audioFrames, CancellationToken cancellationToken = default) { if (WebSocket.State != WebSocketState.Open) @@ -99,6 +139,11 @@ public async ValueTask SendAudioAsync(ReadOnlyMemory audioFrames, Cancella _lastKeepAlive = DateTimeOffset.UtcNow; } + /// + /// Let's the Deepgram livestream API know that you are done sending audio. + /// + /// A to use for the request. + /// A representing the asynchronous operation. public async ValueTask CloseAsync(CancellationToken cancellationToken = default) { if (WebSocket.State == WebSocketState.Closed) @@ -184,7 +229,7 @@ private async Task ReceiveTranscriptionLoopAsync() JsonDocument document = JsonDocument.Parse(_buffer[..(int)error.BytePositionInLine]); _ = _errorReceived.InvokeAsync(this, new() { - Error = new DeepgramWebsocketException(document) + Exception = new DeepgramWebsocketException(document) }); } finally @@ -194,6 +239,7 @@ private async Task ReceiveTranscriptionLoopAsync() } } + /// public void Dispose() { // Do not change this code. Put cleanup code in 'Dispose(bool disposing)' method diff --git a/src/DeepgramLivestreamOptionCollection.cs b/src/DeepgramLivestreamOptionCollection.cs index 19cddd4..cd33d5b 100644 --- a/src/DeepgramLivestreamOptionCollection.cs +++ b/src/DeepgramLivestreamOptionCollection.cs @@ -10,7 +10,7 @@ namespace DeepgramSharp public sealed record DeepgramLivestreamOptionCollection : DeepgramOptionCollection { /// - /// Indicates whether the streaming endpoint should send you updates to its transcription as more audio becomes available. When set to , the streaming endpoint returns regular updates, which means transcription results will likely change for a period of time. By default, this flag is set to . Learn more: + /// Indicates whether the streaming endpoint should send you updates to its transcription as more audio becomes available. When set to , the streaming endpoint returns regular updates, which means transcription results will likely change for a period of time. By default, this flag is set to . Learn more: /// public bool InterimResults { get => bool.Parse(_options[nameof(InterimResults)]); set => _options[nameof(InterimResults)] = value.ToString().ToLowerInvariant(); } diff --git a/src/DeepgramOptionCollection.cs b/src/DeepgramOptionCollection.cs index 0c83be7..715fb2d 100644 --- a/src/DeepgramOptionCollection.cs +++ b/src/DeepgramOptionCollection.cs @@ -13,6 +13,9 @@ namespace DeepgramSharp /// public record DeepgramOptionCollection : IDictionary { + /// + /// The underlying dictionary of options. + /// protected readonly Dictionary _options = []; /// @@ -39,12 +42,12 @@ public record DeepgramOptionCollection : IDictionary public CultureInfo Language { get => CultureInfo.GetCultureInfoByIetfLanguageTag(_options[nameof(Language)]); set => _options[nameof(Language)] = value.IetfLanguageTag; } /// - /// Add punctuation and capitalization to the transcript. Default: . Learn more: + /// Add punctuation and capitalization to the transcript. Default: . Learn more: /// public bool Punctuate { get => bool.Parse(_options[nameof(Punctuate)]); set => _options[nameof(Punctuate)] = value.ToString().ToLowerInvariant(); } /// - /// Remove profanity from the transcript. Default: . Learn more: + /// Remove profanity from the transcript. Default: . Learn more: /// public bool ProfanityFilter { get => bool.Parse(_options[nameof(ProfanityFilter)]); set => _options[nameof(ProfanityFilter)] = value.ToString().ToLowerInvariant(); } @@ -59,22 +62,22 @@ public record DeepgramOptionCollection : IDictionary public bool Diarize { get => bool.Parse(_options[nameof(Diarize)]); set => _options[nameof(Diarize)] = value.ToString().ToLowerInvariant(); } /// - /// Version of the diarization feature to use. Only used when is . Default: latest. Learn more: + /// Version of the diarization feature to use. Only used when is . Default: latest. Learn more: /// public string DiarizeVersion { get => Uri.UnescapeDataString(_options[nameof(DiarizeVersion)]); set => _options[nameof(DiarizeVersion)] = Uri.EscapeDataString(value); } /// - /// Apply formatting to transcript output. When set to true, additional formatting will be applied to transcripts to improve readability. Default: . Learn more: + /// Apply formatting to transcript output. When set to true, additional formatting will be applied to transcripts to improve readability. Default: . Learn more: /// public bool SmartFormat { get => bool.Parse(_options[nameof(SmartFormat)]); set => _options[nameof(SmartFormat)] = value.ToString().ToLowerInvariant(); } /// - /// Whether to include words like "uh" and "um" in transcription output. Default: . Learn more: + /// Whether to include words like "uh" and "um" in transcription output. Default: . Learn more: /// public bool FillerWords { get => bool.Parse(_options[nameof(FillerWords)]); set => _options[nameof(FillerWords)] = value.ToString().ToLowerInvariant(); } /// - /// Transcribe each audio channel independently. Default: . Learn more: + /// Transcribe each audio channel independently. Default: . Learn more: /// public bool MultiChannel { get => bool.Parse(_options[nameof(MultiChannel)]); set => _options[nameof(MultiChannel)] = value.ToString().ToLowerInvariant(); } diff --git a/src/DeepgramPrerecordedApi.cs b/src/DeepgramPrerecordedApi.cs index 0484525..721b5f6 100644 --- a/src/DeepgramPrerecordedApi.cs +++ b/src/DeepgramPrerecordedApi.cs @@ -11,13 +11,32 @@ namespace DeepgramSharp { + /// + /// Represents the Deepgram prerecorded API. + /// + /// The to use for requests. + /// The URI to use for requests. Overwrites the default Uri, . public sealed class DeepgramPreRecordedApi(DeepgramClient client, Uri? baseUri = null) { private static readonly HttpClient HttpClient = new(); + /// + /// The URI to use for requests. + /// public Uri BaseUri { get; init; } = baseUri ?? DeepgramRoutes.PrerecordedUri; + + /// + /// The to use for requests. + /// public DeepgramClient Client { get; init; } = client ?? throw new ArgumentNullException(nameof(client)); + /// + /// Transcribes the audio from the given stream. + /// + /// The stream containing the audio to transcribe. + /// A collection of options to use for the request. + /// A to use for the request. + /// A containing the transcription. public ValueTask TranscribeAsync(Stream audioStream, DeepgramPrerecordedApiOptionCollection? options = null, CancellationToken cancellationToken = default) { ArgumentNullException.ThrowIfNull(audioStream); @@ -30,6 +49,10 @@ public sealed class DeepgramPreRecordedApi(DeepgramClient client, Uri? baseUri = return TranscribeAsync(request, cancellationToken); } + /// + /// The URL that Deepgram should use to download the audio. + /// A collection of options to use for the request. + /// A to use for the request. public ValueTask TranscribeAsync(Uri url, DeepgramPrerecordedApiOptionCollection? options = null, CancellationToken cancellationToken = default) { ArgumentNullException.ThrowIfNull(url); diff --git a/src/DeepgramPrerecordedApiOptionCollection.cs b/src/DeepgramPrerecordedApiOptionCollection.cs index c4d7c0b..823930f 100644 --- a/src/DeepgramPrerecordedApiOptionCollection.cs +++ b/src/DeepgramPrerecordedApiOptionCollection.cs @@ -14,7 +14,7 @@ public sealed record DeepgramPrerecordedApiOptionCollection : DeepgramOptionColl public bool DetectLanguage { get => bool.Parse(_options[nameof(DetectLanguage)]); set => _options[nameof(DetectLanguage)] = value.ToString().ToLowerInvariant(); } /// - /// Split audio into paragraphs. Default: . Learn more: + /// Split audio into paragraphs. Default: . Learn more: /// public bool Paragraphs { get => bool.Parse(_options[nameof(Paragraphs)]); set => _options[nameof(Paragraphs)] = value.ToString().ToLowerInvariant(); } @@ -24,12 +24,12 @@ public sealed record DeepgramPrerecordedApiOptionCollection : DeepgramOptionColl public string Summarize { get => Uri.UnescapeDataString(_options[nameof(Summarize)]); set => _options[nameof(Summarize)] = Uri.EscapeDataString(value); } /// - /// Identify and extract key topics. Default: . Learn more: + /// Identify and extract key topics. Default: . Learn more: /// public bool DetectTopics { get => bool.Parse(_options[nameof(DetectTopics)]); set => _options[nameof(DetectTopics)] = value.ToString().ToLowerInvariant(); } /// - /// Segment speech into meaningful units based on gaps in speech. Default: . Learn more: + /// Segment speech into meaningful units based on gaps in speech. Default: . Learn more: /// public bool Utterances { get => bool.Parse(_options[nameof(Utterances)]); set => _options[nameof(Utterances)] = value.ToString().ToLowerInvariant(); } diff --git a/src/DeepgramRoutes.cs b/src/DeepgramRoutes.cs index 1a2cf49..3bb276f 100644 --- a/src/DeepgramRoutes.cs +++ b/src/DeepgramRoutes.cs @@ -2,14 +2,37 @@ namespace DeepgramSharp { + /// + /// A class containing the routes for the Deepgram API. + /// public static class DeepgramRoutes { + /// + /// The base URL for the Deepgram API. + /// public const string BASE_URL = "https://api.deepgram.com"; + + /// + /// The latest version of the Deepgram API. + /// public const string LATEST_VERSION = "/v1"; + + /// + /// The path to the prerecorded audio endpoint. + /// public const string LISTEN = "/listen"; + /// public static readonly Uri BaseUri = new(BASE_URL + LATEST_VERSION); + + /// + /// The URI for the prerecorded audio endpoint. + /// public static readonly Uri PrerecordedUri = new(BASE_URL + LATEST_VERSION + LISTEN); + + /// + /// The URI for the livestream audio endpoint. + /// public static readonly Uri LivestreamUri = new UriBuilder(PrerecordedUri) { Scheme = "wss" diff --git a/src/EventArgs/DeepgramEventArgs.cs b/src/EventArgs/DeepgramEventArgs.cs index e92c847..5ec5526 100644 --- a/src/EventArgs/DeepgramEventArgs.cs +++ b/src/EventArgs/DeepgramEventArgs.cs @@ -2,5 +2,8 @@ namespace DeepgramSharp.EventArgs { + /// + /// Represents the base class for Deepgram asynchronous event arguments. + /// public abstract class DeepgramEventArgs : AsyncEventArgs; } diff --git a/src/EventArgs/DeepgramLivestreamClosedEventArgs.cs b/src/EventArgs/DeepgramLivestreamClosedEventArgs.cs index 0de5737..eb8783e 100644 --- a/src/EventArgs/DeepgramLivestreamClosedEventArgs.cs +++ b/src/EventArgs/DeepgramLivestreamClosedEventArgs.cs @@ -1,4 +1,7 @@ namespace DeepgramSharp.EventArgs { + /// + /// Represents the event arguments for when a Deepgram livestream is closed. + /// public sealed class DeepgramLivestreamClosedEventArgs : DeepgramEventArgs; } diff --git a/src/EventArgs/DeepgramLivestreamErrorEventArgs.cs b/src/EventArgs/DeepgramLivestreamErrorEventArgs.cs index 829cf03..d2472bf 100644 --- a/src/EventArgs/DeepgramLivestreamErrorEventArgs.cs +++ b/src/EventArgs/DeepgramLivestreamErrorEventArgs.cs @@ -2,8 +2,14 @@ namespace DeepgramSharp.EventArgs { + /// + /// Represents the event arguments for when a Deepgram livestream encounters an error. + /// public sealed class DeepgramLivestreamErrorEventArgs : DeepgramEventArgs { - public required DeepgramWebsocketException Error { get; init; } + /// + /// The exception thrown by the Deepgram websocket API. + /// + public required DeepgramWebsocketException Exception { get; init; } } } diff --git a/src/EventArgs/DeepgramLivestreamMetadataReceivedEventArgs.cs b/src/EventArgs/DeepgramLivestreamMetadataReceivedEventArgs.cs index 7abbf11..6bd18fe 100644 --- a/src/EventArgs/DeepgramLivestreamMetadataReceivedEventArgs.cs +++ b/src/EventArgs/DeepgramLivestreamMetadataReceivedEventArgs.cs @@ -2,8 +2,14 @@ namespace DeepgramSharp.EventArgs { + /// + /// Represents the event arguments for when a Deepgram livestream receives metadata. + /// public sealed class DeepgramLivestreamMetadataReceivedEventArgs : DeepgramEventArgs { + /// + /// The metadata received from the Deepgram websocket API. + /// public required DeepgramMetadata Metadata { get; init; } } } diff --git a/src/EventArgs/DeepgramLivestreamTranscriptReceivedEventArgs.cs b/src/EventArgs/DeepgramLivestreamTranscriptReceivedEventArgs.cs index 49561a0..cd6f9da 100644 --- a/src/EventArgs/DeepgramLivestreamTranscriptReceivedEventArgs.cs +++ b/src/EventArgs/DeepgramLivestreamTranscriptReceivedEventArgs.cs @@ -2,8 +2,14 @@ namespace DeepgramSharp.EventArgs { + /// + /// Represents the event arguments for when a Deepgram livestream receives a transcript. + /// public sealed class DeepgramLivestreamTranscriptReceivedEventArgs : DeepgramEventArgs { + /// + /// The result received from the Deepgram websocket API. + /// public required DeepgramLivestreamResult Result { get; init; } } } diff --git a/src/Exceptions/DeepgramException.cs b/src/Exceptions/DeepgramException.cs index 3253a7e..3db4c66 100644 --- a/src/Exceptions/DeepgramException.cs +++ b/src/Exceptions/DeepgramException.cs @@ -4,12 +4,32 @@ namespace DeepgramSharp.Exceptions { + /// + /// Represents an exception thrown by the Deepgram API. + /// public class DeepgramException : Exception { - public HttpResponseMessage? Response { get; init; } + /// + /// The error code provided by the Deepgram API. + /// public string? ErrorCode { get; init; } + + /// + /// The error message provided by the Deepgram API. + /// public string? ErrorMessage { get; init; } + + /// + /// The request ID provided by the Deepgram API. + /// public Guid RequestId { get; init; } + + /// + /// The that caused the exception. + /// + public HttpResponseMessage? Response { get; init; } + + /// public override string Message => $"Http Error {(int)(Response?.StatusCode ?? 0)}, {ErrorCode}: {ErrorMessage}"; internal DeepgramException(JsonDocument jsonDocument, HttpResponseMessage? response = null) diff --git a/src/Exceptions/DeepgramWebsocketException.cs b/src/Exceptions/DeepgramWebsocketException.cs index da9bfa9..60d4e88 100644 --- a/src/Exceptions/DeepgramWebsocketException.cs +++ b/src/Exceptions/DeepgramWebsocketException.cs @@ -3,8 +3,16 @@ namespace DeepgramSharp.Exceptions { + /// + /// Represents an exception thrown by the Deepgram websocket API. + /// public sealed class DeepgramWebsocketException : DeepgramException { - public DeepgramWebsocketException(JsonDocument jsonDocument) : base(jsonDocument) => Debugger.Break(); + /// + /// Creates a new . + /// + /// The containing the error. + /// A new . + internal DeepgramWebsocketException(JsonDocument jsonDocument) : base(jsonDocument) => Debugger.Break(); } } diff --git a/src/Tiers/DeepgramBaseTier.cs b/src/Tiers/DeepgramBaseTier.cs index 81cf538..6271526 100644 --- a/src/Tiers/DeepgramBaseTier.cs +++ b/src/Tiers/DeepgramBaseTier.cs @@ -1,19 +1,53 @@ namespace DeepgramSharp.Tiers { + /// + /// Base model tiers are built on our signature end-to-end deep learning speech model architecture. They offer a solid combination of accuracy and cost effectiveness in some cases. + /// public sealed record DeepgramBaseTier : IDeepgramTier { + /// public string Tier { get; init; } = "base"; + + /// public DeepgramBaseModel Model { get; init; } = DeepgramBaseModel.General; } + /// public enum DeepgramBaseModel { + /// + /// (Default) Optimized for everyday audio processing. + /// General, + + /// + /// Optimized for conference room settings, which include multiple speakers with a single microphone. + /// Meeting, + + /// + /// Optimized for low-bandwidth audio phone calls. + /// Phonecall, + + /// + /// Optimized for low-bandwidth audio clips with a single speaker. Derived from the phonecall model. + /// Voicemail, + + /// + /// Optimized for multiple speakers with varying audio quality, such as might be found on a typical earnings call. Vocabulary is heavily finance oriented. + /// Finance, + + /// + /// Optimized for use cases in which a human is talking to an automated bot, such as IVR, a voice assistant, or an automated kiosk. + /// ConversationalAI, + + /// + /// Optimized for audio sourced from videos. + /// Video } } diff --git a/src/Tiers/DeepgramEnhancedTier.cs b/src/Tiers/DeepgramEnhancedTier.cs index dc4d76e..00f733f 100644 --- a/src/Tiers/DeepgramEnhancedTier.cs +++ b/src/Tiers/DeepgramEnhancedTier.cs @@ -1,16 +1,38 @@ namespace DeepgramSharp.Tiers { + /// + /// Enhanced model tiers are still some of our most powerful ASR models; they generally have higher accuracy and better word recognition than our base models, and they handle uncommon words significantly better. + /// public sealed record DeepgramEnhancedTier : IDeepgramTier { + /// public string Tier { get; init; } = "enhanced"; + + /// public DeepgramEnhancedModel Model { get; init; } = DeepgramEnhancedModel.General; } + /// public enum DeepgramEnhancedModel { + /// + /// Optimized for everyday audio processing. Likely to be more accurate than any region-specific Base model for the language for which it is enabled. If you aren't sure which model to select, start here. + /// General, + + /// + /// BETA: Optimized for conference room settings, which include multiple speakers with a single microphone. + /// Meeting, + + /// + /// Optimized for low-bandwidth audio phone calls. + /// Phonecall, + + /// + /// BETA: Optimized for multiple speakers with varying audio quality, such as might be found on a typical earnings call. Vocabulary is heavily finance oriented. + /// Finance } } diff --git a/src/Tiers/DeepgramNova2Tier.cs b/src/Tiers/DeepgramNova2Tier.cs index 90c1491..4360bb7 100644 --- a/src/Tiers/DeepgramNova2Tier.cs +++ b/src/Tiers/DeepgramNova2Tier.cs @@ -1,22 +1,68 @@ namespace DeepgramSharp.Tiers { + /// + /// Nova-2 expands on advancements with speech-specific optimizations to the underlying Transformer architecture, advanced data curation techniques, and a multi-stage training methodology. These changes yield reduced word error rate (WER) and enhancements to entity recognition (i.e. proper nouns, alphanumerics, etc.), punctuation, and capitalization. + /// public sealed record DeepgramNova2Tier : IDeepgramTier { + /// public string Tier { get; init; } = "nova-2"; + + /// public DeepgramNova2Model Model { get; init; } = DeepgramNova2Model.General; } + /// public enum DeepgramNova2Model { + /// + /// Optimized for everyday audio processing. + /// General, + + /// + /// Optimized for conference room settings, which include multiple speakers with a single microphone. + /// Meeting, + + /// + /// Optimized for low-bandwidth audio phone calls. + /// Phonecall, + + /// + /// Optimized for low-bandwidth audio clips with a single speaker. Derived from the phonecall model. + /// Voicemail, + + /// + /// Optimized for multiple speakers with varying audio quality, such as might be found on a typical earnings call. Vocabulary is heavily finance oriented. + /// Finance, + + /// + /// Optimized for use cases in which a human is talking to an automated bot, such as IVR, a voice assistant, or an automated kiosk. + /// ConversationalAI, + + /// + /// Optimized for audio sourced from videos. + /// Video, + + /// + /// Optimized for audio with medical oriented vocabulary. + /// Medical, + + /// + /// Optimized for audio sources from drivethrus. + /// DriveThru, + + /// + /// Optimized for audio with automative oriented vocabulary. + /// Automotive } } diff --git a/src/Tiers/DeepgramNovaTier.cs b/src/Tiers/DeepgramNovaTier.cs index 6f5fd8c..b7b126d 100644 --- a/src/Tiers/DeepgramNovaTier.cs +++ b/src/Tiers/DeepgramNovaTier.cs @@ -1,14 +1,29 @@ namespace DeepgramSharp.Tiers { + /// + /// Nova is the predecessor to . Training on this model spans over 100 domains and 47 billion tokens, making it the deepest-trained automatic speech recognition (ASR) model to date. Nova doesn't just excel in one specific domain — it is ideal for a wide array of voice applications that require high accuracy in diverse contexts. + /// + /// public sealed record DeepgramNovaTier : IDeepgramTier { + /// public string Tier { get; init; } = "nova"; + + /// public DeepgramNovaModel Model { get; init; } = DeepgramNovaModel.General; } + /// public enum DeepgramNovaModel { + /// + /// Optimized for everyday audio processing. Likely to be more accurate than any region-specific Base model for the language for which it is enabled. If you aren't sure which model to select, start here. + /// General, + + /// + /// Optimized for low-bandwidth audio phone calls. + /// Phonecall } } diff --git a/src/Tiers/DeepgramWhisperTier.cs b/src/Tiers/DeepgramWhisperTier.cs index 7f61e03..99eb1c0 100644 --- a/src/Tiers/DeepgramWhisperTier.cs +++ b/src/Tiers/DeepgramWhisperTier.cs @@ -1,17 +1,46 @@ namespace DeepgramSharp.Tiers { + /// + /// Deepgram's Whisper Cloud is a fully managed API that gives you access to Deepgram's version of OpenAI’s Whisper model. Read our guide Deepgram Whisper Cloud for a deeper dive into this offering: + /// + /// + /// Whisper models are less scalable than all other Deepgram models due to their inherent model architecture. All non-Whisper models will return results faster and scale to higher load. + /// public sealed record DeepgramWhisperTier : IDeepgramTier { + /// public string Tier => $"whisper-{Model.ToString().ToLowerInvariant()}"; + + /// public DeepgramWhisperModel Model { get; init; } = DeepgramWhisperModel.Medium; } + /// public enum DeepgramWhisperModel { + /// + /// Contains 39 million parameters. The smallest model available. + /// Tiny, + + /// + /// Contains 74 million parameters. + /// Base, + + /// + /// Contains 244 million parameters. + /// Small, + + /// + /// Contains 769 million parameters. The default model if you don't specify a size. + /// Medium, + + /// + /// Contains 1550 million parameters. The largest model available. Defaults to OpenAI’s Whisper large-v2. + /// Large } } diff --git a/src/Tiers/IDeepgramTier.cs b/src/Tiers/IDeepgramTier.cs index bdc6499..9979266 100644 --- a/src/Tiers/IDeepgramTier.cs +++ b/src/Tiers/IDeepgramTier.cs @@ -2,15 +2,34 @@ namespace DeepgramSharp.Tiers { + /// + /// Represents a Deepgram tier. + /// public interface IDeepgramTier { - public string Name => $"{Tier}-{Model.ToString().ToLowerInvariant()}"; + /// + /// The fullname of the Deepgram tier (e.g. "nova2-general"). + /// + public string FullName => $"{Tier}-{Model.ToString().ToLowerInvariant()}"; + + /// + /// The tier of the Deepgram model (e.g. "nova2"). + /// public string Tier { get; } + + /// + /// The model of the Deepgram tier (e.g. "general"). + /// public Enum Model { get; } } + /// + /// A strongly-typed Deepgram tier. + /// + /// The type of the Deepgram model. public interface IDeepgramTier : IDeepgramTier where T : struct, Enum { + /// public new T Model { get; } Enum IDeepgramTier.Model => Model; }