Sentiment Analysis
Transcription:BatchDeployments:ContainerSaaSSentiment Analysis will be offered at no additional cost until 30th September 2023.
Speechmatics enables you to understand the sentiment of what was spoken in your audio. With just a single API call, you can quickly transcribe and extract the sentiment, either positive, negative or neutral to quickly detect areas of conversation to analyse further.
If you're new to Speechmatics, please see our guide on Transcribing a File. Once you are set up, include the following config to enable Sentiment Analysis:
{
"type": "transcription",
"transcription_config": {
"language": "en"
},
"sentiment_analysis_config": {}
}
Quick start
Python client example to return sentiment for a batch file.
1from speechmatics.models import ConnectionSettings
2from speechmatics.batch_client import BatchClient
3from httpx import HTTPStatusError
4
5API_KEY = "YOUR_API_KEY"
6PATH_TO_FILE = "example.wav"
7LANGUAGE = "en" # Transcription language
8
9settings = ConnectionSettings(
10 url="https://asr.api.speechmatics.com/v2",
11 auth_token=API_KEY,
12)
13
14# Define transcription parameters
15conf = {
16 "type": "transcription",
17 "transcription_config": {
18 "language": LANGUAGE
19 },
20 "sentiment_analysis_config": {}
21}
22
23# Open the client using a context manager
24with BatchClient(settings) as client:
25 try:
26 job_id = client.submit_job(
27 audio=PATH_TO_FILE,
28 transcription_config=conf,
29 )
30 print(f'job {job_id} submitted successfully, waiting for transcript')
31
32 # Note that in production, you should set up notifications instead of polling.
33 # Notifications are described here: https://docs.speechmatics.com/features-other/notifications
34 transcript = client.wait_for_completion(job_id, transcription_format='json-v2')
35 sentiment = transcript["sentiment_analysis"]
36 sentiment_summary = sentiment["summary"]
37 sentiment_segments = sentiment["segments"]
38
39 print(sentiment_summary["overall"])
40
41 for segment in sentiment_segments:
42 print(f' {segment["text"]} ({segment["sentiment"]})') # print the sentiment for each segment
43
44 except HTTPStatusError as e:
45 if e.response.status_code == 401:
46 print('Invalid API key - Check your API_KEY at the top of the code!')
47 elif e.response.status_code == 400:
48 print(e.response.json()['detail'])
49 else:
50 raise e
51
Understanding the Response
Sentiment Analysis results are only available in the JSON output format.
Segments of the transcript are labeled with either positive, negative or neutral and a confidence score. This score indicates the model's certainty regarding the assigned sentiment prediction.
Please refer to our API reference for full details about the sentiment API content.
{
"job": { ... },
"metadata": {
"created_at": "2023-07-17T15:01:48.412714Z",
"type": "transcription",
"transcription_config": {
"language": "en",
"diarization": "speaker"
},
"sentiment_analysis_config": {}
...
},
"results": [...],
"sentiment_analysis": {
"segments": [
{
"confidence": 0.88,
"end_time": 7.94,
"sentiment": "positive",
"speaker": "S1",
"start_time": 3.0,
"text": "We're delighted that you've decided to try our speech to text software to get going."
},
{
"confidence": 0.76,
"end_time": 12.18,
"sentiment": "neutral",
"speaker": "S1",
"start_time": 7.95,
"text": "Just create an API key and submit a transcription request to our API."
}
],
"summary": {
"overall": {
"negative_count": 0,
"neutral_count": 1,
"positive_count": 1
},
"speakers": [
{
"speaker": "S1",
"negative_count": 0,
"neutral_count": 1,
"positive_count": 1
}
]
}
}
}
sentiment_analysis.segments
provides a list of transcript segments, each with the following keys:- text: this represents the transcript of the analysed segment.
- sentiment: the assigned sentiment to the segment, which can be
positive
,neutral
ornegative
. - start/end time: the timestamps corresponding to the beginning and end of the transcription segment.
- confidence: a confidence score in the range of 0-1, indicating the model's certainty in the predicted sentiment.
- speaker/channel: the label of the speaker or channel that correspond to the spoken segment.
sentiment_analysis.summary
- contains summaries of the sentiment across the complete file. Each summary provides a breakdown of the total segments, categorized as positive, neutral, or negative.sentiment_analysis.summary.overall
- A summary for all segments in the file.sentiment_analysis.summary.speakers
(optional) - If speaker diarization is set tospeaker
, provides a summary of the sentiment by speaker.sentiment_analysis.summary.channels
(optional) - If speaker diarization is set tochannel
, provides a summary of the sentiment by channel.
Considerations
- Sentiment Analysis is only supported for English.
- Typically, segments equate to full sentences. However, in cases of short utterances composed of 1-2 words, these can be combined with a neighboring sentence to form a segment.
- Punctuation plays a significant role in the accuracy of the Sentiment Analysis. It is therefore recommended to avoid disabling any end of sentence Punctuation Marks or reducing the Punctuation Sensitivity to ensure the best possible results.
- Speaker or channel labels will only be available if diarization is enabled. By default when Diarization is not enabled "speaker":"UU" is returned to indicate that speakers of each segment are unknown.
- Speaker Change is not supported in combination with Sentiment Analysis.
Error Responses
Unsupported Language
Currently Sentiment Analysis is only supported for English.
If Sentiment Analysis is requested for an unsupported language, the transcription process will complete. However, the Sentiment Analysis will not be performed, and an error message will be included in the final JSON output.
{
"job": { ... },
"metadata": {
"created_at": "2023-05-26T15:01:48.412714Z",
"type": "transcription",
"transcription_config": {
"language": "cy"
},
"sentiment_analysis_config": {},
"sentiment_analysis_errors": [
{"type": "unsupported_language", "message": "Sentiment analysis not supported for cy."}
],
...
},
"results": [...]
}
Sentiment Analysis Failed
If Sentiment Analysis fails, the transcription process will complete but the Sentiment Analysis will not be returned, and an error message will be included in the final JSON output.
{
"job": { ... },
"metadata": {
"created_at": "2023-05-26T15:01:48.412714Z",
"type": "transcription",
"transcription_config": {
"language": "en"
},
"sentiment_analysis_config": {},
"sentiment_analysis_errors": [
{"type": "sentiment_analysis_failed", "message": "Sentiment Analysis failed."}
],
...
},
"results": [...]
}