Subtitles (3pm)

Video files (avi mpeg etc) are sometimes accompanied with subtitles, which are currently very popular as text files. \*(C`Subtitles\*(C' provides means for simple loading, re-timing, and storing these subtitle files. A command-line tool subs for the same purpose and using \*(C`Subtitles\*(C' interface is included in the distribution.

The module supports \*(C`srt\*(C', \*(C`sub\*(C', \*(C`smi\*(C', and \*(C`mdvd\*(C' subtitle formats.

Time values are floats, in seconds with millisecond precision.

        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);

Package methods

codecs

Returns array of installed codecs.

hms2time \s-1HOURS\s0, \s-1MINUTES\s0, \s-1SECONDS\s0, \s-1MILLISECONDS\s0

Combines four parameters into float time in seconds.

time2hms \s-1TIME\s0

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 \s-1TIME\s0

Converts time to a human-readable string.

Object methods

clear

Removes all content

codec [ \s-1STRING\s0 ]

If \s-1STRING\s0 is not defined, returns currently associated codec. Otherwise, sets the new codec in association. The \s-1STRING\s0 is the codec's package name, such as \*(C`Subtitles::Codec::srt\*(C'.

dup [ \s-1CLEAR\s0 ]

Duplicates object instance in deep-copy fashion. If \s-1CLEAR\s0 flag is set, timeframes are not copied.

join \s-1GUEST\s0, \s-1GAP\s0

Adds content of object \s-1GUEST\s0 at the end of the list of subtitles with \s-1GAP\s0 in seconds.

length

Returns length of subtitle span.

load \s-1FH\s0 [ \s-1CODEC\s0 ]

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 \s-1CODEC\s0 string is to be used.

lines

Returns number of subtitle cues.

new

Creates a new instance. To force a particular codec, supply \*(C`codec\*(C' string here.

parse_time \s-1STRING\s0

Parses \s-1STRING\s0 which is either a \*(C`[[HH:]MM:]SS[,MSEC]\*(C' string or string in a format specific to a codec, for example, number of a frame.

rate \s-1FPS\s0

Forces a particluar frame-per-second rate, if a codec can make use of it.

save \s-1FH\s0

Writes content of instance into \s-1FH\s0 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 \s-1TIME\s0

Splits the content of the instance between two newly created instances of the same class, by \s-1TIME\s0, and returns these. The both resulting subtitles begin at time 0.

transform A, B [\s-1FROM\s0, \s-1TO\s0]

Applies linear transformation to the time-scale, such as \*(C`u = At + B\*(C' where \*(C`t\*(C' is the original time and \*(C`u\*(C' is the result. If \s-1FROM\s0 and \s-1TO\s0 brackets are set, the changes are applied only to the lines in the timeframe between these.

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.

subs - command-line wrapper for this module

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

Dmitry Karasik, <[email protected]>.