Output formats & subtitles

One transcription, six shapes. Set output_type to choose what the server returns — structured JSON, plain text, subtitle files, or ready-to-share documents. The default is json. The server does the formatting; the SDK never writes a file unless you call save().

The six formats

output_type is a request option across every SDK — a kwarg in Python, an option field in JavaScript, and the OutputType enum in Go (stt.OutputSRT) and C# (OutputType.Srt).

The JSON schema

The default json output is a document whose core is a words array; each word has the token plus optional start, end, speaker, confidence, and language. When diarization runs, the document may also carry diarization segments; when the audio switches languages mid-file, it may also carry a languages array. The SDK reads this into a transcript object — deriving .text, grouping words into .utterances, and keeping the original under .raw.

{
  "words": [
    { "word": "Hi",      "start": 0.50, "end": 0.68, "speaker": "SPEAKER_0", "language": "en" },
    { "word": "there",   "start": 0.68, "end": 0.94, "speaker": "SPEAKER_0", "language": "en" }
  ],
  "diarization": [
    { "speaker": "SPEAKER_0", "start": 0.50, "end": 0.94 }
  ],
  "languages": [
    { "language": "en", "start": 0.50, "end": 0.94 }
  ]
}

The SDK normalizes it into a predictable object. Use result.to_dict() for a provider-neutral dict:

{
  "id": "d1f2...-job-id",
  "status": "completed",
  "text": "Hi there ...",
  "words": [
    { "word": "Hi", "text": "Hi", "start": 0.5, "end": 0.68, "speaker": "SPEAKER_0", "language": "en" }
  ],
  "utterances": [
    { "text": "Hi there", "transcript": "Hi there", "speaker": "SPEAKER_0",
      "start": 0.5, "end": 0.94, "words": [ ... ] }
  ],
  "languages": [
    { "start": 0.5, "end": 0.94, "language": "en" }
  ],
  "output_type": "json"
}

For migrations, result.to_deepgram() reshapes the same data into Deepgram's pre-recorded response — access it at results.channels[0].alternatives[0].transcript. See the Python SDK result-shape table for the full member list.

Subtitles: SRT & VTT

Ask for srt or vtt and the server returns formatted subtitle bytes — you don't assemble cues from word timings yourself. For these non-JSON outputs, result.text is the decoded file contents and result.save() writes it, inferring the extension from the output type when your path has none.

srt = client.transcribe("meeting.mp3", output_type="srt")
print(srt.text)          # the decoded .srt contents
srt.save("meeting")      # -> meeting.srt

vtt = client.transcribe("meeting.mp3", output_type="vtt")
vtt.save("meeting")      # -> meeting.vtt

1
00:00:00,500 --> 00:00:02,100
Hi there, thanks for joining.

2
00:00:03,200 --> 00:00:04,600
Happy to be here.

Documents: DOCX & PDF

docx and pdf return a formatted document as raw bytes. These aren't text you decode — save them straight to disk (or stream to your user). docx stays editable; pdf is fixed-layout and print-ready.

docx = client.transcribe("meeting.mp3", output_type="docx")
docx.save("meeting")     # -> meeting.docx

pdf = client.transcribe("meeting.mp3", output_type="pdf")
# .content is the raw bytes if you'd rather stream than save
with open("meeting.pdf", "wb") as f:
    f.write(pdf.content)

Choosing a format

• Building software — use json. It's the only format with structured timestamps and speaker data you can iterate.
• Captioning video — srt or vtt, formatted server-side and ready to drop in.
• Sharing with people — docx (editable) or pdf (print-ready).
• Just the words — txt.