NAME

FFmpeg::StreamGroup - A group of related media streams, typically encapsulated in a single file

SYNOPSIS

  $ff = FFmpeg->new() #see FFmpeg;
  #...
  $sg = $ff->build_streamgroup();

DESCRIPTION

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.

FEEDBACK

See "FEEDBACK" in FFmpeg for details.

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::StreamGroup();

Function

Builds a new FFmpeg::StreamGroup object

Returns

an instance of FFmpeg::StreamGroup

Arguments

All optional, refer to the documentation of "new()" in FFmpeg, this constructor operates in the same way.

init()

Usage

$obj->init(%arg);

Function

Internal method to initialize a new FFmpeg::StreamGroup object

Returns

true on success

Arguments

Arguments passed to new

streams()

Usage

@arr = $obj->streams();

Function

get the list of streams associated with this stream group.

Returns

a list of FFmpeg::Stream objects

Arguments

none, read only

_add_stream()

Usage

$obj->_add_stream();

Function

internal method. add one or more streams to this stream group.

Returns

true on success

Arguments

one or more FFmpeg::Stream objects

album()

Usage

$obj->album(); #get existing value

Function

album name of stream group, if applicable

Returns

value of album (a scalar)

Arguments

none, read-only

author()

Usage

$obj->author(); #get existing value

Function

entity responsible for encoding the stream group

Returns

value of author (a scalar)

Arguments

none, read-only

bit_rate()

Usage

$obj->bit_rate(); #get existing value

Function

average bit rate of stream group, in bits/second.

Returns

value of bit_rate (a scalar)

Arguments

none, read-only

Notes

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.

comment()

Usage

$obj->comment(); #get existing value

Function

comment on the stream group, if any

Returns

value of comment (a scalar)

Arguments

none, read-only

copyright()

Usage

$obj->copyright(); #get existing value

Function

copyright notice on stream group, if any

Returns

value of copyright (a scalar)

Arguments

none, read-only

data_offset()

Usage

$obj->data_offset(); #get existing value

Function

offset, in bytes, of first stream data. this is effectively the size of the file header.

Returns

value of data_offset (a scalar)

Arguments

none, read-only

duration()

Usage

 $obj->duration();        #get existing Time::Piece

Function

duration of the stream group. this is initialized to '00:00:00' if duration information is for some reason unable from the streamgroup.

Returns

an object of class Time::Piece

Arguments

none, read only

file_size()

Usage

$obj->file_size(); #get existing value

Function

file size of stream group, in bytes

Returns

value of file_size (a scalar)

Arguments

none, read-only

format()

Usage

 $obj->format();        #get existing FFmpeg::FileFormat

Function

format of the stream group (eg mpeg, avi, mov, &c)

Returns

an object of class FFmpeg::FileFormat

Arguments

none, read-only

genre()

Usage

$obj->genre(); #get existing value

Function

genre of stream group, if applicable

Returns

value of genre (a scalar)

Arguments

none, read-only

has_audio()

Usage

$obj->has_audio(); #get existing value

Function

detect if stream group contains audio

Returns

true if any of the contained FFmpeg::Stream objects is an audio stream, false otherwise

Arguments

none, read-only

has_video()

Usage

$obj->has_video(); #get existing value

Function

detect if stream group contains video

Returns

true if any of the contained FFmpeg::Stream objects is an video stream, false otherwise

Arguments

none, read-only

height()

Usage

$obj->height(); #get existing value

Function

height of first video stream in group. it is not implemented to access heights of other streams if they differ from the first.

Returns

value of height (a scalar)

Arguments

none, read-only

track()

Usage

$obj->track(); #get existing value

Function

track number of stream group, if applicable

Returns

value of track (a scalar)

Arguments

none, read-only

url()

Usage

$obj->url(); #get existing value

Function

url or system path of the stream group (ie path to file)

Returns

value of url (a scalar)

Arguments

none, read-only

width()

Usage

$obj->width(); #get existing value

Function

width of first video stream in group. it is not implemented to access widths of other streams if they differ from the first.

Returns

value of width (a scalar)

Arguments

none, read-only

year()

Usage

$obj->year(); #get existing value

Function

production year of stream group, if applicable

Returns

value ofyear (a scalar)

Arguments

none, read-only

_ffmpeg()

Usage

$obj->_ffmpeg(); #get existing value

Function

internal method. holds a reference to a FFmpeg object. use this to manipulate FFmpeg-C's state.

Returns

value of _ffmpeg (a scalar)

Arguments

none, read-only

capture_frame()

Usage

$obj-capture_frame( image_format => $ffmpeg_format, offset => $time_piece, frame_size => "320x240", output_file => "/path/to/file.ppm", ); >

Function

capture a frame from a streamgroup. currently implemented to capture only from first video stream, patches welcome.

Returns

a filehandle on image data on the frame requested in the format requested

Arguments

frame_rate (optional)

affect how many frames/second are captured. for instance, a value of 0.016 will result in one roughly frame per minute. FIXME, this argument should really be a Time::HiRes object.

frame_size (optional)

dimensions for image as a width x height string (eg "320x240"). defaults to streamgroup's native frame size

output_file (optional)

path to filename where captured frame willbe written. defaults to an anonymous tempfile created using File::Temp that is deleted upon program termination

recording_time (optional, IMPORTANT)

A Time::Piece object which determines how many seconds will be recorded.

offset (optional)

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

cpanm FFmpeg

perl -MCPAN -e shell
install FFmpeg