Grafman's FFMPEG Developer Info

graphcomp.com Web

OVERVIEW

FFMPEG is a portable, opensource image/audio/video capture/conversion utility, supporting a large number of media formats/codecs.

It is built on a set of libraries, including libavformat and libavcodec - available via SVN (an opensource source control system):

svn checkout svn://svn.mplayerhq.hu/ffmpeg/trunk ffmpeg

Various binary builds exist for various platforms, particularly Redhat RPMs and Debian packages (apt-get install ffmpeg).

Windows availability: I have successfully built FFMPEG on Windows, but it is a convoluted process, requiring the installation of a unix-like POSIX shell (MSYS) and libraries (MinGW). Note: you do not need Cygwin. The resulting DLLs can be used in a normal MS Visual C++ development environment. The build process is documented on the Salyen's Building FFmpeg on Windows site.

USAGE

FFMPEG usage is documented on the FFMPEG/MPLAYER web site.

NOTE

To determine FFMPEG's version, run ffmpeg -version

To determine FFMPEG's supported formats/codecs, run ffmpeg -formats

For a dump of FFMPEG info, just run ffmpeg, with no parameters.

An example of a simple video conversion:

ffmpeg -i INPUT.avi -s 320x240 -t 180 -ar 44100 OUTPUT.flv

Parameters: -i identifies the input video, -s specifies the output video dimensions, -t truncates the video to 180 seconds, -ar sets the output audio bitrate. FFMPEG will use the input/output file extentions to determine the media formats/codecs to use; this can be overridden by other parameters.

INTERNALS

FFMPEG provides a streaming pipeline with a plugin interface (via shared libs) which supports the use of media filtering/effects.

FFMPEG comes with sister apps: FFPLAY (player for streamed media) and FFSERVER (a streaming media server and transcoder).

Essentially, FFMPEG provides a framework that:

Determines types of media files
Enumerates media streams that it contains
Discovers the codecs necessary to decode/decompress/read the streams
Scans frames and optionally passes them to specified plugins
Optionally converts/saves them to a target format

FFMPEG uses libavformat to determine file type, discover enclosed media streams, and identifies their associated codecs.

FFMPEG use libavcodec to query information about the streams, and to encode/decode the media. While libavcodec is primarily targeted towards audio/video media, it also provides codecs for image formats such as GIF and PNG.

FFMPEG supports virtual hooks (vhook) to pipeline plug-ins, to support media processing and effects. Pointers on creating your own vhook plug-ins below.

DEVELOPEMENT

Developer documentation is pretty sparse. You really need to read through the code - which is in ISO C90-compliant C.

FFMPEG source and APIs are documented via Doxygen.

Martin Böhme has posted some very useful primers on using libavformat and libavcodec for reading/writing video files.

Wikipedia has good documentation on creating an FFMPEG-compatible codec.

As mentioned in the overiew, FFMPEG is open source - available via a Subversion (SVN) source repository. The first step is to get the source. If you are on Windows, I highly recommend the Tortoise SVN client - it integrates into Explorer.

If you wish to participate in FFMPEG development, get familiar with the source base, read the Coding Rules and Development Policy.

You should join the ffmpeg-devel mailing list; you'll need to be registered as a SourceForge member. If you've checked in code, you should subscribe to ffmpeg-cvslog mailing list, to receive bug notices.

PLUGINS

Examples of FFMPEG plug-ins are available in the vhook source directory.

NOTE: As of this writing, the latest source from SVN breaks when trying to build vhooks. The following warning has been added by an FFMPEG contributor to framehook.h:

VHOOK is deprecated please help porting libmpcodecs or a better filter system to ffmpeg instead of wasting your time writing new fiters for this crappy one

As such, you should limit your dependency/use of vhooks until a new plugin architecture can be implemented.

In the mean time, you can continue to build vhooks by disabling ifeq ($(HAVE_IMLIB2),yes) in vhook/Makefile.

Note also: due to recent changes in FMPEG, the logo.c vhook mentioned below no longer works.

Rather than trying to continually update logo.c to work with a moving target, I will attempt to work with the FFMPEG group to establish a new, stable plugin architecture.

The watermark plug-in is a good example of compositing a movie (animated GIF) on another video.

I wrote a sample plug-in (logo.c) that composites a PNG logo (with alpha channels) or GIF (with transparency) onto a video; it demonstrates a fairly straight-forward way of using libavformat's av_read_image to load static images. I intend to submit this to the FFMPEG source base.

NOTE

To enable PNG support, you need to do the following:

uncomment AVImageFormat for png in libavformat/allformats.h
uncomment av_register_image_fromat for png in libavformat/allformats.c
rebuild FFMPEG

I have provided logo.c documentation in Doxygen format.

Here are PNG and GIF sample logos to test with:

I've created a sample MPEG using the above PNG logo, using the following commandline:

ffmpeg -i sample.wmv -vhook 'vhook_path/logo.so -f logo.png -x -10 -y -10 -w 4 -h 4' sample.mpg