How Does mpv Handle Corrupted Media Files?

When mpv encounters a corrupted media file, its default behavior is to aggressively attempt playback by skipping damaged frames, ignoring non-fatal stream errors, and relying on its robust FFmpeg backend to decode as much data as possible. Instead of immediately crashing or throwing a blocking error dialog, mpv logs the corruption to the terminal and tries to maintain synchronization between the audio and video tracks. If the file is completely unreadable or the container headers are destroyed, mpv will gracefully terminate the playback session and output a failure message to the console.

The Role of FFmpeg Demuxing and Decoding

Because mpv uses FFmpeg libavcodec and libavformat under the hood, it inherits highly resilient decoding capabilities. When a file contains bad sectors or missing packets:

• Frame Dropping: If a video frame is corrupted, mpv drops it and immediately attempts to decode the next valid keyframe (I-frame). This often manifests visually as brief pixelation, macroblocking, or a momentary freeze.
• Audio-Video Synchronization: If audio packets are missing, mpv will often mute the audio momentarily or stretch/drop frames to ensure the video track does not desynchronize from the timeline.
• Error Logging: mpv floods the terminal output with warning messages (typically in yellow or red text) indicating packet mismatches, decoding errors, or concealment attempts, allowing users to see exactly where the corruption lies.

Terminal Output and Error Codes

When running mpv from the command line, you will see real-time feedback regarding the file’s integrity. If the corruption is minor, playback continues despite the warnings. However, if the file is severely broken, mpv will halt and return specific exit codes:

• Fatal Errors: If the container format (e.g., MKV, MP4) is so corrupted that the player cannot parse the tracks or metadata, mpv stops immediately and outputs Error selecting/initializing video filter or No video or audio streams found.
• Exit Status: A completely unplayable file typically results in a non-zero exit status, signaling to external scripts or front-ends that the media initialization failed.

Customizing the Default Behavior

If you want to alter how mpv reacts to corrupted files, you can modify its behavior using specific command-line flags or by adding them to your mpv.conf file:

Halting on Errors

If you prefer mpv to stop playing immediately when an error is detected rather than trying to power through it, you can use:

--stop-on-playback-errors=yes

Adjusting Demuxer Cache

For files with corrupted indices or timestamps, increasing the demuxer cache can sometimes help mpv bridge the gap during playback:

--demuxer-max-bytes=500MiB