|
| 1 | +<!DOCTYPE html> |
| 2 | +<html lang="en" data-theme="dark"> |
| 3 | +<head> |
| 4 | + <meta charset="UTF-8"> |
| 5 | + <meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| 6 | + <meta name="theme-color" content="#0a0a0f" media="(prefers-color-scheme: dark)"> |
| 7 | + <meta name="theme-color" content="#f8f8fb" media="(prefers-color-scheme: light)"> |
| 8 | + <script> |
| 9 | + (function() { |
| 10 | + var t = localStorage.getItem('decibri-theme'); |
| 11 | + if (t) document.documentElement.setAttribute('data-theme', t); |
| 12 | + else if (window.matchMedia && window.matchMedia('(prefers-color-scheme: light)').matches) document.documentElement.setAttribute('data-theme', 'light'); |
| 13 | + })(); |
| 14 | + </script> |
| 15 | + <title>Deepgram Real-Time Transcription | decibri docs</title> |
| 16 | + <meta name="description" content="Real-time cloud speech-to-text transcription using decibri and Deepgram in Node.js."> |
| 17 | + <meta name="robots" content="index, follow"> |
| 18 | + <meta property="og:title" content="Deepgram Real-Time Transcription | decibri docs"> |
| 19 | + <meta property="og:description" content="Real-time cloud speech-to-text transcription using decibri and Deepgram in Node.js."> |
| 20 | + <meta property="og:type" content="article"> |
| 21 | + <meta property="og:url" content="https://decibri.dev/docs/node/integrations/deepgram.html"> |
| 22 | + <link rel="canonical" href="https://decibri.dev/docs/node/integrations/deepgram.html"> |
| 23 | + <link rel="icon" href="/favicon.ico" type="image/x-icon"> |
| 24 | + <link rel="preconnect" href="https://fonts.googleapis.com"> |
| 25 | + <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin> |
| 26 | + <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600&family=Outfit:wght@300;400;500;600;700&display=swap" rel="stylesheet"> |
| 27 | + <link rel="stylesheet" href="../../styles.css"> |
| 28 | + <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/themes/prism-tomorrow.min.css"> |
| 29 | +</head> |
| 30 | +<body> |
| 31 | + |
| 32 | + <nav class="docs-nav"> |
| 33 | + <div class="nav-inner"> |
| 34 | + <a href="/docs/index.html" class="nav-logo">deci<span>bri</span> docs</a> |
| 35 | + <div class="mobile-nav"> |
| 36 | + <a href="https://github.com/analyticsinmotion/decibri" class="nav-cta" target="_blank" rel="noopener noreferrer" aria-label="GitHub"><svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg></a> |
| 37 | + <button class="mobile-nav-btn" onclick="toggleTheme()" aria-label="Toggle theme" title="Toggle theme"> |
| 38 | + <svg class="icon-moon" aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"/></svg> |
| 39 | + <svg class="icon-sun" aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="5"/><line x1="12" y1="1" x2="12" y2="3"/><line x1="12" y1="21" x2="12" y2="23"/><line x1="4.22" y1="4.22" x2="5.64" y2="5.64"/><line x1="18.36" y1="18.36" x2="19.78" y2="19.78"/><line x1="1" y1="12" x2="3" y2="12"/><line x1="21" y1="12" x2="23" y2="12"/><line x1="4.22" y1="19.78" x2="5.64" y2="18.36"/><line x1="18.36" y1="5.64" x2="19.78" y2="4.22"/></svg> |
| 40 | + </button> |
| 41 | + <button class="mobile-nav-btn" onclick="toggleMobileMenu()" aria-label="Open menu"> |
| 42 | + <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><line x1="3" y1="6" x2="21" y2="6"/><line x1="3" y1="12" x2="21" y2="12"/><line x1="3" y1="18" x2="21" y2="18"/></svg> |
| 43 | + </button> |
| 44 | + </div> |
| 45 | + </div> |
| 46 | + </nav> |
| 47 | + <div class="mobile-menu-overlay" onclick="toggleMobileMenu()"></div> |
| 48 | + <div class="mobile-menu"></div> |
| 49 | + <div class="sidebar-overlay"></div> |
| 50 | + <aside id="sidebar" class="sidebar"></aside> |
| 51 | + |
| 52 | + <div class="doc-content"> |
| 53 | + <div class="doc-container"> |
| 54 | + |
| 55 | + <div class="breadcrumb"> |
| 56 | + <a href="/docs/index.html">Docs</a> |
| 57 | + <span class="sep">/</span> |
| 58 | + <a href="/docs/node/index.html">Node.js</a> |
| 59 | + <span class="sep">/</span> |
| 60 | + <span class="current">Deepgram Real-Time Transcription</span> |
| 61 | + </div> |
| 62 | + |
| 63 | + <h1>Deepgram Real-Time Transcription</h1> |
| 64 | + <p class="lead">Stream live microphone audio to Deepgram for real-time cloud transcription using decibri and the official Deepgram SDK.</p> |
| 65 | + |
| 66 | + <h2>What this does</h2> |
| 67 | + <p>This integration captures live audio from your microphone using decibri and streams it to Deepgram's cloud API over a WebSocket. Transcription results return in real-time as you speak. There is no model download, no local inference, and no format conversion required.</p> |
| 68 | + <p>Choose this when you need the highest accuracy, support for 30+ languages, or features like speaker diarization and smart formatting without managing local models. For use cases where audio must stay on your device, see the <a href="sherpa-onnx-stt.html">sherpa-onnx</a> or <a href="whisper-cpp.html">whisper.cpp</a> local integrations instead.</p> |
| 69 | + |
| 70 | + <h2>Cloud vs local</h2> |
| 71 | + <div class="callout"> |
| 72 | + <strong>Note:</strong> Deepgram is a cloud service. Audio is sent to Deepgram's servers for processing. Deepgram does not store audio by default. If your use case requires audio to stay entirely on-device, use the local integrations: <a href="sherpa-onnx-stt.html">sherpa-onnx</a> (real-time streaming) or <a href="whisper-cpp.html">whisper.cpp</a> (batch transcription). |
| 73 | + </div> |
| 74 | + |
| 75 | + <h2>Prerequisites</h2> |
| 76 | + |
| 77 | + <h3>Get an API key</h3> |
| 78 | + <ol> |
| 79 | + <li>Sign up at <a href="https://console.deepgram.com" target="_blank" rel="noopener noreferrer">console.deepgram.com</a> (free tier includes $200 in credits, no credit card required)</li> |
| 80 | + <li>Create an API key from the dashboard</li> |
| 81 | + <li>Store it in a <code>.env</code> file in your project root:</li> |
| 82 | + </ol> |
| 83 | + <pre><code class="language-bash">DEEPGRAM_API_KEY=your_key_here</code></pre> |
| 84 | + |
| 85 | + <h3>Install packages</h3> |
| 86 | + <div class="install-cmd" onclick="navigator.clipboard.writeText('npm install decibri @deepgram/sdk dotenv')" role="button" tabindex="0" aria-label="Copy install command"> |
| 87 | + <span class="dollar">$</span> |
| 88 | + <span class="cmd">npm install decibri @deepgram/sdk dotenv</span> |
| 89 | + <svg class="copy-icon" aria-hidden="true" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="13" height="13" rx="2" ry="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/></svg> |
| 90 | + </div> |
| 91 | + <p>The <code>dotenv</code> package loads your API key from the <code>.env</code> file. If you set environment variables another way, you can skip it.</p> |
| 92 | + <p>No model download is required. All processing happens in Deepgram's cloud.</p> |
| 93 | + |
| 94 | + <h2>Code walkthrough</h2> |
| 95 | + |
| 96 | + <h3>1. Configuration</h3> |
| 97 | + <p>Import decibri, the Deepgram SDK, and dotenv. Create a Deepgram client with your API key.</p> |
| 98 | + <pre><code class="language-javascript">require('dotenv').config(); |
| 99 | + |
| 100 | +const Decibri = require('decibri'); |
| 101 | +const { DeepgramClient } = require('@deepgram/sdk'); |
| 102 | + |
| 103 | +const deepgram = new DeepgramClient({ apiKey: process.env.DEEPGRAM_API_KEY });</code></pre> |
| 104 | + |
| 105 | + <h3>2. Connect to Deepgram</h3> |
| 106 | + <p>Create a WebSocket connection with audio parameters that match decibri's configuration. The <code>encoding</code>, <code>sample_rate</code>, and <code>channels</code> must match what decibri outputs.</p> |
| 107 | + <pre><code class="language-javascript">const socket = await deepgram.listen.v1.createConnection({ |
| 108 | + model: 'nova-3', |
| 109 | + language: 'en', |
| 110 | + encoding: 'linear16', |
| 111 | + sample_rate: 16000, |
| 112 | + channels: 1, |
| 113 | + punctuate: true, |
| 114 | + smart_format: true, |
| 115 | +}); |
| 116 | + |
| 117 | +socket.connect(); |
| 118 | +await socket.waitForOpen();</code></pre> |
| 119 | + <p>Audio must only be sent after <code>waitForOpen()</code> resolves. Sending before the WebSocket is open will drop chunks silently.</p> |
| 120 | + |
| 121 | + <h3>3. Open the microphone</h3> |
| 122 | + <p>Create a decibri instance at 16 kHz mono. The default format is 16-bit signed integer PCM, which matches Deepgram's <code>linear16</code> encoding directly.</p> |
| 123 | + <pre><code class="language-javascript">const mic = new Decibri({ sampleRate: 16000, channels: 1 });</code></pre> |
| 124 | + |
| 125 | + <h3>4. Stream audio</h3> |
| 126 | + <p>Send each audio chunk directly to Deepgram. No format conversion is needed. decibri's raw Int16 PCM Buffer is sent as-is via <code>sendMedia()</code>.</p> |
| 127 | + <pre><code class="language-javascript">mic.on('data', (chunk) => { |
| 128 | + socket.sendMedia(chunk); |
| 129 | +});</code></pre> |
| 130 | + |
| 131 | + <h3>5. Handle transcription results</h3> |
| 132 | + <p>Listen for message events on the socket. Results arrive with <code>data.type === 'Results'</code> and contain one or more transcript alternatives.</p> |
| 133 | + <pre><code class="language-javascript">socket.on('message', (data) => { |
| 134 | + if (data.type === 'Results' && data.channel?.alternatives?.[0]) { |
| 135 | + const transcript = data.channel.alternatives[0].transcript; |
| 136 | + if (transcript) { |
| 137 | + console.log(transcript); |
| 138 | + } |
| 139 | + } |
| 140 | +});</code></pre> |
| 141 | + |
| 142 | + <h3>6. Clean shutdown</h3> |
| 143 | + <p>Stop the microphone and close the Deepgram connection when the user presses Ctrl+C.</p> |
| 144 | + <pre><code class="language-javascript">socket.on('close', () => { |
| 145 | + console.log('Connection closed.'); |
| 146 | + process.exit(0); |
| 147 | +}); |
| 148 | + |
| 149 | +socket.on('error', (err) => { |
| 150 | + console.error('Deepgram error:', err); |
| 151 | +}); |
| 152 | + |
| 153 | +mic.on('error', (err) => { |
| 154 | + console.error('Mic error:', err.message); |
| 155 | +}); |
| 156 | + |
| 157 | +process.on('SIGINT', () => { |
| 158 | + mic.stop(); |
| 159 | + socket.requestClose(); |
| 160 | +}); |
| 161 | + |
| 162 | +console.log('Listening... (Ctrl+C to stop)');</code></pre> |
| 163 | + |
| 164 | + <h2>Full example</h2> |
| 165 | + <details> |
| 166 | + <summary>View complete code</summary> |
| 167 | + <pre><code class="language-javascript">'use strict'; |
| 168 | +require('dotenv').config(); |
| 169 | + |
| 170 | +const Decibri = require('decibri'); |
| 171 | +const { DeepgramClient } = require('@deepgram/sdk'); |
| 172 | + |
| 173 | +const live = async () => { |
| 174 | + const deepgram = new DeepgramClient({ apiKey: process.env.DEEPGRAM_API_KEY }); |
| 175 | + |
| 176 | + const socket = await deepgram.listen.v1.createConnection({ |
| 177 | + model: 'nova-3', |
| 178 | + language: 'en', |
| 179 | + encoding: 'linear16', |
| 180 | + sample_rate: 16000, |
| 181 | + channels: 1, |
| 182 | + punctuate: true, |
| 183 | + smart_format: true, |
| 184 | + }); |
| 185 | + |
| 186 | + socket.on('message', (data) => { |
| 187 | + if (data.type === 'Results' && data.channel?.alternatives?.[0]) { |
| 188 | + const transcript = data.channel.alternatives[0].transcript; |
| 189 | + if (transcript) { |
| 190 | + console.log(transcript); |
| 191 | + } |
| 192 | + } |
| 193 | + }); |
| 194 | + |
| 195 | + socket.on('close', () => { |
| 196 | + console.log('Connection closed.'); |
| 197 | + process.exit(0); |
| 198 | + }); |
| 199 | + |
| 200 | + socket.on('error', (err) => { |
| 201 | + console.error('Deepgram error:', err); |
| 202 | + }); |
| 203 | + |
| 204 | + socket.connect(); |
| 205 | + await socket.waitForOpen(); |
| 206 | + |
| 207 | + const mic = new Decibri({ sampleRate: 16000, channels: 1 }); |
| 208 | + |
| 209 | + mic.on('data', (chunk) => { |
| 210 | + socket.sendMedia(chunk); |
| 211 | + }); |
| 212 | + |
| 213 | + mic.on('error', (err) => { |
| 214 | + console.error('Mic error:', err.message); |
| 215 | + }); |
| 216 | + |
| 217 | + process.on('SIGINT', () => { |
| 218 | + console.log('\nStopping...'); |
| 219 | + mic.stop(); |
| 220 | + socket.requestClose(); |
| 221 | + }); |
| 222 | + |
| 223 | + console.log('Listening... (Ctrl+C to stop)\n'); |
| 224 | +}; |
| 225 | + |
| 226 | +live().catch(console.error);</code></pre> |
| 227 | + </details> |
| 228 | + |
| 229 | + <h2>Configuration options</h2> |
| 230 | + <p>The connection options control how Deepgram processes your audio. Here are the most useful ones:</p> |
| 231 | + <div class="table-wrap"> |
| 232 | + <table> |
| 233 | + <thead> |
| 234 | + <tr> |
| 235 | + <th>Option</th> |
| 236 | + <th>Default</th> |
| 237 | + <th>Description</th> |
| 238 | + </tr> |
| 239 | + </thead> |
| 240 | + <tbody> |
| 241 | + <tr> |
| 242 | + <td><code>model</code></td> |
| 243 | + <td><code>'nova-3'</code></td> |
| 244 | + <td>Transcription model. Nova-3 is the latest and most accurate.</td> |
| 245 | + </tr> |
| 246 | + <tr> |
| 247 | + <td><code>language</code></td> |
| 248 | + <td><code>'en'</code></td> |
| 249 | + <td>Language code. Use <code>'multi'</code> for automatic language detection.</td> |
| 250 | + </tr> |
| 251 | + <tr> |
| 252 | + <td><code>punctuate</code></td> |
| 253 | + <td><code>false</code></td> |
| 254 | + <td>Add punctuation to transcripts.</td> |
| 255 | + </tr> |
| 256 | + <tr> |
| 257 | + <td><code>smart_format</code></td> |
| 258 | + <td><code>false</code></td> |
| 259 | + <td>Apply formatting for numerals, currency, and dates.</td> |
| 260 | + </tr> |
| 261 | + <tr> |
| 262 | + <td><code>diarize</code></td> |
| 263 | + <td><code>false</code></td> |
| 264 | + <td>Identify different speakers in the audio.</td> |
| 265 | + </tr> |
| 266 | + <tr> |
| 267 | + <td><code>interim_results</code></td> |
| 268 | + <td><code>false</code></td> |
| 269 | + <td>Return progressive results that refine as more audio is processed.</td> |
| 270 | + </tr> |
| 271 | + <tr> |
| 272 | + <td><code>endpointing</code></td> |
| 273 | + <td><code>10</code></td> |
| 274 | + <td>Milliseconds of silence before a final result is triggered.</td> |
| 275 | + </tr> |
| 276 | + </tbody> |
| 277 | + </table> |
| 278 | + </div> |
| 279 | + <p>See the <a href="https://developers.deepgram.com/docs/getting-started-with-live-streaming-audio" target="_blank" rel="noopener noreferrer">Deepgram streaming API reference</a> for the complete list of options.</p> |
| 280 | + |
| 281 | + <div class="related-links"> |
| 282 | + <h3>Related</h3> |
| 283 | + <ul> |
| 284 | + <li><a href="sherpa-onnx-stt.html">Sherpa-ONNX Speech-to-Text</a>: real-time local transcription, no cloud required</li> |
| 285 | + <li><a href="whisper-cpp.html">Whisper.cpp Speech-to-Text</a>: local batch transcription with OpenAI's Whisper model</li> |
| 286 | + <li><a href="/docs/node/api-reference.html">API Reference</a>: full decibri API documentation</li> |
| 287 | + <li><a href="https://developers.deepgram.com" target="_blank" rel="noopener noreferrer">Deepgram developer docs</a></li> |
| 288 | + <li><a href="https://github.com/deepgram/deepgram-js-sdk" target="_blank" rel="noopener noreferrer">Deepgram Node.js SDK on GitHub</a></li> |
| 289 | + <li><a href="https://www.npmjs.com/package/@deepgram/sdk" target="_blank" rel="noopener noreferrer">@deepgram/sdk on npm</a></li> |
| 290 | + <li><a href="https://console.deepgram.com" target="_blank" rel="noopener noreferrer">Deepgram console (sign up / API keys)</a></li> |
| 291 | + </ul> |
| 292 | + </div> |
| 293 | + |
| 294 | + <footer class="doc-footer"> |
| 295 | + <p>Apache-2.0 © <a href="https://analyticsinmotion.com" target="_blank" rel="noopener noreferrer">Analytics in Motion</a> · <a href="https://github.com/analyticsinmotion/decibri" target="_blank" rel="noopener noreferrer">GitHub</a> · <a href="https://www.npmjs.com/package/decibri" target="_blank" rel="noopener noreferrer">npm</a></p> |
| 296 | + </footer> |
| 297 | + |
| 298 | + </div> |
| 299 | + </div> |
| 300 | + |
| 301 | + <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/prism.min.js"></script> |
| 302 | + <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-javascript.min.js"></script> |
| 303 | + <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-bash.min.js"></script> |
| 304 | + <script src="../../nav.js"></script> |
| 305 | +</body> |
| 306 | +</html> |
0 commit comments