=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.