How to display “pts_time=…” while playing the video with ffplay

To display the pts_time value directly on the video screen during playback with ffplay, use the -vf flag with the drawtext filter and set the text option to 'pts:pts'. This method renders the Presentation Time Stamp as a visible overlay in real-time, allowing you to monitor frame timing without cluttering your terminal output. This approach is essential for debugging synchronization issues or analyzing frame distribution.

Understanding pts_time and ffplay Filters

The pts_time represents the Presentation Time Stamp of the current video frame, measured in seconds. It is a critical metric for understanding how media players schedule frames for display. While many users attempt to capture this data using packet-level debug flags, those methods often send information to standard error streams rather than the visual interface. To see this data visually, we must leverage the video filter chain available within ffplay. ffplay allows you to apply video filters dynamically using the -vf (video filter) argument. The most powerful tool for this specific task is the drawtext filter. This filter can render text onto the video stream at any position, using various expressions to calculate dynamic content. By configuring drawtext to evaluate the expression 'pts:pts', we instruct the player to extract the current presentation timestamp and convert it into a readable string for the overlay. For more complex debugging scenarios involving multiple streams or hardware acceleration, you might find related techniques useful. For instance, if you are working with dual monitors or specific output formats, understanding how filters interact with different backends is crucial. You may also refer to guides on Troubleshooting: 'v4l2' is not a suitable output format if you encounter issues when trying to route filtered video to external devices.

The Drawtext Filter Syntax

The drawtext filter accepts several parameters to control appearance and content. The core parameter for our goal is text. When you pass an expression starting with pts:, the filter evaluates the internal PTS variable. It is important to note that raw PTS values can be large floating-point numbers. The drawtext filter automatically formats these into a human-readable duration format (HH:MM:SS.mmm) by default, which is usually sufficient for monitoring purposes. If you need precise millisecond accuracy or a specific format, you can combine the pts expression with other functions, but for general monitoring, the simple 'pts:pts' syntax is robust and widely supported across FFmpeg versions.

Step-by-Step Implementation

To implement this solution, follow these steps carefully. Ensure you have a recent version of FFmpeg installed, as older versions may lack full support for dynamic expressions in drawtext.

1. Open your terminal: Navigate to the directory containing your video file or provide the full path to the file.
2. Construct the command: Use the following base structure:

   ffplay -vf "drawtext=text='pts:pts':fontsize=24:fontcolor=white:x=w-tw-10:y=h-th-10" input.mp4

   This command tells ffplay to load the video and apply a single video filter.
3. Analyze the components:
   • -vf: Specifies the video filter chain.
   • drawtext=...: Invokes the text drawing engine.
   • text='pts:pts': Sets the content to the current presentation time stamp.
   • fontsize=24: Makes the text large enough to read easily.
   • fontcolor=white: Ensures contrast against most video backgrounds.
   • x=w-tw-10: Positions the text horizontally at the right edge, subtracting the text width (tw) and a 10-pixel margin.
   • y=h-th-10: Positions the text vertically at the bottom edge, subtracting the text height (th) and a 10-pixel margin.
4. Execute and observe: Run the command. As the video plays, look at the bottom-right corner of the window. You will see the timestamp incrementing in sync with the audio and video playback.

Customizing the Display Position

Depending on your video resolution and personal preference, you might want to move the timestamp. The variables w (width), h (height), tw (text width), and th (text height) allow for dynamic positioning. For example, to place the timestamp in the top-left corner, change the x and y calculations to x=10 and y=10. This flexibility ensures the overlay does not obscure important visual elements in your video. If you are integrating this into a larger pipeline, such as playing videos on dual monitors, ensure that the filter graph remains lightweight to avoid performance drops. You can check out resources on Playing 2x4 KVideos on Dual Monitors with FFmpeg in Linux for advanced multi-stream management tips.

Troubleshooting Common Issues

Sometimes the text may not appear, or it may appear garbled. Here are common fixes:

• Missing Font: If you get an error about missing fonts, specify a font file explicitly using fontfile=/path/to/font.ttf. Standard system fonts like Arial or Helvetica usually work well.
• Performance Lag: On very low-end hardware, rendering text every frame can cause slight stuttering. Try reducing the fontsize or disabling other heavy filters.
• Incorrect Format: If you see hex codes instead of time, ensure you are using pts:pts and not just pts alone in some older contexts. The colon syntax is the standard for extracting the PTS value in expressions.

By using the drawtext filter with the pts:pts expression, you gain immediate visual feedback on your video's timing. This is invaluable for developers and quality assurance engineers who need to verify that their encoding pipelines are producing correctly timed frames.

Frequently Asked Questions

Can I display pts_time in milliseconds?

Yes, you can modify the expression to multiply the PTS by 1000. Use text='pts*1000' inside the drawtext filter to get integer millisecond values. Note that this removes the automatic HH:MM:SS formatting, so you may need to handle formatting manually if you expect long durations.

Why does my text disappear after a few seconds?

This usually happens if the video codec uses B-frames heavily and the PTS calculation becomes non-linear, or if there is a buffer underrun. Ensure your video file is not corrupted. Also, check if other filters in your chain are resetting the text state; keep the filter chain minimal for stability.

How do I change the color of the pts_time text?

You can adjust the fontcolor parameter in the drawtext filter. For example, use fontcolor=yellow or fontcolor=0xFFFFFF for hex colors. Adding a shadow with shadowcolor=black:shadowx=1:shadowy=1 can improve readability against bright backgrounds.

Is this method compatible with hardware accelerated playback?

Generally, yes, but it depends on your backend. If you are using OpenGL or VDPAU backends, the drawtext filter is applied before the hardware conversion. However, some older hardware decoders might struggle with additional filter graphs. Test with a small clip first to ensure smooth playback.

What if I want to show DTS instead of PTS?

You can replace pts:pts with dts:dts in the text expression. The Decoding Time Stamp (DTS) shows when the frame is decoded, while PTS shows when it is displayed. Comparing both can help identify decoding delays or reordering issues in the container.