diff --git a/README.md b/README.md index 9a5788e9..2443f7f4 100644 --- a/README.md +++ b/README.md @@ -1,55 +1,55 @@ # Deepgram Go SDK -Community Go SDK for [Deepgram](https://www.deepgram.com/). Power your apps with world-class speech and Language AI models. +Community Go SDK for [Deepgram](https://www.deepgram.com/). Start building with our powerful transcription & speech understanding API. > This SDK only supports hosted usage of api.deepgram.com. -* [Deepgram Go SDK](#deepgram-go-sdk) -* [Getting an API Key](#getting-an-api-key) -* [Documentation](#documentation) -* [Installation](#installation) -* [Requirements](#requirements) -* [Configuration](#configuration) -* [Transcription](#transcription) - * [Remote Files](#remote-files) - * [UrlSource](#urlsource) - * [Local files](#local-files) - * [ReadStreamSource](#readstreamsource) - * [PrerecordedTranscriptionOptions](#prerecordedtranscriptionoptions) -* [Generating Captions](#generating-captions) - * [Live Audio](#live-audio) - * [LiveTranscriptionOptions](#livetranscriptionoptions) -* [Projects](#projects) - * [Get Projects](#get-projects) - * [Get Project](#get-project) - * [Update Project](#update-project) - * [Delete Project](#delete-project) -* [Keys](#keys) - * [List Keys](#list-keys) - * [Get Key](#get-key) - * [Create Key](#create-key) - * [Delete Key](#delete-key) -* [Members](#members) - * [Get Members](#get-members) - * [Remove Member](#remove-member) -* [Scopes](#scopes) - * [Get Member Scopes](#get-member-scopes) - * [Update Scope](#update-scope) -* [Invitations](#invitations) - * [List Invites](#list-invites) - * [Send Invite](#send-invite) - * [Delete Invite](#delete-invite) - * [Leave Project](#leave-project) -* [Usage](#usage) - * [Get All Requests](#get-all-requests) - * [UsageRequestListOptions](#usagerequestlistoptions) - * [Get Request](#get-request) - * [Summarize Usage](#summarize-usage) - * [UsageOptions](#usageoptions) - * [Get Fields](#get-fields) - * [GetUsageFieldsOptions](#getusagefieldsoptions) - * [Development and Contributing](#development-and-contributing) - * [Getting Help](#getting-help) +- [Deepgram Go SDK](#deepgram-go-sdk) +- [Getting an API Key](#getting-an-api-key) +- [Documentation](#documentation) +- [Installation](#installation) +- [Requirements](#requirements) +- [Configuration](#configuration) +- [Transcription](#transcription) + - [Remote Files](#remote-files) + - [UrlSource](#urlsource) + - [Local files](#local-files) + - [ReadStreamSource](#readstreamsource) + - [PrerecordedTranscriptionOptions](#prerecordedtranscriptionoptions) +- [Generating Captions](#generating-captions) + - [Live Audio](#live-audio) + - [LiveTranscriptionOptions](#livetranscriptionoptions) +- [Projects](#projects) + - [Get Projects](#get-projects) + - [Get Project](#get-project) + - [Update Project](#update-project) + - [Delete Project](#delete-project) +- [Keys](#keys) + - [List Keys](#list-keys) + - [Get Key](#get-key) + - [Create Key](#create-key) + - [Delete Key](#delete-key) +- [Members](#members) + - [Get Members](#get-members) + - [Remove Member](#remove-member) +- [Scopes](#scopes) + - [Get Member Scopes](#get-member-scopes) + - [Update Scope](#update-scope) +- [Invitations](#invitations) + - [List Invites](#list-invites) + - [Send Invite](#send-invite) + - [Delete Invite](#delete-invite) + - [Leave Project](#leave-project) +- [Usage](#usage) + - [Get All Requests](#get-all-requests) + - [UsageRequestListOptions](#usagerequestlistoptions) + - [Get Request](#get-request) + - [Summarize Usage](#summarize-usage) + - [UsageOptions](#usageoptions) + - [Get Fields](#get-fields) + - [GetUsageFieldsOptions](#getusagefieldsoptions) + - [Development and Contributing](#development-and-contributing) + - [Getting Help](#getting-help) # Getting an API Key @@ -75,6 +75,19 @@ go get github.com/deepgram-devs/deepgram-go-sdk dg := deepgram.NewClient(DEEPGRAM_API_KEY) ``` +# Testing + +## Using Example Projects to test new features + +Contributors to the SDK can test their changes locally by running the projects in the `examples` folder. This can be done when making changes without adding a unit test, but of course it is recommended that you add unit tests for any feature additions made to the SDK. + +Go to the folder `examples` and look for these two projects, which can be used to test out features in the Deepgram Go SDK: + +- prerecorded +- streaming + +These are standalone projects, so you will need to follow the instructions in the README.md files for each project to get it running. + # Transcription ## Remote Files diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 00000000..ad702798 --- /dev/null +++ b/examples/README.md @@ -0,0 +1,35 @@ +# Examples for Testing Features Locally + +The example projects are meant to be used to test features locally by contributors working on this SDK. + +## Steps to Test Your Code + +If you are contributing changes to this SDK, you can test those changes by using the `prerecorded` or `streaming` projects in the `examples` folder. Here are the steps to follow: + +### Add Your Code + +Make your changes to the SDK (be sure you are on a branch you have created to do this work). + +### Install dependencies + +If the project requires third-party dependencies and not just standard library dependencies, you will have to install them. Make sure you are in the folder of the specific project (for example: `streaming`) and then use this command: + +``` +go mod tidy +``` + +### Edit the API key, the file, and the mimetype (as needed) + +Replace the API key where it says "YOUR_DEEPGRAM_API_KEY" + +```go +DEEPGRAM_API_KEY = "YOUR_DEEPGRAM_API_KEY" +``` + +### Run the project + +Make sure you're in the directory with the `main.go` file and run the project with the following command. + +``` +go run main.go +``` \ No newline at end of file diff --git a/examples/liveTranscription_example.go b/examples/liveTranscription_example.go deleted file mode 100644 index e3cd530f..00000000 --- a/examples/liveTranscription_example.go +++ /dev/null @@ -1,65 +0,0 @@ -package main - -import ( - "bufio" - "fmt" - "log" - "net/http" - "reflect" - "time" - - "github.com/Jeffail/gabs/v2" - "github.com/deepgram-devs/deepgram-go-sdk/deepgram" - "github.com/gorilla/websocket" -) - -func main() { - client := new(http.Client) - // IMPORTANT: Make sure you add your own API key here - dg := *deepgram.NewClient("YOUR_API_KEY") - resp, err := client.Get("http://stream.live.vc.bbcmedia.co.uk/bbc_world_service") - if err != nil { - log.Println("ERRROR getting stream", err) - } - fmt.Println("Stream is up and running ", reflect.TypeOf(resp)) - reader := bufio.NewReader(resp.Body) - - options := deepgram.LiveTranscriptionOptions{ - Language: "en-US", - Punctuate: true, - } - - dgConn, _, err := dg.LiveTranscription(options) - - chunk := make([]byte, 1024*2) - - go func() { - for { - _, message, err := dgConn.ReadMessage() - if err != nil { - fmt.Println("ERROR reading message") - log.Panic(err) - } - - jsonParsed, jsonErr := gabs.ParseJSON(message) - if jsonErr != nil { - log.Panic(err) - } - log.Printf("recv: %s", jsonParsed.Path("channel.alternatives.0.transcript").String()) - - } - }() - - for { - bytesRead, err := reader.Read(chunk) - - if err != nil { - fmt.Println("ERROR reading chunk") - log.Panic(err) - } - dgConn.WriteMessage(websocket.BinaryMessage, chunk[:bytesRead]) - time.Sleep(10 * time.Millisecond) - - } - -} diff --git a/examples/preRecordedFromStream_example.go b/examples/preRecordedFromStream_example.go deleted file mode 100644 index e62fcadf..00000000 --- a/examples/preRecordedFromStream_example.go +++ /dev/null @@ -1,56 +0,0 @@ -package main - -import ( - "flag" - "fmt" - "log" - "os" - - "github.com/deepgram-devs/deepgram-go-sdk/deepgram" -) - -var ( - key = flag.String("key", "", "Deepgram API key") - file = flag.String("file", "", "Path to file that will be transcribed") - mimetype = flag.String("mimetype", "", "Mimetype of file") -) - -func main() { - flag.Parse() - - dg := deepgram.NewClient(*key) - file, err := os.Open(*file) - if err != nil { - log.Panicf("error opening file %s: %v", *file, err) - } - source := deepgram.ReadStreamSource{Stream: file, Mimetype: *mimetype} - res, err := dg.PreRecordedFromStream(source, deepgram.PreRecordedTranscriptionOptions{Punctuate: true, Diarize: true, Language: "en-US", Utterances: true}) - if err != nil { - fmt.Println("ERROR", err) - return - } - // Log the results - log.Printf("recv: %+v", res.Results) - f, err := os.Create("transcription.vtt") - if err != nil { - fmt.Printf("error creating VTT file: %v", err) - } - // Convert the results to WebVTT format - vtt, err := res.ToWebVTT() - if err != nil { - log.Panic(err) - } - f.WriteString(vtt) - - // Convert the results to SRT format - srtF, err := os.Create("transcription.srt") - if err != nil { - fmt.Printf("error creating SRT file: %v", err) - } - srt, err := res.ToSRT() - if err != nil { - log.Panic(err) - } - srtF.WriteString(srt) - -} diff --git a/examples/preRecordedFromUrl_example.go b/examples/preRecordedFromUrl_example.go deleted file mode 100644 index b79d2115..00000000 --- a/examples/preRecordedFromUrl_example.go +++ /dev/null @@ -1,43 +0,0 @@ -package main - -import ( - "fmt" - "log" - "os" - - "github.com/deepgram-devs/deepgram-go-sdk/deepgram" -) - -func main() { - dg := deepgram.NewClient("YOUR_API_KEY") - // Feel free to use this as your audio url to test https://anchor.fm/s/3e9db190/podcast/play/22624519/https%3A%2F%2Fd3ctxlq1ktw2nl.cloudfront.net%2Fstaging%2F2020-10-15%2F128822202-44100-1-79cab5de0d7af3c9.mp3 - res, err := dg.PreRecordedFromURL(deepgram.UrlSource{Url: "AUDIO_FILE_URL"}, deepgram.PreRecordedTranscriptionOptions{Punctuate: true, Diarize: true, Language: "en-US", Utterances: true}) - if err != nil { - fmt.Println("ERROR", err) - return - } - // Log the results - log.Printf("recv: %+v", res.Results) - f, err := os.Create("transcription.vtt") - if err != nil { - fmt.Printf("error creating VTT file: %v", err) - } - // Convert the results to WebVTT format - vtt, err := res.ToWebVTT() - if err != nil { - log.Panic(err) - } - f.WriteString(vtt) - - // Convert the results to SRT format - srtF, err := os.Create("transcription.srt") - if err != nil { - fmt.Printf("error creating SRT file: %v", err) - } - srt, err := res.ToSRT() - if err != nil { - log.Panic(err) - } - srtF.WriteString(srt) - -} diff --git a/examples/prerecorded/main.go b/examples/prerecorded/main.go new file mode 100644 index 00000000..cfb7c650 --- /dev/null +++ b/examples/prerecorded/main.go @@ -0,0 +1,71 @@ +package main + +import ( + "encoding/json" + "fmt" + "log" + "os" + "strings" + + "github.com/deepgram-devs/deepgram-go-sdk/deepgram" +) + +func main() { + credentials := "DEEPGRAM_API_KEY" + dg := deepgram.NewClient(credentials) + + filePath := "https://static.deepgram.com/examples/Bueller-Life-moves-pretty-fast.wav" + var res interface{} + var err error + + if isURL(filePath) { + res, err = dg.PreRecordedFromURL( + deepgram.UrlSource{Url: filePath}, + deepgram.PreRecordedTranscriptionOptions{ + Punctuate: true, + Diarize: true, + Language: "en-US", + Utterances: true, + }, + ) + if err != nil { + fmt.Println("ERROR", err) + return + } + } else { + file, err := os.Open(filePath) + if err != nil { + log.Panicf("error opening file %s: %v", filePath, err) + } + defer file.Close() + + source := deepgram.ReadStreamSource{Stream: file, Mimetype: "YOUR_FILE_MIME_TYPE"} + + res, err = dg.PreRecordedFromStream( + source, + deepgram.PreRecordedTranscriptionOptions{ + Punctuate: true, + Diarize: true, + Language: "en-US", + Utterances: true, + }, + ) + if err != nil { + fmt.Println("ERROR", err) + return + } + } + + jsonStr, err := json.MarshalIndent(res, "", " ") + if err != nil { + fmt.Println("Error marshaling JSON:", err) + return + } + + log.Printf("%s", jsonStr) +} + +// Function to check if a string is a valid URL +func isURL(str string) bool { + return strings.HasPrefix(str, "http://") || strings.HasPrefix(str, "https://") +} diff --git a/examples/streaming/main.go b/examples/streaming/main.go new file mode 100644 index 00000000..c3b5233b --- /dev/null +++ b/examples/streaming/main.go @@ -0,0 +1,84 @@ +package main + +import ( + "bufio" + "fmt" + "log" + "net/http" + "reflect" + "time" + + "github.com/Jeffail/gabs/v2" + "github.com/deepgram-devs/deepgram-go-sdk/deepgram" + "github.com/gorilla/websocket" +) + +const ( + DEEPGRAM_API_KEY = "DEEPGRAM_API_KEY" + STREAM_URL = "http://stream.live.vc.bbcmedia.co.uk/bbc_world_service" + CHUNK_SIZE = 1024 * 2 + TEN_MILLISECONDS_SLEEP = 10 * time.Millisecond +) + +func main() { + client := new(http.Client) + + dg := *deepgram.NewClient(DEEPGRAM_API_KEY) + + res, err := client.Get(STREAM_URL) + if err != nil { + log.Println("ERROR getting stream", err) + return + } + defer res.Body.Close() + + fmt.Println("Stream is up and running ", reflect.TypeOf(res)) + + reader := bufio.NewReader(res.Body) + + liveTranscriptionOptions := deepgram.LiveTranscriptionOptions{ + Language: "en-US", + Punctuate: true, + } + + dgConn, _, err := dg.LiveTranscription(liveTranscriptionOptions) + if err != nil { + log.Println("ERROR creating LiveTranscription connection:", err) + return + } + defer dgConn.Close() + + chunk := make([]byte, CHUNK_SIZE) + + go func() { + for { + _, message, err := dgConn.ReadMessage() + if err != nil { + log.Println("ERROR reading message:", err) + return + } + + jsonParsed, jsonErr := gabs.ParseJSON(message) + if jsonErr != nil { + log.Println("ERROR parsing JSON message:", err) + return + } + log.Printf("recv: %s", jsonParsed.Path("channel.alternatives.0.transcript").String()) + } + }() + + for { + bytesRead, err := reader.Read(chunk) + + if err != nil { + log.Println("ERROR reading chunk:", err) + return + } + err = dgConn.WriteMessage(websocket.BinaryMessage, chunk[:bytesRead]) + if err != nil { + log.Println("ERROR writing message:", err) + return + } + time.Sleep(TEN_MILLISECONDS_SLEEP) + } +}