Easily integrate subtitles into videos using Lua

Tim Koschützki

Co-founder · Berlin, Germany ·

Adding subtitles to videos enhances accessibility and bolsters viewer engagement. Lua, a lightweight and versatile scripting language, provides a simple yet efficient approach to integrate subtitles into your video projects.

The significance of subtitles in video content

Subtitles are vital for reaching a broader audience. They assist viewers with hearing impairments while also catering to multilingual users by providing translated text. Integrating subtitles can notably improve comprehension and enhance user engagement.

Lua: a lightweight scripting language for video processing

Lua is renowned for its speed, simplicity, and ease of embedding. Its minimal footprint makes it ideal for scripting tasks, including video processing. With Lua’s clear syntax, you can quickly implement automation for adding subtitles without unnecessary overhead.

Setting up your Lua environment for video processing

The script below targets Lua 5.3 or newer on Linux or macOS, with a POSIX shell and /dev/fd. FFmpeg must include the subtitles filter, which requires libass, and the libx264 encoder. Package builds differ: check ffmpeg -filters and ffmpeg -encoders after installation.

For Ubuntu/Debian:

sudo apt-get update
sudo apt-get install lua5.3 ffmpeg

For macOS:

brew update
brew install lua ffmpeg

The default macOS FFmpeg package may not include libass. Use a build with the required filter; installing Lua alone does not enable subtitle rendering. On Windows, use a compatible Linux environment such as WSL rather than running this POSIX-shell script through CMD or PowerShell.

Working with subtitle formats

Before integrating subtitles, confirm that your subtitle files are in a supported format. The most common formats include:

SRT (SubRip): Standard format with timing and text information; widely supported.
SSA/ASS (Advanced SubStation Alpha): Offers advanced styling and positioning options.
VTT (Web Video Text Tracks): Commonly used for web-based video applications.

Ensure your subtitle files are saved in UTF-8 encoding and adhere to the proper timing specifications.

Step-by-step guide on adding subtitles using Lua and FFmpeg

The following Lua script burns UTF-8 SRT subtitles into an MP4. It quotes shell arguments and passes the subtitle file through descriptor 3, so its filename never becomes part of FFmpeg's filter syntax. This also handles names containing spaces, quotes, colons, and brackets.

#!/usr/bin/env lua

if #arg ~= 0 and #arg ~= 3 then
  io.stderr:write("Usage: lua add_subtitles.lua <video.mp4> <subtitles.srt> <new-output.mp4>\n")
  os.exit(1)
end

local video_file = arg[1] or "input.mp4"
local subtitles_file = arg[2] or "subtitles.srt"
local output_file = arg[3] or "output.mp4"

local existing = io.open(output_file, "rb")
if existing then
  existing:close()
  io.stderr:write("Output already exists; choose a new filename.\n")
  os.exit(1)
end

local function shell_quote(value)
  return "'" .. value:gsub("'", "'\\''") .. "'"
end

local function local_path(value)
  if value:sub(1, 1) == "/" then return value end
  return "./" .. value
end

local filter = "subtitles=/dev/fd/3"
local command = string.format(
  "ffmpeg -nostdin -n -i %s -vf %s -c:v libx264 -crf 23 -c:a copy %s 3<%s",
  shell_quote(local_path(video_file)),
  shell_quote(filter),
  shell_quote(local_path(output_file)),
  shell_quote(local_path(subtitles_file))
)

local success = os.execute(command)
if not success then
  io.stderr:write("Subtitle conversion failed. Inspect any partial output before retrying.\n")
  os.exit(1)
end
print("Subtitles added successfully.")

Save this script as add_subtitles.lua and make it executable:

chmod +x add_subtitles.lua

Run the script with:

./add_subtitles.lua input.mp4 subtitles.srt output.mp4

The preflight check reports an existing output as an error, and -n tells FFmpeg not to replace it. Use a private working directory with no concurrent writers: this small script does not provide transactional publication if another process creates the output after the check. A failed conversion can still leave a new partial file; inspect it and choose a fresh output path before retrying. Audio is copied, so the input audio codec must be compatible with MP4. For untrusted uploads, run FFmpeg in an isolated worker with filesystem, network, memory, and execution-time limits. Shell quoting is not a media sandbox.

Troubleshooting common issues

Below are some tips to resolve issues commonly encountered during subtitle integration:

Character Encoding Issues:

If your subtitle file is not in UTF-8, convert it with:
```
iconv -f ISO-8859-1 -t UTF-8 input.srt > output.srt
```
Subtitle Timing Synchronization:

If subtitles appear out of sync, add a delay using FFmpeg. For example, to add a 2.5-second delay, create a separate shifted SRT file, then pass that file to the Lua script:
```
ffmpeg -nostdin -n -itsoffset 2.5 -i subtitles.srt -c:s srt shifted.srt
lua add_subtitles.lua input.mp4 shifted.srt delayed.mp4
```
Font Rendering Issues:

Install a font containing your subtitle characters, then replace only the filter variable in the script. For example, with DejaVu Sans installed:
```
local filter = "subtitles=/dev/fd/3:force_style='FontName=DejaVu Sans,FontSize=24'"
```

Keep this style string fixed in the script. Arbitrary user-supplied filter expressions need their own validation; shell quoting does not validate FFmpeg filter syntax.

Advanced subtitle manipulation (optional)

For richer styling, author an ASS subtitle file with a dedicated subtitle editor and inspect the result before burning it into the video. FFmpeg's subtitles filter documentation describes the supported options. Keep subtitle timing adjustments separate from rendering, as in the SRT example above, instead of treating delay as a font-style option.

Best practices for subtitle integration

When integrating subtitles into your videos, keep these best practices in mind:

Validate all input files before processing.
Ensure subtitle files use UTF-8 encoding and follow the correct format.
Test on shorter video segments to verify synchronization and formatting.
Maintain backups of your original files to prevent accidental data loss.
Implement error handling in your scripts to simplify troubleshooting.

Conclusion

Overlaying subtitles using Lua and FFmpeg is a practical solution to enhance video accessibility and engagement. By combining Lua's scripting power with FFmpeg's robust capabilities, you can automate the process while effectively managing common challenges. For scalable projects and advanced processing needs, consider exploring Transloadit, which offers comprehensive APIs and services for video encoding and subtitle integration.