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

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 stream duration in seconds
$obj->duration(format=>'HMS'); #get existing value in HH::MM::SS format

Function

duration of the stream group in seconds. this is initialized to 0 if duration information is for some reason unable from the streamgroup.

Returns

value of duration (a float), or a formatted time string.

Arguments

none, read only

duration_HMS()

returns duration() in HH:MM:SS.uuuu format

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, video_geometry => "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

video_rate (optional): 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.
video_geometry (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 will be written. defaults to an anonymous tempfile created using File::Temp that is deleted upon program termination
duration (optional, IMPORTANT): A string specifying how many seconds will be recorded. defaults to 00:00:00.001 (typically resulting in 1 frame captured).
offset (optional): a string in HH:MM:SS format specifying offset at which to capture the frame. defaults to 00:00:00

transcode()

Usage

$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

); >

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.

Returns

A new FFmpeg::StreamGroup object.

Arguments

file_format (optional, required if 'output_file' argument is given)
output_file (optional): Path to file where captured frame will be written. Defaults to an anonymous tempfile created using File::Temp that is deleted upon program termination.
offset (optional): A string in HH:MM:SS.mmm format specifying offset at which to begin transcoding. Milliseconds optional. Defaults to 00:00:00.
duration (optional IMPORTANT): 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.
video_rate (optional): 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.
video_bitrate (optional): FIXME
video_codec (optional): FIXME
video_geometry (optional): Dimensions for image as a width x height string (eg "320x240"). defaults to StreamGroup's native frame size.
audio_rate (optional): FIXME
audio_bitrate (optional): FIXME
audio_codec (optional): FIXME

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.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

FEEDBACK

AUTHOR

COPYRIGHT AND LICENSE

APPENDIX

new()

init()

streams()

_add_stream()

album()

author()

bit_rate()

comment()

copyright()

data_offset()

duration()

duration_HMS()

file_size()

format()

genre()

has_audio()

has_video()

height()

track()

url()

width()

year()

_ffmpeg()

capture_frame()

transcode()

Module Install Instructions