Deepgram Python SDK

Official Python SDK for Deepgram. Power your apps with world-class speech and Language AI models.

This SDK only supports hosted usage of api.deepgram.com.

Getting an API Key

🔑 To access the Deepgram API you will need a free Deepgram API Key.

Documentation

Complete documentation of the Python SDK can be found at Deepgram Docs.

You can learn more about the Deepgram API at developers.deepgram.com.

Getting Started

pip install deepgram-sdk

Usage

Transcribe an Existing File or Pre-recorded Audio

from deepgram import Deepgram
import json

DEEPGRAM_API_KEY = 'YOUR_API_KEY'
PATH_TO_FILE = 'some/file.wav'

def main():
    # Initializes the Deepgram SDK
    deepgram = Deepgram(DEEPGRAM_API_KEY)
    # Open the audio file
    with open(PATH_TO_FILE, 'rb') as audio:
        # ...or replace mimetype as appropriate
        source = {'buffer': audio, 'mimetype': 'audio/wav'}
        response = deepgram.transcription.sync_prerecorded(source, {'punctuate': True})
        print(json.dumps(response, indent=4))

main()

Transcribe an Existing File or Pre-recorded Audio Asynchronously

from deepgram import Deepgram
import asyncio, json

DEEPGRAM_API_KEY = 'YOUR_API_KEY'
PATH_TO_FILE = 'some/file.wav'

async def main():
    # Initializes the Deepgram SDK
    deepgram = Deepgram(DEEPGRAM_API_KEY)
    # Open the audio file
    with open(PATH_TO_FILE, 'rb') as audio:
        # ...or replace mimetype as appropriate
        source = {'buffer': audio, 'mimetype': 'audio/wav'}
        response = await deepgram.transcription.prerecorded(source, {'punctuate': True})
        print(json.dumps(response, indent=4))

asyncio.run(main())

Transcribe Audio in Real-Time or Streaming Audio

from deepgram import Deepgram
import asyncio
import aiohttp

# Your Deepgram API Key
DEEPGRAM_API_KEY = 'YOUR_API_KEY'

# URL for the audio you would like to stream
URL = 'http://stream.live.vc.bbcmedia.co.uk/bbc_world_service'

async def main():
  # Initialize the Deepgram SDK
  deepgram = Deepgram(DEEPGRAM_API_KEY)

  # Create a websocket connection to Deepgram
  # In this example, punctuation is turned on, interim results are turned off, and language is set to US English.
  try:
    deepgramLive = await deepgram.transcription.live({ 'punctuate': True, 'interim_results': False, 'language': 'en-US' })
  except Exception as e:
    print(f'Could not open socket: {e}')
    return

# Listen for the connection to close
  deepgramLive.registerHandler(deepgramLive.event.CLOSE, lambda c: print(f'Connection closed with code {c}.'))

  # Listen for any transcripts received from Deepgram and write them to the console
  deepgramLive.registerHandler(deepgramLive.event.TRANSCRIPT_RECEIVED, print)

  # Listen for the connection to open and send streaming audio from the URL to Deepgram
  async with aiohttp.ClientSession() as session:
    async with session.get(URL) as audio:
      while True:
        data = await audio.content.readany()
        deepgramLive.send(data)

        # If there's no data coming from the livestream then break out of the loop
        if not data:
            break

  # Indicate that we've finished sending data by sending the customary zero-byte message to the Deepgram streaming endpoint, and wait until we get back the final summary metadata object
  await deepgramLive.finish()

asyncio.run(main())

Parameters

Query parameters like punctuate are added as part of the TranscriptionOptions dict in the .prerecorded/.live transcription call. Multiple query parameters can be added similarly, and any dict will do - the types are provided for reference/convenience.

response = await dg_client.transcription.prerecorded(source, {'punctuate': True, 'keywords': ['first:5', 'second']})

Depending on your preference, you can also add parameters as named arguments, instead.

response = await dg_client.transcription.prerecorded(source, punctuate=True, keywords=['first:5', 'second'])

Testing

Setup

Run the following command to install pytest and pytest-cov as dev dependencies.

pip install -r requirements-dev.txt

Run All Tests

Setup

pip install pytest
pip install pytest-cov

Run All Tests

pytest --api-key <key> tests/

Test Coverage Report

pytest --cov=deepgram --api-key <key> tests/

Using Example Projects to test new features

Contributors to the SDK can test their changes locally by running the projects in the examples folder. This can be done when making changes without adding a unit test, but of course it is recommended that you add unit tests for any feature additions made to the SDK.

Go to the folder examples and look for these two projects, which can be used to test out features in the Deepgram Python SDK:

• prerecorded
• streaming

These are standalone projects, so you will need to follow the instructions in the README.md files for each project to get it running.

Development and Contributing

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.

Getting Help

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:

• Open an issue in this repository
• Join the Deepgram Github Discussions Community
• Join the Deepgram Discord Community