How to subtitle videos using the VEED API
Tags: videoapi, subtitlevideoapi, videoeditingapi, veed
Published: 2021-03-30 00:46:17


In modern times, captioning videos has become a major way to make your content standout as it makes it easier to follow along with the dialogue as viewers watch a video.

Another, not so obvious reason to add captions to your videos is acessibility and improved SEO on video platforms like youtube.

In this article, we will walk through the steps required to subtitle videos automatically via the VEED API.

Let’s get into it!


# Installation & setup

To get started, we will set up the project, install all necessary dependencies  and prepare to get our final result in 4 simple steps.


## 1. Signup and get your API Key

Follow the link to  [signup for your free Veed account](https://www.veed.io/signup).

Once you finish signup, you should see your **Workspace Dashboard**. This is your home for managing your video editing activity on Veed.

On your **Workspace Dashboard**, click on the **Settings** tab on the side menu. This will open up a section as shown below. At the bottom of the page, you will find a button that reads “***Enable API****”*. Click on that button to enable the API section of your dashboard.


![](https://paper-attachments.dropbox.com/s_D366B4D15E6DE887648DB4FE9841A41FEF1A84B6DBBCBBF79F869F7B8C8F0D7A_1614545049240_image.png)


Once, you have done that, you will be taken to the section shown below. Here, you can copy your API keys which will be required for all interactions with the API. You will also notice that an **API tab** has now been added to your side menu for easy access subsequently.


![](https://paper-attachments.dropbox.com/s_D366B4D15E6DE887648DB4FE9841A41FEF1A84B6DBBCBBF79F869F7B8C8F0D7A_1614545089746_image.png)


**Note:**
Make sure to use the test key `key_test_XXXXXXXXXXXXXX` while in development and switch to the production key `key_live_XXXXXXXXXXXXXX` for your deployment environment.


## 2. Install Node and NPM

Make sure you have `npm` installed on your system:


    node -v && npm -v

You should see the respective version numbers printed to the console. If not, you can go to the official [Node.js site](https://nodejs.org/en/) to get installation instructions for your platform.

Now that you have node and NPM installed, run the commands below to setup the project directory.


## 3. Setup project directory

Create project directory.


    mkdir subtitle-video-app 

Enter the directory you just created and initalize the project.


    cd subtitle-video-app && npm init -y

This will create a `package.json` file which holds configurations pertaining to the project but most importantly, it will contain the dependencies for this project.


## 4. Install dependencies

For this project, the only dependency we need to install is the VEED API Node library. To do so, execute the command below in your terminal.


    npm i @veedstudio/veed-node --save

Now that we have successfully installed the necessary dependencies, for the final step we need to setup our webhook.


## 5. Setting up your webhook

Instead of polling the API each time in order to know when our render is complete, the VEED API provides support for a webhook so that users can receive events from time to time when an action worthy of note occurs e.g a render has started, a render has completed e.t.c

To get a webhook URL for this purpose, head over to https://webhook.site/ to retrieve your webhook URL. Copy your unique URL and head over to your Workspace dashboard. On the API tab, you’d see an input labeled `Webhook URL`, paste the URL you had copied earlier in there and click “Save”.

Now that we have done all that, we are ready to start subtitling videos.



# Subtitling the video

We will break the steps involved in subtitling a video into two as shown below:

1. Upload and transcribe video
2. Subtitle video


## Upload and transcribe video

First we need to create the transcription. **Video transcription** is the process of translating your **video's** audio into text.
To transcribe a video with the VEED API, you need to create an asset (check out our [managing media assets guide](https://veed.readme.io/docs/managing-media-assets) for more info on how to do this). As you are creating the asset, you will need to pass the `transcribe: true` option as a body parameter. 


## Subtitle video

Once you have your asset uploaded and processed (with the transcription), we can start constructing the render object request for the subtitles.

First we need to add uploaded asset as a video element:


    {
      "elements": [
        {
          "type": "video",
          "params": {
            "source": {
              "asset_id": "28a510a8-6690-4cdc-b319-e0e02ebf1a2e" 
            },
          }
        }    
      ]
    }

Next step is to create a subtitle element, making sure it references the correct `asset_id`


    {
      "elements": [
        {
          "type": "video",
          "params": {
            "source": {
              "asset_id": "28a510a8-6690-4cdc-b319-e0e02ebf1a2e" 
            },
          }
        },
        {
          "type": "subtitles",
          "params": {
            "source": {
              "asset_id": "28a510a8-6690-4cdc-b319-e0e02ebf1a2e" 
            },
          }
        }
      ]
    }

Now you are ready to send the request. Save the above as a `render.json` file, and run this command:


    -X POST \
      --header "Authorization: veed_test_oEnZhnd3vg0LEoTs6Z9Ij" \
      --data @render.json \
      https://api.veed.io/api/render

Make sure to use your own API key. You should get a response that looks like this:


    {
      "id": "b477e483-592a-4bc6-a22b-563ef7f48e25",
    }


# Getting the result

We recommend using a [Webhook](https://veed.readme.io/reference#working-with-webhooks) to process all your rendering events, but for this example we'll be polling the API (you can find more info on polling the API here, under '[Getting the final render](https://veed.readme.io/docs/making-first-render#getting-the-final-render)'):


    curl \
      --header "Authorization: veed_test_oEnZhnd3vg0LEoTs6Z9Ij" \
      https://api.veed.io/api/render/b477e483-592a-4bc6-a22b-563ef7f48e25

You should get a `RENDER_SUCCESS` response, once the rendering is done:


    {
        "type": "RENDER/SUCCESS",
        "payload": {
          "id": "b477e483-592a-4bc6-a22b-563ef7f48e25",
          "progress": 100,
          "url": "https://cdn.veed.dev/R1vqZ0KfPp5y2z7ddiTyt.mp4"
        }
      }

You can use the `url`in the response to download the render and enjoy your new video, with hardcoded subtitles!


# Getting the subtitled video

There are several ways to get the subtitled video. 


## 1. Using the webhook

Return to the https://webhook.site page where you had copied the webhook URL that you added to the dashboard. You will notice that the several events are being sent to this URL as the render proceeds.


![](https://paper-attachments.dropbox.com/s_D366B4D15E6DE887648DB4FE9841A41FEF1A84B6DBBCBBF79F869F7B8C8F0D7A_1614592144526_image.png)


You can find the list of events received on the left. You can click on any them to see the data that was sent in each payload. You would notice the the render starts out from progress `percentage` `0`, up until `100` when the render is completed. 



    {
      "type": "RENDER/PROGRESS",
      "payload": {
        "render_id": "17cf9aad-807d-4f68-98b7-f748b8d67c22",
        "percentage": 0
      }
    }

On completion, you get a `RENDER/SUCCESS` event which contains the URL to the subtitled video as requested.


    {
      "type": "RENDER/SUCCESS",
      "payload": {
        "render_id": "e52aad52-5ab0-465d-8341-fdabd6302cf1",
        "progress": 100,
        "url": "https://storage.googleapis.com/veed-prod-video-bucket/veedapi%2Frenders%2Fe52aad52-5ab0-465d-8341-fdabd6302cf1%2Foutput%2Fh5PIjzgDpai~x1srAbH1X.mp4?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=prod-api%40veed-prod-server.iam.gserviceaccount.com%2F20210228%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20210228T210416Z&X-Goog-Expires=9000&X-Goog-SignedHeaders=host&X-Goog-Signature=4ce2e4664470fb81f450e91fe63bdcd29e1077eed756a94eb3923b5740acbbc4618a91b148a5cd4b3540db615a95f0842893cc013aa965a8099d671724de058852816ec795bd17d483a51b944b8cc461a7b3bf0e3f51b5ed702dde0a5bbada3bb68fcc1de3d6fd1bcb8262f3199b28218d2de0dd9a4b2eaee5583b0ccbd52022e5a99a49f71972ed1c0ba28a9ae2d93f0e1b88f2b1308f8ff6375ad3ae31c80c42a9968d7ee572cfab03c0e153ac3ee67a4cdf9f8f8b4dca3fa42ae4240e01e259aa4808973607a71df681bee691e64d663436600b0b95852d26aa857dfc6d74e571207c93d201f31d0e1505dbc374d36076bf5caccd6a38281771af50017892"
      }
    }


## 2. Poll the API

Without the webhook, there is no way to tell at what exact time a render is complete. Hence, another approach will be to poll the API. You can use the VEED package for this. Simply replace `veed.render.create(renderOptions)` with `veed.render.get({id:'YOUR_RENDER_ID_GOES_HERE'})`. Run the script again. You should see the response printed to the console. If the render is completed and the download URL is ready, you will get a response like the one below:


    {
      id: '540ba741-bead-42cd-bcbe-dcd2d0663d8d',
      workspace_id: '78c897c9-810d-4a33-97e2-15c796a05161',
      data: { elements: [ [Object], [Object] ] },
      latest_event: {
        type: 'RENDER/SUCCESS',
        payload: {
          render_id: '540ba741-bead-42cd-bcbe-dcd2d0663d8d',
          progress: 100,
          url: 'https://storage.googleapis.com/veed-prod-video-bucket/veedapi%2Frenders%2F540ba741-bead-42cd-bcbe-dcd2d0663d8d%2Foutput%2FzBG_du_k~qL5dLS9YT6Oa.mp4?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=prod-api%40veed-prod-server.iam.gserviceaccount.com%2F20210301%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20210301T084032Z&X-Goog-Expires=9001&X-Goog-SignedHeaders=host&X-Goog-Signature=7b9dd8d71a055867a1cc0947f24050ec145b863be3c787963f820ff218d9a55201c45b509cbdb48c8460a71c2f3c433c4809c55ffa610c5964d07e7fdcee3f19f3bb2cde93b104b7b66930fde8ccbc278c0a33afac5ad671d6265ab2e6e9ae0a96ddf6103ba7028f3508dfd1fb35aef37dc6a0cf28d245fcfc8d4ef825a3656aec6f0cee6f25c69422351e84d56226129b9168ce364d394bbffd8682b37efdd438b90b259aa964e41b714660343885020b3a4664db37c35019b82f397d270085881098a1ece6a7e2bc4c055d4db6b3ea3137fbd2c7576eb140b8ef1cb2d6479d36094450b2ee82335a84514b5ec14c28ef770eb0c4188e8fde6321ff68ee28a9'
        }
      },
      created_at: 1614588003775,
      modified_at: 1614588032628
    }
    

You can now copy the `url` and paste it into your browser. Hit `enter` and the download should start automatically.

# Conclusion

Congratulations, you have successfully learnt how to transcribe and subtitle videos in Node using the VEED API. You are encouraged to explore the API further using the documentation and build out your own application or API that utilizes this API in a more clever way and share in the comment section below. 

I’d love to see the magic you create. See you in the next one!


# Resources
- [Our website](https://www.veed.io/)
- [More about our API](https://www.veed.io/api)
- [Our API Documentation](https://documentation.veed.io/reference#getting-started)