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>.