Skip to main content

Transcribe a file

Transcription:Batch Deployments:All

The 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​

  1. Create an account on the Speechmatics Portal here.
  2. Navigate to the manage access page in the Speechmatics portal.
  3. Enter a name for your API key and store your API key somewhere safe.
info

Enterprise customers should speak to support at support@speechmatics.com to get your API keys.

Quick start​

To submit a job, just copy in your API key and file name.

API_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 page on job polling. 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}"

Batch transcription examples​

The examples below will help you get started by using the official Speechmatics Python library and CLI. The Speechmatics Python library can be 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:
37        print('Invalid API key - Check your API_KEY at the top of the code!')
38

Transcript result format​

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"
      }
   ]
}