Debugging Video Playback Issues with FFprobe and FFmpeg

Yassine Qarbal — Tue, 03 Nov 2026 14:42:24 +0000

A video plays perfectly on a laptop but fails on an Android TV. The audio works, yet the screen stays black. Another file plays, but freezes every few seconds.

It's tempting to blame the network or the media player immediately. However, playback failures often involve several independent layers: container parsing, codec compatibility, hardware decoding, frame timestamps, and network delivery.

This tutorial demonstrates a reproducible workflow for diagnosing these problems using two open-source tools: FFprobe and FFmpeg.

1. Understand the Video Playback Pipeline

Before investigating a failure, it helps to understand what happens between receiving a media file and displaying an image.

A simplified playback pipeline looks like this:

Media file or network stream
          |
          v
    Container parser
          |
          v
    Audio/video tracks
          |
          v
     Video decoder
          |
          v
    Frame renderer
          |
          v
       Display

A failure at any stage can affect playback.

For example:

A container parser may fail to recognize a track.
The device may not support the video's codec profile.
Hardware decoding may be unavailable.
Incorrect timestamps may cause irregular presentation.
Network interruptions may prevent the player from receiving sufficient data.

The challenge is identifying which layer is responsible.

2. Inspect the Video Before Changing Player Settings

Start by collecting the media's technical properties.

ffprobe -v error \
  -show_entries \
  stream=index,codec_name,profile,width,height,pix_fmt,level,r_frame_rate \
  -of json input.mp4

This command reports information such as the video codec, profile, resolution, pixel format, and nominal frame rate.

For example, you might encounter these properties:

{
  "codec_name": "hevc",
  "profile": "Main 10",
  "width": 3840,
  "height": 2160,
  "pix_fmt": "yuv420p10le",
  "r_frame_rate": "60/1"
}

This describes a 4K HEVC video using a 10-bit pixel format at a nominal 60 frames per second.

Not every television supporting HEVC can decode that combination.

A device might support HEVC Main at 1080p while lacking support for Main 10 at 4K60.

Key principle: codec support alone does not guarantee compatibility. Resolution, profile, bit depth, level, and frame rate also matter.

3. Separate Container Problems from Codec Problems

MP4, MKV, and MPEG-TS are containers, not video compression formats.

A container can hold multiple audio and video streams, subtitles, and metadata.

If you suspect a container issue, try remuxing the file:

ffmpeg -i input.mkv \
  -map 0:v:0 -map 0:a? \
  -c copy output.mp4

This copies the selected streams without re-encoding them, provided the destination container supports their codecs and stream configurations.

If the command fails, inspect the error before switching containers or codecs.

If remuxing resolves playback, the original problem may involve container support, metadata, or the application's demultiplexer.

If the file still fails, continue investigating the decoding stage.

Remuxing does not magically make an unsupported video codec compatible with a television. ### Additional Reading: H.264 vs H.265 Compatibility

Understanding the difference between AVC and HEVC is useful when diagnosing playback failures. Compression efficiency, device capabilities, and codec profiles can all influence whether a video plays correctly.

Additional Reading: H.264 vs H.265 Compatibility

For a broader comparison of these technologies, see this French-language technical guide to H.264 and H.265, which covers bitrate efficiency, hardware compatibility, and common Smart TV playback issues.

4. Test Whether the Video Can Be Decoded

FFmpeg can attempt to decode the video without generating an output file.

ffmpeg -v warning \
  -i input.mp4 \
  -map 0:v:0 \
  -f null -

This is useful for detecting certain bitstream corruption and decoding errors.

However, successful software decoding on a computer does not prove that the video will work with a television's hardware decoder.

The computer and television may use entirely different decoding implementations.

To investigate a specific television, compare the stream properties with the device's documented media capabilities.

For Android-based devices, the Android media format documentation provides a useful starting point.

5. Build a Compatible Test File

When testing a playback issue, avoid changing multiple settings simultaneously.

One controlled experiment is to encode a short H.264 test file:

ffmpeg -i input.mp4 \
  -t 30 \
  -map 0:v:0 \
  -map 0:a:0? \
  -c:v libx264 \
  -pix_fmt yuv420p \
  -profile:v high \
  -level:v 4.0 \
  -vf "scale=1280:720" \
  -r 30 \
  -c:a aac \
  -b:a 128k \
  test-h264.mp4

This generates a short 720p test file with H.264 video and AAC audio, assuming the required encoders are available.

It provides a more conservative compatibility baseline, although it is not guaranteed to work on every device.

Now compare both versions on the same player:

Observation	Possible interpretation
Both videos fail	Investigate player configuration, container handling, or rendering
H.264 works; original HEVC fails	Investigate HEVC decoder capability
Both play locally but fail over the network	Investigate transport, buffering, or stream delivery
Video works but audio fails	Inspect the audio codec and output configuration

These observations narrow the investigation. They are not definitive diagnoses by themselves.

6. Investigate Frame Timestamps

Not every stuttering problem is caused by insufficient bandwidth.

Media timestamps determine when decoded frames should be presented.

Inspect video packet timestamps using:

ffprobe -v error \
  -select_streams v:0 \
  -show_entries \
  packet=pts_time,dts_time,duration_time \
  -of csv=p=0 input.mp4

Pay attention to:

Missing timestamps.
Unexpected gaps in presentation time.
Irregular packet durations.
Discontinuities near playback failures.

Remember that decoding timestamps and presentation timestamps serve different purposes.

For codecs using frame reordering, their values may legitimately differ.

Likewise, variable-frame-rate video can contain uneven frame intervals without being broken.

The goal is to distinguish expected behavior from actual timestamp corruption.

7. Diagnose Network Playback Separately

For HTTP-based video delivery, a successful local playback test can help separate network problems from decoding problems.

Common network-related symptoms include buffering, delayed startup, and intermittent interruptions.

Useful checks include:

Compare local and network playback of an equivalent media sample.
Observe response failures and connection interruptions.
Measure available throughput over time.
Check whether the stream bitrate exceeds sustainable network capacity.
Inspect player buffering events and error logs.

A download speed test alone is insufficient.

Network performance can change during playback, and a high average bandwidth does not rule out packet loss, latency spikes, or unstable delivery.

For adaptive streaming protocols, inspect playlist and segment behavior as well.

8. Use a Repeatable Debugging Checklist

Here is a compact process that can be integrated into a QA workflow:

START
  |
  v
Inspect media metadata
  |
  v
Verify container and codecs
  |
  v
Run FFmpeg decoding test
  |
  v
Create conservative H.264 sample
  |
  v
Compare playback on target device
  |
  +--> Local failure:
  |      inspect decoder and renderer
  |
  +--> Network-only failure:
  |      inspect delivery and buffering
  |
  v
Record results and reproduce

For reliable comparisons, record the device model, operating system version, media player version, video profile, and exact error.

That information is often more valuable than a vague report saying that a video "doesn't work."

Conclusion

Video playback debugging becomes much easier when each layer is tested independently.

FFprobe reveals what the media contains. FFmpeg helps identify decoding errors, test container changes, and create controlled comparison samples.

The most important lesson is to avoid treating every black screen or frozen video as a network problem.

A systematic approach saves time, makes bugs reproducible, and provides developers with evidence they can actually act on.

References

Disclosure: This article was prepared with AI writing assistance. Technical commands and recommendations should be validated against the target device and media before production use.

DEV Community: Yassine Qarbal