.jpg)
Getting started with a new technology can be daunting, but we’re going to break down speech-to-text transcription with node.js to make it easier!
In this post, we will make a basic node.js command-line interface app (often abbreviated to CLI app).
We will first pass a URL of an audio recording as an argument to an upload function. This second function will send an HTTP request to the AssemblyAI speech-to-text transcription API.
Then, we’ll print the response from AssemblyAI on the command-line as well as the ID of our transcription. Next, we’ll pass the transcription ID as an argument to a second function that will go and fetch our transcription and print it to the screen!

Prerequisites
- A free AssemblyAI account
- A code editor such as VS Code
- Node.js and npm
If you would like to see the completed code project, it is available at this GitHub repository.
Getting your development environment setup
Create a new directory on your computer using your favourite command-line program, such as Terminal or Powershell. I’ve called my directory `transcribe`. Navigate into it and initialise a new Node.js project:
Create three new files inside your new `transcribe` directory:
If using Windows:
And if using macOS or Linux:
If you don’t already have it installed, we will need the node package `dotenv` to manage our AssemblyAI API key. You can install it with the following command:
We will also use the Fetch API to make our REST call, so make sure to install that too:
Open the `.env` file in your code editor and add an environment variable to store your AssemblyAI API Key. You can find your API key in the AssemblyAI dashboard and add it as the value to the above variable.
Uploading an audio file to the AssemblyAI Transcription API
Open the “upload.js” that we created earlier in your code editor. Copy and paste the following code into this file:
The above code will import the two packages that we added earlier, `dotenv` and `fetch`. We also define the AssemblyAI API endpoint as `url`.
We will need to pass the hosted audio file URL as a command-line argument when we run the application. The following code to take that CLI argument and assign it to a variable called `audioUrl`.
If you would like to upload a file from your computer instead, this blog will take take you through the steps.
AssemblyAI is expecting an HTTP POST request with a JSON body. The JSON will contain the audio URL we passed as an argument. So let’s define that next.
Now it’s time to think about our HTTP request.
We are using `fetch` via the package `node-fetch`. This module brings the `window.fetch` from a browser to our Node application.
`fetch` needs some parameters, including our AssemblyAI API key, JSON body, and Headers. We will make a JavaScript object called `params` to contain these parameters.
The last step of our `upload` function is to make the HTTP request and print the response to the command-line.
`fetch` supports promises, so we will make the request and use the `then` keyword to extract the returned data from the response, displaying both the full JSON response and the transcription ID to the command-line. We will use the `catch` keyword to display an error in the case that something went wrong.
The entire upload.js file should look like this:
Let’s try it out!
From the command-line, type the following (remember you need to be in the same directory as your code files). You can use the URL provided below or one of your choosing, just make sure you can play it in a browser first.
If all went well, you should see the entire returned JSON object from AssemblyAI printed to the screen. This will also include the transcription ID printed in isolation at the end.
Download a transcription from AssemblyAI
In this application, we will make a request to the AssemblyAI endpoint to check if our transcript is completed.
AssemblyAI also supports webhooks, which means AssemblyAI will make a POST request to your application once the transcription is finished.
Open up the “download.js” file that we created earlier in your code editor.
Just as in “upload.js”, we will need to import both `dotenv` and `fetch`, along with arguments from the command-line.
Note that this time we are getting the ID as an argument from the command-line and then using string literals to add the ID to the AssemblyAI endpoint for retrieving transcriptions.
We will need to set the parameters for `fetch` again only this time we are doing a `GET` request so there will not be any body data.
This is now where the code will differ slightly from the upload code.
Transcription may take a few moments, so when we get a response back from AssemblyAI, we will need to check if the audio file has been processed yet.
We can determine this by checking the `status` of the response. If AssemblyAI says the transcription is still `queued` or `processing` then we will need to try again a little later. If the status is `completed` the transcription text will be included in the response.
Let’s write a function that handles this for us.
We are using a simple switch statement here to test if the status is `queued`, `processing` or `completed`. If the status is something else, we will assume that something went wrong.
Finally, we can make our API call using `fetch`.
The entire “download.js” file should be as follows:
Time to test it out!
From the command-line and using the transcription ID returned from the upload function in the command-line, write the following code and press enter
If your transcription’s status was `completed`, the text should be printed on the command-line. 🎉
What next?
You have successfully written a command-line application to upload an audio file URL to AssemblyAI and then download the completed transcription and print it on screen.
Challenge: Can you write a loop that will check the processing status and if it’s `queued` automatically poll the API at regular intervals until the status is `completed`?
Let me know how you get on or if you have any questions about the topics covered in this blog post or AssemblyAI in general. I would love to hear from you!
- Email: layla@assemblyai.com
- Twitter: @LaylaCodesIt
- GitHub: layla-p
- Twitch: LaylaCodesIt