/ 
FFmpeg-6036
River stage zero No dependents
/ FFmpeg

NAME

FFmpeg - Perl interface to FFmpeg, a video converter written in C

SYNOPSIS

use FFmpeg;

my @media = qw(my.mpg my.avi my.mov my.mp2 my.mp3);

#instantiate a new FFmpeg object.
my $ff = FFmpeg->new();

foreach my $media (@media){
  #load each media file
  $ff->input_file($media);

  #or from a URL.  note that input_url
  #enables use of other input_url_* args
  $ff->input_url('http://wherever.org/whatever.mpg');
  $ff->input_url_referrer('http://somewhere.org/overtherainbow');
  $ff->input_url_max_size('5000'); #in bytes

  #and create the stream info, accessible in a
  #FFmpeg::StreamGroup object.
  my $sg = $ff->create_streamgroup();

  #we're only interested in StreamGroups with
  #a visual component
  next unless $sg->has_video;

  #capture a frame at offset 30s into the video
  #stream in jpeg format, and get a filehandle on
  #the jpeg data stream.
  my $fh = $sg->capture_frame(
             image_format => $ff->image_format('jpeg'),
             start_time => '00:00:30'
           );

  #write the jpeg to a file.
  open(JPEG, ">$media.jpg");
  print JPEG $_ while <$fh>;
  close(JPEG);
}

DESCRIPTION

FFmpeg (in this module, referred to here as FFmpeg-Perl) is a Perl interface to the base project FFmpeg (referred to here as FFmpeg-C). From the FFmpeg-C homepage:

FFmpeg-C is a complete solution to record, convert and stream audio and video. It includes libavcodec, the leading audio/video codec library. FFmpeg-C is developed under Linux, but it can compiled under most OSes, including Windows.

The project is made of several components:

ffmpeg

a command line tool to convert one video file format to another. It also supports grabbing and encoding in real time from a TV card.

ffserver

an HTTP (RTSP is being developped) multimedia streaming server for live broadcasts. Time shifting of live broadcast is also supported.

ffplay

a simple media player based on SDL and on the ffmpeg libraries.

libavcodec

a library containing all the ffmpeg audio/video encoders and decoders. Most codecs were developed from scratch to ensure best performances and high code reusability.

libavformat

a library containing parsers and generators for all common audio/video formats.

FFmpeg-Perl currently only supports the functionality of the ffmpeg and libavformat components of the FFmpeg-C suite. That is, functions exist for extracting metadata from media streams and transforming one media stream format to another, but no effort is (yet) made to port HTTP broadcasting or playback functionality (provided by the ffserver and ffplay components, respectively).

FEEDBACK

Mailing Lists

Questions, feedback, and bug reports related to the FFmpeg-Perl interface to FFmpeg-C should be sent to the Perl Video mailing list. Subscribe here:

http://sumo.genetics.ucla.edu/mailman/listinfo/perl-video/

Questions, feedback, and bug reports related to the underlying FFmpeg-C code should be sent to the general ffmpeg user and developer. More information is available here:

http://ffmpeg.sourceforge.net/

Reporting Bugs

See "Mailing Lists" above.

Patches

I'm very open to bug reports in the form of patches, as well as patches that extend or add to the functionality of the library. Please send a diff using "diff -up", along with a summary of the purpose of the patch to the Perl Video mailing list (address above, see "Mailing Lists").

AUTHOR

Allen Day <allenday@ucla.edu>

COPYRIGHT AND LICENSE

Copyright (c) 2003-2004 Allen Day

This library is released under GPL, the Gnu Public License

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.

new()

Usage

my $obj = new FFmpeg();

Function

Builds a new FFmpeg object

Returns

an instance of FFmpeg

Arguments
All optional.

all get/set methods can have their value initialized by new() if new is called as:

my $ff = FFmpeg->new(input_file => 'my.file', verbose => 10);

with as many/few get/set fields as you like.

init()

Usage

$obj->init(%arg);

Function

Internal method to initialize a new FFmpeg object

Returns

true on success

Arguments
Arguments passed to "new()"

create_streamgroup()

Usage

$sg = $obj->create_streamgroup();

Function

This factory method creates and returns a new FFmpeg::StreamGroup object for the file set by a call to "input_file()".

Returns

A FFmpeg::StreamGroup object, or undef on failure

Arguments
None

codec()

Usage

$obj->codec($codec_name);

Function

returns a codec by name or id.

Returns

A FFmpeg::Codec object, or undef if the codec specified could not be found.

Arguments
name (or id) of codec to retrieve

codecs()

Usage

@codecs = $obj->codecs();

Function

returns a list of all codecs FFmpeg-C supports.

Returns

A list of FFmpeg::Codec objects

Arguments
none, read-only

format_duration_HMS()

FIXME document this

create_timepiece()

Usage

$tp = $obj->create_timepiece("00:30:00"); #create a Time::Piece at 30 minutes.

Function

Factory method that creates a Time::Piece object from a string. See "strptime()" in Time::Piece or details on the string format expected. The resolution on this object is unfortunately 1 second. I am still looking for a module to manipulate time in sub-second units as easily as Time::Piece.

Returns

A Time::Piece object on success.

Arguments
time string

a string (see Usage) in HH:MM:SS format representing the time offset of interest

file_format()

Usage

$obj->file_format($file_format_name);

Function

returns a file format by name.

Returns

A FFmpeg::FileFormat object, or undef if the file format specified could not be found.

Arguments
name of file format to retrieve

file_formats()

Usage

@formats = $obj->file_formats();

Function

returns a list of all file formats FFmpeg-C supports.

Returns

A list of FFmpeg::FileFormat objects

Arguments
none, read-only

force_format()

Usage
$obj->force_format('mpeg');
Function

Force parsing of "input_file()" or "input_url()" as a file of this format. Useful for file fragments, or otherwise mangled files

Returns

n/a

Arguments
a format name. FIXME should be an object.

image_format()

Usage

$obj->image_format($image_format_name);

Function

returns an image format by name.

Returns

A FFmpeg::ImageFormat object, or undef if the image format specified could not be found.

Arguments
name of image format to retrieve

image_formats()

Usage

@formats = $obj->image_formats();

Function

returns a list of all image formats FFmpeg-C supports.

Returns

A list of FFmpeg::ImageFormat objects

Arguments
none, read-only

input_file()

Usage
$obj->input_file();        #get existing value

$obj->input_file($newval); #set new value
Function

Holds path to file for input and processing. This get/setter additionally validates the existance of the file on set and throws an exception if the file does not exist.

Returns

value of input_file (a scalar)

Arguments
(optional) on set, a scalar

input_url()

Usage
$obj->input_url();        #get existing value

$obj->input_url($newval); #set new value
Function

Holds URL of a file for input and processing. This get/setter is used in "init()" to populate "input_file()".

Returns

value of input_url (a scalar)

Arguments
(optional) on set, a scalar

input_url_max_size()

Usage
$obj->input_url_max_size();        #get existing value

$obj->input_url_max_size($newval); #set new value
Function

Number of bytes to download from </input_url()>. Note that a second HEAD request is made to the server to determine the true file size by inspecting the Content-Length header.

Returns

value of input_url_max_size (a scalar)

Arguments
(optional) on set, a scalar

input_url_referrer()

Usage
$obj->input_url_referrer();        #get existing value

$obj->input_url_referrer($newval); #set new value
Function

URL to use as referrer when GETting "input_url()".

Returns

value of input_url_referrer (a scalar)

Arguments
(optional) on set, a scalar

toggle_stderr()

Usage
$obj->toggle_stderr();
Function

temporarily remaps STDERR to /dev/null. this prevents FFmpeg-C internal writes to STDERR from making through the FFmpeg-Perl call to the caller.

Returns

n/a

Arguments

a true value - silence STDERR a false value - turn STDERR back on

toggle_stdout()

Usage
$obj->toggle_stdout();
Function

temporarily remaps STDOUT to /dev/null. this prevents FFmpeg-C internal writes to STDOUT from making through the FFmpeg-Perl call to the caller.

Returns

n/a

Arguments

a true value - silence STDOUT a false value - turn STDOUT back on

verbose()

Usage
$obj->verbose();        #get existing value

$obj->verbose($newval); #set new value
Function

adjust the reporting of FFmpeg-C to STDERR. this is initialized to -1, or near-silent, the lowest level of verbosity possible in FFmpeg-C.

Returns

value of verbose (a scalar)

Arguments
(optional) on set, a scalar

_AVFormatContext()

Usage
$obj->_AVFormatContext();        #get existing value

$obj->_AVFormatContext($newval); #set new value
Function

internal method, don't mess with this unless you know what you're doing, and/or want to risk coredumping and/or crashing your machine. this holds an int-cast pointer to a FFmpeg-C AVFormatContext struct. it is needed to manipulate the media streams.

Returns

value of _AVFormatContext (a scalar)

Arguments
(optional) on set, a scalar