Transcribe a File
Transcription:BatchDeployments:AllThe quickest way to try transcribing for free is by creating a Speechmatics account and using our Batch Demo in your browser.
This page will show you how to use the Speechmatics REST API to transcribe an audio or video file saved on your local machine. If you want to transcribe a file that is hosted on the Web, you can use our Fetch URL feature.
Finally, you can also learn about On-Prem deployments by following our guides.
Set Up
- Create an account on the Speechmatics Portal here.
- Navigate to Manage > API Keys page in the Speechmatics On-Demand Portal.
- Enter a name for your API key and store your API key somewhere safe.
Enterprise customers should speak to Support to get your API keys.
Batch Transcription Examples
The examples below will help you get started by using the official Speechmatics CLI, Python and JavaScript libraries. You can of course integrate using the programming language of your choice by referring to the Jobs API Reference.
- CLI
- Python
- Javascript
- cURL
The Speechmatics Python library and CLI can found on GitHub and installed using pip:
pip3 install speechmatics-python
speechmatics config set --auth-token $API_KEY
speechmatics batch transcribe example.wav
The Speechmatics Python library and CLI can found on GitHub and installed using pip:
pip3 install speechmatics-python
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"
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}
21
22# Open the client using a context manager
23with BatchClient(settings) as client:
24 try:
25 job_id = client.submit_job(
26 audio=PATH_TO_FILE,
27 transcription_config=conf,
28 )
29 print(f'job {job_id} submitted successfully, waiting for transcript')
30
31 # Note that in production, you should set up notifications instead of polling.
32 # Notifications are described here: https://docs.speechmatics.com/features-other/notifications
33 transcript = client.wait_for_completion(job_id, transcription_format='txt')
34 # To see the full output, try setting transcription_format='json-v2'.
35 print(transcript)
36 except HTTPStatusError as e:
37 if e.response.status_code == 401:
38 print('Invalid API key - Check your API_KEY at the top of the code!')
39 elif e.response.status_code == 400:
40 print(e.response.json()['detail'])
41 else:
42 raise e
43The Speechmatics JavaScript SDK can be found on GitHub.
The package for interacting with the Batch API can be installed via NPM:
npm install @speechmatics/batch-client
This library can be used in the browser and backend runtimes like NodeJS and Bun! Check out our examples on Github.
Below is a basic NodeJS example transcribing a file.
1// This example transcribes a file in NodeJS.
2// For examples in other environments, see the link above
3
4import { BatchClient } from '@speechmatics/batch-client';
5import { openAsBlob } from 'node:fs';
6
7const client = new BatchClient({ apiKey: YOUR_API_KEY, appId: 'nodeJS-example' });
8
9console.log('Sending file for transcription...');
10
11async function transcribeFile() {
12 const blob = await openAsBlob('./example.wav');
13 const file = new File([blob], 'example.wav');
14
15 const response = await client.transcribe(
16 file,
17 {
18 transcription_config: {
19 language: 'en',
20 },
21 },
22 'json-v2',
23 );
24
25 console.log('Transcription finished!');
26
27 console.log(
28 // Transcripts can be strings when the 'txt' format is chosen
29 typeof response === 'string'
30 ? response
31 : response.results.map((r) => r.alternatives?.[0].content).join(' '),
32 );
33}
34
35transcribeFile();
36API_KEY="YOUR_API_KEY"
PATH_TO_FILE="example.wav"
curl -L -X POST "https://asr.api.speechmatics.com/v2/jobs/" \
-H "Authorization: Bearer ${API_KEY}" \
-F data_file=@${PATH_TO_FILE} \
-F config='{"type": "transcription","transcription_config": { "operating_point":"enhanced", "language": "en" }}'
Jobs will typically take less than half the audio length to process. You will need to recheck periodically until the transcript is ready. It is also possible to get the status of up to 100 jobs at once. For more information, see the Check Job Status page. To set up a callback when the transcript is ready, see the page on Notifications.
JOB_ID="JOB_ID_FROM_PREVIOUS_STEP"
curl -L -X GET "https://asr.api.speechmatics.com/v2/jobs/${JOB_ID}/transcript?format=txt" \
-H "Authorization: Bearer ${API_KEY}"
Note that Windows users will need to update the examples above due to differences in formatting strings and variables when compared to Mac/Unix.
Transcript Outputs
As well as the content itself, the transcript will include information about the job and metadata such as the transcription config that was used.
Please refer to our API Reference for full details about the transcript contents.
{
"format": "2.8",
"job": {
"created_at": "2019-01-17T17:50:54.113Z",
"data_name": "example.wav",
"duration": 275,
"id": "yjbmf9kqub"
},
"metadata": {
"created_at": "2019-01-17T17:52:26.222Z",
"language_pack_info": {
"adapted": false,
"itn": true,
"language_description": "English",
"word_delimiter": " ",
"writing_direction": "left-to-right"
},
"transcription_config": {
"diarization": "none",
"language": "en"
},
"type": "transcription"
},
"results": [
{
"alternatives": [
{
"confidence": 0.9,
"content": "Just",
"language": "en",
"speaker": "UU"
}
],
"end_time": 1.07,
"start_time": 0.9,
"type": "word"
},
{
"alternatives": [
{
"confidence": 1,
"content": "this",
"language": "en",
"speaker": "UU"
}
],
"end_time": 1.44,
"start_time": 1.11,
"type": "word"
},
{
"alternatives": [
{
"confidence": 1,
"content": ".",
"language": "en",
"speaker": "UU"
}
],
"attaches_to": "previous",
"end_time": 273.64,
"start_time": 273.64,
"type": "punctuation"
}
]
}