Python SDK V2 to V3 Migration Guide
Migrating from Deepgram Python SDK v2 to the Deepgram Python SDK v3
This guide is for users with experience using the Deepgram Python SDK v2 who want to migrate to the Deepgram Python SDK v3. This is not an end-to-end guide, but a reference for people using our existing Python SDK to migrate to our newest version.
Notable Changes
- Significant Restructure of the Python SDK
- Improved implementation for Live Client
- Implements both Sync(/Threaded) and Async(/Await) Classes and Functions
- Verbosity Logging Levels for Troubleshooting
- WebVTT and SRT captions published as a standalone package
- Custom Header and Query Parameters for API calls
- Support for future products (APIs)
- Better error handling
Migration Guide
This migration guide focuses primarily on the Sync/Threaded classes and methods in this SDK. The Async/Await classes and methods are very similar, where the class name will be prepended with "Async" and properties prepended with "async".
For example, the Prerecorded Client for Sync/Threaded would be Prerecorded
and the Async/Await would be AsyncPrerecorded
.
If accessing the Pre-recorded Client from the deepgram.listen
properties, the Sync/Threaded property would be deepgram.listen.prerecorded
and the Async/Await would be deepgram.listen.asyncprerecorded
.
Installation
pip install deepgram-sdk==3.*
Initialization
from deepgram import Deepgram
# Your Deepgram API Key
DEEPGRAM_API_KEY = 'YOUR_DEEPGRAM_API_KEY'
# Initialize the Deepgram SDK
deepgram = Deepgram(DEEPGRAM_API_KEY)
from deepgram import DeepgramClient
# Create a Deepgram client using the DEEPGRAM_API_KEY from environment variables
deepgram = DeepgramClient()
Transcription: Pre-recorded
We have separated the callback
feature into its own method. The functionality below is not valid with the callback feature.
Local File Transcription
Transcribe a local file on the same filesystem as the app is running.
FILE = 'interview_speech-analytics.wav'
# file is local
# Open the audio file
audio = open(FILE, 'rb')
# Set the source
source = {
'buffer': audio,
}
# Send the audio to Deepgram and get the response
response = await asyncio.create_task(
deepgram.transcription.prerecorded(
source,
{
'smart_format': "true",
'summarize': "v2",
}
)
)
# Write the response to the console
print(json.dumps(response, indent=4))
AUDIO_FILE = "preamble.wav"
# Call the transcribe_file method on the prerecorded class
with open(AUDIO_FILE, "rb") as file:
buffer_data = file.read()
payload: FileSource = {
"buffer": buffer_data,
}
options = PrerecordedOptions(
smart_format=True,
summarize="v2",
)
file_response = deepgram.listen.rest.v("1").transcribe_file(payload, options)
json = file_response.to_json()
print(f"{json}")
URL File Transcription
Transcribe a remote file by sending us a publicly accessible URL to it.
URL = 'https://static.deepgram.com/examples/interview_speech-analytics.wav'
# Set the source
source = {
'url': URL,
}
# Send the audio to Deepgram and get the response
response = await asyncio.create_task(
deepgram.transcription.prerecorded(
source,
{
'smart_format': "true",
'summarize': "v2",
}
)
)
# Write the response to the console
print(json.dumps(response, indent=4))
AUDIO_URL = {
"url": "https://static.deepgram.com/examples/Bueller-Life-moves-pretty-fast.wav"
}
options = PrerecordedOptions(
smart_format=True,
summarize="v2",
)
url_response = deepgram.listen.rest.v("1").transcribe_url(AUDIO_URL, options)
json = url_response.to_json()
print(f"{json}")
Transcription: Live
The Live Client abstracts the underlying Websocket implementation from the user. This in turn only requires that you deal with higher level functions like start()
, write()
, finish()
methods.
Live Transcription
Transcribe live audio streams. Previously only Async/Await class and methods were available. As of this release, both Sync/Threaded and Await/Await classes and methods are provided, but the prefered method of performing live transcription is Sync/Threaded.
try:
deepgramLive = await deepgram.transcription.live({
'smart_format': True,
'interim_results': False,
'language': 'en-US',
'model': 'nova-2',
})
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
# IMPORTANT: This is a blocking call with no way to exit except through a Cntl-C,
# IMPORTANT: disconnecting your internet, or killing the streaming (assuming you control that)
async with aiohttp.ClientSession() as session:
async with session.get(URL) as audio:
while True:
data = await audio.content.readany()
deepgramLive.send(data)
# If no data is being sent from the live stream, 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()
try:
deepgram: DeepgramClient = DeepgramClient()
dg_connection = deepgram.listen.websocket.v("1")
# define callbacks for transcription messages
def on_message(self, result, **kwargs):
sentence = result.channel.alternatives[0].transcript
if len(sentence) == 0:
return
print(f"speaker: {sentence}")
dg_connection.on(LiveTranscriptionEvents.Transcript, on_message)
# connect to websocket
options = LiveOptions(model="nova-2", interim_results=False, language="en-US")
dg_connection.start(options)
lock_exit = threading.Lock()
exit = False
# define a worker thread
def myThread():
with httpx.stream("GET", URL) as r:
for data in r.iter_bytes():
lock_exit.acquire()
if exit:
break
lock_exit.release()
dg_connection.send(data)
# start the worker thread
myHttp = threading.Thread(target=myThread)
myHttp.start()
# signal finished
input("Press Enter to stop recording...\n\n")
lock_exit.acquire()
exit = True
lock_exit.release()
# Wait for the HTTP thread to close and join
myHttp.join()
# Indicate that we've finished
dg_connection.finish()
except Exception as e:
print(f"Could not open socket: {e}")
return
Management API
This provides a transition guide from Async/Await to Sync/Threaded Manage APIs.
get all projects for a user
result = await deepgram.projects.list()
result = deepgram.manage.v("1").get_projects()
See our API reference for more info.
get a project
result = await deepgram.projects.get(PROJECT_ID)
result = deepgram.manage.v("1").get_project(projectId)
See our API reference for more info.
update a project
result = await deepgram.projects.update(object)
result = deepgram.manage.v("1").update_project(projectId, name="My TEST RENAME Example")
See our API reference for more info.
delete a project
result = await deepgram.projects.delete(PROJECT_ID)
result = deepgram.manage.v("1").delete_project(projectId)
See our API reference for more info.
get all project key details
result = await deepgram.keys.list(PROJECT_ID)
result = deepgram.manage.v("1").get_keys(projectId)
See our API reference for more info.
get a project key
result = await deepgram.keys.get(PROJECT_ID, KEY_ID)
result = deepgram.manage.v("1").get_key(projectId, myKeyId)
See our API reference for more info.
create a project key
result = await deepgram.keys.create(PROJECT_ID, COMMENT_FOR_KEY, SCOPES)
options = KeyOptions(
comment="MyTestKey",
scopes=["member"],
)
result = deepgram.manage.v("1").create_key(projectId, options)
See our API reference for more info.
delete a project key
result = await deepgram.keys.delete(PROJECT_ID, KEY_ID)
result = deepgram.manage.v("1").delete_key(projectId, keyId)
See our API reference for more info.
get all project members
result = await deepgram.members.list_members(PROJECT_ID);
result = deepgram.manage.v("1").get_members(projectId)
See our API reference for more info.
remove a project member
result = await deepgram.members.remove_member(PROJECT_ID, MEMBER_ID)
result = deepgram.manage.v("1").remove_member(projectId, memberId)
See our API reference for more info.
get all scopes for a project member
result = await deepgram.scopes.get_scope(PROJECT_ID, MEMBER_ID)
result = deepgram.manage.v("1").get_member_scopes(projectId, memberId)
See our API reference for more info.
update a scope for a project member
result = await deepgram.scopes.update_scope(PROJECT_ID, MEMBER_ID, 'member')
options = ScopeOptions
scope="admin"
)
result = deepgram.manage.v("1").update_member_scope(projectId, memberId, options)
See our API reference for more info.
get all project invites
result = await deepgram.invitations.list_invitations(PROJECT_ID);
result = deepgram.manage.v("1").get_invites(projectId)
See our API reference for more info.
send a project invite
result = await deepgram.invitations.send_invitation(PROJECT_ID, {
email: '[email protected]',
scope: 'member',
})
options = InviteOptions(
email="[email protected]",
scope="member"
)
result = deepgram.manage.v("1").send_invite_options(projectId, options)
See our API reference for more info.
delete a project invite
result = await deepgram.invitations.remove_invitation(
PROJECT_ID,
'[email protected]'
)
result = deepgram.manage.v("1").delete_invite(projectId, "[email protected]")
See our API reference for more info.
leave a project
result = await deepgram.invitation.leave_project(PROJECT_ID);
result = deepgram.manage.v("1").leave_project(projectId)
See our API reference for more info.
get all usage requests for a project
result = await deepgram.usage.list_requests(PROJECT_ID, {
'limit': 10,
# other options are available
});
result = deepgram.manage.v("1").get_usage_requests(projectId, options)
See our API reference for more info.
get a usage request for a project
result = await deepgram.usage.get_request(PROJECT_ID, REQUEST_ID);
result = deepgram.manage.v("1").get_usage_request(projectId, requestId)
See our API reference for more info.
get the project usage summary
result = await deepgram.usage.get_usage(PROJECT_ID, {
'start': '2020-01-01T00:00:00+00:00',
# other options are available
});
result = deepgram.manage.v("1").get_usage_summary(projectId, options)
See our API reference for more info.
get project usage fields
result = await deepgram.usage.get_fields(PROJECT_ID, {
'start': '2020-01-01T00:00:00+00:00',
# other options are available
});
result = deepgram.manage.v("1").get_usage_fields(projectId, options)
See our API reference for more info.
get all project balances
result = await deepgram.billing.list_balance(PROJECT_ID);
result = deepgram.manage.v("1").get_balances(projectId)
See our API reference for more info.
get a project balance
result = await deepgram.billing.get_balance(PROJECT_ID, BALANCE_ID);
result = deepgram.manage.v("1").get_balance(projectId, balanceId)
See our API reference for more info.
Self-Hosted API
[NOTICE] The self-hosted API has not changed since the last release, but in v4
these APIs will likely go through a breaking change. There was only so much we could do with this release and unfortunately, these APIs failed to make the cut off.
Updated 5 months ago