view release on metacpan or  search on metacpan

FFmpeg/StreamGroup.pm  view on Meta::CPAN

Objects of this class are not intended to be
instantiated directly by the end user.  Access
L<FFmpeg::StreamGroup|FFmpeg::StreamGroup> objects using methods in
L<FFmpeg|FFmpeg>.  Refer to L<FFmpeg> for more information.

This is a composite class of L<FFmpeg::Stream|FFmpeg::Stream> objects.
A StreamGroup in most cases maps directly to a file, but it is also possible
that it can represent data coming over a socket (eg HTTP), filehandle
(eg STDIN), or a peripheral device (eg a TV tuner card).

A media stream, represented by the L<FFmpeg::Stream|FFmpeg::Stream> class
is never created without a parent stream group.  Metadata that may be attached
to a stream is always attached to the group which contains the stream.

An example of this is an MP3 file which has been ID3 "tagged".  Metadata regarding
the MP3 audio data in the file, such as year of recording, artist name, album
name, and genre are attached to a L<FFmpeg::StreamGroup|FFmpeg::StreamGroup>
rather than onto the L<FFmpeg::Stream|FFmpeg::Stream> object representing the
audio data itself.

The L<FFmpeg::StreamGroup|FFmpeg::StreamGroup> object is useful not only for
retrieving stream group metadata, but also for inspecting the component streams
of the group.  See L</streams()> for details.

This class also has rudimentary support for transcoding, in the form of a
"frame grab".  See L</capture_frame()> for details.

=head1 FEEDBACK

See L<FFmpeg/FEEDBACK> for details.

=head1 AUTHOR

Allen Day E<lt>allenday@ucla.eduE<gt>

=head1 COPYRIGHT AND LICENSE

Copyright (c) 2003-2006 Allen Day

This library is released under GPL, the Gnu Public License

=head1 APPENDIX

The rest of the documentation details each of the object methods.
Internal methods are usually preceded with a '_'.  Methods are
in alphabetical order for the most part.

=cut


# Let the code begin...


package FFmpeg::StreamGroup;
use strict;
use Data::Dumper;
use File::Copy;
use File::Temp qw(tempfile tempdir);

use IO::String;
use Image::Magick::Iterator;

use base qw();
our $VERSION = '0.01';

=head2 new()

=over

=item Usage

my $obj = new L<FFmpeg::StreamGroup|FFmpeg::StreamGroup>();

=item Function

Builds a new L<FFmpeg::StreamGroup|FFmpeg::StreamGroup> object

=item Returns

an instance of L<FFmpeg::StreamGroup|FFmpeg::StreamGroup>

=item Arguments

All optional, refer to the documentation of L<FFmpeg/new()>, this constructor
operates in the same way.

=back

=cut

sub new {
  my($class,%arg) = @_;

  my $self = bless {}, $class;
  $self->init(%arg);

  return $self;
}

=head2 init()

=over

=item Usage

$obj->init(%arg);

=item Function

Internal method to initialize a new L<FFmpeg::StreamGroup|FFmpeg::StreamGroup> object

=item Returns

true on success

=item Arguments

Arguments passed to new

=back

FFmpeg/StreamGroup.pm  view on Meta::CPAN

Affects how many frames/second are captured.  for instance, a
value of 0.016 will result in one roughly frame per minute.  Default
behavior is to capture every frame.

=item video_geometry (optional)

Dimensions for image as a width x height string (eg "320x240").
Defaults to Streamgroup's native frame size

=item output_file (optional)

Path to filename where captured frame will be written.  defaults
to an anonymous tempfile created using L<File::Temp|File::Temp> that is
deleted upon program termination

=item duration (optional, B<IMPORTANT>)

A string specifying how many seconds will be recorded.  defaults to 00:00:00.001
(typically resulting in 1 frame captured).

=item offset (optional)

a string in HH:MM:SS format specifying
offset at which to capture the frame. defaults to 00:00:00

=back

=back

=cut

sub capture_frame {
  my ($self,%arg) = @_;
  $arg{duration} = '00:00:00.001';

  my $iterator = $self->capture_frames(%arg);
  #warn $iterator;
  my $next = $iterator->next();
  #warn $next;
  return $next;
}

sub capture_frames {
  my ($self,%arg) = @_;

  $arg{ 'file_format' } = $self->_ffmpeg->file_format( 'image2pipe' );

  my($fh, $fn);
  if ( ! defined( $arg{ 'output_file' } ) ) {
    ($fh, $fn) = tempfile( UNLINK => 1, SUFFIX => '.ppm' );
    $arg{ 'output_file' } = $fn;
  } else {
    $fn = $arg{ 'output_file' };
  }

  $self->transcode( %arg );

  open($fh,$fn) or die "couldn't open '$fn': $!";

  my $iter = Image::Magick::Iterator->new();
  $iter->format( 'PPM' );
  $iter->handle($fh );

  return $iter;
}

=head2 transcode()

=over

=item Usage

C<
$sg->transcode(
  file_format    => $format,        # (optional, required if 'output_file' argument is given) specifies written file format
  output_file    => '/tmp/out.flv', # (optional) path to written file, named pipe, device, etc
  offset         => '00:00:05',     # (optional) transcode from 5s into file
  duration       => '00:00:30',     # (optional) transcode for 30s

  video_rate     => 0.5,            # (optional) use every other frame
  video_bitrate  => 8000,           # (optional) bitrate of video stream(s)
  video_codec    => $vcodec,        # (optional) a FFmpeg::Codec object for which can_write() and is_video are both true
  video_geometry => '320x240',      # (optional) use frame size of 320x240 (WxH)

  audio_rate     => 44100,          # (optional) sample rate of audio stream(s)
  audio_bitrate  => 8000,           # (optional) bitrate of audio stream(s)
  audio_codec    => $acodec,        # (optional) a FFmpeg::Codec object for which can_write() and is_audio are both true

);
>

=item Function

Transcode (i.e. convert from one format/encoding to another)
a StreamGroup.  Currently implemented to operate only on the first
video and audio stream(s), patches welcome.

=item Returns

A new L<FFmpeg::StreamGroup> object.

=item Arguments

=over

=item file_format (optional, required if 'output_file' argument is given)

=item output_file (optional)

Path to file where captured frame will be written.  Defaults
to an anonymous tempfile created using L<File::Temp|File::Temp> that is
deleted upon program termination.

=item offset (optional)

A string in HH:MM:SS.mmm format specifying offset at which to begin transcoding.
Milliseconds optional.  Defaults to 00:00:00.

=item duration (optional B<IMPORTANT>)