=pod

=encoding UTF-8

=head1 NAME

Time::Timecode - Video timecode class and command line program

=for html <a href="https://travis-ci.org/sshaw/Time-Timecode"><img src="https://travis-ci.org/sshaw/Time-Timecode.svg?branch=master"></a>

=head1 SYNOPSIS

To install the C<timecode> executable see L</TIMECODE UTILITY PROGRAM>.

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

=head1 DESCRIPTION

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

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 L<the 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 considered
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 L<the dropframe argument|/* dropframe> to false.

=back

=head2 OPTIONS

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

=over 4

=item * fps:

Frames per second, must be greater than 0. Defaults to C<$Time::Timecode::DEFAULT_FPS>

=item * dropframe:

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

=item * delimiter:

The character used to delimit the timecode's hours, minutes,
and seconds. Use L<the frame_delimiter option|/* frame_delimiter> for delimiting the frames.
Defaults to C<$Time::Timecode::DEFAULT_DELIMITER>.

=item * frame_delimiter:

The character used to delimit the timecode's frames.
Use L<the delimiter option|/* delimiter> 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 except C<frames> which, depending on the
frame rate, can return a float.

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

Returns the timecode in frames

=item C<to_string([FORMAT])>

Returns the timecode as string described by C<FORMAT>. If C<FORMAT> is not provided the
string will be constructed according to the L<instance's defaults|/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

C<FORMAT> is string of characters synonymous (mostly, in some way) with
those used by C<< 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 C<< printf(3) >>.

The following formats are supported:

%H B<H>ours

%M B<M>inutes

%S B<S>econds

%f B<f>rames

%i B<i>n frames (i.e., C<< $tc->total_frames >>)

%r Frame B<r>ate

%s Frames as a fraction of a second

%T B<T>imecode in the L<instance's default format|/DEFAULTS>.

%% Literal percent character

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

If a C<FORMAT> is not provided 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 and will be called when an instance is quoted. I.e., C<< "$tc" eq $tc->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
will be taken from the calling instance.

The converted timecode will be non-dropframe.

=back

=head1 ARITHMETIC & COMPARISON

Arithmatic and comparison are provided via operator overloading. When applicable results get
L<their options|/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.

=head2 Supported Operations

=head3 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';

=head3 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';

=head3 Multiplication

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

=head3 Division

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

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

=head3 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';
  # ....

=head1 DEFAULTS

All defaults except C<$DEFAULT_TO_STRING_FORMAT> can be overridden when L<creating a new instance|/CONSTRUCTOR>.
C<$DEFAULT_TO_STRING_FORMAT> can be overridden by passing a format to C<< L<to_string|/to_string([FORMAT])> >>.

C<$DEFAULT_FPS = 29.97>

C<$DEFAULT_DROPFRAME = 0>

C<$DEFAULT_DELIMITER = ':'>

C<$DEFAULT_FRAME_DELIMITER = ':'>

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

=head1 TIMECODE UTILITY PROGRAM

C<Time::Timecode> includes an executable called C<timecode> that allows one to perform timecode conversions
and arithmetic.

Using it requires L<Perl|https://www.perl.org/get.html>. Once Perl is installed run the following command to
install it: C<cpan Time::Timecode>

=head2 Usage

  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.

=head2 Examples

=head3 Convert frames to a 29.97 dropframe timecode

  timecode -c 29.97df 1800
  00:01:00:02

=head3 Convert 24 to 29.97 dropframe and output the result as frames

  timecode -i 24 -c 29.97df -f %i 00:12:33:19
  18091

=head3 Subtract two dropframe timecodes

  timecode -c 29.97 23:00:04.29-00:00:05.00
  22:58:37.05

=head3 Convert a list of timecodes from a file to a custom format, ignoring invalid timecodes

  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

=head1 SEE ALSO

=over 2

=item L<< C<Time::Timecode source code>|https://github.com/sshaw/Time-Timecode >>

=item L<xslt-timecode|https://github.com/sshaw/xslt-timecode> - A pure, dependency free, XSLT 1.0 library for video timecode manipulation

=item L<iTunes Store Transporter: GUI|http://transportergui.com> - GUI and workflow automation for the iTunes Store’s Transporter (iTMSTransporter)

=back

=head1 AUTHOR

Made by L<ScreenStaring|http://screenstaring.com>.

=head1 CREDITS

Jinha Kim for schooling me on dropframe timecodes.

L<Andrew Duncan|http://andrewduncan.net/> (and L<David Heidelberger|http://www.davidheidelberger.com/>)
for the L<nice drop frame algorithm|http://www.davidheidelberger.com/blog/?p=29>.

=head1 REFERENCES

For information about dropframe timecodes see:
L<http://andrewduncan.net/timecodes/>, L<http://dropframetimecode.org/>, L<http://en.wikipedia.org/wiki/SMPTE_time_code#Drop_frame_timecode>

=head1 COPYRIGHT

Copyright (c) 2009-2018 Skye Shaw. All rights reserved.

=head1 LICENSE

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