---
name: "Subtitles"
section: "3pm"
platform: "linux"
package: "libsubtitles-perl"
version: "1.04-3"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Subtitles"
---

# Subtitles(3pm)

handle video subtitles in various text formats

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