Add Video Subtitles To Videos Using PHP
Tags: php, webdev, beginners, tutorial
Published: 2022-07-09 09:05:11

Video captions, often referred to as subtitles, are more important than ever. Not only do they assist hearing impaired 
users but some estimates claim that up to 80% of videos online are watched on mute or with the volume disabled. To 
learn more, check out our [captions and subtitles guide](../introduction-to-captions-subtitles/).

##Prerequisites

#### Shotstack API
[Shotstack.io](https://shotstack.io/) provides a video-editing API which that makes it easy to programmatically edit videos. The Shotstack PHP API enables you to automatically apply text and titles to a video with just a few lines of code. Using this feature and a simple SRT file you can create applications, scripts and workflows that will automatically transcribe your videos and add captions or subtitles.  [Sign up] (https://dashboard.shotstack.io/register) for the free developer account to get started.

#### PHP
[PHP (>= 7.2)](https://www.php.net/) is a powerful general purpose scripting language. We'll be using PHP to edit the video.

#### Git
Basic understanding of using git and version control system.

For this guide we already have our SRT file available, but if you are looking at creating SRT files based on your own videos you should take a look at some of our other articles on how you can to use [AWS Transcribe to generate audio transcriptions](/learn/transcribe-video-with-aws-transcribe) and [convert these transcriptions to SRT files](/learn/convert-aws-transcriptions-to-srt-subtitles).

### Using the PHP SDK to apply subtitles to your videos

For this demo we will be using PHP, the Shotstack [PHP video editor library](/product/sdk/php/) (SDK) and a video and
SRT file from our [Test Media](https://github.com/shotstack/test-media/tree/main/captioning) GitHub project. Technically
speaking we are adding captions, but the exact same code would be used to add subtitles.

This is the source video we will apply captions to:

<video id="player" playsinline controls>
  <source src="https://d1uej6xx5jo4cd.cloudfront.net/scott-ko.mp4" type="video/mp4" />
</video>

### Setup
For this guide we'll use an existing PHP script from the Shotstack PHP demos project which is open source and publicly 
available on GitHub.

Checkout the [shotstack/php-demos](https://github.com/shotstack/php-demos) project:

```bash
git clone https://github.com/shotstack/php-demos.git
```

Install dependencies including the Shotstack SDK and [SRT Parser](https://github.com/benlipp/srt-parser) library:

```bash
composer install
```

Set your API key as an environment variable (Linux/Mac):

```bash
export SHOTSTACK_KEY=your_key_here
```

or, if using Windows:

```bash
set SHOTSTACK_KEY=your_key_here
```

Replace `your_key_here` with your provided API key.


### PHP video captions script

Open the file [examples/captions.php](https://github.com/shotstack/php-demos/blob/main/examples/captions.php) 
from the php-demos project. This script loads our video and applies the captions. Below we walk through how the script 
automatically adds captions to a video.

#### Adding the video file

The [video asset](/docs/api/#tocs_videoasset) is used to load videos and add them to our 
edit. In this example we use the URL of our video on GitHub.

```php
$videoAsset = new VideoAsset();
$videoAsset
    ->setSrc('https://github.com/shotstack/test-media/raw/main/captioning/scott-ko.mp4')
    ->setVolume(1);
```

A [clip](/docs/api/#tocs_clip) is a container for an asset, i.e. a title, image or video.
In this example we will use our video asset with our GitHub video. We set the length to the duration of the video 
(25.85 seconds) and the start to 0 so it starts playing straight away.

```php
$videoClip = new Clip();
$videoClip
    ->setAsset($videoAsset)
    ->setLength(25.85)
    ->setStart(0);
```

#### Adding the captions

Next, we'll need to load the SRT file and add the captions. For this, we use the [SRT Parser](https://github.com/benlipp/srt-parser)
library.

```php
$parser = new Parser();
$parser->loadFile(__DIR__ . '/assets/transcript.srt');
$captions = $parser->parse();
```

```parse()``` returns an array of captions, so we're going to iterate over this array to process the items. Each caption
entry will be converted to a [title asset](/docs/api/#tocs_titleasset) and added to a 
clip.

We set the font style, background and position of the text to make it look like captions and also use the PHP 
`wordwrap` function to make sure our text stays on screen. We also use some basic maths from the timestamps returned in 
the parser to calculate when to start and stop displaying the subtitle.

```php
foreach ($captions as $index => $caption) {
    $captionAsset = new TitleAsset();
    $captionAsset
        ->setText(wordwrap($caption->text, 80, "\n"))
        ->setStyle('subtitle')
        ->setBackground('#000000')
        ->setPosition('bottom')
        ->setOffset((new Offset)->setY(-0.4))
        ->setSize('small');

    $clip = new Clip();
    $clip
        ->setAsset($captionAsset)
        ->setLength($caption->endTime - ($caption->startTime + 0.1) )
        ->setStart($caption->startTime);

    $clips[] = $clip;
}
```

#### Adding the clips to a timeline

Shotstack API uses a [timeline](/docs/api/#tocs_timeline), which represents the 
contents of a video edit over time, in seconds, and [tracks](/docs/api/#tocs_track)
which allow us to layer clips over one another.

We'll now combine the initial video asset, with the clips generated from the SRT files, and use tracks to layer them on 
top of the video. `$track1` contains the subtitle clips and `$track2` is the background video.

```php
$track1 = new Track();
$track1
    ->setClips($clips);

$track2 = new Track();
$track2
    ->setClips([$videoClip]);

$timeline = new Timeline();
$timeline
    ->setTracks([$track1,$track2]);
```

#### Configure the output

Finally we configure the [output](/docs/api/#tocs_output) format and add the timeline and 
output to create an [Edit](/docs/api/#tocs_edit).

```php
$output = new Output();
$output
    ->setFormat('mp4')
    ->setResolution('sd');

$edit = new Edit();
$edit
    ->setTimeline($timeline)
    ->setOutput($output);
```

#### Sending the edit to the Shotstack API

The final step in our script is to send the data to the API for processing. The Shotstack SDK takes care of converting 
our PHP objects to JSON, adding our key to the request header and sending everything to the API.

```php
try {
    $response = $client->postRender($edit)->getResponse();
} catch (Exception $e) {
    print_r($e->getMessage());
    die('Request failed: ' . $e->getMessage());
}
```

### Running the script

To run the script use the php command from the root folder of the project:

```bash
php examples/captions.php
```

If the render request is successful, the API will return the render id we can use to retrieve the status of the render.

For this, you can run a different script included in our sample repo:

```bash
php examples/status.php {renderId}
```

Replace `{renderId}` with the ID returned from the first step.

Depending on the progress of the video render, the output will be one of:

```text
>> Video URL: <url to download your file>
```

```text
>> Something went wrong, rendering has terminated and will not continue.
```

```text
>> Rendering in progress, please try again shortly.
>> Note: Rendering may take up to 1 minute to complete.
```

Re-run the status.php script every 4-5 seconds until either a video URL is returned or there is an error message.

### The final result

After about 30 seconds, the video should be rendered with the captions rendered in to the video, as shown below:

<video id="player" playsinline controls>
  <source src="https://d1uej6xx5jo4cd.cloudfront.net/scott-ko-w-captions.mp4" type="video/mp4" />
</video>

### Building an automated subtitle video app using PHP

You can use this example as a starting point to build out an automated subtitle or caption application or create a 
workflow to generate and add captions to your videos.

Combine the Shotstack API with the power of AI audio-to-text services such as 
[AWS Transcribe](https://aws.amazon.com/transcribe/) and you can quickly and easily add powerful, scalable, caption 
functionality to your videos.

There are also AI translation services like [AWS Translate](https://aws.amazon.com/translate/) which could be used to 
add foreign subtitles automatically to a video.

The possibilities of what you can do with the Shotstack [video editing API](/product/video-editing-api/) are many, captions 
and subtitles are just one of the use cases. I hope this article inspires you to explore the API and see what you can 
build.

Follow [Shotstack ](https://dev.to/shotstack) to get similar  articles about programmable videos and applications. Start with our [learn resources](https://shotstack.io/learn/) to learn to start programmable videos. Sign up for free to start building today!