Skip to content

Tag HEVC output as hvc1 for all HEVC encoders in ISOBMFF containers#153

Open
kazukinakai wants to merge 1 commit into
ladaapp:mainfrom
kazukinakai:feat/hvc1-faststart
Open

Tag HEVC output as hvc1 for all HEVC encoders in ISOBMFF containers#153
kazukinakai wants to merge 1 commit into
ladaapp:mainfrom
kazukinakai:feat/hvc1-faststart

Conversation

@kazukinakai

Copy link
Copy Markdown

Problem

VideoWriter only sets the hvc1 codec tag for hevc_videotoolbox. ffmpeg defaults HEVC-in-MP4/MOV to the hev1 tag, which is spec-valid but rejected by Apple's AVFoundation — Finder thumbnails, QuickLook, QuickTime Player and Safari all treat hev1-tagged HEVC as unsupported.

So restored output produced with hevc_nvenc (and libx265 / hevc_amf / hevc_qsv) silently fails to preview/play on Apple platforms, while hevc_videotoolbox output works. We hit exactly this: NVENC-encoded restored .mp4 files have no Finder thumbnail and won't QuickLook on macOS.

Fix

Set tag = 'hvc1' for every HEVC encoder when the container is ISOBMFF (.mp4 / .mov / .m4v), not just hevc_videotoolbox:

hevc_encoders = ('libx265', 'hevc_nvenc', 'hevc_amf', 'hevc_qsv', 'hevc_videotoolbox')
if encoder in hevc_encoders and output_path.lower().endswith(('.mp4', '.mov', '.m4v')):
    stream_options['tag'] = 'hvc1'

It's a metadata-only change (no re-encode, no quality/size impact), and non-Apple players accept both hev1 and hvc1.

Note on venue

I see the project's canonical home is Codeberg and GitHub is a mirror — apologies if PRs here aren't your preferred flow. Happy to re-open this on Codeberg; opening here since this is where my fork lives. The patch is a single small diff in lada/utils/video_utils.py and easy to cherry-pick.

The VideoWriter only set the 'hvc1' codec tag for hevc_videotoolbox. ffmpeg
defaults HEVC-in-MP4/MOV to the 'hev1' tag, which is spec-valid but rejected by
Apple's AVFoundation: Finder thumbnails, QuickLook, QuickTime Player and Safari
all treat hev1-tagged HEVC as unsupported. So output from hevc_nvenc / libx265 /
hevc_amf / hevc_qsv silently failed to preview/play on Apple platforms.

Set 'hvc1' for every HEVC encoder when the container is ISOBMFF (mp4/mov/m4v).
It's a metadata-only change (no re-encode, no quality/size impact) and non-Apple
players accept both tags.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant