NAME

Time::Timecode - Video timecode class

SYNOPSIS

use Time::Timecode;

my $tc1 = Time::Timecode->new(2, 0, 0, 12); # hh, mm, ss, ff
print $tc1->fps;                            # $DEFAULT_FPS
print $tc1;                                 # 02:00:00:12
print $tc1->hours;                          # 2
print $tc1->hh;                             # shorthanded version
print $tc1->to_string('%Hh%Mm%Ss%ff')       # 2h0m0s12f

my $tc2 = Time::Timecode->new('00:10:30:00', { fps => 25 } );
print $tc2->total_frames;                   # 15750
print $tc2->fps;                            # 25

$tc2 = Time::Timecode->new(1800);           # Total frames
print $tc1 + $tc2;                          # 02:01:00:12

$tc1 = Time::Timecode->new('00:01:00;04');  # Dropframe (see the ";")
print $tc1->is_dropframe;                   # 1

my $diff = $tc1 - 1800;                     # Subtract 1800 frames
print $tc1->is_dropframe;                   # 1, maintains LHS' options
print $diff;                                # 00:00:02;00

# Conversions
my $pal  = $tc->convert(25);
my $ntsc = $pal->convert(30), { dropframe => 1 });
my $ndf  = $ntsc->to_non_dropframe;

my $opts = { delimiter => ',', frame_delimiter => '+' };
$Time::Timecode::DEFAULT_FPS = 23.976;
$tc2 = Time::Timecode->new('00,10,30+00', $opts);
print $tc2->fps                             # 23.976
print $tc2->minutes;                        # 10
print $tc2->seconds;                        # 30

DESCRIPTION

Time::Timecode supports any frame rate, drop/non-drop frame counts, basic arithmetic, and conversion between frame rates and drop/non-drop frame counts. The only requirements are that the timecode be between 00:00:00:00 and 99:99:99:99, inclusive, and frames per second (fps) are greater than zero. This means that you can create nonstandard timecodes (feature or bug? :^). Dropframe rules will still apply.

Time::Timecode instances can be created from a a variety of representations, see "CONSTRUCTOR".

Time::Timecode instances are immutable.

CONSTRUCTOR

new( TIMECODE [, OPTIONS ] ): Creates an immutable instance for TIMECODE with the given set of OPTIONS. If no OPTIONS are given the package defaults are used.

TIMECODE

TIMECODE can be one of the following:

A list denoting hours, minutes, seconds, and/or frames:

$tc1 = Time::Timecode->new(1, 2, 3)
$tc1 = Time::Timecode->new(1, 2, 3, 0)   #same as above

Frame count:

$tc1 = Time::Timecode->new(1800)   # 00:01:00:00 @ 30 fps

Timecode string:
```
$tc1 = Time::Timecode->new('00:02:00:25')
```
Timecode strings with dropframe frame delimiters

In the video encoding world timecodes with a frame delimiter of "." or ";" are considered dropframe. If either of these characters are used in the timecode string passed to new the resulting instance will dropframe.

This can be overridden by setting the dropframe argument to false.

OPTIONS

OPTIONS must be a hash reference and can contain any of the following:

fps:

Frames per second, must be greater than 0. Decimal values are rounded 0 places when performing calculations: 29.976 becomes 30. Defaults to $Time::Timecode::DEFAULT_FPS
dropframe:

A boolean value denoting wheather or not the timecode is dropframe. Defaults to $Time::Timecode::DEFAULT_DROPFRAME.
delimiter:

The character used to delimit the timecode's hours, minutes, and seconds. Use the frame_delimiter option for delimiting the frames. Defaults to $Time::Timecode::DEFAULT_DELIMITER.
frame_delimiter:

The character used to delimit the timecode's frames. Use the delimiter option for delimiting the rest of the timecode. Defaults to $Time::Timecode::DEFAULT_FRAME_DELIMITER.

METHODS

All time part accessors return an integer except frames which, depending on the frame rate, can return a float.

hours

hrs

hh

Returns the hour part of the timecode

minutes

mins

mm

Returns the mintue part of the timecode

seconds

secs

ss

Returns the second part of the timecode

frames

ff

Returns the frame part of the timecode

fps

Returns the frames per second

total_frames

Returns the timecode in frames

to_string([FORMAT])

Returns the timecode as string described by FORMAT. If FORMAT is not provided the string will be constructed according to the instance's defaults.

$tc = Time::Timecode->new(2,0,10,24);
$tc->to_string                  # 02:00:10:24
"$tc"                                   # Same as above
$tc->to_string('%02H%02M%S.%03f DF')    # 020010.024 DF

FORMAT is string of characters synonymous (mostly, in some way) with those used by strftime(3), with the exception that no leading zero will be added to single digit values. If you want leading zeros you must specify a field width like you would with printf(3).

The following formats are supported:

%H Hours

%M Minutes

%S Seconds

%f frames

%i in frames (i.e., $tc->total_frames)

%r Frame rate

%T Timecode in the instance's default format.

%% Literal percent character

When applicable, formats assume the width of the number they represent.

If a FORMAT is not provided the delimiter used to separate each portion of the timecode can vary. If the delimiter or frame_delimiter options were provided they will be used here. If the timecode was created from a timecode string that representation will be reconstructed.

This method is overloaded and will be called when an instance is quoted. I.e., "$tc" eq $tc->to_string

is_dropframe

Returns a boolean value denoting whether or not the timecode is dropframe.

to_non_dropframe

Converts the timecode to non-dropframe and returns a new Time::Timecode instance. The framerate is not changed.

If the current timecode is non-dropframe $self is returned.

to_dropframe

Converts the timecode to dropframe and returns a new Time::Timecode instance. The framerate is not changed.

If the current timecode is dropframe $self is returned.

convert( FPS [, OPTIONS ] )

Converts the timecode to FPS and returns a new instance.

OPTIONS are the same as those allowed by the CONSTRUCTOR. Any unspecified options will be taken from the calling instance.

The converted timecode will be non-dropframe.

ARITHMETIC & COMPARISON

Arithmatic and comparison are provided via operator overloading. When applicable results get their options from the left hand side (LHS) of the expression. If the LHS is a literal the options will be taken from the right hand side.

Supported Operations

Addition

$tc1 = Time::Timecode->new(1800);
$tc2 = Time::Timecode->new(1);
print $tc1 + $tc2;
print $tc1 + 1800;
print 1800 + $tc1;
print $tc1 + '00:10:00:00';

Subtraction

$tc1 = Time::Timecode->new(3600);
$tc2 = Time::Timecode->new(1);
print $tc1 - $tc2;
print $tc1 - 1800;
print 1800 - $tc1;
print $tc1 - '00:00:02:00';

Multiplication

$tc1 = Time::Timecode->new(1800);
print $tc1 * 2;
print 2 * $tc1;

Division

$tc1 = Time::Timecode->new(1800);
print $tc1 / 2;

Pre/postincrement with/without assignment

$tc1 = Time::Timecode->new(1800);
$tc1 += 10;             # Add 10 frames
print ++$tc1;           # Add 1 frame
print $tc1--;           # Subtract it after printing

All comparison operators

$tc1 = Time::Timecode->new(1800);
$tc2 = Time::Timecode->new(1800);
print 'equal!' if $tc1 == $tc2;
print 'less than' if $tc1 < '02:00:12;22';
print 'greater than' if $tc1 >= '02:00:12;22';
# ....

DEFAULTS

All defaults except $DEFAULT_TO_STRING_FORMAT can be overridden when creating a new instance. $DEFAULT_TO_STRING_FORMAT can be overridden by passing a format to to_string.

$DEFAULT_FPS = 29.97

$DEFAULT_DROPFRAME = 0

$DEFAULT_DELIMITER = ':'

$DEFAULT_FRAME_DELIMITER = ':'

$DEFAULT_TO_STRING_FORMAT = 'HHxMMxSSxFF' where x represents the instance's frame and time separators.

AUTHOR

Skye Shaw (sshaw AT lucas.cis.temple.edu)

CREDITS

Jinha Kim for schooling me on dropframe timecodes.

REFERENCES

For information about dropframe timecodes see: http://dropframetimecode.org/, http://en.wikipedia.org/wiki/SMPTE_time_code#Drop_frame_timecode

COPYRIGHT

LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

kfatehi / time-timecode Goto Github PK

time-timecode's Introduction