JavaScript SDK V2 to V3 Migration Guide

Migrating from Deepgram Node SDK v2 to the Deepgram JavaScript SDK v3.

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

Notable Changes

  • ESM and UMD support
  • WebVTT and SRT captions published as a standalone package
  • Separate async and sync transcription methods.
  • JavaScript and Node.js friendly (isomorphic)
  • Improved live transcription events
  • Switch from request to fetch
  • Initialization by function instead of class
  • Scoped constructor config
  • Better errors
  • Support for future products
  • Support for self-hosted (formerly called on-prem) deployments

UMD

You can now use plain <script>s to import deepgram from CDNs, like:

html
1<script src="https://cdn.jsdelivr.net/npm/@deepgram/sdk"></script>

or even:

html
1<script src="https://unpkg.com/@deepgram/sdk"></script>

Then you can use it from a global deepgram variable:

html
1<script>
2 const { createClient } = deepgram
3 const _deepgram = createClient('deepgram-api-key');
4
5 console.log('Deepgram Instance: ', _deepgram);
6 // ...
7</script>

ESM

You can now use type=“module” <script>s to import deepgram from CDNs, like:

html
1<script type="module">
2 import { createClient } from 'https://cdn.jsdelivr.net/npm/@deepgram/sdk/+esm';
3 const deepgram = createClient('deepgram-api-key');
4
5 console.log('Deepgram Instance: ', deepgram);
6 // ...
7</script>

Migration Guide

Installation

Terminal
1npm install @deepgram/sdk

Initialization

1import { Deepgram } from "@deepgram/sdk";
2// - or -
3// const { Deepgram } = require("@deepgram/sdk");
4
5const deepgram = new Deepgram(DEEPGRAM_API_KEY);

Scoped Configuration

A new feature is scoped configuration. You’ll be able to configure various aspects of the SDK from the initialization.

TypeScript
1import { createClient } from "@deepgram/sdk";
2// - or -
3// const { createClient } = require("@deepgram/sdk");
4
5const deepgram = createClient(DEEPGRAM_API_KEY, { global: { url: "http://localhost:8080" }});

Transcription Methods (Synchronous)

We have separated the callback feature into its own method. The functionality below is not valid with the callback feature.

Local File Transcription

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

1const response = await deepgram.transcription.preRecorded(
2 {
3 stream: fs.createReadStream("./examples/spacewalk.wav"),
4 mimetype: MIMETYPE_OF_FILE,
5 },
6 {
7 model: "nova-3",
8 }
9);

or

1const response = await deepgram.transcription.preRecorded(
2 {
3 stream: fs.readFileSync("./examples/spacewalk.wav"),
4 mimetype: MIMETYPE_OF_FILE,
5 },
6 {
7 model: "nova-3",
8 }
9);

URL File Transcription

Transcribe a remote file by sending us a publicly accessible URL to it.

1const response = await deepgram.transcription.preRecorded(
2 {
3 url: "https://dpgr.am/spacewalk.wav"
4 },
5 {
6 model: "nova-3",
7 }
8);

Transcription Methods (Asynchronous)

The below are examples of using a callback endpoint with our new SDK. You’ll need additionally need the CallbackUrl class from the Deepgram SDK.

TypeScript
1import { createClient, CallbackUrl } from "@deepgram/sdk";
2// - or -
3// const { createClient, CallbackUrl } = require("@deepgram/sdk");

Local File Transcription

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

1const response = await deepgram.transcription.preRecorded(
2 {
3 stream: fs.createReadStream("./examples/spacewalk.wav"),
4 mimetype: MIMETYPE_OF_FILE,
5 },
6 {
7 model: "nova-3",
8 callback: "http://callback/endpoint"
9 }
10);

or

1const response = await deepgram.transcription.preRecorded(
2 {
3 stream: fs.readFileSync("./examples/spacewalk.wav"),
4 mimetype: MIMETYPE_OF_FILE,
5 },
6 {
7 model: "nova-3",
8 callback: "http://callback/endpoint"
9 }
10);

URL File Transcription

Transcribe a remote file by sending us a publicly accessible URL to it.

1const response = await deepgram.transcription.preRecorded(
2 {
3 url: "https://dpgr.am/spacewalk.wav"
4 },
5 {
6 model: "nova-3",
7 callback: "http://callback/endpoint"
8 }
9);

Transcription Methods (Live)

Our live transcription uses a WebSocket to receive audio data, and return results.

Live Transcription

Transcribe live audio streams.

1const dgConnection = await deepgram.transcription.live({
2 model: "nova-3",
3});
4
5source.addListener('got-some-audio', async (event) => {
6 dgConnection.send(event.raw_audio_data);
7})
8
9dgConnection.addListener("transcriptReceived", (transcription) => {
10 console.log(transcription.data);
11});

Management API

get all projects for a user

1const result = await deepgram.projects.list();

See our API reference for more info.

get a project

1const result = await deepgram.projects.get(projectId);

See our API reference for more info.

update a project

1const result = await deepgram.projects.update(projectId, options);

See our API reference for more info.

delete a project

1await deepgram.projects.delete(projectId);

See our API reference for more info.

get all project key details

1const result = await deepgram.keys.list(projectId);

See our API reference for more info.

get a project key

1const result = await deepgram.keys.get(projectId, projectKeyId);

See our API reference for more info.

create a project key

1let scopes = ["member", "etc"];
2const result = await deepgram.keys.create(projectId, comment, scopes, options);

See our API reference for more info.

delete a project key

1await deepgram.keys.delete(projectId, projectKeyId);

See our API reference for more info.

get all project members

1const result = await deepgram.members.listMembers(projectId);

See our API reference for more info.

remove a project member

1const result = await deepgram.members.removeMember(projectId, projectMemberId);

See our API reference for more info.

get all scopes for a project member

1const result = await deepgram.scopes.get(projectId, projectMemberId);

See our API reference for more info.

update a scope for a project member

1let scope = "member:read";
2const result = await deepgram.scopes.update(projectId, projectMemberId, scope);

See our API reference for more info.

get all project invites

1const result = await deepgram.invitation.list(projectId);

See our API reference for more info.

send a project invite

1const result = await deepgram.invitation.send(projectId, options);

See our API reference for more info.

delete a project invite

1let email = "[email protected]";
2const result = await deepgram.invitation.delete(projectId, email);

See our API reference for more info.

leave a project

1const result = await deepgram.invitation.leave(projectId);

See our API reference for more info.

get all usage requests for a project

1const result = await deepgram.usage.listRequests(projectId, options);

See our API reference for more info.

get a usage request for a project

1const result = await deepgram.usage.getRequest(projectId, request_id);

See our API reference for more info.

get the project usage summary

1const result = await deepgram.usage.getUsage(projectId, options);

See our API reference for more info.

get project usage fields

1const result = await deepgram.usage.getFields(projectId, options);

See our API reference for more info.

get all project balances

1const result = await deepgram.billing.listBalances(projectId);

See our API reference for more info.

get a project balance

1const result = await deepgram.billing.getBalance(projectId, balanceId);

See our API reference for more info.

Self-Hosted (on-prem) APIs (new)

list self-hosted credentials

Newly available functionality.

TypeScript
1const { result, error } = await deepgram.onprem.listCredentials(projectId);

See our API reference for more info.

get self-hosted credentials

Newly available functionality.

TypeScript
1const { result, error } = await deepgram.onprem.getCredentials(
2 projectId,
3 credentialId
4);

See our API reference for more info.

create self-hosted credentials

Newly available functionality.

TypeScript
1const { result, error } = await deepgram.onprem.createCredentials(projectId, options);

See our API reference for more info.

delete self-hosted credentials

Newly available functionality.

TypeScript
1const { result, error } = await deepgram.onprem.deleteCredentials(
2 projectId,
3 credentialId
4);

See our API reference for more info.

Built with