=head1 NAME Time::Timecode - Video timecode class =head1 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 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; # Maintains LHS' opts print $diff; # 00:00:02;00 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 # Conversions my $pal = $tc->convert(25); my $ntsc = $pal->convert(30), { dropframe => 1 }); my $ndf = $ntsc->to_non_dropframe; =head1 DESCRIPTION C 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. C instances can be created from a a variety of representations, see L. C instances are immutable. =head1 CONSTRUCTOR =over 2 =item C Creates an immutable instance for C with the given set of C. If no C are given the L<"package defaults"|/DEFAULTS> are used. =back =head2 TIMECODE C can be one of the following: =over 4 =item * 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 =item * Frame count: $tc1 = Time::Timecode->new(1800) # 00:01:00:00 @ 30 fps =item * Timecode string: $tc1 = Time::Timecode->new('00:02:00:25') B In the video encoding world timecodes with a frame delimiter of '.' or ';' are dropframe. If either of these characters are used in the timecode string passed to C the resulting instance will dropframe. This can be overridden by setting the L<"dropframe argument"|/OPTIONS> to false. =back =head2 OPTIONS C must be a hash reference containg any of the following: =over 4 B: Frames per second, must be greater than 0. Decimal values are rounded 0 places when performing calculations: 29.976 becomes 30. Defaults to C<$Time::Timecode::DEFAULT_FPS> B: A boolean value denoting wheather or not the timecode is dropframe. Defaults to C<$Time::Timecode::DEFAULT_DROPFRAME>. B: The character used to delimit the timecode's hours, minutes, and seconds. Use the B option for delimiting the frames. Defaults to C<$Time::Timecode::DEFAULT_DELIMITER>. B: The character used to delimit the timecode's frames. Use the B option for delimiting the rest of the timecode. Defaults to C<$Time::Timecode::DEFAULT_FRAME_DELIMITER>. =back =head1 METHODS All time part accessors return an integer. =over 2 =item C =item C =item C Returns the hour part of the timecode =item C =item C =item C Returns the mintue part of the timecode =item C =item C =item C Returns the second part of the timecode =item C =item C Returns the frame part of the timecode =item C Returns the frames per second =item C Returns the timecode as string in a HH:MM:SS:FF format. The delimiter used to separate each portion of the timecode can vary. If the C or C 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. Using a C instance in a scalar context results in a call to C. =item C Returns a boolean value denoting whether or not the timecode is dropframe. =item C Converts the timecode to non-dropframe and returns a new C instance. The framerate is not changed. If the current timecode is non-dropframe C<$self> is returned. =item C Converts the timecode to dropframe and returns a new C instance. The framerate is not changed. If the current timecode is dropframe C<$self> is returned. =item C Converts the timecode to C and returns a new instance. C are the same as L. Any unspecified options are taken from the calling instance. The converted timecode will be non-dropframe. =back =head1 ARITHMATIC =over 2 =item Addition =item Subtraction =item Multiplacation =item Division All results get their options from the left hand side (LHS) of the expression. If LHS is a literal, options will be taken from RHS. =back =head1 DEFAULTS These can be overridden L. C<$DEFAULT_FPS = 29.97> C<$DEFAULT_DROPFRAME = 0> C<$DEFAULT_DELIMITER = ':'> C<$DEFAULT_FRAME_DELIMITER = ':'> =head1 AUTHOR Skye Shaw (sshaw AT lucas.cis.temple.edu) =head1 REFERENCES For information about dropframe timecodes see: L, L =head1 COPYRIGHT Copyright (c) 2009-2010 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.