Time::Timecode - Video timecode class and command line program
To install the timecode executable see "TIMECODE UTILITY PROGRAM".
timecode
To use with your Perl program:
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
Time::Timecode supports SMTPE timecodes, 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
Time::Timecode instances can be created from a a variety of representations, see "CONSTRUCTOR".
Time::Timecode instances are immutable.
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
OPTIONS
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.
new
This can be overridden by setting the dropframe argument to false.
OPTIONS must be a hash reference and can contain any of the following:
fps:
Frames per second, must be greater than 0. Defaults to $Time::Timecode::DEFAULT_FPS
$Time::Timecode::DEFAULT_FPS
dropframe:
A boolean value denoting wheather or not the timecode is dropframe. Defaults to $Time::Timecode::DEFAULT_DROPFRAME.
$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.
$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.
$Time::Timecode::DEFAULT_FRAME_DELIMITER
All time part accessors return an integer except frames which, depending on the frame rate, can return a float.
frames
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
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.
FORMAT
$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).
strftime(3)
printf(3)
The following formats are supported:
%H Hours
%M Minutes
%S Seconds
%f frames
%i in frames (i.e., $tc->total_frames)
$tc->total_frames
%r Frame rate
%s Frames as a fraction of a second
%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.
delimiter
frame_delimiter
This method is overloaded and will be called when an instance is quoted. I.e., "$tc" eq $tc->to_string
"$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.
$self
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.
FPS
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.
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.
$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';
$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';
$tc1 = Time::Timecode->new(1800); print $tc1 * 2; print 2 * $tc1;
$tc1 = Time::Timecode->new(1800); print $tc1 / 2;
$tc1 = Time::Timecode->new(1800); $tc1 += 10; # Add 10 frames print ++$tc1; # Add 1 frame print $tc1--; # Subtract it after printing
$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'; # ....
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_TO_STRING_FORMAT
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.
$DEFAULT_TO_STRING_FORMAT = 'HHxMMxSSxFF'
x
Time::Timecode includes an executable called timecode that allows one to perform timecode conversions and arithmetic.
Using it requires Perl. Once Perl is installed run the following command to install it: cpan Time::Timecode
cpan Time::Timecode
usage: timecode [-h] [-c spec] [-f format] [-i spec] [expression] -h --help option help -c --convert spec convert expression according to `spec' `spec' can be a number of FPS proceeded by an optional `D', `ND', `DF' or a comma separated list of key=value. key can be fps, dropframe, delimiter, frame_delimiter -f --format format output timecode according to `format' e.g., '%H:%M:%S at %r FPS'. %H=hours, %M=mins, %S=secs, %f=frames, %i=total frames, %r=frame rate, %s=frames in secs -i --input spec process incoming expressions according to `spec'; see -c for more info -q --quiet ignore invalid expressions -v --version print version information Expression can be a timecode, a number of frames, or an arithmetic expression composed one or both. If no expression is given timecode will read from stdin.
timecode -c 29.97df 1800 00:01:00:02
timecode -i 24 -c 29.97df -f %i 00:12:33:19 18091
timecode -c 29.97 23:00:04.29-00:00:05.00 22:58:37.05
cat > /tmp/times.txt 02:01:00:12 foo! 02:02:21:00 02:01:00:02 timecode -qi 24 -f '%Hh %Mm %Ss and %f frames' < /tmp/times.txt 02:01:00:12 2h 1m 0s and 12 frames 02:02:21:00 2h 2m 21s and 0 frames 02:01:00:02 2h 1m 0s and 2 frames
Time::Timecode source code
Made by ScreenStaring.
Jinha Kim for schooling me on dropframe timecodes.
Andrew Duncan (and David Heidelberger) for the nice drop frame algorithm.
For information about dropframe timecodes see: http://andrewduncan.net/timecodes/, http://dropframetimecode.org/, http://en.wikipedia.org/wiki/SMPTE_time_code#Drop_frame_timecode
Copyright (c) 2009-2018 Skye Shaw. All rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install Time::Timecode, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Time::Timecode
CPAN shell
perl -MCPAN -e shell install Time::Timecode
For more information on module installation, please visit the detailed CPAN module installation guide.