The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
FFMPEG-Effects-1.0.rev1
River stage zero No dependents
++
/ FFMPEG::Effects

NAME

FFMPEG::Effects - PERL Routines To Simplify ffmpeg Video Filter Usage.

VERSION

Version 1.0 -- For Use With FFMPEG Release Branch 1.0

SYNOPSIS

use FFMPEG::Effects;

        my $effect=FFMPEG::Effects->new('debug=1');

        $effect->Help('all');

        $effect->FadeIn('videofile=short.mpg', 
                        'size=cif', 
                        'framerate=30', 
                        'color=cyan', 
                        'opacity=70', 
                        'fadeinframes=90', 
                        'holdframes=31' ); 

        $effect->TitleSplash('size=cif',
                        'framerate=30', 
                        'color=black', 
                        'opacity=100', 
                        'fadeinframes=50', 
                        'fadeoutframes=50', 
                        'holdframes=30', 
                        'titleframes=299', 
                        'fontcolor=white', 
                        'font=Courier', 
                        'justify=center' );

        $effect->FadeOut('videofile=short.mpg', 
                        'size=cif', 
                        'framerate=30', 
                        'color=cyan', 
                        'opacity=70', 
                        'fadeoutframes=56', 
                        'holdframes=31' );

USAGE

The Methods Shown Above Are Shown With Their Relevant Arguments.

They Can Be Called With No Arguments And Will Attempt To Produce Useful Output.

Use This Module As In The Examples Above, Sending A List Of Quoted Arguments To Each Function.

Make a Call to Help() To Find Out More.

DEPENDENCIES

This Module is Written, and Numbered Against FFMPEG Release Branches. e.g.: FFMPEG::Effects-1.0 Is Written For Use With FFMPEG Release Branch 1.0.

The Version Number of This Module Will Always Be The Same As The FFMPEG Release It Is Written For. Check The $REVISION Number or Release Date To Make Sure You Have The Latest Version.

This Module Depends On The GhostScript And ImageMagick Programs. They Must Be Installed And In Your $PATH.

EXPLANATION

All Functions Listed in the USAGE Section Can Be Called Without Arguments and Will Attempt To Produce Something Meaningful.

When Particular Arguments To Functions Are Not Relevant They Will Be Ignored.

If A Particular Value Is Needed And It Is Not Specified A Default Value Will Be Used. The Help() Function Will List Default Values For Critical Settings.

The TitleSplash() Function Will Create A New Video Based on the 'textfile=' argument. If no textfile is specified it will create a single color video segmnent with the opacity you set, and the pngfile as the background, if any.

The FadeIn() and FadeOut() Methods Operate on A Video You Specify. See EXAMPLES Below, For More Info.

The Values for The Arguments Listed Below All Apply To The Output Video File, Except 'videofile', and 'textfile' Which Name Input Files.

ARGUMENTS

The Methods in FFMPEG::Effects Take The Following Arguments Where Relevant:

        'videofile'      The File Name of The Video File To Be Used As Input
        'size'           Video Image Size -- Can Use 'cif', etc, or <Width>x<Height>
        'framerate'      Output File Frame Rate
        'fadeinframes'   Number of Frames A Fade In Is Spread Over
        'fadeoutframes'  Number of Frames A Fade Out Is Spread Over
        'holdframes'     Number Of Frames Added to Beginning or End of Effect To Increase Its Duration
        'titleframes'    Number of Frames That Title Frame Will Persist
        'color'          The Fade To And Fade From Color
        'opacity'        Final Opacity of Fade Sequence
        'fontcolor'      Text Color Used In Generated Titles
        'justify'        'Left', 'Center', or 'Right' Justify Text In Generated Titles
        'textfile'       ASCII Text File Containing The Content For Generating Titles
        'pngfile'        PNG Image File Used To Underlay Generated Titles
        'font'           Font For Generated Titles. -- 'Helvetica' or 'Courier'

See SIZES, and COLORS below for specifying sizes and colors.

SIZES

FFMPEG::Effects understands the following Size Specs:

         "sqcif"  "128x96"
         "qcif"   "176x144"
         "cif"    "352x288"
         "4cif"   "704x576"
         "16cif"  "1408x1152"
         "qqvga"  "160x120"
         "qvga"   "320x240"
         "vga"    "640x480"
         "svga"   "800x600"
         "xga"    "1024x768"
         "uxga"   "1600x1200"
         "qxga"   "2048x1536"
         "sxga"   "1280x1024"
         "qsxga"  "2560x2048"
         "hsxga"  "5120x4096"
         "wvga"   "852x480"
         "wxga"   "1366x768"
         "wsxga"  "1600x1024"
         "wuxga"  "1920x1200"
         "woxga"  "2560x1600"
         "wqsxga" "3200x2048"
         "wquxga" "3840x2400"
         "whsxga" "6400x4096"
         "whuxga" "7680x4800"
         "cga"    "320x200"
         "ega"    "640x350"
         "hd480"  "852x480"
         "hd720"  "1280x720"

 Size Can Be Specified either by common name, or
 by "<Width>x<Height>", as above.

 This Module Has been repeatedly tested  with the sizes above up to
 1920x1200.

COLORS

Colors are case-insensitive, specified by common name as below:

        'red' 'blue' 'green' 'cyan' 'magenta' 'yellow' 'white' 'grey' 'black'

The 'color' argument to methods can be specied as above or as a Hexadecimal Value like '#RRGGBB' For Red Green And Blue.

The 'fontcolor' Argument is specified by color name as above.

CAVEATS

1) Unfortunately This Module Nneeds To Convert Videos To PNG Files To Do Some Of Its Effects. This Can Be Slow For Larger Image Sizes.

2) Likewise, This Module Currently Outputs Only .mpg Container Format. In FFMPEG This Is The 'mpeg1video' Video Format. It Will By Convention Transcode Whatever Input Format to mpeg1video Output.

3) The Duration Of The Video Is A Necessary Parameter. If The Internal Timecode of A File Is Broken, The Duration Can Not Be Obtained Correctly. Using A Video File As Input That Was Concatenated Together From Multiple Files Can Cause This Problem. For Best Results, Use Single MPEG Video Files That Were Generated With FFMPEG.

4) Audio Is Not Supported At This Time. FFMPEG::Effects produces a new video, so the audio from your original can be added to it after the fact.

HINTS

1) Small Image Sizes Are Processed VERY Fast. Larger Ones Become Considerably Slower. Try Prototyping Your Scenes With Thumbnail Sizes, And When You Have It To Your Liking, Render It Full-Size. Then You Will Have Time For Coffee.

2) This Module Uses an Auto-Scaling Algorithm Based on the Number of Lines, and The Longest Line in the 'textfile', to Adjust The Font Size In The Video.

3) This Module Was Designed For Working With A Video Split Up Into Separate Comparatively Short Scenes. It Is Intended To Be A Useful Tool For Scripting Routine Effects Like Titles And Fades.

4) Beacause of The Complexities Involved In Being Able To Specify Video Time In Seconds, This Module Always Deals With Effects On A Frame-by-Frame Basis.

EXAMPLES

This Module Ships With The Following Simple Example Scripts:

        FFMPEG-Effects.titlesplash.pl
        FFMPEG-Effects.help.pl
        FFMPEG-Effects.fadeout.pl
        FFMPEG-Effects.fadein.pl

SUBROUTINES/METHODS

This Module Has The Following Methods Available:

        new()  Instantiate The Class, and Set Debug Level.

        Help() Print Help.

        SetParams()  Set Necessary Parameters To Operate.

        FadeIn()  Fade In From Solid Or Transparent Color To Scene.

        FadeOut()  Fade Out From Scene To Solid Or Transparent Color.

        GetDuration()  Get Duration Seconds Of Video.

        GetStreamInfo()  Get Various Stream Parameters.

        TitleSplash()  Generate A Title From PostScript With Fade In And Out.

        PSTitleFrame() Returns PostScript Title Frame Template.

AUTHOR

Piero Bugoni, <PBugoni at cpan.org>

BUGS

Please Report Problems Using This Module To The ffmpeg-user mailing list. That is The Only Place That Will Be Checked.

SUPPORT

You can find documentation for this module with the UNIX `man` Command:

    man FFMPEG::Effects

Otherwise, Search The ffmpeg-user mailing List for References to This Module.

ACKNOWLEDGEMENTS

The FFMPEG Development Crew.

LICENSE AND COPYRIGHT

Copyright 2011-Present Piero Bugoni.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.