Why won't video from ffmpeg show in QuickTime, iMovie or quick preview?

I've been using ffmpeg for the occasional video conversion for quite some time, and recently discovered that H.264 (libx264) videos generated by ffmpeg aren't working in iMovie or QuickTime (nor will they play or show a preview in Finder with the quick view feature).

If I generate videos using OS X applications which internally use ffmpeg (e.g. MP4tools or Adapter) the videos work fine, but not when I try to use ffmpeg directly, e.g. to convert a video:

# ffmpeg -i input.avi output.mp4

or to combine some images into a video:

# ffmpeg -f image2 -pattern_type sequence image-%04d.png output.mp4

iMovie just imports the video as black/blank, quick preview just shows the file info, (but no video preview), and Quicktime tells me it cannot play it:

What's going on?!

In short, you (often) need to include the argument -pix_fmt yuv420p when using ffmpeg to generate H.264 content for Apple software/devices, and a bunch of other decoders that don't handle yuv444p.

# ffmpeg -i input.avi -pix_fmt yuv420p output.mp4

This is not mentioned in the output when using the defaults, but can be found in their Encode/H.264 guide.

It turns out that ffmpeg have chosen a default pixel format of yuv444p for libx264 encoding (under some circumstances), which is not compatible with Apple's software/hardware H.264 decoders (and perhaps not very widely compatible in general?). Unfortunately this seems unlikely to change, and there's no warning about it, so just something you have to know if using ffmpeg to make H.264 files.

As far as I can tell, if converting a video that's already using yuv420p it'll maintain that, but if converting from something a bit more exotic (e.g. images or a GIF or whatever) the pixel format must be specified for general Apple compatibility.