Working with Subtitles

Stork has first-class support for the SRT subtitle file format. Stork will not only extract and parse the text in a subtitle file, but also maintain the mapping from each individual word to its associated timestamp. This means Stork lets your users click on a search result and automatically get linked to the timestamp in the video where the search query was mentioned.

In many cases, you won't have to do any further configuration beyond making sure the file extension of your subtitle is .srt. If Stork recognizes your files as SRT files, it will automatically parse and link the timestamps automatically.

Stork's default SRT linking configuration is based on YouTube's timestamp link format:

https://youtube.com/watch=v?WUvTyaaNkzM&t=255

We can imagine the YouTube link above split up into four parts:

• https://youtube.com/watch?v=: A common prefix used for every url.
• WUvTyaaNkzM: The ID of the video
• &t={}: A format string appended onto the URL, with a defined place for the timestamp to go.
• 255: The timestamp of the video, in seconds.

When those four elements listed above are combined, they generate an entire YouTube timestamp URL. Stork lets you configure each of those elements to determine how a timestamp URL is generated in the browser, and therefore how Stork links to specific timestamps from its search results.

Stork's configuration format lets you customize the way URLs are generated from timestamp information encoded in SRT files. To demonstrate, we can create a Stork configuration file that links to Vimeo timestamp links, instead of YouTube timestamp links. Because Vimeo's timestamp links use a different format, we have to configure that format within the Stork configuration file.

For reference, Vimeo timestamp links look like this:

https://vimeo.com/81400335#t=1m2s

Now, our four timestamp link components are set as such:

• https://vimeo.com/: the URL prefix prepended to each search result.
• 81400335: The ID of the video, determined by Vimeo.
• #t={}: The format string. The placeholder {} will be replaced with the actual timestamp.
• 1m2s: The timestamp is formatted with a number of minutes and a number of seconds, instead of just a total number of seconds.

The Stork configuration file supports an object, [input.srt_config], that lets you control how timestamp links are generated.

The following configuration file will set the timestamp links to be in "Vimeo format" instead of "YouTube format":

[input.srt_config]
timestamp_format = "MinutesAndSeconds"
timestamp_template_string = "#t={}"

[[input.files]]
# ...

The input.srt_config.timestamp_template_string value defines the URL suffix to be appended when your user searches for something. Stork will build the URL as usual—combining the URL prefix with the URL from the file object, but will then add the timestamp_template_string to the end.

The timestamp_format value describes how the timestamp should be formatted within that template string. The two possible options are NumberOfSeconds, which renders a result like 62, and MinutesAndSeconds, which renders a result like 1m2s.

The {} placeholder in the timestamp_template_string will be replaced by the formatted timestamp.