willitplay

Will this video actually play in the browser? One command answers it, per browser, and prints the exact ffmpeg command that fixes it.

The file plays fine in VLC. You put it on a web page: black screen in Safari, no sound in Chrome, or nothing starts until 2 GB have downloaded. The information needed to debug this is scattered across ffprobe output, browser codec tables and old Stack Overflow answers. willitplay reads the file and just tells you.

$ willitplay holiday-cut.mp4

holiday-cut.mp4  (1.2 MB, 0:02)
  container mp4 | video hevc 1920x1080 (hev1) | audio ac3 6-ch

  ! Video codec 'hevc' does not play everywhere
     needs hardware HEVC decode (most recent machines have it); recent Firefox with hardware decode only
  ✗ HEVC tagged 'hev1': Safari and iOS refuse it
     Same codec, wrong label. A 2-second remux with -tag:v hvc1 fixes it.
  ✗ Audio 'ac3' is silent in Chrome/Edge, Firefox
     The video plays but with no sound there. Re-encode audio to AAC.
  ! moov atom at the end of the file (no faststart)
     Streamed over HTTP, playback cannot start until the whole file is downloaded.

Will it play?
  ~ Chrome/Edge    probably  (needs hardware HEVC decode · SILENT: AC-3 not licensed in Chrome)
  ~ Firefox        probably  (recent Firefox with hardware decode only · SILENT: AC-3)
  ✗ Safari (macOS) no  (HEVC is tagged 'hev1', Safari requires 'hvc1')
  ✗ iOS Safari     no  (HEVC is tagged 'hev1', Safari requires 'hvc1')

The fix
  Quick fix, video untouched (retag for Safari, audio to AAC):
    ffmpeg -i "holiday-cut.mp4" -c:v copy -tag:v hvc1 -c:a aac -b:a 160k -ac 2 -movflags +faststart "holiday-cut-web.mp4"
  Plays everywhere (re-encodes):
    ffmpeg -i "holiday-cut.mp4" -c:v libx264 -pix_fmt yuv420p -profile:v high -crf 18 -preset medium -c:a aac -b:a 160k -ac 2 -movflags +faststart "holiday-cut-web.mp4"

Install

Single file, Python 3.8+ standard library only. Needs ffprobe (part of FFmpeg) on your machine.

curl -fsSL https://raw.githubusercontent.com/ericfontaine13/willitplay/main/willitplay.py -o ~/.local/bin/willitplay && chmod +x ~/.local/bin/willitplay

Or with pipx:

pipx install git+https://github.com/ericfontaine13/willitplay

No ffprobe yet? brew install ffmpeg (macOS), sudo apt install ffmpeg (Debian/Ubuntu), winget install ffmpeg (Windows).

Usage

willitplay video.mp4              # human-readable report
willitplay *.mp4                  # several files at once
willitplay --json video.mp4       # machine-readable, for scripts

Exit codes make it a CI gate for your upload pipeline:

code	meaning
0	plays everywhere, nothing blocking
1	at least one problem found
2	file unreadable, or ffprobe missing

If the ffprobe on your PATH is broken or you want a specific build, point at it: FFPROBE=/opt/homebrew/bin/ffprobe willitplay video.mp4.

What it checks

check	the failure it catches
container	MKV/AVI/FLV/MPEG-TS served to a <video> tag, renamed-not-remuxed files
video codec	ProRes, DivX, MPEG-2 and friends; HEVC/AV1/VP9 hardware caveats per browser
HEVC atom tag	the infamous hev1 vs hvc1: same codec, Safari refuses one of them
pixel format	10-bit H.264 (plays nowhere), 4:2:2 / 4:4:4 chroma from cameras and editors
audio codec	AC-3/E-AC-3 that plays silent in Chrome and Firefox but fine in Safari, DTS, PCM, Vorbis
faststart	moov atom at the end: playback waits for the full download
HDR	PQ/HLG transfer that looks washed out on SDR screens, with a tone-map fix
metadata	stored rotation, variable frame rate, multiple tracks, embedded cover art, odd dimensions, missing duration

How the fix commands are chosen

The tool never re-encodes more than needed, and never runs anything itself: it prints commands, you run them.

1. If a lossless -c copy remux solves it (wrong container, missing faststart, hvc1 retag), that is the fix. Seconds, zero quality loss.
2. If only the audio is the problem, the video is copied untouched.
3. Only when the video itself cannot play (codec, bit depth, chroma) does it propose a full re-encode to H.264/AAC, the one combination that plays on effectively every browser and device.

Honesty notes

Browser support is a moving target. The verdicts here are deliberately conservative and aimed at "will this work for my visitors", not "does the newest browser on the newest hardware support it". probably means exactly that: recent browsers on recent hardware yes, older setups no. Corrections welcome, the matrices are three small dicts at the top of willitplay.py.

Tests

python3 -m unittest discover -s tests -v

35 tests. The integration suite uses ffmpeg to generate genuinely broken files (10-bit H.264, hev1-tagged HEVC, AC-3 audio, missing faststart, ProRes) and checks the diagnosis for each, then runs the tool's own suggested fix commands and verifies the repaired files pass.

License

MIT. Built by Eric Fontaine, co-founder of Chunkify, where the big brother of this tool transcodes VOD libraries for a living.