feat: add Deepgram file transcription support

Uses Deepgram's pre-recorded API (POST /v1/listen) with binary file upload.
Supports nova-3 model, auto language detection, speaker diarization,
smart formatting, and word-level timestamps. Maximum 2GB file size.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: XimilalaXiang

frontend/src/hooks/useFileTranscription.ts

@@ -40,6 +40,11 @@ import {
   transcribeFile as elevenlabsTranscribeFile,
   type ElevenLabsWord,
 } from '../utils/elevenlabsFileApi'
+import {
+  transcribeFile as deepgramTranscribeFile,
+  type DeepgramFileWord,
+  type DeepgramFileUtterance,
+} from '../utils/deepgramFileApi'
 
 /* ─── Soniox result conversion ──────────────────────────────── */
 
@@ -662,6 +667,92 @@ async function executeCloudflare(
   }
 }
 
+/* ─── Deepgram result conversion ───────────────────────────── */
+
+function deepgramWordsToTokens(words: DeepgramFileWord[]): TranscriptTokenData[] {
+  return words.map((w) => ({
+    text: w.punctuated_word || w.word,
+    isFinal: true,
+    startMs: Math.round(w.start * 1000),
+    endMs: Math.round(w.end * 1000),
+    confidence: w.confidence,
+    speaker: w.speaker != null ? String(w.speaker) : undefined,
+  }))
+}
+
+function deepgramUtterancesToSegments(utterances: DeepgramFileUtterance[]): TranscriptSegment[] {
+  return utterances.map((u) => ({
+    text: u.transcript.trim(),
+    startMs: Math.round(u.start * 1000),
+    endMs: Math.round(u.end * 1000),
+    isFinal: true,
+    speaker: u.speaker != null ? String(u.speaker) : undefined,
+  }))
+}
+
+function deepgramExtractSpeakers(utterances: DeepgramFileUtterance[]): TranscriptSpeaker[] {
+  const ids = new Set<number>()
+  for (const u of utterances) {
+    if (u.speaker != null) ids.add(u.speaker)
+  }
+  return Array.from(ids)
+    .sort((a, b) => a - b)
+    .map((id) => ({ id: String(id), name: `Speaker ${id}` }))
+}
+
+async function executeDeepgram(
+  file: File,
+  config: FileTranscriptionConfig,
+  apiKey: string,
+  jobId: string,
+  updateJob: (id: string, u: Record<string, unknown>) => void,
+  signal: AbortSignal,
+): Promise<TranscriptionResult> {
+  updateJob(jobId, { status: 'uploading', progress: 20 })
+
+  updateJob(jobId, { status: 'transcribing', progress: 40 })
+  const response = await deepgramTranscribeFile(
+    apiKey,
+    file,
+    {
+      model: config.model || 'nova-3',
+      language: config.languageHints?.[0],
+      diarize: config.enableSpeakerDiarization,
+      punctuate: true,
+      utterances: true,
+      smartFormat: true,
+    },
+    signal,
+  )
+
+  updateJob(jobId, { progress: 90 })
+
+  const channel = response.results.channels[0]
+  const alt = channel?.alternatives[0]
+  const transcript = alt?.transcript ?? ''
+  const words = alt?.words ?? []
+  const utterances = response.results.utterances ?? []
+
+  const tokens = words.length > 0
+    ? deepgramWordsToTokens(words)
+    : [{ text: transcript, isFinal: true, startMs: 0, endMs: (response.metadata.duration ?? 0) * 1000 }]
+
+  const segments = utterances.length > 0
+    ? deepgramUtterancesToSegments(utterances)
+    : [{ text: transcript.trim(), startMs: 0, endMs: (response.metadata.duration ?? 0) * 1000, isFinal: true }]
+
+  const speakers = deepgramExtractSpeakers(utterances)
+  const durationMs = (response.metadata.duration ?? 0) * 1000
+
+  return {
+    transcript,
+    tokens,
+    segments,
+    speakers,
+    durationMs,
+  }
+}
+
 /* ─── Main hook ─────────────────────────────────────────────── */
 
 export function useFileTranscription() {
@@ -712,6 +803,8 @@ export function useFileTranscription() {
           result = await executeGladia(file, config, apiKey!, jobId, updateJob, controller.signal)
         } else if (providerId === 'elevenlabs') {
           result = await executeElevenLabs(file, config, apiKey!, jobId, updateJob, controller.signal)
+        } else if (providerId === 'deepgram') {
+          result = await executeDeepgram(file, config, apiKey!, jobId, updateJob, controller.signal)
         } else {
           result = await executeSoniox(file, config, apiKey!, jobId, updateJob, controller.signal)
         }

frontend/src/providers/implementations/DeepgramProvider.ts

@@ -50,7 +50,10 @@ export class DeepgramProvider extends BaseASRProvider {
           acceptedFileKinds: ['audio'],
         },
         fileTranscription: {
-          availability: 'unsupported',
+          availability: 'compatible',
+          executionMode: 'single-request',
+          inputSources: ['file'],
+          acceptedFileKinds: ['audio', 'video'],
         },
       },
       supportsConfigTest: true,

frontend/src/utils/deepgramFileApi.ts

@@ -0,0 +1,120 @@
+import { DEEPGRAM_DEFAULT_MODEL } from '../types/asr/vendors/deepgram'
+
+const DEEPGRAM_API_BASE = 'https://api.deepgram.com'
+
+export interface DeepgramFileWord {
+  word: string
+  start: number
+  end: number
+  confidence: number
+  speaker?: number
+  punctuated_word?: string
+}
+
+export interface DeepgramFileChannel {
+  alternatives: Array<{
+    transcript: string
+    confidence: number
+    words?: DeepgramFileWord[]
+  }>
+}
+
+export interface DeepgramFileUtterance {
+  start: number
+  end: number
+  confidence: number
+  channel: number
+  transcript: string
+  words: DeepgramFileWord[]
+  speaker?: number
+  id: string
+}
+
+export interface DeepgramFileTranscriptionResponse {
+  metadata: {
+    request_id: string
+    created: string
+    duration: number
+    channels: number
+    models: string[]
+    sha256: string
+  }
+  results: {
+    channels: DeepgramFileChannel[]
+    utterances?: DeepgramFileUtterance[]
+  }
+}
+
+export interface DeepgramFileTranscribeParams {
+  model?: string
+  language?: string
+  diarize?: boolean
+  punctuate?: boolean
+  utterances?: boolean
+  smartFormat?: boolean
+}
+
+function getMimeType(fileName: string): string {
+  const ext = fileName.split('.').pop()?.toLowerCase()
+  const mimeMap: Record<string, string> = {
+    wav: 'audio/wav',
+    mp3: 'audio/mpeg',
+    mp4: 'video/mp4',
+    m4a: 'audio/mp4',
+    ogg: 'audio/ogg',
+    flac: 'audio/flac',
+    webm: 'audio/webm',
+    aac: 'audio/aac',
+    wma: 'audio/x-ms-wma',
+    avi: 'video/x-msvideo',
+    mov: 'video/quicktime',
+    mkv: 'video/x-matroska',
+  }
+  return mimeMap[ext ?? ''] ?? 'audio/wav'
+}
+
+export async function transcribeFile(
+  apiKey: string,
+  file: File,
+  params: DeepgramFileTranscribeParams = {},
+  signal?: AbortSignal,
+): Promise<DeepgramFileTranscriptionResponse> {
+  const queryParams = new URLSearchParams()
+  queryParams.set('model', params.model || DEEPGRAM_DEFAULT_MODEL)
+  queryParams.set('punctuate', String(params.punctuate ?? true))
+  queryParams.set('utterances', String(params.utterances ?? true))
+  queryParams.set('smart_format', String(params.smartFormat ?? true))
+
+  if (params.language) {
+    queryParams.set('language', params.language)
+  } else {
+    queryParams.set('detect_language', 'true')
+  }
+
+  if (params.diarize) {
+    queryParams.set('diarize', 'true')
+  }
+
+  const arrayBuffer = await file.arrayBuffer()
+
+  const res = await fetch(`${DEEPGRAM_API_BASE}/v1/listen?${queryParams.toString()}`, {
+    method: 'POST',
+    headers: {
+      Authorization: `Token ${apiKey}`,
+      'Content-Type': getMimeType(file.name),
+    },
+    body: arrayBuffer,
+    signal,
+  })
+
+  if (!res.ok) {
+    let errorMsg = `Deepgram API error ${res.status}`
+    try {
+      const body = await res.json()
+      errorMsg = body.err_msg || body.error || body.message || errorMsg
+    } catch { /* ignore */ }
+    throw new Error(errorMsg)
+  }
+
+  return res.json()
+}