Real-Time Video Waveform Analysis in FFplay

This guide demonstrates how to use ffplay, the lightweight media player included with FFmpeg, to monitor media with real-time visual waveform analysis. You will learn the exact terminal commands required to display both video luminance/color waveforms (video scopes) and live audio waveforms directly alongside or on top of your video during playback.

Real-Time Video Waveform (Exposure & Color Analysis)

In video production, a waveform monitor displays signal levels such as luminance and chrominance across the frame, helping you assess exposure, clipping, and color balance.

1. Display Waveform Only

To replace the standard video display entirely with a real-time waveform monitor:

ffplay -vf "waveform" input.mp4

2. Display Original Video and Waveform Side by Side

To view your video alongside its real-time waveform analysis, use the split and hstack (horizontal stack) filters:

ffplay -vf "split=2[orig][temp];[temp]waveform=m=column:c=7[wf];[orig][wf]hstack" input.mp4
  • split=2[orig][temp]: Duplicates the video stream into two paths.
  • waveform=m=column:c=7[wf]: Converts the second stream into a column-mode waveform with colored components (c=7 displays RGB parades or YUV depending on input).
  • hstack: Places the original frame and the waveform side by side.

Real-Time Audio Waveform Analysis

If you need to analyze the sound frequency or amplitude of a video track in real time, you can render an audio waveform alongside the video.

1. Audio Waveform Stacked Underneath Video

To stack a live oscilloscope-style waveform below the video:

ffplay -filter_complex "[0:v]null[v];[0:a]showwaves=s=1280x240:mode=line[w];[v][w]vstack" input.mp4
  • showwaves: Converts the incoming audio track into a visual waveform.
  • s=1280x240: Sets the resolution of the audio display (adjust width to match your video).
  • mode=line: Renders the wave as a continuous line (other options include point, p2p, and cline).
  • vstack: Stacks the video on top and the audio waveform on the bottom.

2. Audio Waveform Overlaid on the Video

To overlay a semi-transparent audio waveform directly on top of the video playback:

ffplay -filter_complex "[0:a]showwaves=s=640x120:mode=line:colors=cyan[wave];[0:v][wave]overlay=x=10:y=H-h-10" input.mp4
  • colors=cyan: Sets the waveform color.
  • overlay=x=10:y=H-h-10: Anchors the waveform to the bottom-left corner with a 10-pixel margin.

Useful Shortcuts During Playback

While ffplay is running your waveform analysis, you can control playback directly:

  • Space: Pause or resume playback.
  • Left / Right Arrow: Seek backward or forward by 10 seconds.
  • Up / Down Arrow: Seek backward or forward by 1 minute.
  • s: Step forward a single frame (useful for examining exposure or audio spikes frame-by-frame).
  • f: Toggle fullscreen mode.
  • q or Esc: Exit playback.