{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Get Started with Speech Recognition in Python","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"get-started-with-speech-recognition-in-python","__idx":0},"children":["Get Started with Speech Recognition in Python"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["By Vikram Vaswani, Developer Advocate - September 27, 2022"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"introduction","__idx":1},"children":["Introduction"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Rev AI's speech-to-text APIs power automatic speech recognition in thousands of applications and services. To make it easier for developers to integrate these APIs into their applications, Rev AI also offers ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/sdk"},"children":["SDKs for many programing languages"]},"...including the topic of this tutorial, Python."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this tutorial, I'll introduce you to the basics of using Rev AI's ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api/asynchronous"},"children":["Asynchronous Speech-to-Text API"]}," using Python and the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/sdk/python"},"children":["Rev AI Python SDK"]},". If you've ever wondered how to integrate speech recognition capabilities with your Python application, this tutorial will give you all the information you need to get started."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"assumptions","__idx":2},"children":["Assumptions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This tutorial assumes that:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You have a Rev AI account and access token. If not, ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://www.rev.ai/auth/signup"},"children":["sign up for a free account"]}," and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/get-started#step-1-get-your-access-token"},"children":["generate an access token"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You have a properly-configured Python development environment with Python 3.x. If not, ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://www.python.org/downloads/"},"children":["download and install Python"]}," for your operating system."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You have installed pip, the Python dependency manager. If not, ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://pip.pypa.io/en/stable/installation/"},"children":["download and install pip"]}," for your operating system."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You have an audio file to transcribe. If not, use this ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://www.rev.ai/FTC_Sample_1.mp3"},"children":["example audio file from Rev AI"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1-install-the-sdk","__idx":3},"children":["Step 1: Install the SDK"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This tutorial will use the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/sdk/python"},"children":["Rev AI Python SDK"]}," to submit transcription requests to the Rev AI ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api/asynchronous"},"children":["Asynchronous Speech-to-Text API"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Begin by installing the SDK with pip:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"pip install --upgrade rev_ai\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Within your application code, initialize the Rev AI API client as below. Replace the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<REVAI_ACCESS_TOKEN>"]}," placeholder with your Rev AI access token:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"from rev_ai import apiclient\n\n# configure access token\ntoken = \"<REVAI_ACCESS_TOKEN>\"\n\n# initialize Rev AI API client\nclient = apiclient.RevAiAPIClient(token)\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Here, the Rev AI API client is automatically initialized with the base endpoint for the Asynchronous Speech-to-Text API, which is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://api.rev.ai/speechtotext/v1/"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every request to the API must be in JSON format and must include an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization"]}," header containing the API access token. The Rev AI Python SDK automatically takes care of attaching this required header to all its client requests."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2-submit-a-file-for-transcription","__idx":4},"children":["Step 2: Submit a file for transcription"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To generate a transcript from an audio file, you must submit an HTTP POST request to the API endpoint at ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://api.rev.ai/speechtotext/v1/jobs"]},". The Rev AI Python SDK simplifies this process with two methods: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["submit_job_local_file()"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["submit_job_url()"]},", for local and remote files respectively."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following example demonstrates how to submit a local audio file for transcription."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To use this example, replace the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<FILEPATH>"]}," placeholder with the path to the file you wish to transcribe and the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<REVAI_ACCESS_TOKEN>"]}," placeholder with your Rev AI account's access token."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"from rev_ai import apiclient\n\n# configure access token and audio source\ntoken = \"<REVAI_ACCESS_TOKEN>\"\nfilepath = \"<FILEPATH>\"\n\n# initialize Rev AI API client\nclient = apiclient.RevAiAPIClient(token)\n\n# submit a file for transcription\njob = client.submit_job_local_file(filepath)\n\n# get job id\njob_id = job.id\nprint(\"Job submitted with id: \" + job_id)\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To run this example, save it as a file, such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["example.py"]}," and then execute ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["python example.py"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this example, the API client internally makes a POST request to the API, passing it the audio file to be transcribed. The response body is then received and converted into a Python object."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Here is an example of the API response, represented as a Python object:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"{'callback_url': (None,),\n 'completed_on': None,\n 'created_on': '2022-09-14T14:43:35.46Z',\n 'custom_vocabulary_id': None,\n 'delete_after_seconds': None,\n 'duration_seconds': None,\n 'failure': None,\n 'failure_detail': None,\n 'filter_profanity': None,\n 'id': 'xsDRpD6ladtf',\n 'language': 'en',\n 'media_url': None,\n 'metadata': None,\n 'name': 'myfile.mp3',\n 'remove_disfluencies': None,\n 'rush': None,\n 'segments_to_transcribe': None,\n 'skip_diarization': None,\n 'skip_punctuation': None,\n 'speaker_channels_count': None,\n 'status': <JobStatus.IN_PROGRESS: 1>,\n 'transcriber': None,\n 'verbatim': None}\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The API response contains a job identifier (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," field). This job identifier will be required to check the job status and obtain the job result."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["It is also possible to use a remote audio file, as shown in the following example:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"from rev_ai import apiclient\n\n# configure access token and audio source\ntoken = \"<REVAI_ACCESS_TOKEN>\"\nurl = \"<URL>\"\n\n# initialize Rev AI API client\nclient = apiclient.RevAiAPIClient(token)\n\n# submit a file for transcription\njob = client.submit_job_url(url)\n\n# get job id\njob_id = job.id\nprint(\"Job submitted with id: \" + job_id)\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api/asynchronous"},"children":["Learn more about submitting an asynchronous transcription job in the API reference guide"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-3-check-transcription-status","__idx":5},"children":["Step 3: Check transcription status"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To check the status of the transcription job, you must submit an HTTP GET request to the API endpoint at ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://api.rev.ai/speechtotext/v1/jobs/<ID>"]},", where ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<ID>"]}," is a placeholder for the job identifier. Again, the Rev AI Python SDK makes this easy with its ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["get_job_details()"]}," method, which accepts a job identifier as input and returns the current status of the job as a Python object."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following example demonstrates how to check the status of an asynchronous transcription job."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To use this example, replace the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<ID>"]}," placeholder with the job identifier and the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<REVAI_ACCESS_TOKEN>"]}," placeholder with your Rev AI account's access token."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"from rev_ai import apiclient\n\n# configure access token and job identifier\ntoken = \"<REVAI_ACCESS_TOKEN>\"\njob_id = \"<ID>\"\n\n# initialize Rev AI API client\nclient = apiclient.RevAiAPIClient(token)\n\n# check job status\nstatus = client.get_job_details(job_id)\n\n# print response object\nprint(vars(status))\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Here is an example of the response object received after the job has completed:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"{'callback_url': (None,),\n 'completed_on': '2022-09-14T14:44:09.774Z',\n 'created_on': '2022-09-14T14:43:35.46Z',\n 'custom_vocabulary_id': None,\n 'delete_after_seconds': None,\n 'duration_seconds': 107.0,\n 'failure': None,\n 'failure_detail': None,\n 'filter_profanity': None,\n 'id': 'xsDRpD6ladtf',\n 'language': 'en',\n 'media_url': None,\n 'metadata': None,\n 'name': 'myfile.mp3',\n 'remove_disfluencies': None,\n 'rush': None,\n 'segments_to_transcribe': None,\n 'skip_diarization': None,\n 'skip_punctuation': None,\n 'speaker_channels_count': None,\n 'status': <JobStatus.TRANSCRIBED: 2>,\n 'transcriber': None,\n 'verbatim': None}\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api/asynchronous"},"children":["Learn more about retrieving the status of an asynchronous transcription job in the API reference guide"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-4-retrieve-the-transcript","__idx":6},"children":["Step 4: Retrieve the transcript"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once the job's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," changes to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRANSCRIBED"]},", you can retrieve the results by submitting an HTTP GET request to the API endpoint at ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://api.rev.ai/speechtotext/v1/jobs/<ID>/result"]},", where ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<ID>"]}," is a placeholder for the job identifier. The Rev AI Python SDK offers three methods for this: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["get_transcript_text()"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["get_transcript_json()"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["get_transcript_object()"]},", which return the transcript as plaintext, JSON and a Python object respectively."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following example demonstrates how to retrieve the results of an asynchronous transcription job."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To use this example, replace the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<ID>"]}," placeholder with the job identifier and the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<REVAI_ACCESS_TOKEN>"]}," placeholder with your Rev AI account's access token."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"from rev_ai import apiclient\n\n# configure access token and job identifier\ntoken = \"<REVAI_ACCESS_TOKEN>\"\njob_id = \"<ID>\"\n\n# initialize Rev AI API client\nclient = apiclient.RevAiAPIClient(token)\n\n# get transcript\ntranscript = client.get_transcript_json(job_id)\n\n# print transcript\nprint(transcript)\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Here is an example of the transcript returned from a successful job, represented as JSON:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"{\n  \"monologues\": [\n    {\n      \"speaker\": 0,\n      \"elements\": [\n        {\n          \"type\": \"text\",\n          \"value\": \"Hi\",\n          \"ts\": 0.17,\n          \"end_ts\": 0.52,\n          \"confidence\": 1\n        },\n        {\n          \"type\": \"punct\",\n          \"value\": \",\"\n        },\n        {\n          \"type\": \"punct\",\n          \"value\": \" \"\n        },\n        {\n          \"type\": \"text\",\n          \"value\": \"my\",\n          \"ts\": 0.52,\n          \"end_ts\": 0.76,\n          \"confidence\": 1\n        },\n        ...\n      ]\n    },\n    ...\n  ]\n}\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api/asynchronous"},"children":["Learn more about obtaining a transcript in the API reference guide"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-5-create-and-test-a-simple-application","__idx":7},"children":["Step 5: Create and test a simple application"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Using the code samples shown previously, it's possible to create a simple application that accepts an audio file URL and returns a transcript, as shown below:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"from rev_ai import apiclient\nfrom time import sleep\n\ndef main(token, url):\n  # initialize Rev AI API client\n  client = apiclient.RevAiAPIClient(token)\n\n  # submit a file for transcription\n  job = client.submit_job_url(url)\n\n  # get job id\n  job_id = job.id\n  print(\"Job submitted with id: \" + job_id)\n\n  # check job status\n  while (job.status.name == 'IN_PROGRESS'):\n    details = client.get_job_details(job_id)\n    print(\"Job status: \" + details.status.name)\n    # if successful, print result\n    if (details.status.name == 'TRANSCRIBED'):\n      print(client.get_transcript_json(job_id))\n      break\n    # if unsuccessful, print error\n    if (details.status.name == 'FAILED'):\n      print(\"Job failed: \" + details.failure_detail)\n      break\n    sleep(30)\n\ntoken = \"<REVAI_ACCESS_TOKEN>\"\nurl = \"<URL>\"\nmain(token, url)\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This example application begins by initializing an instance of the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RevAiAPIClient"]}," object, passing the Rev AI access token to the object constructor. It then submits a remote file for transcription using the object's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["submit_job_url()"]}," method. It then uses the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["get_job_details()"]}," method to repeatedly poll the API every 30 seconds to obtain the status of the job. Once the job status is no longer ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IN_PROGRESS"]},", it uses the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["get_transcript_json()"]}," method to retrieve the transcript and prints it to the console."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Here is an example of the output generated by the example application:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"Job submitted with id: XyHxoqX5cH5A\nJob status: IN_PROGRESS\nJob status: IN_PROGRESS\nJob status: TRANSCRIBED\n{'monologues': [{'speaker': 0, 'elements': [{'type': 'text', 'value': 'Hi', 'ts': 0.17, 'end_ts': 0.52, 'confidence': 1.0}, {'type': 'punct', 'value': ','}, ...]}, ..., ]}\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The example above polls the API repeatedly to check the status of the transcription job. This is presented only for illustrative purposes and is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["strongly recommended against"]}," in production scenarios. For production scenarios, use ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api/asynchronous/webhooks"},"children":["webhooks"]}," to asynchronously receive notifications once the job completes."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":8},"children":["Next steps"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Learn more about the topics discussed in this tutorial by visiting the following links:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Documentation: ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api/asynchronous"},"children":["Asynchronous Speech-To-Text API job submission"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Documentation: ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/sdk/python"},"children":["Python SDK"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Documentation: ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api/asynchronous/best-practices"},"children":["Asynchronous Speech-To-Text API best practices"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Code samples: ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api/asynchronous/code-samples"},"children":["Asynchronous Speech-To-Text API"]}," and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/sdk/python/code-samples"},"children":["Python SDK"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Tutorial: ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/resources/tutorials/get-started-api-webhooks"},"children":["Get Started with Rev AI API Webhooks"]}]}]}]},"headings":[{"value":"Get Started with Speech Recognition in Python","id":"get-started-with-speech-recognition-in-python","depth":1},{"value":"Introduction","id":"introduction","depth":2},{"value":"Assumptions","id":"assumptions","depth":2},{"value":"Step 1: Install the SDK","id":"step-1-install-the-sdk","depth":2},{"value":"Step 2: Submit a file for transcription","id":"step-2-submit-a-file-for-transcription","depth":2},{"value":"Step 3: Check transcription status","id":"step-3-check-transcription-status","depth":2},{"value":"Step 4: Retrieve the transcript","id":"step-4-retrieve-the-transcript","depth":2},{"value":"Step 5: Create and test a simple application","id":"step-5-create-and-test-a-simple-application","depth":2},{"value":"Next steps","id":"next-steps","depth":2}],"frontmatter":{"title":"Get Started with Speech Recognition in Python","date":"2022-09-27T00:00:00.000Z","byline":"Vikram Vaswani, Developer Advocate","disableLastModified":false,"toc":{"enable":true},"seo":{"title":"Get Started with Speech Recognition in Python"}},"lastModified":"2026-02-24T14:47:49.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/resources/tutorials/get-started-python","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}