Getting Started

The Subtitle Generator is an open web service that uses Open AI Whisper to generate subtitles for a video or audio file. A compressed audio file is created and split into smaller chunks with time code information preserved. This makes it possible to combine all subtitle segments into one subtitle file with correct timing information. It attempts to produce more professional-looking subtitles that are easier to read and follow industry standards for broadcast and streaming platforms. This tutorial walks you through how you quickly can get started with automatic subtitling in Eyevinn Open Source Cloud.

Based on OpenAI Speech to Text for transcription and translation (whisper-1 model). Visit the OpenAI documentation for a full list of supported languages.

Prerequisites

If you have not already done so, sign up for free for an Eyevinn OSC account.
An OpenAI account and API key.
AWS S3 CLI installed.

In this tutorial we will use 3 open web services in Eyevinn Open Source Cloud, in addition to this Subtitle Generator we will use:

This implies that you have at least 3 available services on your subscription plan. See pricing for more details.

Step 1: Create secrets

Navigate to the Subtitle Generator service in the Eyevinn Open Source Cloud web console. Click on the tab Service Secrets and create a service secret for the OpenAI API key.

Skärmavbild 2025-02-20 kl 23 57 09

Step 2: Create storage buckets

Create two storage buckets input and subs. Read this guide to learn how to create buckets with the open web service Minio in Open Source Cloud.

Download this example file and upload it to the input bucket:

% export AWS_ACCESS_KEY_ID=<minio-username>
% export AWS_SECRET_ACCESS_KEY=<minio-password>
% aws s3 --endpoint-url=<minio-endpoint-url> cp osc-reel.mp4 s3://input/

Verify that the file has been uploaded successfully

% aws s3 --endpoint-url=<minio-endpoint-url> ls s3://input/
2025-06-07 22:11:56  147287789 osc-reel.mp4

Step 3: Create a Subtitle Generator

Go to the tab "My generators" and click on the button "Create generator". Enter the following in the create instance dialog:

Skärmavbild 2025-06-07 kl 22 21 47

We have also stored the credentials for the MinIO bucket as secrets in this example.

Name: the name of your generator
Openaikey: the OpenAI API key, in this example: {{secrets.openaikey}}
AwsAccessKeyId: access key id for the S3 buckets, in this example: {{secrets.accesskeyid}}
AwsSecretAccessKey: secret access key for the S3 buckets, in this example: {{secrets.secretaccesskey}}
AwsRegion: for AWS S3 buckets provide in which region the buckets are. For MinIO instances in Open Source Cloud write osc
S3Endpoint: for non AWS S3 buckets provide the server endpoint (for example a MinIO instance)

Now press the button create.

Step 4: Generate subtitles

Click on the three dots on the instance card and open the menu. Click on the menu item "Open API Docs".

Skärmavbild 2025-02-21 kl 00 04 25

Now you are presented with the API documentation that you can use to try this out. Select the accordion /transcribe/s3 and as an example enter the following values.

Skärmavbild 2025-06-07 kl 22 19 47

{
  "url": "s3://input/osc-reel.mp4",
  "language": "en",
  "format": "srt",
  "bucket": "subs",
  "key": "osc-reel_en1"
}

This will create subtitles for the file osc-reel.mp4 available on the S3 bucket input. It will transcribe and translate to English (if spoken language is not English). The subtitles will be written to a file on a bucket called subs and in the SubRip format (SRT). The file will be called osc-reel_en1.srt.

Press the button "Execute" and wait a few minutes. When the job has finished the subtitle file will be placed in the S3 bucket that you specified.

% aws s3 --endpoint-url=<minio-endpoint-url> ls s3://subs/
[2025-02-20 23:26:54 CET]  17KiB STANDARD osc-reel_en1.srt

We can open the video file and the generated subtitle file in VLC to check the result.

Skärmavbild 2025-06-07 kl 23 01 36

Include subtitle in VOD package

We can now take this generated subtitle file and include it when we create a VOD package. For example using Shaka Packager in Open Source Cloud and the Open Source Cloud CLI. For Shaka Packager we need to have the subtitles in the VTT format. Let us run a subtitle generation job again but with vtt as subtitle format.

{
  "url": "s3://input/osc-reel.mp4",
  "language": "en",
  "format": "vtt",
  "bucket": "subs",
  "key": "osc-reel_en1"
}

We should now have a file in VTT format in addition to SubRip.

% aws s3 --endpoint-url=<minio-endpoint-url> ls s3://subs/
2025-06-07 22:59:15       1332 osc-reel_en1.srt
2025-06-07 23:13:15       1307 osc-reel_en1.vtt

Copy this VTT file to the input bucket.

% aws s3 --endpoint-url=<minio-endpoint-url> cp s3://subs/osc-reel_en1.vtt s3://input/

Now we can create a VOD package by creating a Shaka Packager job in Open Source Cloud. Before running the command below make sure you have created the secrets accesskeyid and secretkey for the Shaka Packager service. These are not the same as you created for the Subtitle Generator service.

% npx -y @osaas/cli create eyevinn-shaka-packager-s3 subs \
  -o cmdLineArgs="-s s3://input -d s3://subs/vod/ -i a:audio=osc-reel.mp4 -i v:2069=osc-reel.mp4 -i t:en=osc-reel_en1.vtt" \
  -o awsAccessKeyId="{{secrets.accesskeyid}}" \
  -o awsSecretAccessKey="{{secrets.secretkey}}" \
  -o s3EndpointUrl=<minio-endpoint-url>

Skärmavbild 2025-06-07 kl 23 26 21

Provide callback endpoint for status reporting

In the subtitle job request you can provide an URL to a callback endpoint. This endpoint will receive an HTTP POST when subtitle process has started and completed. This way your application can get a notification when the submitted job has finished. Extend the JSON payload with this.

{
  "url": "s3://input/osc-reel.mp4",
  "callbackUrl": "<your-callback-listener-endpoint-url>",
  "language": "en",
  "format": "vtt",
  "bucket": "subs",
  "key": "osc-reel_en1"
}

Support

Join our Slack workspace for real-time support and to connect with other users.