NAME¶
Subtitles - handle video subtitles in various text formats
DESCRIPTION¶
Video files (avi mpeg etc) are sometimes accompanied with subtitles, which are
currently very popular as text files. "Subtitles" provides means for
simple loading, re-timing, and storing these subtitle files. A command-line
tool
subs for the same purpose and using "Subtitles"
interface is included in the distribution.
The module supports "srt", "sub", "smi", and
"mdvd" subtitle formats.
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 array of installed codecs.
- hms2time HOURS, MINUTES, SECONDS, MILLISECONDS
- Combines four parameters into float time in seconds.
- time2hms TIME
- Splits time into four integers, - hours, minutes, seconds, and
milliseconds. If time is less than zero, zero times are returned.
- time2shms
- Splits time into five integers, - time sign, hours, minutes, seconds, and
milliseconds.
- time2str TIME
- Converts time to a human-readable string.
Object methods¶
- clear
- Removes all content
- codec [ STRING ]
- If STRING is not defined, returns currently associated codec. Otherwise,
sets the new codec in association. The STRING is the codec's package name,
such as "Subtitles::Codec::srt".
- dup [ CLEAR ]
- Duplicates object instance in deep-copy fashion. If CLEAR flag is set,
timeframes are not copied.
- join GUEST, GAP
- Adds content of object GUEST at the end of the list of subtitles with GAP
in seconds.
- length
- Returns length of subtitle span.
- load FH [ CODEC ]
- Reads subtitle content into object. If successful, returns 1; otherwise
undef is returned and $@ contains the error.
By default, tries to deduce which codec to use; to point the selection
explicitly CODEC string is to be used.
- lines
- Returns number of subtitle cues.
- new
- Creates a new instance. To force a particular codec, supply
"codec" string here.
- parse_time STRING
- Parses STRING which is either a "[[HH:]MM:]SS[,MSEC]" string or
string in a format specific to a codec, for example, number of a
frame.
- rate FPS
- Forces a particluar frame-per-second rate, if a codec can make use of
it.
- save FH
- Writes content of instance into FH file handle, using the associated
codec.
- scale A
- Changes 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 these. The both resulting subtitles
begin at time 0.
- transform A, B [FROM, TO]
- Applies linear transformation to the time-scale, such as "u = At +
B" where "t" is the original time and "u" is the
result. If 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 rather that anything else, so most
surely bugs are lurking.
Anyway: not all subtitle types are recognized. The modules 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>.