How to Output Detailed Debugging Logs from FFmpeg

When troubleshooting a failing codec or an unexpected error during media processing, enabling verbose logging in FFmpeg is essential. This article explains how to increase FFmpeg's log level to output detailed debugging information, redirect those logs to a text file for analysis, and use the built-in report feature to capture comprehensive diagnostic data.

Using the -loglevel Option

FFmpeg controls the verbosity of its terminal output using the -loglevel (or -v) option. By default, FFmpeg is set to info, which hides deep technical details about codec initialization and packet decoding.

To troubleshoot codec failures, you should increase the log level to verbose, debug, or trace.

  • verbose: Shows detailed information, including input/output stream configurations and codec details.
  • debug: Shows everything in verbose, plus step-by-step codec operations, decoding decisions, and library-specific logs.
  • trace: Extremely detailed, showing packet-level information (can produce massive amounts of text).

To use this option, place -loglevel debug (or -v debug) near the beginning of your command:

ffmpeg -loglevel debug -i input.mp4 -c:v libx264 output.mp4

Redirecting Debug Logs to a File

FFmpeg writes its console logs to stderr (standard error) rather than stdout (standard output). Because debug logs scroll by too quickly to read in the terminal, you should redirect the output to a text file.

Standard Shell Redirection

On Linux, macOS, or Windows (PowerShell/CMD), use the 2> operator to redirect standard error to a log file:

ffmpeg -loglevel debug -i input.mp4 -c:v libx264 output.mp4 2> ffmpeg_debug.log

Using the FFREPORT Environment Variable

The cleanest way to generate a detailed troubleshooting log is by using FFmpeg’s built-in FFREPORT environment variable. This forces FFmpeg to write a highly detailed log (equivalent to -loglevel debug) to an automatically named file in your current directory.

  • On Linux/macOS:

    export FFREPORT=file=ffmpeg_report.log:level=48
ffmpeg -i input.mp4 -c:v libx264 output.mp4

  • On Windows (PowerShell):

    $env:FFREPORT="file=ffmpeg_report.log:level=48"
ffmpeg -i input.mp4 -c:v libx264 output.mp4

In these commands, level=48 corresponds to the debug log level. After running the command, you can inspect ffmpeg_report.log with any text editor.

Analyzing the Log Output

Once you have generated the log file, open it and search for the following key indicators to diagnose the failing codec:

  • [codec_name]: Look for tags corresponding to your codec (e.g., [h264], [libx264], or [aac]). This localizes where the error occurred.
  • Error / Failure: Search for words like Error, Failed, Invalid, Unsupported, or not found.
  • Parser and Decoder Init: Look at the initialization sequence of the decoder to see if it failed to allocate memory, parse the header, or negotiate the pixel/sample format.