Convert Video to Play on iPhone with ffmpeg on Linux

To play videos on an iPhone using ffmpeg on Linux, you must encode the output in H.264 video and AAC audio within an MP4 container. This ensures maximum compatibility with Apple’s hardware decoders, which expect specific pixel formats like yuv420p and limited-range color space rather than full-range RGB or non-standard HDR pipelines.

Understanding iOS Video Requirements

Apple devices are notoriously picky about media containers and codecs. While modern iPhones support a wide array of formats, the most reliable method for universal playback is sticking to the baseline specifications that have been supported since the early days of iOS. The primary goal is to produce an .mp4 file containing H.264 video and AAC audio. The video codec should be libx264, which is widely available on Linux systems and produces highly compatible streams. For audio, aac (specifically the built-in FFmpeg AAC encoder or fdk_aac if installed) is the standard. Using other codecs like HEVC (H.265) can work but may fail on older devices or in certain apps, so H.264 remains the safest bet for guaranteed playback. Crucially, the pixel format matters. Older drafts often suggested using full-range RGB, but this is incorrect. iOS expects YUV 4:2:0 color sampling with limited range (16-235). If you provide full-range data, the colors may appear washed out or incorrectly saturated. Therefore, explicitly setting the pixel format to yuv420p is essential.

Essential ffmpeg Command Structure

The core command for converting a video involves mapping the streams and specifying the codecs. A typical robust command looks like this:

ffmpeg -i input.mp4 -c:v libx264 -preset fast -crf 23 -pix_fmt yuv420p -c:a aac -b:a 192k output.mp4

Let's break down each component to ensure you understand why it is necessary.

• -i input.mp4: Specifies the source file. This can be any format FFmpeg supports, such as MKV, AVI, or MOV.
• -c:v libx264: Sets the video encoder to x264. This is the industry standard for H.264 encoding.
• -preset fast: Balances encoding speed and compression efficiency. Use medium or slow for better quality at the cost of time. Avoid ultrafast as it produces large files with poor quality.
• -crf 23: Constant Rate Factor. Lower values mean higher quality. 23 is the default and offers a good balance. For iPhone screens, 20-28 is usually sufficient. Values below 18 are rarely noticeable on mobile devices but significantly increase file size.
• -pix_fmt yuv420p: Forces the pixel format to YUV 4:2:0 planar. This is critical for iOS compatibility. Without this, FFmpeg might choose yuv444p or rgb24, which can cause playback issues or color distortion on Apple devices.
• -c:a aac: Sets the audio encoder to AAC.
• -b:a 192k: Sets the audio bitrate to 192 kbps. This is a standard high-quality bitrate for stereo audio on mobile devices.

For more advanced users who need to maintain aspect ratio or handle specific frame rates, you can add flags like -vf scale=-2:720 to downscale to 720p if the source is 4K, which reduces file size without noticeable quality loss on smaller screens.

Handling Audio and Metadata

Audio synchronization is vital. If your source video has multiple audio tracks, FFmpeg will only copy the first one by default. To ensure you get the correct track, use -map 0:a:0 to select the first audio stream from the first input. Metadata such as title, artist, and date can be included using the -metadata flag. However, iOS does not strictly require metadata for playback, so omitting it saves processing time. If you do include it, ensure special characters are properly escaped or removed to avoid container errors. Another common issue is duration reporting. Some converters strip duration metadata, causing the video player to show "00:00" or infinite length. Adding -movflags +faststart moves the moov atom to the beginning of the file, which allows for progressive downloading and ensures players correctly identify the file length.

ffmpeg -i input.mkv -c:v libx264 -crf 23 -pix_fmt yuv420p -c:a aac -b:a 192k -movflags +faststart output.mp4

This addition is particularly useful if you plan to transfer the video over Wi-Fi or cellular networks, as it improves streaming performance.

Common Pitfalls and Troubleshooting

Even with the correct commands, issues can arise. One frequent problem is the "Invalid data found when processing input" error. This usually means the source file is corrupted or uses a codec that FFmpeg cannot decode. Check the source file integrity first. Another issue is black screens with audio. This often happens when the pixel format is incompatible. Ensure you are using yuv420p. If you are working with HDR content, note that standard H.264 does not support HDR natively in a way iOS plays seamlessly without specific profiles. You may need to tone-map HDR to SDR using filters like tonemap, but this is complex and often unnecessary for general video conversion. If you encounter errors related to GPU acceleration, such as those involving NVENC, refer to our guide on solving failed queries for NVIDIA encoders. These errors typically stem from driver mismatches rather than FFmpeg configuration. Similarly, if you are capturing from a webcam, ensure your output format is suitable; v4l2 is an input format, not an output, so you must specify an output format like mp4. For users who want to generate videos from static images, check our tutorial on generating video with images at regular intervals, as the parameters differ slightly due to the lack of motion data. Additionally, verifying that your stream contains both video and audio before conversion can save debugging time. Finally, always test the converted file on the target device. iOS has strict caching mechanisms, and sometimes a file that plays in VLC on Linux may stutter on an iPhone due to buffer size limits. Using a lower bitrate or reducing resolution can resolve these playback stutters.

Frequently Asked Questions

Why does my video look washed out on iPhone?

This is almost always caused by an incorrect pixel format. iOS expects limited-range YUV, but FFmpeg might default to full-range RGB or YUV. Always force the -pix_fmt yuv420p flag to ensure correct color representation.

Can I use HEVC (H.265) instead of H.264?

Yes, newer iPhones support HEVC, but H.264 is still the most compatible option across all iOS versions and third-party apps. HEVC files are smaller but may fail to play on older devices or in restricted environments like some email attachments.

How do I reduce the file size without losing quality?

Increase the CRF value slightly (e.g., from 23 to 26) or lower the resolution using the -vf scale filter. Downscaling to 720p is often imperceptible on mobile screens while cutting file size by half compared to 1080p.

What if the audio is out of sync?

Sync issues usually result from variable frame rates in the source. Add -fflags +genpts to your command to regenerate timestamps, or convert the source to a constant frame rate using -r 30 before encoding.

Does faststart improve playback on iOS?

Yes, -movflags +faststart moves metadata to the start of the file, allowing iOS players to read the header immediately. This prevents buffering delays and ensures the duration is displayed correctly in the Photos app.