Burn subtitles into a video using a captions API

Adding captions to videos helps make your videos stand out on social media platforms and reach a broader audience. You can use captions to add style and colour to your videos, making them more engaging. Captions also allow users scrolling through their feeds to get your message even when their volume is off.

In this guide, you will learn how to add captions to your videos using Shotstack. You will also learn how to add different style options to improve the look and feel of the captions in your videos.

About Shotstack

Shotstack is a cloud-based media automation platform that enables you to create thousands of videos in minutes. It provides APIs that make it easy to create workflows and integrate video editing capabilities into your applications. In this tutorial, you will learn how to burn captions using our video editing API.

Requirement

Here's what you will need to follow along with the steps in this guide:

• A Shotstack API key. Sign up and get one for free.
• Basic knowledge of the curl utility and running commands in a terminal.

How to burn subtitles into video

The following is the example video we will be using in this tutorial.

We've already generated an SRT transcript file from the video for the captions. If you do not yet have an SRT file, we've created a full guide that will walk you through generating SRT and VTT subtitles from a video.

When you have your video and SRT file ready, you can follow along with the steps below to add the captions to the video.

Create the captions JSON Edit

Let's start by creating a new captions.json file. Copy and save the JSON below to the file you created.

{
  "timeline": {
      "tracks": [
          {
              "clips": [
                  {
                      "asset": {
                          "type": "caption",
                          "src": "https://shotstack-assets.s3.amazonaws.com/captions/transcript.srt"
                      },
                      "start": 0,
                      "length": "end"
                  }
              ]
          },
          {
              "clips": [
                  {
                      "asset": {
                          "type": "video",
                          "src": "https://shotstack-ingest-api-dev-sources.s3.ap-southeast-2.amazonaws.com/lu8ta6o0i8/zzz01hyh-seb52-vhz1d-8k58f-nxfv13/source.mp4"
                      },
                      "start": 0,
                      "length": "auto"
                  }
              ]
          }
      ]
  },
  "output": {
      "format": "mp4",
      "resolution": "sd"
  }
}

The JSON includes two tracks, one for the captions and another for the video. We're using the smart clips feature which allows you to use assets without the need to manually set values for the start and length properties. Shotstack automatically sets these values based on the asset's duration and its position on the track.

In the JSON above, the video has a value of 0 for start and auto for the length property which means it will play from the beginning to the end. The captions also have a start value of 0 and a length value of end which will make it show up for the entire duration of the video.

Post the JSON edit to the render endpoint

In your terminal, navigate to the directory with the captions.json file. Run the cURL command below to make a POST request to the Edit API. Be sure to replace SHOTSTACK_API_KEY with your sandbox API key.

curl -X POST \
    -H "Content-Type: application/json" \
    -H "x-api-key: SHOTSTACK_API_KEY" \
    -d @captions.json \
        https://api.shotstack.io/edit/stage/render

If the request is successful, the API will respond with JSON that looks like the following.

{
    "success": true,
    "message": "Created",
    "response": {
    "message": "Render Successfully Queued",
        "id": "da76dc5a-04e8-4b77-9ad5-830e4b446a23"
    }
}

Take note of the value of response.id. You will need it to check the render status of the video in the next step.

Check the render status of the video

Run the command below to check the render status of the video. Replace SHOTSTACK_API_KEY with your API key and RENDER_ID with the value of the response.id from the previous step.

curl -X GET \
    -H "Content-Type: application/json" \
    -H "x-api-key: SHOTSTACK_API_KEY" \
        https://api.shotstack.io/stage/render/RESPONSE_ID?data=false

The API response will be like the one below. It will include a response.status value which should be equal to done when the render is complete. If it's not equal to done, wait for a few seconds and run the GET request again.

You can also use a webhook to get a notification of the render status. The Shotstack webhook will notify you when rendering is completed successfully or fails. You can easily set up a webhook callback by adding a callback parameter to the JSON edit.

When the render.status value is equal to done, the response will include a URL that points to the final video with the captions.

{
    "success": true,
    "message": "OK",
    "response": {
        "id": "da76dc5a-04e8-4b77-9ad5-830e4b446a23",
        "owner": "rvoer3rfug",
        "plan": "sandbox",
        "status": "done",
        "error": "",
        "duration": 25.9,
        "billable": 25.9,
        "renderTime": 13486.21,
        "url": "https://shotstack-api-stage-output.s3-ap-southeast-2.amazonaws.com/rvoer3rfug/da76dc5a-04e8-4b77-9ad5-830e4b446a23.mp4",
        "poster": null,
        "thumbnail": null,
        "created": "2024-06-13T05:32:18.369Z",
        "updated": "2024-06-13T05:32:32.755Z"
    }
}

Copy and paste the URL into your browser to view or download the video.

The video above includes the captions but it's hard to read because the default version is just plain text and it doesn't contrast well with the background. In the next section, we'll look at some styling options you can use to make the captions better.

Adding style to the captions

There are several styling options you can add to improve the look and feel of the captions. Let's look at some examples below.

Applying a stroke effect to the text

Adding a stroke to captions creates an outline around the text, which makes the text more legible compared to the default option. To apply a stroke, you can use the stroke property for the colour and the strokeWidth property for its size.

Let's make changes to the same JSON for the default captions example to add the stroke. The only change we'll make is adding a font property with a stroke value of #000000 and strokeWidth of 0.5.

  "asset": {
      "type": "caption",
      "src": "https://shotstack-assets.s3.amazonaws.com/captions/transcript.srt",
      "font": {
          "stroke": "#000000",
          "strokeWidth": 0.5
      }
  },

The stroke makes the captions more readable than the default option. However, there’s more we can do to make the text stand out.

Adjusting the text size

You can also change the font size using the size property. Let's see an example below where we're applying a font size of 35.

  "asset": {
      "type": "caption",
      "src": "https://shotstack-assets.s3.amazonaws.com/captions/transcript.srt",
      "font": {
          "size": 25
      }
  }

Changing the colour of the captions

Another styling option you can use is changing the colour of the caption text. In the following example, we've applied a color code of #fcba03 to the text.

  "asset": {
      "type": "caption",
      "src": "",
      "font": {
          "color": "#fcba03"
      }
  }

Adding a background to the captions

You can also add a background to the captions to make it stand out. To add a background, you use the background property and specify various style options. For example, in the JSON excerpt below, we're applying a background with a color code of #fcba03, a padding of 20, and a borderRadius of 8.

  "asset": {
      "type": "caption",
      "src": "",
      "background": {
          "color": "#fcba03",
          "padding": 20,
          "borderRadius": 8
      }
  }

Adding a background has made the captions more visually appealing and also easy to read.

Using built-in fonts for captions

The family attribute of the font property allows you to specify your preferred font for the captions. In the following example, we're using "Permanent Marker", one of the built-in fonts.

  "asset": {
      "type": "caption",
      "src": "https://shotstack-assets.s3.amazonaws.com/captions/transcript.srt",
      "font": {
          "family": "Permanent Marker"
      }
  }

Other built-in font options include the following;

• Arapey Regular
• Clear Sans Regular
• Didact Gothic Regular
• Montserrat ExtraBold
• Montserrat SemiBold
• MovLette
• Open Sans Bold
• Permanent Marker Regular
• Roboto Black Italic
• Sue Ellen Francisco
• Uni Neue Bold
• Work Sans Light

Using custom fonts for captions

Shotstack also allows you to use custom fonts. To use a custom font, you add the "fonts" property to the timeline and its value should be the URL to the .ttf file for the font. Here's an example that uses the Lilita One font. We've uploaded the font to an S3 bucket and we're using the link in the JSON edit.

  "timeline": {
      "fonts": [
          {
              "src": "https://shotstack-assets.s3-ap-southeast-2.amazonaws.com/fonts/LilitaOne-Regular.ttf"
          }
      ],
      "tracks": {...}      
  }

Once you've added the URL to the .tff file, you can reference the font in the JSON edit using the correct family name.

  "asset": {
      "type": "caption",
      "src": "https://shotstack-assets.s3.amazonaws.com/captions/transcript.srt",
      "font": {
          "family": "Lilita One"
      }
  }

Repositioning the captions

You can also adjust the position of the captions using custom margins. In the example below, the captions are positioned on the top left of the screen by adding the following margin values to the JSON:

• top: 0.25
• left: 0.05
• right: 0.45

  "asset": {
      "type": "caption",
      "src": "https://shotstack-assets.s3.amazonaws.com/captions/transcript.srt",
      "font": {
          "color": "#ffffff",
          "family": "Montserrat ExtraBold",
          "size": 30,
          "lineHeight": 0.8
      },
      "margin": {
          "top": 0.25,
          "left": 0.05,
          "right": 0.45
      }
  }

Conclusion

In this guide, you have learned how to add captions to videos using an API. The guide also covered some styling options you can use to the captions more readable and visually appealing. Whether you need to add captions to a single video or looking for a way to automate adding captions to many videos, Shotstack is flexible and scalable to meet your needs. Also, instead of manually running cURL command as we did in this guide, you can use any of our SDKs to create a script to automate the process.