SUBS(1p)

✨ SUBS(1p) — like, the subtitle glow-up tool ✨

okay bestie, gather round 💖 this is subs(1p), a page from the User Contributed Perl Documentation collection, and it is literally the main character of subtitle wrangling. it converts, joins, splits, and re-times subtitles. that's the whole vibe. no cap.

---

🎀 FORMAT 🎀

so here's how you call it, and yes the brackets are real:

subs [options] subfile [ subfile ... ]

you can hand it one subfile, or a whole little squad of subfiles. it's flexible like that. 💅

---

🌸 OPTIONS 🌸

every single one, no skips, periodt:

• -a coeff, -b time — these two are the a and b coefficients in the linear transformation u=at+b, where t and u are the src and dest times. the default (identity transform, i.e. "leave my timeline alone") is [a=1,b=0]. cute lil detail: -a can also be set as a ratio, f.ex. 23.9/25. slay.
• -c codec — use codec to write the file. wanna know which codecs you actually have installed? run subs -h and it'll spill the whole list. 🔥
• -d — tries to prolong the duration of text that disappears too fast. and "quickly" here means less than 0.8 second per line of text. so if your subs are out here blinking like a strobe light, this is your girl.
• -e command — runs perl code for each line of text in the file. on every run, the text and time variables get initialized, and any new values get written back to the file. the variables are:
  • $_ — subtitle text line
  • $b — cue beginning
  • $e — cue end
  • $i — line number
  • $n — number of lines
  • %p — persistent data between runs

and yes, you can specify -e several times. stack them. go feral. 🧚

• -h — Display help. (hi, hello, help)
• -i — Edit files in place, and it makes a backup in .bak files. iconic, but pls read the warning later 👀
• -j sec — Time interval between joins, in seconds. default is 2.
• -o file — the File to save processed subtitles to. default is out.sub.
• -O — Separate overlapped lines. untangle that mess, bestie.
• -p t1 t2 or -P t2 t1 — Set a control point, where t1 is the time a phrase is spoken in the film and t2 is the time when that same phrase appears in the subtitle. you need two points to deduce the -a and -b coefficients; if you only give one point, it just assumes the other one is [0,0].

times can be relative, f.ex. -p 01:00 +3.5 -p -20 1:00:00

and here's the tea on -P vs -p: they're the same except the argument sequence is reversed. -P exists for when you typed the arguments to -p manually and in the wrong order. we've all been there. 🙈

• -q t1 t2 — Restrict changes, if any, to the time span t1-t2. the word end can be used as an alias to the end of the file. default values are 0 and end.
• -r rate — Force frame-per-second rate for frame-based subs.
• -s time — Split in two parts by time.
• -v — Be verbose. spill everything. main character energy. 👑
• -z file.sub — Zip subtitle files, so that the time information is read from file.sub, while the text information is read from the input file(s). lil franken-sub. 💀

---

🦋 NOTES 🦋

the time format is either [[HH:]MM:]SS[.MSEC] or whatever is subtitle format-specific. iykyk.

---

🌈 EXAMPLES 🌈

Warning: -i is a great feature, but use it with certain caution. like, great feature, but she bites. 🫶

if subtitles are shown too early (by 5 seconds):

subs -i -b 5 file.sub

if subtitles are for a movie in 25 fps, but need to be for 24 (only actually matters for frame-based formats):

subs -i -a 24/25 file.sub

if subtitles start ok, but after 1 hour are late by 7 seconds:

subs -i -p 0 0 -p 1:00:00 +7 file.sub

join two parts with a 15-second gap:

subs -o joined.sub -j 15 part1.sub part2.sub

split in two after 50 minutes and half a second (this makes basename.1.sub and basename.2.sub):

subs -o basename.sub -s 50:00.5 toobig.sub

remove closed caption-specific comments such as '[Sneezing]' or '[Music playing]':

subs -e 's/[\s-]*\[.*\]\s*\n*//gs' sub.sub

---

💀 BUGS 💀

subtitles written as ".smi" format may differ from the original. not a vibe, but forewarned is forearmed.

---

⭐ SEE ALSO ⭐

• Subtitles — the backend module for this program

---

💜 AUTHOR 💜

Dmitry Karasik, <dmitry@karasik.eu.org>.

---

and that's the whole page, bestie ✨ this one's from perl v5.34.0, dated 2022-06-17 — go forth and subtitle responsibly 🎀💖