@deepgram/sdk
Advanced tools
Official Node.js SDK for Deepgram's automated speech recognition APIs.
To access the API you will need a Deepgram account. Sign up for free at signup.
You can learn more about the full Deepgram API at https://developers.deepgram.com.
npm install @deepgram/sdk
yarn add @deepgram/sdk
const { Deepgram } = require("@deepgram/sdk");
const deepgram = new Deepgram({
apiKey: DEEPGRAM_API_KEY,
apiUrl: CUSTOM_API_URL, // Optionally used for on-premises customers
});
The transcription property can handle both pre-recorded and live transcriptions.
The transcription.preRecorded method handles sending an existing file or
buffer to the Deepgram API to generate a transcription. Additional options
can be provided to customize the result.
// Sending a file
const fileSource = { url: URL_OF_FILE };
// Sending a buffer
const bufferSource = { buffer: BUFFER_OF_FILE, mimetype: MIMETYPE_OF_FILE };
// Both fileSource or bufferSource could be provided as the source parameter
const response = await deepgram.transcription.preRecorded(
fileSource | bufferSource,
{
punctuate: true,
// other options are available
}
);
The transcription.live method provides access to a websocket connection
to the Deepgram API for generating streaming transcriptions. Additional options
can be provided to customize the result.
const deepgramLive = deepgram.transcription.live({ punctuate: true });
socket.on("microphone-stream", (stream) => {
deepgramSocket.send(stream);
});
/**
* Receive transcriptions based on sent streams
*/
deepgramLive.addListener("transcriptReceived", (transcription) => {
console.log(transcription.data);
});
The following events are fired by the live transcription object:
| Event | Description | Data |
|---|---|---|
open | The websocket connection to Deepgram has been opened. | The DG live transcription object |
close | The websocket connection to Deepgram has been closed. | WebSocket.CloseEvent |
error | An error occurred with the websocket connection | Error object |
transcriptReceived | Deepgram has responded with a transcription | Transcription Response |
Additional transcription options can be provided to both the pre-recorded and live transcriptions.
{
// AI model used to process submitted audio.
model?: "general" | "phonecall" | "meeting" | "<custom-string>",
// BCP-47 language tag that hints at the primary spoken language.
// Defaults to en-US
language?: "en-GB" | "en-IN" | "en-NZ" | "en-US" | "es" | "fr" | "ko" | "pt" | "pt-BR" | "ru" | "tr" | null,
// Indicates whether to add punctuation and capitalization to the transcript.
punctuate?: true | false,
// Indicates whether to remove profanity from the transcript.
profanity_filter?: true | false,
// Maximum number of transcript alternatives to return.
// Defaults to 1
alternatives?: integer,
// Indicates whether to redact sensitive information, replacing redacted
// content with asterisks (*).
redact?: ["pci", "numbers", "ssn"],
// Indicates whether to recognize speaker changes.
diarize?: true | false,
// Indicates whether to transcribe each audio channel independently.
multichannel?: true | false,
// Indicates whether to convert numbers from written format (e.g., one) to
// numerical format (e.g., 1).
numerals?: true | false,
// Terms or phrases to search for in the submitted audio.
search?: [string],
// Callback URL to provide if you would like your submitted audio to be
// processed asynchronously.
callback?: string,
// Keywords to which the model should pay particular attention to boosting
// or suppressing to help it understand context.
keywords?: [string],
// Indicates whether Deepgram will segment speech into meaningful semantic
// units, which allows the model to interact more naturally and effectively
// with speakers' spontaneous speech patterns.
utterances?: true | false,
// Length of time in seconds of silence between words that Deepgram will
// use when determining where to split utterances. Used when utterances
// is enabled.
// Defaults to 0.8 seconds
utt_split?: number,
// Mimetype of the source
// Mimetype is required if the provided source is a buffer
mimetype?: string,
}
{
"metadata": {
"request_id": "string",
"transaction_key": "string",
"sha256": "string",
"created": "string",
"duration": 0,
"channels": 0
},
"results": {
"channels": [
{
"search": [
{
"query": "string",
"hits": [
{
"confidence": 0,
"start": 0,
"end": 0,
"snippet": "string"
}
]
}
],
"alternatives": [
{
"transcript": "string",
"confidence": 0,
"words": [
{
"word": "string",
"start": 0,
"end": 0,
"confidence": 0
}
]
}
]
}
]
}
}
Retrieve all projects
const projects = await deepgram.projects.list();
{
projects: [
{
id: string,
name: string,
},
],
}
Retrieves all project based on the provided project id.
const project = await deepgram.projects.get(PROJECT_ID);
{
id: string,
name: string,
}
Retrieves all keys for a given project.
const response = await deepgram.keys.list(PROJECT_ID);
{
keys: [
{
id: string,
comment: string,
created: Date,
scopes: Array<string>
},
];
}
Create a new API key for a project using the keys.create method
with a name for the key.
const response = await deepgram.keys.create(PROJECT_ID, COMMENT_FOR_KEY);
{
id: string,
key: string,
comment: string,
created: Date,
scopes: Array<string>
}
Delete an existing API key using the keys.delete method with the key to
delete.
await deepgram.keys.delete(PROJECT_ID, KEY_ID);
Retrieves transcription requests for a project based on the provided options.
const response = await deepgram.usage.listRequests(PROJECT_ID, {
limit: 10,
// other options are available
});
{
// The time to retrieve requests made since
// Example: "2020-01-01T00:00:00+00:00"
start?: string,
// The time to retrieve requests made until
// Example: "2021-01-01T00:00:00+00:00"
end?: string,
// Page of requests to return
// Defaults to 0
page?: number,
// Number of requests to return per page
// Defaults to 10. Maximum of 100
limit?: number,
// Filter by succeeded or failed requests
// By default, all requests are returned
status?: 'succeeded' | 'failed'
}
{
page: number,
limit: number,
requests?: [
{
id: string;
created: string;
path: string;
accessor: string;
response?: {
details: {
usd: number;
duration: number;
total_audio: number;
channels: number;
streams: number;
model: string;
method: string;
tags: Array<string>;
features: Array<string>;
config: {
diarize: true;
multichannel: true;
};
}
}, ||
{
message?: string;
},
callback?: {
code: number;
completed: string;
},
},
];
}
Retrieves a specific transcription request for a project based on the provided
projectId and requestId.
const response = await deepgram.usage.getRequest(PROJECT_ID, REQUEST_ID);
{
id: string;
created: string;
path: string;
accessor: string;
response?: {
details: {
usd: number;
duration: number;
total_audio: number;
channels: number;
streams: number;
model: string;
method: string;
tags: Array<string>;
features: Array<string>;
config: {
diarize: true;
multichannel: true;
};
}
}, ||
{
message?: string;
},
callback?: {
code: number;
completed: string;
}
}
Retrieves aggregated usage data for a project based on the provided options.
const response = await deepgram.usage.getUsage(PROJECT_ID, {
start: "2020-01-01T00:00:00+00:00",
// other options are available
});
{
// The time to retrieve requests made since
// Example: "2020-01-01T00:00:00+00:00"
start?: string,
// The time to retrieve requests made until
// Example: "2021-01-01T00:00:00+00:00"
end?: string,
// Specific identifer for a request
accessor?: string,
// Array of tags used in requests
tag?: Array<string>,
// Filter requests by method
method?: "sync" | "async" | "streaming",
// Filter requests by model used
model?: string,
// Filter only requests using multichannel feature
multichannel?: boolean,
// Filter only requests using interim results feature
interim_results?: boolean,
// Filter only requests using the punctuation feature
punctuate?: boolean,
// Filter only requests using ner feature
ner?: boolean,
// Filter only requests using utterances feature
utterances?: boolean,
// Filter only requests using replace feature
replace?: boolean,
// Filter only requests using profanity_filter feature
profanity_filter?: boolean,
// Filter only requests using keywords feature
keywords?: boolean,
// Filter only requests using sentiment feature
sentiment?: boolean,
// Filter only requests using diarization feature
diarize?: boolean,
// Filter only requests using detect_language feature
detect_language?: boolean,
// Filter only requests using search feature
search?: boolean,
// Filter only requests using redact feature
redact?: boolean,
// Filter only requests using alternatives feature
alternatives?: boolean,
// Filter only requests using numerals feature
numerals?: boolean
}
{
start: string,
end: string,
resolution: {
units: string,
amount: number
};
results: [
{
start: string,
end: string,
hours: number,
requests: number
}
];
}
Retrieves features used by the provided projectId based on the provided options.
const response = await deepgram.usage.getUsage(PROJECT_ID, {
start: "2020-01-01T00:00:00+00:00",
// other options are available
});
{
// The time to retrieve requests made since
// Example: "2020-01-01T00:00:00+00:00"
start?: string,
// The time to retrieve requests made until
// Example: "2021-01-01T00:00:00+00:00"
end?: string
}
{
tags: Array<string>,
models: Array<string>,
processing_methods: Array<string>,
languages: Array<string>,
features: Array<string>
}
A sample js file is in the sample directory. To run it, update the config
located at the top of the file.
const config = {
deepgramApiKey: "YOUR_DEEPGRAM_API_KEY",
urlToFile:
"https://static.deepgram.com/examples/Bueller-Life-moves-pretty-fast.wav",
};
The sample demonstrates the following uses:
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.
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:
Check out the Developer Documentation at https://developers.deepgram.com/
FAQs
Isomorphic Javascript client for Deepgram
The npm package @deepgram/sdk receives a total of 45,390 weekly downloads. As such, @deepgram/sdk popularity was classified as popular.
We found that @deepgram/sdk demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Company News
Socket is joining TC54 to help develop standards for software supply chain security, contributing to the evolution of SBOMs, CycloneDX, and Package URL specifications.
Security News
PyPI now allows maintainers to archive projects, improving security and helping users make informed decisions about their dependencies.
Research
Security News
Malicious npm package postcss-optimizer delivers BeaverTail malware, targeting developer systems; similarities to past campaigns suggest a North Korean connection.