Skip to main content

Deepgram Python SDK

Contributor Covenant

This SDK is under active development; feel free to provide feedback via GitHub issues and suggest new features.

Official Python SDK for Deepgram's automated speech recognition APIs.

To access the API you will need a Deepgram account. Sign up for free at console.deepgram.com.

You can learn more about the full 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 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 for the example resource will change depending on whether user is outside or inside the UK
# Outside the UK
URL = 'http://stream.live.vc.bbcmedia.co.uk/bbc_radio_fourlw_online_nonuk'
# Inside the UK
# URL = 'http://stream.live.vc.bbcmedia.co.uk/bbc_radio_fourfm'

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'])

Code Samples

To run the sample code, you may want to create a virtual environment to isolate your Python projects, but it's not required. You can learn how to make and activate these virtual environments in this article on our Deepgram blog.

Streaming Audio Code Samples

In the sample-projects folder, there are examples from four different Python web frameworks of how to do live streaming audio transcription with Deepgram. These include:

  • Flask 2.0
  • FastAPI
  • Django
  • Quart

Each of the examples has a README file you can follow to set up and run your project. If you get stuck, please feel free to Tweet us! We're @DeepgramDevs on Twitter

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:

Further Reading

Check out the Developer Documentation at https://developers.deepgram.com/

Metadata

Release files for deepgram-sdk 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for deepgram-sdk 0.3.0
File Size Uploaded Provenance Actions
deepgram-sdk-0.3.0.tar.gz 14.4 kB Without provenance Details for deepgram-sdk-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for deepgram-sdk 0.3.0
File Interpreter ABI Platform Actions
deepgram_sdk-0.3.0-py3-none-any.whl Python 3 none any Details for deepgram_sdk-0.3.0-py3-none-any.whl

Total release size: 30.1 kB

Release files / deepgram-sdk-0.3.0.tar.gz

Download URL deepgram-sdk-0.3.0.tar.gz
Size 14.4 kB
Tags Source
SHA-256 checksum
How to use checksums
ddd904663bec02fb3f49dcd4243b051bcc4c9d0796c396a078b70a71632b6eb6
BLAKE2b-256 checksum
How to use checksums
f5952fbf4166c183a98f3a847ccb4ef8876633c83405d325d968d623e89d0652
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/4.0.1 CPython/3.9.13

Release files / deepgram_sdk-0.3.0-py3-none-any.whl

Download URL deepgram_sdk-0.3.0-py3-none-any.whl
Size 15.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
74a6302a9df005a86dfb68edae79c644573bf599af49a556c35e3c408cd71d1e
BLAKE2b-256 checksum
How to use checksums
01cc9b904edf90aff61c1eb987291ba7332b558bf962cf08a031393ad1d3f9bc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/4.0.1 CPython/3.9.13

Security for deepgram-sdk 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.3.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page