How to add captions to video 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.

The Shotstack 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.

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

Prerequisites

• Shotstack API key. You can register without a credit card and start using our API for free. After registration, retrieve your API key from the dashboard.
• PHP (>= 7.2)
• Git

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();

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

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: 

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