Transcribe a File

Transcription:BatchDeployments: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 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

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

Python

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
43

NodeJS

The Speechmatics JavaScript library can be found on GitHub and installed using NPM:

npm install speechmatics

1const fs = require('fs');
2const { Speechmatics } = require('speechmatics');
3
4const API_KEY = "YOUR_API_KEY";
5const PATH_TO_FILE = "example.wav";
6
7const sm = new Speechmatics(API_KEY);
8const inputFile = new Blob([
9  fs.readFileSync(PATH_TO_FILE),
10]);
11
12sm.batch
13  .transcribe({ input: inputFile, transcription_config: { language: 'en' }, format: 'text' })
14  .then((transcriptText) => {
15    console.log(transcriptText);
16  })
17  .catch((error) => {
18    console.log(error);
19    process.exit(1);
20  });
21

cURL

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

info

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