Documentation
Free API Key

JavaScript SDK V2 to V3 Migration Guide

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

Suggest Edits

📘

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:

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

or even:

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

Then you can use it from a global deepgram variable:

<script>
  const { createClient } = deepgram
  const _deepgram = createClient('deepgram-api-key');

  console.log('Deepgram Instance: ', _deepgram);  
  // ...  
</script>

ESM

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

<script type="module">
  import { createClient } from 'https://cdn.jsdelivr.net/npm/@deepgram/sdk/+esm';
  const deepgram = createClient('deepgram-api-key');

  console.log('Deepgram Instance: ', deepgram);
  // ...
</script>

Migration Guide

Installation

npm install @deepgram/sdk

Initialization

import { Deepgram } from "@deepgram/sdk";
// - or -
// const { Deepgram } = require("@deepgram/sdk");

const deepgram = new Deepgram(DEEPGRAM_API_KEY);

const { createClient } = require("@deepgram/sdk");
// - or -
// import { createClient } from "@deepgram/sdk";

const deepgram = createClient(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.

import { createClient } from "@deepgram/sdk";
// - or -
// const { createClient } = require("@deepgram/sdk");

const 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.

const response = await deepgram.transcription.preRecorded(
  {
    stream: fs.createReadStream("./examples/spacewalk.wav"),
    mimetype: MIMETYPE_OF_FILE,
  },
  {
    model: "nova-2",
  }
);

const { result, error } = await deepgram.listen.prerecorded.transcribeFile(
  fs.createReadStream("./examples/spacewalk.wav"),
  {
    model: "nova-2",
  }
);

or

const response = await deepgram.transcription.preRecorded(
  {
    stream: fs.readFileSync("./examples/spacewalk.wav"),
    mimetype: MIMETYPE_OF_FILE,
  },
  {
    model: "nova-2",
  }
);

const { result, error } = await deepgram.listen.prerecorded.transcribeFile(
  fs.readFileSync("./examples/spacewalk.wav"),
  {
    model: "nova-2",
  }
);

URL File Transcription

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

const response = await deepgram.transcription.preRecorded(
  {
    url: "https://dpgr.am/spacewalk.wav"
  },
  {
    model: "nova-2",
  }
);

const { result, error } = await deepgram.listen.prerecorded.transcribeUrl(
  {
    url: "https://dpgr.am/spacewalk.wav"
  },
  {
    model: "nova-2",
  }
);

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.

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

Local File Transcription

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

const response = await deepgram.transcription.preRecorded(
  {
    stream: fs.createReadStream("./examples/spacewalk.wav"),
    mimetype: MIMETYPE_OF_FILE,
  },
  {
    model: "nova-2",
    callback: "http://callback/endpoint"
  }
);

import fs from "fs";
// - or -
// const fs = require("fs");

const { result, error } = await deepgram.listen.prerecorded.transcribeFileCallback(
  fs.createReadStream("./examples/spacewalk.wav"),
  new CallbackUrl("http://callback/endpoint"),
  {
    model: "nova-2",
  }
);

or

const response = await deepgram.transcription.preRecorded(
  {
    stream: fs.readFileSync("./examples/spacewalk.wav"),
    mimetype: MIMETYPE_OF_FILE,
  },
  {
    model: "nova-2",
    callback: "http://callback/endpoint"
  }
);

import fs from "fs";
// - or -
// const fs = require("fs");

const { result, error } = await deepgram.listen.prerecorded.transcribeFileCallback(
  fs.readFileSync("./examples/spacewalk.wav"),
  new CallbackUrl("http://callback/endpoint"),
  {
    model: "nova-2",
  }
);

URL File Transcription

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

const response = await deepgram.transcription.preRecorded(
  {
    url: "https://dpgr.am/spacewalk.wav"
  },
  {
    model: "nova-2",
    callback: "http://callback/endpoint"
  }
);

const { result, error } = await deepgram.listen.prerecorded.transcribeUrlCallback(
  {
    url: "https://dpgr.am/spacewalk.wav"
  },
  new CallbackUrl("http://callback/endpoint"),
  {
    model: "nova-2",
  }
);

Transcription Methods (Live)

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

Live Transcription

Transcribe live audio streams.

const dgConnection = await deepgram.transcription.live({
  model: "nova-2",
});

source.addListener('got-some-audio', async (event) => {
  dgConnection.send(event.raw_audio_data);
})

dgConnection.addListener("transcriptReceived", (transcription) => {
	console.log(transcription.data);
});

const dgConnection = deepgram.listen.live({ model: "nova" });

dgConnection.on(LiveTranscriptionEvents.Open, () => {
  dgConnection.on(LiveTranscriptionEvents.Transcript, (data) => {
    console.log(data);
  });

  source.addListener('got-some-audio', async (event) => {
    dgConnection.send(event.raw_audio_data); 
  })
});

Management API

get all projects for a user

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

const { result, error } = await deepgram.manage.getProjects();

See our API reference for more info.

get a project

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

const { result, error } = await deepgram.manage.getProject(projectId);

See our API reference for more info.

update a project

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

const { result, error } = await deepgram.manage.updateProject(projectId, options);

See our API reference for more info.

delete a project

await deepgram.projects.delete(projectId);

const { error } = await deepgram.manage.deleteProject(projectId);

See our API reference for more info.

get all project key details

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

const { result, error } = await deepgram.manage.getProjectKeys(projectId);

See our API reference for more info.

get a project key

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

const { result, error } = await deepgram.manage.getProjectKey(
  projectId,
  projectKeyId
);

See our API reference for more info.

create a project key

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

const { result, error } = await deepgram.manage.createProjectKey(projectId, options);

See our API reference for more info.

delete a project key

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

const { error } = await deepgram.manage.deleteProjectKey(
  projectId,
  projectKeyId
);

See our API reference for more info.

get all project members

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

const { result, error } = await deepgram.manage.getProjectMembers(projectId);

See our API reference for more info.

remove a project member

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

const { error } = await deepgram.manage.removeProjectMember(
  projectId,
  projectMemberId
);

See our API reference for more info.

get all scopes for a project member

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

const { result, error } = await deepgram.manage.getProjectMemberScopes(
  projectId,
  projectMemberId
);

See our API reference for more info.

update a scope for a project member

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

const { result, error } = await deepgram.manage.updateProjectMemberScope(
  projectId,
  projectMemberId,
  options
);

See our API reference for more info.

get all project invites

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

const { result, error } = await deepgram.manage.getProjectInvites(projectId);

See our API reference for more info.

send a project invite

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

const { result, error } = await deepgram.manage.sendProjectInvite(projectId, options);

See our API reference for more info.

delete a project invite

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

const { error } = await deepgram.manage.deleteProjectInvite(
  projectId,
  email
);

See our API reference for more info.

leave a project

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

const { result, error } = await deepgram.manage.leaveProject(projectId);

See our API reference for more info.

get all usage requests for a project

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

const { result, error } = await deepgram.manage.getProjectUsageRequests(projectId, options);

See our API reference for more info.

get a usage request for a project

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

const { result, error } = await deepgram.manage.getProjectUsageRequest(
  projectId,
  requestId
);

See our API reference for more info.

get the project usage summary

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

const { result, error } = await deepgram.manage.getProjectUsageSummary(projectId, options);

See our API reference for more info.

get project usage fields

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

const { result, error } = await deepgram.manage.getProjectUsageFields(projectId, options);

See our API reference for more info.

get all project balances

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

const { result, error } = await deepgram.manage.getProjectBalances(projectId);

See our API reference for more info.

get a project balance

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

const { result, error } = await deepgram.manage.getProjectBalance(
  projectId,
  balanceId
);

See our API reference for more info.

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

list self-hosted credentials

Newly available functionality.

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

See our API reference for more info.

get self-hosted credentials

Newly available functionality.

const { result, error } = await deepgram.onprem.getCredentials(
  projectId,
  credentialId
);

See our API reference for more info.

create self-hosted credentials

Newly available functionality.

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

See our API reference for more info.

delete self-hosted credentials

Newly available functionality.

const { result, error } = await deepgram.onprem.deleteCredentials(
  projectId,
  credentialId
);

See our API reference for more info.

Updated 5 months ago