:: Open source :: Articles :: FFmpeg on Mac OS X How-to

Installing and using FFmpeg on Mac OS X

The FFmpeg project is a fast, accurate multimedia transcoder which can be applied in a variety of scenarios on OS X.

If you just want to add a good video transcoder to a toolset that already includes Final Cut Pro, Adobe Photoshop, and similar tools, FFmpegX may be your best choice because of its familiar Mac-style user interface.

But it's possible that you are interested in using FFmpeg to set up an automated, web based system to transcode a variety of input video formats to the Flash video format, which can easily be displayed on the web.

In this case it will be neccesary to approach FFmpeg on its own terms as a command-line, Linux-centric project. You will need to learn the installation techniques commonly used by open source projects, and the starting point for your work will be running Terminal and working mostly from the command line. This article will apply these techniques in a step-by-step manner to installing a version of FFmpeg which has most of the features you will need. Some techniques will be used without explanation, so be prepared to do some Googling to fill in the gaps in your knowledge.

Before you can follow these instructions, you must install Apple's Developer Tools.

Prerequisites: LAME

MP3 is the audio codec most often used with Flash video, so you will need an MP3 encoder. FFmpeg doesn't include one, but it will use LAME, which creates good quality audio files, if you install it. Header files will be needed during the compile, so it is not enough to install a prebuilt binary using a package manager. Instead follow these directions to compile it from source:

Start by creating a working directory:

mkdir ~/lame
cd ~/lame

On a good day you can get the latest source code release of LAME from Sourceforge. The file you want will be named lame-3.97.tar.gz or something similar.

If that doesn't work, do what I did and get the bleeding edge release from revision control:

cvs \
cvs -z3 \ \
  co -P lame

If you download the tar file, you need to unpack it as follows (this command is not necessary if you used CVS):

tar xvzf lame-3.97.tar.gz

After downloading and unpacking the source or checking it out from CVS, change to the main directory and then enter the three commands which are typically used to build open source projects:

cd lame-3.97
sudo make install

Each command will take a minute or so to complete. You should keep an eye out for any errors which may occur, but installing LAME is generally trouble-free.

Optional: FAAC and FAAD

Since Quicktime commonly uses AAC for audio, you may want to encode and decode that format. Here again FFmpeg doesn't include built-in codecs, but it will use the codecs provided by another open source project if you install them first.

Installing these codecs used to be so difficult that I wouldn't even have tried to address it in an introductory article, but recent improvements mean that you can simply download the latest releases and follow the instructions they provide, for example:

mkdir ~/faad
cd ~/faad
curl -O
tar xvzf faad2-2.6.1.tar.gz
cd faad2
# (follow the instructions you see there)

It's generally a good idea to poke around in the main directory for files named INSTALL and README and pay attention to the instructions there. Often that's all you need.

Building FFmpeg for Mac OS X Leopard

Recent versions of FFmpeg will compile successfully on versions of OS X as far back as 10.3. Before that OS X used an older version of the C compiler which is no longer compatible with FFmpeg. It's possible to get an older version of FFmpeg running on OS X 10.2 (read on), but you may not be satisfied with its capabilities.

If you have a choice it's best to run a recent version of FFmpeg, which means downloading the source code from one of the revision control systems used by the developers, or getting a nightly snapshot. Using revision control for something this simple is pretty easy, and it's a useful technique, so that's what we'll do. Recent versions of Xcode already include Subversion (a newish revision control tool which really isn't so bad), so we'll use that.

First create a working directory:

mkdir ~/ffmpeg
cd ~/ffmpeg

The up-to-date version of FFmpeg generally compiles cleanly, and that is the version you usually will want:

svn checkout svn:// ffmpeg
cd ffmpeg

Next, configure and make

./configure --enable-libmp3lame --enable-shared \
  --disable-mmx --arch=x86_64
sudo make install

The --disable-mmx flag is not required on a PowerPC. If you leave it out on an Intel Mac, you will probably get a compile error, but it's worth trying since it will provide a speed boost. If you installed the AAC codecs, add the flags --enable-libfaac and --enable-libfaad.

(According to a discussion on ffmpeg-user The "--arch" flag is required under Snow Leopard. Experiment.)

A fallback

When I tested for this article originally, the latest source in the Subversion repository did not compile cleanly. My workaround was to use a known stable revision. In general, FFmpeg is a moving target and you may encounter new issues that I did not. See the mailing lists for the latest information. Here's how to build FFmpeg if you have problems with the latest release

cd ~/ffmpeg
svn checkout --revision 15624 \
  svn:// ffmpeg-15624
cd ffmpeg-15624
./configure --enable-libmp3lame --enable-shared --disable-mmx
sudo make install

Once again, the --disable-mmx flag is not required on a PowerPC-based Mac. There is nothing special about revision 15624, it's just a version that happened to compile when this article was revised. If FFmpeg is not compiling on OS X because of a recent change, subtracting a small amount from the latest revision number will probably fix the issue. Work your way backwards until you find something that works.

Congratulations, you've installed FFmpeg. The next section describes a similar procedure for OS X 10.2, so skip ahead for additional information on running FFmpeg.

Building FFmpeg for Mac OS X 10.2

[Update: the OS X 10.2 procedure results in an ffmpeg binary that can decode only some of the video formats listed in the ffmpeg documentation. In particular, it can't decode Quicktime video. Take this into account before you go to the trouble of downloading and compiling it. On the other hand, this is one of the few free alternatives to Macromedia Flash for converting mpeg into Flash video, and you may be able to convert Quicktime to mpeg by other means.]

Start by creating a build directory:

mkdir ~/ffmpeg
cd ~/ffmpeg

Compiling on OS X 10.2 requires a patch, and it makes sense to patch against a known release. So we will download a recent release, which can be found by clicking here, and unpack it:

tar xvzf ffmpeg-0.4.9-pre1.tar.gz

I have modified a patch by Christoph Seibert to compile on Mac OS X 10.2 (if it doesn't work on another version of OS X, try Christoph's patch). Download it by right-clicking here and uncompress it:

gzip -d ffmpeg-0.4.9-pre1-macosx-10-2.patch.gz

Change to the ffmpeg source directory and apply the patch:

cd ffmpeg-0.4.9-pre1
patch -p1 < ../ffmpeg-0.4.9-pre1-macosx-10-2.patch

(For more information on using patch, see my article on diff and patch.)

Now build the project:

./configure --enable-mp3lame --enable-shared --enable-pthreads \
sudo make install

Some flv examples

FFmpeg is now installed. There are instructions in the doc/ directory, but basic commands are quite simple, and you will find that they are similar to ImageMagick, if you have used it. To convert an mpeg video to Flash, use:

ffmpeg -i video.mpg -ar 22050 video.flv

(The "-ar 22050" flag sets an audio sample rate of 22050 Hz. It is usually necessary to set a sample rate when encoding flv files because the MP3 encoder only supports rates of 11025, 22050, and 44100 Hz.) That's the basic idea, but in practical uses you will probably want to take control over more of the quality settings. A more realistic command would look like this:

ffmpeg -i -b 600k -r 24 -ar 22050 -ab 96k video.flv


These are the parameters you will adjust most often. Finding the perfect values for your material is a matter of experiment.


flv 1.1 metadata

FFmpeg is a moving target, and this issue is resolved in the latest version of FFmpeg from the Subversion repository. In older versions, however, FFmpeg didn't write the FLV metadata which is required for the scrubber bar to work in some Flash video players.

If you experience this problem, there is a fix:

  1. First, try upgrading to the latest version of FFmpeg.

  2. If for some reason you can't upgrade, get the FLV Metadata Injector (Windows-only), or FLVTool2 (OS X and Linux) and process your flv files with them. See the links for instructions.

make build errors

According to the mailing list, FFmpeg is sensitive to the version of "make" you are running and the build will fail in many cases. Recent testing shows that the current stable version of GNU make (3.81) will work, but 3.79 and 3.80 will both fail, for different reasons. BSD make (also distributed with OS X as "bsdmake") will fail with multiple errors. If you are having a problem with make, the simple solution would be to upgrade Developer Tools.

Alternate download methods

If your version of Xcode doesn't include a Subversion client, refer to the FFmpeg download page and pick another method to get the source, for example:

curl -O
tar xvjf ffmpeg-export-snapshot.tar.bz2

Runtime errors

Some FFmpeg error messages are a little cryptic. Here are a few I have encountered:

  1. If you try to decode a video format that FFmpeg does not understand, you get the message

    No audio or video streams available

    Just try again with another format, or recompile FFmpeg to add the codec you need.

  2. If you build FFmpeg without the --enable-libmp3lame flag and try to encode to Flash video, the audio stream will be silently discarded. Only by encoding to another format that does not require MP3 will you discover that this is not the expected behavior. In this case just follow the instructions in this article to install LAME, if necessary, and recompile FFmpeg with LAME support.

  3. When encoding to MP3, you may receive the message

    Could not write header for output file #0 (incorrect codec
    parameters ?)

    In practice, this means that you should use the -ar flag to set an audio sample rate of 11025, 22050, or 44100 Hz.

Further reading

Now that you have video in Flash video format, you may be interested in publishing it on the web. See my Flash Video Howto for complete instructions.

Howard Pritchett publishes an FFmpeg user's guide which includes lots of useful information if you're just starting out with FFmpeg.

Comment on this article and its topic

Copyright © 2006-2008 Stephen Jungels. Written permission is required to repost or reprint this article

Valid HTML 4.01 Transitional

Last modified: Tue Feb 22 10:41:16 CST 2011