Troubleshooting Video Playback Issues faced by users

Hasan Tariq Updated by Hasan Tariq

Troubleshooting: Video Uploads Failing or Not Playing Correctly

The Issue

Common Symptoms:

  • The video plays perfectly on your local computer or laptop.
  • The video plays correctly within our platform's preview.
  • The video plays when sent manually via personal WhatsApp.
  • The Failure: When the system attempts to process the video or send it programmatically (e.g., via the WhatsApp Business API), it returns an error or fails to play on the user end.

The Cause: "Moov Atom" Placement

While the video file itself is not corrupt, the issue lies in how the data inside the MP4 file is structured.

Technically, this is known as MP4 Moov Atom Placement.

  • How your file is currently set up: The file's metadata (the index that tells a player the duration, frame rate, and codec) is written at the very end of the file.
  • Why this causes an error: Strictly linear playback engines (like those used by Meta/WhatsApp automation) read files from start to finish. If they don't see the metadata (the index) at the very beginning, they cannot decode the stream and will reject the file before reading the rest of it.

The Solution

To fix this, you need to relocate the metadata to the start of the file. This is often called making a video "Web Optimized" or "Fast Start" enabled.

We recommend using FFmpeg, a free, open-source software project that produces libraries and programs for handling multimedia data.

Step-by-Step Fix

  1. Ensure you have FFmpeg installed on your machine.
  2. Open your terminal or command prompt.
  3. Run the following command. This will copy your video data (without reducing quality) and simply move the metadata to the front of the file.
ffmpeg -i input.mp4 -c copy -movflags +faststart output.mp4

Breakdown of the command:

  • -i input.mp4: Your original video file.
  • -c copy: Tells the software to copy the video and audio streams exactly as they are (no re-encoding or quality loss).
  • -movflags +faststart: The critical flag that moves the "moov atom" (metadata) to the header of the file.
  • output.mp4: The name of your new, fixed file.

Once the process is complete, try uploading the output.mp4 file again. It should now be accepted by all playback engines and linear ingestion workflows.

Still facing issues?

If you have run this command and are still receiving playback errors, please reach out to our support team with a copy of the video file so we can investigate further.

Was this article helpful?

Journey integration for Email sends

Contact