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 because people are looking at graphs like this:

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.

Part of my work involves building automated transcoding systems based on FFmpeg that run on a variety of operating systems. If you're interested in hiring me to do something like this, use the contact form to get in touch.

Prerequisites: LAME

MP3 is the only commonly available audio format 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 CVS:

cvs -d:pserver:anonymous@lame.cvs.sourceforge.net:/cvsroot/lame 
  login
cvs -z3 
  -d:pserver:anonymous@lame.cvs.sourceforge.net:/cvsroot/lame 
  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 install open source projects:

cd lame-3.97
./configure
make
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
# (now download the file to this folder using your browser)
tar xvzf faad2-2.6.1.tar.gz
cd faad2
less INSTALL
# (follow the instructions you see there)

When working with open source projects, 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 10.4 and 10.3

Recent versions of FFmpeg wll 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 not compatible with newer versions of 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 the Subversion repository. This isn't too difficult, but there are some prerequisites that you may not have if you're not in the habit of compiling software from source. In particular, you need a Subversion client, and since the easiest way to get Subversion is probably to install it via Fink, you also need Fink.

Explaining how to install Fink is outside the scope of this article, but you should not have too much trouble if you start at the Fink project home page and follow the instructions there.

Once Fink is installed, use these commands to install the Subversion client:

sudo apt-get update
sudo apt-get install svn-client

You are now ready to fetch the source with Subversion. 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://svn.mplayerhq.hu/ffmpeg/trunk ffmpeg
cd ffmpeg

Next, configure and make

./configure --enable-libmp3lame --disable-vhook --enable-shared 
  --disable-mmx
make
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.

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 10000 
  svn://svn.mplayerhq.hu/ffmpeg/trunk ffmpeg-10000
cd ffmpeg-10000
./configure --enable-libmp3lame --enable-shared --disable-mmx 
  --disable-vhook
make
sudo make install

Once again, the --disable-mmx flag is not required on a PowerPC-based Mac. The revision number 10000 is just an example. If FFmpeg is not compiling on OS X because of a recent change, just 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 
  --disable-vhook
make
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 video.mov -b 600k -r 24 -ar 22050 -ab 96k video.flv

where

• "-b 600k" selects a video bitrate of 600 kilobits per second. This is a compromise between quality and bandwidth (with older versions of FFmpeg you would use "-b 600". Type "ffmpeg -h" to check which units are expected in your version);

• "-r 24" selects 24 video frames per second;

• "-ar 22050" selects an audio sample rate of 22050 Hz, which is sufficient for voice;

• "-ab 96k" selects an audio bit rate of 96 kilobits per second; you could go a little lower for voice-only audio (with older versions of FFmpeg you would use "-ab 96". Type "ffmpeg -h" to check.)

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.

FFmpeg error messages

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 has put together an FFmpeg user's guide which includes lots of useful information if you're just starting out with FFmpeg.

mplayer 맨페이지 옵션 무지 많고 쓸만한 example는 없어서 맨

[SETTING]

; MENCODER default parameter
PARAM_GENERAL = "$PATH_VIDEO$" -o "$PATH_OUT$" -mc 0

; do not use this option with mp2 or aac
PARAM_ETC_AUDIOPRELOAD0 = -audio-preload 0.0

; ENCODING TEST PARAM ( encoding 60 seconds of file only )
PARAM_TEST = -endpos 60

; CONTAINER
PARAM_CONTAINER_AVI = -noodml
PARAM_CONTAINER_MP4 = -of lavf -lavfopts format=MP4

; divx / xvid / x264 / MS-MPEG4(=Divx 3.1) / Motion JPEG / Lossless JPEG / WMV1(=WMV7) / WMV2(=WMV8)
PARAM_DIVX = -ovc lavc -lavcopts vcodec=mpeg4   -lavcopts vbitrate=$VID_BITRATE$  -ffourcc DIVX
PARAM_XVID = -ovc xvid -xvidencopts bitrate=$VID_BITRATE$
PARAM_DIV3 = -ovc lavc -lavcopts vcodec=msmpeg4 -lavcopts vbitrate=$VID_BITRATE$  -ffourcc DIV3
PARAM_MP43 = -ovc lavc -lavcopts vcodec=msmpeg4 -lavcopts vbitrate=$VID_BITRATE$  -ffourcc MP43
PARAM_WMV1 = -ovc lavc -lavcopts vcodec=wmv1    -lavcopts vbitrate=$VID_BITRATE$
PARAM_WMV2 = -ovc lavc -lavcopts vcodec=wmv2    -lavcopts vbitrate=$VID_BITRATE$
PARAM_X264 = -ovc x264 -x264encopts bitrate=$VID_BITRATE$:subq=1:global_header:trellis=0:level_idc=13
PARAM_DX50 = -ovc lavc -lavcopts vcodec=mpeg4   -lavcopts vbitrate=$VID_BITRATE$  -ffourcc DX50
PARAM_MJPG = -ovc lavc -lavcopts vcodec=mjpeg   -lavcopts vbitrate=$VID_BITRATE$
PARAM_LJPG = -ovc lavc -lavcopts vcodec=ljpeg   -lavcopts vbitrate=$VID_BITRATE$

; INDEX REBUILD ONLY
PARAM_INDEXREBUILD = -noodml "$PATH_VIDEO$" -o "$PATH_OUT$" -ovc copy -oac copy

; COPY ONLY
PARAM_VID_COPY = -ovc copy
PARAM_AUD_COPY = -oac copy

; SAMPLE RATE (optional)
PARAM_SRATE = -srate $AUD_SRATE$

; FPS (optional)
PARAM_FPS = -ofps $VID_FPS$

; VIDEO RESIZE OPTION (optional)
PARAM_RESIZE = -vf-add crop=$VID_CROP_W$:$VID_CROP_H$:-1:-1  -vf-add scale=$VID_SCALE_W$:$VID_SCALE_H$ -vf-add expand=$VID_W$:$VID_H$:-1:-1:1

; LAME MP3 OPTION (optional?) // -lameopts vol=$AUD_VOL$
PARAM_LAME = -oac mp3lame -lameopts vbr=$AUD_VBR$  -lameopts br=$AUD_BITRATE$ -lameopts mode=$AUD_MODE$ -lameopts aq=$AUD_ALGORITHM$ -lameopts padding=3
PARAM_AC3  = -oac lavc -lavcopts acodec=ac3:abitrate=$AUD_BITRATE$ -channels 2
PARAM_MP2  = -oac lavc -lavcopts acodec=mp2:abitrate=$AUD_BITRATE$ -channels 2
PARAM_AAC  = -oac faac -faacopts br=$AUD_BITRATE$:mpeg=4:object=2:raw

; subtitle option (optional)
PARAM_SUB = -font "$PATH_FONT$" -sub "$PATH_SUB$" -utf8  -subpos $SUB_POS$ -subfont-text-scale $SUB_SIZE$ -subfont-blur $SUB_BLUR$ -subfont-outline $SUB_OUTLINE$

; volnorm
PARAM_VOLNORM = -af volnorm
PARAM_VOLUME = -af volume=$AUD_VOL$:1

; multi thread video encoding
PARAM_MULTITHREAD = -lavcopts threads=$CPU_COUNT$ -xvidencopts threads=$CPU_COUNT$ -lavdopts threads=$CPU_COUNT$ -x264encopts threads=$CPU_COUNT$

 

[COMMENTS]
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;                                    여기 부터는 주석                                              ;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

* mencoder 에 대한 자세한 설명은 mplayer.html 파일 참조

* 변수 설명

$PATH_VIDEO$     : 비디오 원본 경로
$PATH_SUB$       : 자막 원본 경로 (utf8 이어야만 한다.)
$PATH_OUT$       : 출력 비디오 경로
$PATH_FONT$      : 폰트 경로
$VID_BITRATE$    : 비디오 비트레이트(kbps)
$VID_CROP_W$     : 원본이미지에서 잘라낼 폭
$VID_CROP_H$     :                       높이
$VID_FPS$        : 프레임(fps)
$VID_SCALE_W$    : 원본이미지에서 잘라낸 이미지를 리사이징할 크기
$VID_SCALE_H$    :
$VID_W$          : VID_SCALE_W 로 리사이징된 이미지를 확장할 크기 (주:위아래 검은 여백은 이때 생긴다.)
$VID_H$
$AUD_BITRATE$    : 오디오 비트레이트(bps)
$AUD_VOL$        : 오디오 볼륨 증폭(gain) (0~10)
$AUD_ALGORITHM$  : lame 오디오 인코딩 알고리즘 algorithmic quality (0-best/slowest, 9-worst/fastest)
$AUD_MODE$       : 오디오 모드 (생략시 자동) 0:stereo, 1:joint-stereo, 2:dualchannel, 3:mono
$AUD_VBR$        : 오디오 VBR 모드 0:cbr, 1:mt, 2:rh, 3:abr(권장), 4:mtrh
$AUD_SRATE$      : 오디오 비트레이트(Hz) 22100 44100 22050

 

* 파라메터 풀어 쓰기

MENCODER_PARAM =

// 기본 설정 
" -noodml "
// 경로 설정
" "$PATH_VIDEO$" -o "$PATH_OUT$" -font "$PATH_FONT$" "
// 비디오 설정
" -ovc lavc "
" -lavcopts vcodec=mpeg4 -lavcopts vbitrate=$VID_BITRATE$ "
// 비디오 스페셜
" -vf-add crop=$VID_CROP_W$:$VID_CROP_H$:-1:-1  "
// 비디오 설정
" -ofps $VID_FPS$ "
" -vf-add scale=$VID_SCALE_W$:$VID_SCALE_H$ "
" -vf-add expand=$VID_W$:$VID_H$:-1:-1:1 "
// 오디오 설정 (lame)
" -oac mp3lame "
" -lameopts vbr=$AUD_VBR$ -lameopts br=$AUD_BITRATE$ -lameopts vol=$AUD_VOL$ -lameopts mode=$AUD_MODE$ -lameopts aq=$AUD_ALGORITHM$"

SUB_PARAM =
// 자막 설정
" -utf8 -sub "$PATH_SUB$" -subpos $SUB_POS$ "
" -subfont-text-scale $SUB_SIZE$" 
" -subfont-blur $SUB_BLUR$ -subfont-outline $SUB_OUTLINE$ "

[힌트]
"-oac mp3lame" 대신 "-oac lavc" 를 쓰면 libavcodec 으로 mp3 인코딩이 가능하다. (차이점은 아직 잘 모르겠다.)