Zane C. Bowers-Hadley

NAME

FFmpeg::Stream::Helper - Helper for streaming and transcoding using ffmpeg.

VERSION

Version 0.1.1

SYNOPSIS

This module is for helping generate a command for ffmpeg that should be good for streaming to HTML5.

This module also does it securely by using String::ShellQuote for every definable option passed to ffmpeg.

    # Defaults Are...
    # Output: -  ((standard out))
    # Bit Rate: 2000 kbps
    # Bound: undef
    # Format: mp4
    # Log Level: quiet
    # Threads: 0
    my $fsh=FFmpeg::Stream::Helper->new;

    #sets the bit rate to 1500
    $fsh->bitRateSet('1500');
    if ( $fsh->error ){
        warn('error:'.$fsh->error.': '.$fsh->errorString);
    }

    # Enable printing of errors.
    $fsh->loglevelSet('error');
    if ( $fsh->error ){
        warn('error:'.$fsh->error.': '.$fsh->errorString);
    }

    # set the width bound to 800 for scaling
    # aspect will be kept
    $fsh->boundSet('800');
    if ( $fsh->error ){
        warn('error:'.$fsh->error.': '.$fsh->errorString);
    }    

    # Disable pretty much all error output. This is great if you are sending stuff
    # to STDOUT and what you are sending it to can't tell the difference between it
    # and STDERR
    $fsh->loglevelSet('quiet');
    if ( $fsh->error ){
        warn('error:'.$fsh->error.': '.$fsh->errorString);
    }

    # What? No. We can't stop here. This is bat country.
    my $command=$fsh->command('/arc/video/movies/Fear and Loathing in Las Vegas.avi');
    if ( $fsh->error ){
        warn('error:'.$fsh->error.': '.$fsh->errorString);
    }

METHODS

new

Inits a new object for use.

No need for error checking. This will always succeed.

    my $fsh=FFmpeg::Stream::Helper->new;

bitRateGet

Returns the kilobits per second used for encoding.

    my $kbps=$fsh->boundGet;
    print "Bit Rate: ".$kbps."kbps\n"

bitRateSet

This sets the bitrate.

One argument is required and that is a integer represting the kilobits per second.

    $fsh->bitRateSet('1500');
    if ( $fsh->error ){
        warn('error:'.$fsh->error.': '.$fsh->errorString);
    }

boundGet

Returns the current width bound for scaling the video.

    my $bound=$fsh->boundGet;
    if ( ! defined( $bound ) ){
        print "No bound set.\n";
    }else{
        print "Bound: ".$bound."\n"
    }

boundSet

Sets a new bound. The bound is the maximum size the width can be while keeping aspect when it is scaled.

One argument is taken and that is the integer to use found bounding.

If undef is specified, then no scaling will be done.

    #calls it with a the bound being undef, removing it
        $fsh->boundSet;

    #sets it to 900px
    $fsh->boundSet('900');
    if ( $fsh->error ){
        warn('error:'.$fsh->error.': '.$fsh->errorString);
    }

command

The command to run ffmpeg with the specified options.

One argument is taken and that is the file name to run it for.

Escaping it is not needed as String::ShellQuote is used for that as well as any of the other values being passed to it.

    my $command=$fsh->command('/arc/video/movies/Fear and Loathing in Las Vegas.avi');
    if ( $fsh->error ){
        warn('error:'.$fsh->error.': '.$fsh->errorString);
    }

formatGet

Returns the current format to be used.

    my $format=$fsh->formatGet;
    print "Format: ".$format."\n";

formatSet

Sets the new format to use.

One argument is required and that is the format to use. The following are supported.

    mp4
    webm
    ogg

    $fsh->formatSet('webm');
    if ( $fsh->error ){
        warn('error:'.$fsh->error.': '.$fsh->errorString);
    }

loglevelGet

Returns what it is currently set to output to.

    my $output=$fsh->outputGet;
    print "Output: ".$output."\n";

loglevelSet

This sets the -loglevel for ffmpeg. Please see the man for that for the value.

One argument is taken and that is the -loglevel to use.

Currently it only recognizes the text version, which are as below.

    quiet
    panic
    fatal
    error
    warning
    info
    verbose
    debug
    trace


    $fsh->loglevelSet('panic');
    if ( $fsh->error ){
        warn('error:'.$fsh->error.': '.$fsh->errorString);
    }

presetsGet

Return the current x264 -preset value.

    my $output=$fsh->outputGet;
    print "Output: ".$output."\n";

outputGet

Returns what it is currently set to output to.

    my $output=$fsh->outputGet;
    print "Output: ".$output."\n";

outputSet

The file to output to. If not specified, "-" will be used.

One argument is required and that is the what it should output to.

There is no need to escape anything as that is handled by String::ShellQuote.

    #output to STDOUT
    $fsh->outputSet('-');
    if ( $fsh->error ){
        warn('error:'.$fsh->error.': '.$fsh->errorString);
    }

    #output to '/tmp/Fear and Loathing in Las Vegas.mp4'
    $fsh->outputSet('/tmp/Fear and Loathing in Las Vegas.mp4');
    if ( $fsh->error ){
        warn('error:'.$fsh->error.': '.$fsh->errorString);
    }

threadsGet

Gets the number of threads to use.

    my $threads=$fsh->threadsGet;
    if ( ( $threads eq '0' ) || ( $threads eq 'auto' ) ){
        print "The number of threads will automatically be determined.\n";
    }else{
        print $threads." threads will be used for this.\n";
    }

threadsSet

Sets the number of threads to use for encoding.

One argument is taken and that is a integeer representing the number of threads.

'auto' may also be specified and should be the same as '0'. If either are specified, ffmpeg will choose the best thread count.

    $fsh->threadsSet('0');
    if ( $fsh->error ){
        warn('error:'.$fsh->error.': '.$fsh->errorString);
    }

ERROR CODES/FLAGS

1/fileUNDEF

No file specified.

2/noFile

File does not exist or is not a file.

3/notINT

Not an integer.

4/formatUNDEF

Format is undef.

5/invalidFormat

Not a valid format. Must be one of the ones below.

    mp4
    webm
    ogg

The default is mp4.

6/loglevelUNDEF

Nothing specified to use for -loglevel.

7/invalidLoglevel

Not a valid -loglevel value.

The ones recognized by name are as below.

    quiet
    panic
    fatal
    error
    warning
    info
    verbose
    debug
    trace

Please see the ffmpeg man for descriptions.

8/threadsUNDEF

No value specified for what to use for -threads.

9/threadsBadVal

A bad value has been specified for threads. It needs to match one of the ones below.

    /^auto$/
    /[0123456789]*/

AUTHOR

Zane C. Bowers-Hadley, <vvelox at vvelox.net>

BUGS

Please report any bugs or feature requests to bug-ffmpeg-stream-helper at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=FFmpeg-Stream-Helper. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc FFmpeg::Stream::Helper

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

Copyright 2016 Zane C. Bowers-Hadley.

This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0

Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License. By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license.

If your Modified Version has been derived from a Modified Version made by someone other than you, you are nevertheless required to ensure that your Modified Version complies with the requirements of this license.

This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder.

This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement, then this Artistic License to you shall terminate on the date that such litigation is filed.

Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.