Subtitles(3pm)

💖 Subtitles(3pm) 💖

okay bestie, so this is the manual page for Subtitles, a Perl module that lives in the User Contributed Perl Documentation corner of your system. Buckle up, it's cute and it's useful.

---

✨ NAME ✨

Subtitles — handle video subtitles in various text formats 🎬

---

🌸 DESCRIPTION 🌸

so like. video files (avi mpeg etc) are sometimes accompanied by subtitles, which rn are super popular as text files. Subtitles gives you the tools for simple loading, re-timing, and storing these subtitle files. there's also a command-line tool, subs, that does the same thing and uses the Subtitles interface — it ships in the distribution. 💅

the module supports the srt, sub, smi, and mdvd subtitle formats. no cap.

time values are floats, in seconds, with millisecond precision. ⏱️

---

🦋 SYNOPSIS 🦋

use Subtitles;

my $sub = Subtitles->new();

open F, 'Ichi The Killer.sub' or die "Cannot read:$!";
die "Cannot load:$@\n" unless $sub-> load(\*F);
close F;

# back two minutes
$sub-> shift( $sub-> parse_time('-02:00'));

# re-frame from 25 fps
$sub-> scale( 23.976 / 25 );

# or both
$sub-> transform( -120, 0.96);
$sub-> transform( -120, 0.96, 0, $sub-> length - 60);

# split in 2
my ( $part1, $part2) = $sub-> split( $self-> length / 2);

# join back with 5-second gap
$part1-> join( $part2, 5);

# save
open F, "> out.sub" or die "Cannot write:$!\n";
$part1-> save( \*F);
close F;

# report
print "sub is ", time2str( $sub-> length);

---

👑 API 👑

🎀 Package methods

• codecs — returns an array of the installed codecs. that's it, that's the vibe check. ✨
• hms2time HOURS, MINUTES, SECONDS, MILLISECONDS — smushes all four params together into a float time in seconds. 🫶
• time2hms TIME — splits time into four integers: hours, minutes, seconds, and milliseconds. and listen — if the time is less than zero, you just get zero times back. 🙈
• time2shms — splits time into five integers: the time sign, hours, minutes, seconds, and milliseconds. sign girlie 💅
• time2str TIME — turns a time into a human-readable string. iconic for printing. 🌈

💜 Object methods

• clear — removes all content. poof. 💀
• codec [ STRING ] — if STRING isn't defined, it hands you the currently associated codec. otherwise it sets the new codec in association. the STRING is the codec's package name, like Subtitles::Codec::srt. 🎀
• dup [ CLEAR ] — duplicates the object instance in deep-copy fashion. if the CLEAR flag is set, the timeframes are not copied. ✨
• join GUEST, GAP — adds the content of object GUEST at the end of the list of subtitles, with GAP in seconds. besties reunited 🫶
• length — returns the length of the subtitle span. 📏
• load FH [ CODEC ] — reads subtitle content into the object. if it works, returns 1; otherwise undef comes back and $@ holds the error. by default it tries to deduce which codec to use, but to point the selection explicitly you pass the CODEC string. 🦋
• lines — returns the number of subtitle cues. count 'em 🔢
• new — creates a new instance. to force a particular codec, supply the codec string right here. ✨
• parse_time STRING — parses STRING, which is either a "[[HH:]MM:]SS[,MSEC]" string, or a string in a format specific to a codec — for example, the number of a frame. 🔥
• rate FPS — forces a particular frame-per-second rate, if a codec can make use of it. 🎞️
• save FH — writes the content of the instance into the FH file handle, using the associated codec. 💾
• scale A — changes the time-scale. if A is 2, the subtitles go off 2 times slower; if 0.5, two times faster, etc. ⏱️
• shift B — shifts timings by B seconds. B can be negative. ⏪
• split TIME — splits the content of the instance between two newly created instances of the same class, by TIME, and returns them. both resulting subtitles begin at time 0. 🌱
• transform A, B [FROM, TO] — applies a linear transformation to the time-scale, like u = At + B, where t is the original time and u is the result. if the FROM and TO brackets are set, the changes are applied only to the lines in the timeframe between these. ✨

---

😭 BUGS 😭

this is alpha code, more a proof-of-concept than anything else, so most surely bugs are lurking. bestie, be careful. 💀

anyway, also: not all subtitle types are recognized. and the module doesn't handle multi-language subtitles. 🙈

---

🔍 SEE ALSO 🔍

subs — command-line wrapper for this module 🫶

---

💖 THANKS 💖

<http://dvd.box.sk/>, <http://subs.2ya.com>. 🎀

---

👑 AUTHOR 👑

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

---

and that's the whole thing, bestie — this page is from perl v5.34.0, dated 2022-06-17, and it's the Subtitles(3pm) page. slay, go time-shift some subtitles. 💅✨🦋