Add Video Subtitles To Videos Using PHP

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.

Prerequisites

Shotstack API

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 for the free developer account to get started.

PHP

PHP (>= 7.2) 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 and convert these transcriptions to SRT files.

Using the PHP SDK to apply subtitles to your videos

For this demo we will be using PHP, the Shotstack PHP video editor library (SDK) and a video and
SRT file from our Test Media 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:

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 project:

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

Install dependencies including the Shotstack SDK and SRT Parser library:

composer install

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

export SHOTSTACK_KEY=your_key_here

or, if using Windows:

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
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 is used to load videos and add them to our
edit. In this example we use the URL of our video on GitHub.

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

A 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.

$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
library.

$parser = new Parser();
$parser->loadFile(__DIR__ . '/assets/transcript.srt');
$captions = $parser->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, which represents the
contents of a video edit over time, in seconds, and tracks
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.

$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 format and add the timeline and
output to create an Edit.

$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.

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:

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:

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:

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

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

>> 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:

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 and you can quickly and easily add powerful, scalable, caption
functionality to your videos.

There are also AI translation services like AWS 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 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 to get similar articles about programmable videos and applications. Start with our learn resources to learn to start programmable videos. Sign up for free to start building today!