FFmpeg::StreamGroup - A group of related media streams, typically encapsulated in a single file
$ff = FFmpeg->new() #see FFmpeg; #... $sg = $ff->build_streamgroup();
Objects of this class are not intended to be instantiated directly by the end user. Access FFmpeg::StreamGroup objects using methods in FFmpeg. Refer to FFmpeg for more information.
This is a composite class of 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 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 FFmpeg::StreamGroup rather than onto the FFmpeg::Stream object representing the audio data itself.
The FFmpeg::StreamGroup object is useful not only for retrieving stream group metadata, but also for inspecting the component streams of the group. See "streams()" for details.
This class also has rudimentary support for transcoding, in the form of a "frame grab". See "capture_frame()" for details.
See "FEEDBACK" in FFmpeg for details.
Allen Day <allenday@ucla.edu>
Copyright (c) 2003-2006 Allen Day
This library is released under GPL, the Gnu Public License
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.
my $obj = new FFmpeg::StreamGroup();
Builds a new FFmpeg::StreamGroup object
an instance of FFmpeg::StreamGroup
All optional, refer to the documentation of "new()" in FFmpeg, this constructor operates in the same way.
$obj->init(%arg);
Internal method to initialize a new FFmpeg::StreamGroup object
true on success
Arguments passed to new
@arr = $obj->streams();
get the list of streams associated with this stream group.
a list of FFmpeg::Stream objects
none, read only
$obj->_add_stream();
internal method. add one or more streams to this stream group.
one or more FFmpeg::Stream objects
$obj->album(); #get existing value
album name of stream group, if applicable
value of album (a scalar)
none, read-only
$obj->author(); #get existing value
entity responsible for encoding the stream group
value of author (a scalar)
$obj->bit_rate(); #get existing value
average bit rate of stream group, in bits/second.
value of bit_rate (a scalar)
some stream encoders do not store this value in bits/second, but in Kbits/second, or other unknown units. this FFmpeg::StreamGroup attribute should be considered accordingly.
From the FFmpeg documentation: ------------------------------
if file_size() and duration() are available, the return value is calculated. otherwise, the return value is extracted from the stream group, and is zero if not available.
$obj->comment(); #get existing value
comment on the stream group, if any
value of comment (a scalar)
$obj->copyright(); #get existing value
copyright notice on stream group, if any
value of copyright (a scalar)
$obj->data_offset(); #get existing value
offset, in bytes, of first stream data. this is effectively the size of the file header.
value of data_offset (a scalar)
$obj->duration(); #get stream duration in seconds $obj->duration(format=>'HMS'); #get existing value in HH::MM::SS format
duration of the stream group in seconds. this is initialized to 0 if duration information is for some reason unable from the streamgroup.
value of duration (a float), or a formatted time string.
returns duration() in HH:MM:SS.uuuu format
$obj->file_size(); #get existing value
file size of stream group, in bytes
value of file_size (a scalar)
$obj->format(); #get existing FFmpeg::FileFormat
format of the stream group (eg mpeg, avi, mov, &c)
an object of class FFmpeg::FileFormat
$obj->genre(); #get existing value
genre of stream group, if applicable
value of genre (a scalar)
$obj->has_audio(); #get existing value
detect if stream group contains audio
true if any of the contained FFmpeg::Stream objects is an audio stream, false otherwise
$obj->has_video(); #get existing value
detect if stream group contains video
true if any of the contained FFmpeg::Stream objects is an video stream, false otherwise
$obj->height(); #get existing value
height of first video stream in group. it is not implemented to access heights of other streams if they differ from the first.
value of height (a scalar)
$obj->track(); #get existing value
track number of stream group, if applicable
value of track (a scalar)
$obj->url(); #get existing value
url or system path of the stream group (ie path to file)
value of url (a scalar)
$obj->width(); #get existing value
width of first video stream in group. it is not implemented to access widths of other streams if they differ from the first.
value of width (a scalar)
$obj->year(); #get existing value
production year of stream group, if applicable
value ofyear (a scalar)
$obj->_ffmpeg(); #get existing value
internal method. holds a reference to a FFmpeg object. use this to manipulate FFmpeg-C's state.
value of _ffmpeg (a scalar)
$obj-capture_frame( image_format => $ffmpeg_format, offset => $time_piece, video_geometry => "320x240", output_file => "/path/to/file.ppm", ); >
$obj-
capture a frame from a streamgroup. Currently implemented to capture only from first video stream, patches welcome.
a filehandle on image data on the frame requested in the format requested
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.
Dimensions for image as a width x height string (eg "320x240"). Defaults to Streamgroup's native frame size
Path to filename where captured frame will be written. defaults to an anonymous tempfile created using File::Temp that is deleted upon program termination
A string specifying how many seconds will be recorded. defaults to 00:00:00.001 (typically resulting in 1 frame captured).
a string in HH:MM:SS format specifying offset at which to capture the frame. defaults to 00:00:00
$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
$sg-
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
); >
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.
A new FFmpeg::StreamGroup object.
Path to file where captured frame will be written. Defaults to an anonymous tempfile created using File::Temp that is deleted upon program termination.
A string in HH:MM:SS.mmm format specifying offset at which to begin transcoding. Milliseconds optional. Defaults to 00:00:00.
A string in HH:MM:SS.mmm format specifying how many seconds will be transcoded. Milliseconds optional. Defaults to the duration of the input StreamGroup.
Affect how many frames/second are transcoded. For instance, a value of 0.016 will result in one roughly frame per minute. Defaults to the frame rate of the input StreamGroup.
FIXME
Dimensions for image as a width x height string (eg "320x240"). defaults to StreamGroup's native frame size.
width x height
320x240
To install FFmpeg, copy and paste the appropriate command in to your terminal.
cpanm
cpanm FFmpeg
CPAN shell
perl -MCPAN -e shell install FFmpeg
For more information on module installation, please visit the detailed CPAN module installation guide.