Allen Day > FFmpeg > FFmpeg::StreamGroup

Download:
FFmpeg-6036.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  1
Open  1
View/Report Bugs
Module Version: 0.01   Source  

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-2006 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 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

syntax highlighting: