Last updated
Common causes and fixes
| Problem | What VideoZ checks | Fix |
|---|---|---|
| HEVC tagged hev1 | Sample entry type in stsd | ffmpeg -i in.mp4 -c copy -tag:v hvc1 out.mp4 (no re-encode) |
| H.264 High 10, 4:2:2 or 4:4:4 | Profile in avcC | Re-encode: -c:v libx264 -profile:v high -pix_fmt yuv420p |
| Interlaced H.264 | frame_mbs_only_flag in the SPS | Deinterlace while re-encoding: -vf yadif |
| High H.264 level on older devices | Level in avcC (above 4.2) | Re-encode with -level 4.1 |
| Unusual audio (AAC Main, Opus on older iOS, PCM) | Audio sample entry and esds object type | Re-encode audio: -c:a aac |
| moov at the end of the file | Box order | ffmpeg -i in.mp4 -c copy -movflags +faststart out.mp4 |
Why hev1 vs hvc1 matters
Both tags mean HEVC. With hvc1, the parameter sets (VPS, SPS, PPS) are stored once in the sample description; with hev1 they may appear inside the stream instead. Apple’s players require hvc1, so an hev1 file often plays in VLC or Chrome but shows a black screen or refuses to open in Safari and QuickTime. Changing the tag is a remux, not a re-encode.
Reference
Apple’s HLS Authoring Specification is the most detailed public description of the codecs, profiles and tags Apple devices expect, and applies to progressive MP4 playback as well.
Frequently asked questions
- Why does the file play in VLC but not in Safari?
- VLC ships its own decoders and accepts almost anything. Safari uses the system’s hardware decoders, which only accept specific codecs, profiles and tags.
- Is H.264 Baseline or Main profile OK?
- Yes. Baseline, Main and High profile 8-bit 4:2:0 H.264 play on all current Apple devices.
- Do I need to re-encode?
- Only for profile, interlacing or audio problems. Fixing the hev1 tag or moving moov for faststart is a quick remux with -c copy.