.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Subtitles 3pm"
.TH Subtitles 3pm "2022-06-17" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Subtitles \- handle video subtitles in various text formats
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Video files (avi mpeg etc) are sometimes accompanied with subtitles, which are
currently very popular as text files. \f(CW\*(C`Subtitles\*(C'\fR provides means for simple
loading, re-timing, and storing these subtitle files.  A command-line tool
\&\fIsubs\fR for the same purpose and using \f(CW\*(C`Subtitles\*(C'\fR interface is included in
the distribution.
.PP
The module supports \f(CW\*(C`srt\*(C'\fR, \f(CW\*(C`sub\*(C'\fR, \f(CW\*(C`smi\*(C'\fR, and \f(CW\*(C`mdvd\*(C'\fR subtitle formats.
.PP
Time values are floats, in seconds with millisecond precision.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&        use Subtitles;
\&        
\&        my $sub = Subtitles\->new();
\&
\&        open F, \*(AqIchi The Killer.sub\*(Aq or die "Cannot read:$!";
\&        die "Cannot load:$@\en" unless $sub\-> load(\e*F);
\&        close F;
\&
\&        # back two minutes
\&        $sub\-> shift( $sub\-> parse_time(\*(Aq\-02:00\*(Aq)); 
\&
\&        # 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:$!\en";
\&        $part1\-> save( \e*F);
\&        close F;
\&
\&        # report
\&        print "sub is ", time2str( $sub\-> length);
.Ve
.SH "API"
.IX Header "API"
.SS "Package methods"
.IX Subsection "Package methods"
.IP "codecs" 4
.IX Item "codecs"
Returns array of installed codecs.
.IP "hms2time \s-1HOURS, MINUTES, SECONDS, MILLISECONDS\s0" 4
.IX Item "hms2time HOURS, MINUTES, SECONDS, MILLISECONDS"
Combines four parameters into float time in seconds.
.IP "time2hms \s-1TIME\s0" 4
.IX Item "time2hms TIME"
Splits time into four integers, \- hours, minutes, seconds, and milliseconds.
If time is less than zero, zero times are returned.
.IP "time2shms" 4
.IX Item "time2shms"
Splits time into five integers, \- time sign, hours, minutes, seconds, and milliseconds.
.IP "time2str \s-1TIME\s0" 4
.IX Item "time2str TIME"
Converts time to a human-readable string.
.SS "Object methods"
.IX Subsection "Object methods"
.IP "clear" 4
.IX Item "clear"
Removes all content
.IP "codec [ \s-1STRING\s0 ]" 4
.IX Item "codec [ STRING ]"
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 \f(CW\*(C`Subtitles::Codec::srt\*(C'\fR.
.IP "dup [ \s-1CLEAR\s0 ]" 4
.IX Item "dup [ CLEAR ]"
Duplicates object instance in deep-copy fashion. If \s-1CLEAR\s0
flag is set, timeframes are not copied.
.IP "join \s-1GUEST, GAP\s0" 4
.IX Item "join GUEST, GAP"
Adds content of object \s-1GUEST\s0 at the end of the list of subtitles with \s-1GAP\s0 in seconds.
.IP "length" 4
.IX Item "length"
Returns length of subtitle span.
.IP "load \s-1FH\s0 [ \s-1CODEC\s0 ]" 4
.IX Item "load FH [ CODEC ]"
Reads subtitle content into object. If successful, returns 1;
otherwise undef is returned and \f(CW$@\fR contains the error.
.Sp
By default, tries to deduce which codec to use; to point the
selection explicitly \s-1CODEC\s0 string is to be used.
.IP "lines" 4
.IX Item "lines"
Returns number of subtitle cues.
.IP "new" 4
.IX Item "new"
Creates a new instance. To force a particular
codec, supply \f(CW\*(C`codec\*(C'\fR string here.
.IP "parse_time \s-1STRING\s0" 4
.IX Item "parse_time STRING"
Parses \s-1STRING\s0 which is either a \f(CW\*(C`[[HH:]MM:]SS[,MSEC]\*(C'\fR string
or string in a format specific to a codec, for example, number
of a frame.
.IP "rate \s-1FPS\s0" 4
.IX Item "rate FPS"
Forces a particluar frame-per-second rate, if a codec
can make use of it.
.IP "save \s-1FH\s0" 4
.IX Item "save FH"
Writes content of instance into \s-1FH\s0 file handle,
using the associated codec.
.IP "scale A" 4
.IX Item "scale A"
Changes time-scale. If A is 2, the subtitles 
go off 2 times slower, if 0.5 \- two times faster, etc.
.IP "shift B" 4
.IX Item "shift B"
Shifts timings by B seconds. B can be negative.
.IP "split \s-1TIME\s0" 4
.IX Item "split TIME"
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.
.IP "transform A, B [\s-1FROM, TO\s0]" 4
.IX Item "transform A, B [FROM, TO]"
Applies linear transformation to the time-scale,
such as \f(CW\*(C`u = At + B\*(C'\fR where \f(CW\*(C`t\*(C'\fR is the original 
time and \f(CW\*(C`u\*(C'\fR 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.
.SH "BUGS"
.IX Header "BUGS"
This is alpha code, more a proof-of-concept rather
that anything else, so most surely bugs are lurking.
.PP
Anyway: not all subtitle types are recognized.
The modules doesn't handle multi-language subtitles.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
subs \- command-line wrapper for this module
.SH "THANKS"
.IX Header "THANKS"
<http://dvd.box.sk/>, <http://subs.2ya.com>.
.SH "AUTHOR"
.IX Header "AUTHOR"
Dmitry Karasik, <dmitry@karasik.eu.org>.