=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<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. C<Time::Timecode> instances can be created from a a variety of representations, see L</CONSTRUCTOR>. C<Time::Timecode> instances are immutable. =head1 CONSTRUCTOR =over 2 =item C<new( TIMECODE [, OPTIONS ] )> Creates an immutable instance for C<TIMECODE> with the given set of C<OPTIONS>. If no C<OPTIONS> are given the L<"package defaults"|/DEFAULTS> are used. =back =head2 TIMECODE C<TIMECODE> 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<Timecode strings with dropframe frame delimiters> 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<new()> the resulting instance will dropframe. This can be overridden by setting the L<"dropframe argument"|/OPTIONS> to false. =back =head2 OPTIONS C<OPTIONS> must be a hash reference containg any of the following: =over 4 B<fps>: 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<dropframe>: A boolean value denoting wheather or not the timecode is dropframe. Defaults to C<$Time::Timecode::DEFAULT_DROPFRAME>. B<delimiter>: The character used to delimit the timecode's hours, minutes, and seconds. Use the B<frame_delimiter> option for delimiting the frames. Defaults to C<$Time::Timecode::DEFAULT_DELIMITER>. B<frame_delimiter>: The character used to delimit the timecode's frames. Use the B<delimiter> 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<hours()> =item C<hrs()> =item C<hh()> Returns the hour part of the timecode =item C<minutes()> =item C<mins()> =item C<mm()> Returns the mintue part of the timecode =item C<seconds()> =item C<secs()> =item C<ss()> Returns the second part of the timecode =item C<frames()> =item C<ff()> Returns the frame part of the timecode =item C<fps()> Returns the frames per second =item C<to_string()> 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<delimiter> or C<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. Using a C<Time::Timecode> instance in a scalar context results in a call to C<to_string()>. =item C<is_dropframe()> Returns a boolean value denoting whether or not the timecode is dropframe. =item C<to_non_dropframe()> Converts the timecode to non-dropframe and returns a new C<Time::Timecode> instance. The framerate is not changed. If the current timecode is non-dropframe C<$self> is returned. =item C<to_dropframe()> Converts the timecode to dropframe and returns a new C<Time::Timecode> instance. The framerate is not changed. If the current timecode is dropframe C<$self> is returned. =item C<convert( FPS [, OPTIONS ] )> Converts the timecode to C<FPS> and returns a new instance. C<OPTIONS> are the same as L<those allowed by the CONSTRUCTOR|/OPTIONS>. 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<when creating a new instance|/CONSTRUCTOR>. 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<http://dropframetimecode.org/>, L<http://en.wikipedia.org/wiki/SMPTE_time_code#Drop_frame_timecode> =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.