Reference - Python SDK

This page contains detailed descriptions of the class and objects supported by the Symbl Python SDK.

Audio Class
Video Class
Text Class
Conversation Object
Telephony Class
Streaming Class

Audio Class

Symbl's Async APIs provide the functionality for processing audio recordings from files or public/signed URLs. The data processed for these conversations are available via the Conversation APIs once the APIs have completed the processing.

You can utilize different functions of Async APIs by directly utilizing symbl.Audio.

process_file(file_path):

Returns conversation object.

Name	Required	Description
`file_path`	Mandatory	A valid path to a file.
`credentials`	Optional	Don't add this parameter if you have symbl.conf file in your home directory or working directory.
`content_type`	Optional	Parameter defining the content_type of audio. Acceptable values are `audio/wav`, `audio/mp3`, `audio/mpeg`. Leave it blank if you're not sure about the content_type of file.
`wait`	Optional	This accepts a Boolean value and is by default `true`. Value False will execute the function `submit_audio` on a separate thread making it a non-blocking API call. This also has callback support.
`parameters`	Optional	By default {}) Dictionary, Any parameter and it's value can be provided in the dictionary format. For getting a list of value check Process Audio.

process_url(url):

Returns conversation object.

Name	Required	Description
`payload`	Mandatory	A valid payload having `url` as the member and it should be valid to a file hosted directly. valid payload [`payload = { 'url': "<url>" }`]
`credentials`	Optional	Don't add this parameter if you have symbl.conf file in your home directory or working directory.
`wait`	Optional	Accepts a Boolean value, by default, set to `true`. Value False will execute the function `submit_video` on a separate thread making it a non-blocking API call (Has callback support).
`parameters`	Optional	By default {}) Dictionary, Any parameter and it's value can be provided in the dictionary format. For getting a list of value check Process Audio.

append_file(file_path, conversation_id):

Returns conversation object.

Name	Required	Description
`file_path`	Mandatory	A valid path to a file.
`conversation_id`	Mandatory	Unique identifier of the previous conversation to which appending the current conversation.
`content_type`	Optional	Parameter defining the content_type of audio. Acceptable values are `audio/wav`, `audio/mp3`, `audio/mpeg`. Leave it blank if you're not sure about the `content_type` of file.
`credentials`	Optional	Don't add this parameter if you have symbl.conf file in your home directory or working directory.
`wait`	Optional	Accepts a Boolean value. By default set to `true`. Value False will execute the function `submit_audio` on a separate thread making it a non-blocking API call (Has callback support).
`parameters`	Optional	By default {}) Dictionary, Any parameter and it's value can be provided in the dictionary format. For getting a list of value check Process Audio.

append_url(url, conversation_id):

Returns conversation object.

Name	Required	Description
`payload`	Mandatory	A valid payload having `url` as the member and it should be valid to a file hosted directly. valid payload [`payload = { 'url': "<url>" }`]
`conversation_id`	Mandatory	Unique `conversationId` of a previous conversation to which appending the current conversation.
`wait`	Optional	Accepts a Boolean value, By default `true`. Value False will execute the function `submit_video` on a separate thread making it a non-blocking API call (Has callback support).
`credentials`	Optional	Don't add this parameter if you have symbl.conf file in your home directory or working directory.
`parameters`	Optional	By default {}) Dictionary, Any parameter and it's value can be provided in the dictionary format. For getting a list of value check Process Audio.

Video Class

Symbl's Async APIs provide the functionality for processing video recordings from files or public/signed URLs. The data processed for these conversations are available via the Conversation APIs once the APIs have completed the processing.

You can utilize different functions of Async APIs by directly utilizing symbl.Video.

process_file(file_path):

Returns conversation object.

Name	Required	Description
`file_path`	Mandatory	A valid path to a file.
`credentials`	Optional	Don't add this parameter if you have symbl.conf file in your home directory or working directory.
`content_type`	Optional	Parameter defining the `content_type` of video. Acceptable values are `video/mp4`. Leave it blank if you're not sure about the `content_type` of file.
`wait`	Optional	Accepts a Boolean value. By default set to `true`. Value False will execute the function `submit_video` on a separate thread making it a non-blocking API call (Has callback support).
`parameters`	Optional	By default {}) Dictionary, Any parameter and it's value can be provided in the dictionary format. For getting a list of value check Process Video.

process_url(payload):

Returns conversation object.

Name	Required	Description
`payload`	Mandatory	A valid payload having `url` as the member and it should be valid to a file hosted directly. valid payload [`payload = { 'url': "<url>" }`].
`credentials`	Optional	Don't add this parameter if you have symbl.conf file in your home directory or working directory.
`wait`	Optional	Accepts a Boolean. By default set to `true`. Value False will execute the function submit_video on a separate thread making it a non-blocking API call (Has callback support).
`parameters`	Optional	By default {}) Dictionary, Any parameter and it's value can be provided in the dictionary format. For getting a list of value check Process Video.

append_file(file_path, conversation_id):

Returns conversation object.

Name	Required	Description
`file_path`	Mandatory	A valid path to a file.
`conversation_id`	Mandatory	Unique `conversationId` of a previous conversation to which appending the current conversation.
`credentials`	Optional	Don't add this parameter if you have symbl.conf file in your home directory or working directory.
`content_type`	Optional	Parameter defining the `content_type` of video. Acceptable values are `video/mp4`. Leave it blank if you're not sure about the `content_type` of file.
`wait`	Optional	Accepts a Boolean value: `true` or `false`. By default set to `true`. Value `false` will execute the function `submit_video` on a separate thread making it a non-blocking API call (Has callback support).
`parameters`	Optional	By default {}) Dictionary, Any parameter and it's value can be provided in the dictionary format. For getting a list of value check Process Video.

append_url(payload, conversation_id):

Returns conversation object.

Name	Required	Description
`payload`	Mandatory	A valid payload having `url` as the member and it should be valid to a file hosted directly. valid payload [`payload = { 'url': "<url>" }`].
`conversation_id`	Mandatory	Unique `conversationId` of a previous conversation to which appending the current conversation.
`credentials`	Optional	Don't add this parameter if you have symbl.conf file in your home directory or working directory.
`wait`	Optional	Accepts a Boolean value: `true` or `false`. Value False will execute the function `submit_video` on a separate thread making it a non-blocking API call (Has callback support).
`parameters`	Optional	By default {}) Dictionary, Any parameter and it's value can be provided in the dictionary format. For getting a list of value check Process Video.

Text Class

Symbl's Async APIs provide the functionality for processing textual content from a conversation. The data processed for these conversations are available via the Conversation APIs once the APIs have completed the processing.

You can utilize different functions of Async APIs by directly utilizing symbl.Text.

process(payload):

Returns conversation object.

Name	Required	Description
`payload`	Mandatory	Textual dictionary containing the conversation to be processed in textual form, See Async API Documentation for payload.
`credentials`	Optional	Don't add this parameter if you have symbl.conf file in your home directory or working directory.
`content_type`	Optional	Parameter defining the content_type of the text conversation. Acceptable value is `application/json`.
`wait`	Optional	Accepts a Boolean value: `true` or `false`. By default, it is set to `true`. Value False will execute the function submit_text on a separate thread making it a non-blocking API call (Has callback support).
`parameters`	Optional	By default {}) Dictionary, Any parameter and it's value can be provided in the dictionary format. For getting a list of value check Process Text.

append(payload, conversation_id):

Returns conversation object.

Name	Required	Description
`payload`	Mandatory	Textual dictionary containing the conversation to be processed in textual form, See docs for payload.
`conversation_id`	Mandatory	Unique `conversationId` of a previous conversation to which appending the current conversation.
`credentials`	Optional	Don't add this parameter if you have symbl.conf file in your home directory or working directory.
`wait`	Optional	Accepts a Boolean value: `true` or `false`. By default, it is set to `true`. Value False will execute the function `submit_text` on a separate thread making it a non-blocking API call (Has callback support).
`parameters`	Optional	By default {}) Dictionary, Any parameter and it's value can be provided in the dictionary format. For getting a list of value check Process Text.

Conversation object

The Text, Audio, and Video classes of the Async API return the Conversation object. The conversation object is a shorthand for conversation API and can be utilized for fetching multiple insights.

conversation_object.get_conversation_id():

Returns a unique Conversation Id of the conversation which you are currently processing.

conversation_object.get_job_id():

Returns a Job Id of the conversation which you are currently processing.

conversation_object.get_action_items():

Returns Action Items which are some specific outcomes recognized in the conversation that requires one or more people in the conversation to act in the future.

conversation_object.get_follow_ups():

Returns a category of action items with a connotation to follow-up a request or a task like sending an email or making a phone call or booking an appointment or setting up a meeting.

conversation_object.get_members():

Returns a list of all the members in a conversation. A Member is referred to as a participant in the conversation that is uniquely identified as a speaker. Identifying different participants in the meetings can be done by implementing speaker separation.

conversation_object.get_messages():

parameters:- (Optional) dictionary, takes a dictionary of parameters. For list of parameters accepted, see Speech-to-Text.

Returns a list of messages (sentences spoken by speakers) in a conversation. You can use this for providing transcription for video conference, meeting or telephone call.

conversation_object.get_questions():

Returns explicit question or request for information that comes up during the conversation, whether answered or not, is recognized as a question.

conversation_object.get_topics():

parameters:- (Optional) dictionary, takes a dictionary of parameters. For list of parameters accepted, see Topics.

Returns The most relevant topics of discussion from the conversation that is generated based on the combination of the overall scope of the discussion.

conversation_object.get_conversation():

Returns the conversation meta-data like meeting name, member name and email, start and end time of the meeting, meeting type, and meeting ID.

conversation_object.get_entities()

Extracts entities such as custom, location, person, date, number, organization, datetime, daterange, and so on, from the conversation.

conversation_object.get_trackers()

Returns the occurrence of certain key words or phrases from the conversation.

conversation_object.get_analytics()

Returns the speaker ratio, talk time, silence, pace and overlap from the conversation.

conversation_object.put_members(members_id, parameters={})

members_id:- (mandatory) string, that takes the id of the member who's details you would like to update.

parameters:- (mandatory) takes a dictionary of parameters. For list of parameters accepted, see PUT Member Information page.

Updates an existing member in an conversation. This API can be used for updating the unique speakers detected as members from diarization as well.

To see an example of the usage of put_members functionality, go to out GitHub examples page.

conversation_object.put_speakers_events(parameters={})

parameters:- (mandatory) takes a dictionary which contains speakerEvents. For list of parameters accepted, see Speaker Events Object page.

This API provides the functionality to update Speakers in a conversation after it has been processed.

To checkout an example of the usage of put_speakers_events functionality using Conversations class for Async APIs, see this GitHub example page.

To checkout an example of the usage of put_speakers_events functionality using Conversations class for Streaming APIs, see this GitHub example page.

Example to demonstrate the use of conversation class:

import symbl

file = "<file_path>"
conversation_object = symbl.Audio.process_file(file_path=file)

print(conversation_object.get_messages())
print(conversation_object.get_action_items())
print(conversation_object.get_follow_ups())
print(conversation_object.get_members())
print(conversation_object.get_topics())
print(conversation_object.get_questions())

Conversations Class

The Conversation API provides a REST API interface for getting your processed Speech to Text data(also known as Transcripts) and conversational insights.

These APIs require a conversationId.

You can utilize different functions of Conversation APIs by directly utilizing symbl.Conversations.

get_conversation_id():

Returns a unique Conversation Id of the conversation which you are currently processing.

get_job_id():

Returns a Job Id of the conversation which you are currently processing.

get_action_items(conversation_id):

Returns Action Items which are some specific outcomes recognized in the conversation that requires one or more people in the conversation to act in the future

get_follow_ups(conversation_id):

Returns a category of action items with a connotation to follow-up a request or a task like sending an email or making a phone call or booking an appointment or setting up a meeting.

get_members(conversation_id):

Returns a list of all the members in a conversation. A Member is referred to a participant in the conversation that is uniquely identified as a speaker. Identifying different participants in the meetings can be done by implementing speaker separation.

get_messages(conversation_id):

parameters:- (Optional) dictionary, takes a dictionary of parameters. For list of parameters accepted, please click Speech-to-Text.

Returns a list of messages (sentences spoken by speakers) in a conversation. You can use this for providing transcription for video conference, meeting or telephone call.

get_questions(conversation_id):

Returns explicit question or request for information that comes up during the conversation, whether answered or not, is recognized as a question.

get_topics(conversation_id):

parameters:- (Optional) dictionary, takes a dictionary of parameters. For list of parameters accepted, please click Topics.

Returns The most relevant topics of discussion from the conversation that is generated based on the combination of the overall scope of the discussion.

get_conversation(conversation_id)

Returns the conversation meta-data like meeting name, member name and email, start and end time of the meeting, meeting type and meeting ID.

get_entities(conversation_id)

Provides a functionality to extract entities(custom, location, person, date, number, organization,datetime,daterange, etc ) from the conversation.

get_trackers(conversation_id)

Returns the occurrence of certain key words or phrases from the conversation.

get_analytics(conversation_id)

Returns the speaker ratio, talk time, silence, pace and overlap from the conversation.

put_members(conversation_id, members_id, parameters={})

members_id:- (mandatory) string, that takes the ID of the member who's details you would like to update.

parameters:- (mandatory) takes a dictionary of parameters. For list of parameters accepted, see Update members.

Updates an existing member in an conversation. This API can be used for updating the unique speakers detected as members from diarization as well.

To see an example of the usage of put_members functionality using Conversations class, see symbl-python-sdk / put_members.py | github.com.

put_speakers_events(conversation_id, parameters={})

parameters:- (mandatory) takes a dictionary which contains speakerEvents. For list of parameters accepted, see Speaker Event Object page.

This API provides the functionality to update Speakers in a conversation after it has been processed.

To see an example of the usage of put_speakers_events functionality using Conversations class for Async APIs, see our symbl-python-sdk / put_speaker_events_async.py | github.com page.

To see an example of the usage of put_speakers_events functionality using Conversations class for Streaming APIs, see symbl-python-sdk / put_speaker_events_streaming.py | github.com page.

Example to demonstrate the use of conversation class:

import symbl

conversation_id=1234567890 # Update with the conversation Id of your conversation

print(symbl.conversations.get_messages(conversation_id))

Telephony Class

Based on PSTN and SIP protocols, the Telephony API provides an interface for the developers to have Symbl bridge/join VoIP calls and get the results back in real-time as well. Optionally, the developer can also trigger an email at the end of the conversation containing the URL to view the transcription, insights and topics in a single page Web Application.

start_pstn(phoneNumber, dtmf, actions, data):

Returns a connection object.

phoneNumber: (Mandatory) phoneNumber where symbl should call.
credentials : (Optional) Don't add this parameter if you have symbl.conf file in your home directory or working directory.
dtmf : (Optional) dtmf sequence to entered by symbl to join the call.
actions : (Optional) follows the following pattern.

[{invokeOn: "stop", name: "sendSummaryEmail", parameters: {emails: ["[email protected]"]}}]

data: (Optional) {session: {name: "sessionName"}}
languages : (Optional) To provide the Language list explicitly.
timezone : (Optional) To provide timezone explicitly.

For more details check documentation here.

start_sip(uri, audioConfig, actions, data):

Returns a connection object.

uri: (Mandatory) URI where symbl should connect.
audioConfig: (Optional) audioConfigs of the SIP.
credentials : (Optional) Don't add this parameter if you have symbl.conf file in your home directory or working directory.
actions : (Optional) follows the following pattern.


[{invokeOn: "stop", name: "sendSummaryEmail", parameters: {emails: ["[email protected]"]}}]
data: (Optional) {session: {name: "sessionName"}}

For more details check documentation here.

languages : (Optional) To provide the Language list explicitly.
timezone : (Optional) To provide timezone explicitly.

stop(connectionId):

Only connectionId parameter is Mandatory. Other optional parameters can be added as defined in the Telephony API reference.

Return an updated connection object which will have the conversationId in the response.

Streaming Class

Symbl's Streaming API is based on WebSocket protocol and can be used for real-time use-cases where both the audio and its results from Symbl's back-end need to be available in real-time.

start_connection(credentials=None, speaker=None, insight_types=None):

Returns a connection object.

Parameter	Required	Description
`credentials`	Optional	Don't add this parameter if you have `symbl.conf` file in your home directory or working directory.
`speaker`	Optional	Speaker object containing `name` and `email` field.
`insight_type`	Optional	The insights to be returned in the WebSocket connection.
`config`	Optional	Use this parameter to pass `confidenceThreshold`, `languageCode` For more details, see the Config parameter documentation here.
`languages`	Optional	To provide the Language list explicitly.
`timezone`	(Optional)	To provide timezone explicitly.

You can subscribe to the following events for Streaming API by the connection object.

insight_response:- generates an event whenever a question or an action_item is found.
message_response:- generates an event whenever a transcription is available.
tracker_response:- It will generate an event whenever a tracker is identified in any transcription.
topic_response:- It will generate an event whenever a topic is identified in any transcription.
message:- (Part of streaming API only), It will generate an event for live transcriptions. It will include isFinal property which will be False initially, meaning the transcription is not finalized.

Example of subscribing to events:

events = {
   'message_response': lambda response: print('Final Messages -> ', [message['payload']['content'] for message in response['messages']])}

insight_types = ['question', 'action_item']

connection_object = symbl.Streaming.start_connection(
   insight_types=insight_types)

connection_object.subscribe(events)

connection_object.send_audio_from_mic()

connection object

The connection object is returned by telephony API's start_pstn & start_sip or Streaming API' start_connection function. A connection object can be utilized for communicating with Symbl Server through underlying websocket implementation.

connection_object.subscribe({'event': callback, ...}):

Subscribe function can be used with both Telephony as well as Streaming class.
Takes a dictionary parameter, where the key can be an event and it's value can be a callback function that should be executed on the occurrence of that event.

The list of events that can be subscribed by connection object are:-

insight_response :- generates an event whenever a question or an action_item is found.
message_response:- generates an event whenever a transcription is available.
tracker_response:- It will generate an event whenever a tracker is identified in any transcription.
topic_response:- It will generate an event whenever a topic is identified in any transcription.
message:- It will generate an event for live transcriptions. It will include isFinal property which will be False initially, meaning the transcription is not finalized.

Example:

events = {'message_response': lambda message: print('printing the transcription', str(message)),
'insight_response': lambda insight: print('printing the insight response ', str(insight))}

connection_object.stop():
Stops the Streaming connection.
connection.send_audio_from_mic(device=None):
send_audio_from_mic function can be used with Streaming class only. It uses the sounddevice library to take input from the speaker's microphone and sends data directly to the websockets. Recommended function for first time users. Device parameter can take the deviceId (integer) as input, for more information see API Documentation - python-sounddevice > sounddevice.query_devices().

If this function is not running correctly, make sure the sounddevice library is installed correctly and has access to your microphone. For details, see Installation python-sounddevice.
connection_object.send_audio(data):
send_audio function can be used with Streaming class only.

Can be used when user is willing to send custom audio data from some other library.

send_audio function sends audio data to websockets in binary format.
Conversation Object:
Connection object has a conversation parameter, through which you can directly query the Conversations API with the provided conversationId.

import symbl

connection_object = symbl.Streaming.start_connection()

...

connection_object.conversation.get_topics()