How to Generate Subtitles with Voice-API and Bash Script

voice-api team

Mar 2025

How to Automatically Generate Subtitles Using Voice-API with a Bash Script

Subtitles are essential for making videos more accessible, whether you're a content creator, filmmaker, or someone who enjoys watching videos with captions.This guide will walk you through how to automatically generate subtitles using Voice-API with a simple Bash script. We’ll cover everything from installation to running the script, ensuring that even users without prior IT knowledge can follow along.

About Voice-API and the Subtitle Script

Voice-API provides a powerful API for converting audio into text with high accuracy. To make our clients' lives easier, we also offer a free-of-charge Bash script that simplifies subtitle creation. This script automates the entire process, including:

Extracting audio from a video file
Uploading the audio to Voice-API for transcription
Downloading the subtitles in an SRT file format

This means you don’t have to manually handle file conversions or API interactions—the script does it all for you!

Prerequisites

Before using the script, ensure that you have the necessary tools installed on your system. This guide is suitable for both Linux and macOS users.

Required Dependencies

The script requires the following programs:

ffmpeg – Extracts the audio from video files.
jq – Handles JSON parsing.
curl – Communicates with the Voice-API server.
bc – Performs calculations for quota management.

To check if these tools are installed, run the following command in your terminal:

which ffmpeg jq curl bc

If any of them are missing, install them as follows:

Installing Dependencies on macOS

brew install ffmpeg jq curl bc

Installing Dependencies on Ubuntu/Debian

sudo apt update && sudo apt install ffmpeg jq curl bc -y

Installing Dependencies on Arch Linux

sudo pacman -S ffmpeg jq curl bc

Once all dependencies are installed, you’re ready to use the script!

Step 1: Generate your API key

The script requires an API key for Voice-API authentication. You can get your API Key by signing up at: Voice-API Dashboard

Find or generate api key

If you do not have an active subscription please take a look at available options

Step 2: Download the Subtitle Script

To download the script manually our website click on this link

Create a new script file and copy the provided Bash script into it. Open a terminal and run:

1
2
3

touch subtitle_generator.sh
chmod +x subtitle_generator.sh
nano subtitle_generator.sh

Paste the script inside the file and save it (CTRL + X, then Y, and press ENTER).

Or alternatively you can navigate to a folder where you would like to store the script and run following command that will download file and set execution rights automatically:

1
2

curl -o subtitle_generator.sh https://voice-api.app/tools/scripts/subtitle_generator.sh
chmod +x subtitle_generator.sh

Step 3: Replace api key in the script

Once you have the key and the script, replace the placeholder in the script:

API_KEY="your-actual-api-key"

This is how it looks like in the script:

Step 4: Running the Script

To generate subtitles for a video file, run:

./subtitle_generator.sh path/to/your/video.mp4

Replace path/to/your/video.mp4 with the actual location of your video file.

In this example video in the same folder with the script. The command will look like on the screenshot:

Run subtitles generator

Step 5: Understanding the Script’s Workflow

The script follows a structured process to to ensure that everything needed to create accurate subtitles is in place:

1. Checking Dependencies

Before proceeding, the script ensures that ffmpeg, jq, curl, and bc are installed. If any are missing, it will notify you.

You will see output similar to one on the screenshot:

Run subtitles generator

2. Extracting Audio from the Video

It identifies the available audio tracks in the video and asks you to select the correct one. After selection, it extracts and converts the audio into a format suitable for processing.

Extracting Audio

Please select audio track by typing track number and press Enter

Once audio track selected the script will extract it and inform you with following output

Audio extracted

3. Uploading Audio to Voice-API

The script securely uploads the extracted audio to Voice-API, using an API key for authentication.

Once audio uploaded you will see an output that contains jobId that we will use later to request results. Output also contains information about your subscription and remaining credits

Uploading Audio

4. Waiting for the Transcription to Complete

Since transcription takes some time, the script will check the status of the request periodically and display progress.

5. Downloading and Saving the Subtitle File

Once transcription is complete, the script downloads the subtitle file in SRT format, naming it based on the video file and detected language.

Step 6: Handling API Errors

If something goes wrong, the script will notify you of the exact error and suggest actions. Common issues include:

Invalid API Key: Ensure you copied the key correctly.
Quota Exceeded: If you run out of minutes, upgrade your plan.
Subscription Issues: If your subscription has expired, renew it.

Step 7: Viewing the Subtitle File

After successful processing, the subtitles will be saved as:

video-name.voice-api.app.language-code.srt

Actual name will be printed the script output:

Api key placeholder to replace

You can open and edit the .srt file in any text editor or import it into a video player for captioning.

Conclusion

This script automates the process of generating subtitles using Voice-API. By following this guide, even users with no prior technical knowledge can create high-quality subtitles effortlessly. The script handles audio extraction, uploading, and subtitle retrieval, so you don’t have to worry about technical steps.

If you need more transcription minutes, visit the Voice-API Website to explore subscription plans.

Now, go ahead and try it out! 🎬