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.
AlvinShenSSW pushed a commit to AlvinShenSSW/lada that referenced this pull request Jun 21, 2026
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 macOS.

Set 'hvc1' for every HEVC encoder when the container is ISOBMFF (mp4/mov/m4v).
Metadata-only change (no re-encode, no quality/size impact); non-Apple players
accept both tags.

Adapts ladaapp#153 by kazukinakai.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
AlvinShenSSW pushed a commit to AlvinShenSSW/lada that referenced this pull request Jun 22, 2026
…option)

PR ladaapp#153 set the hvc1 tag via stream.options['tag'], but PyAV/ffmpeg treats
that as an encoder private option and silently ignores it, so HEVC output in
mp4/mov/m4v stayed tagged 'hev1'. Verified with PyAV 16.1.0: options['tag']
yields 'hev1', while stream.codec_tag yields 'hvc1'. Set codec_tag on the
stream instead so the muxer FourCC is actually written.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@AlvinShenSSW

Copy link
Copy Markdown

Heads up — I tested this change and the hvc1 tag doesn't actually get applied. PyAV/ffmpeg treats stream.options as encoder private options and silently ignores the tag key, so HEVC output in mp4/mov/m4v stays tagged hev1.

Verified on PyAV 16.1.0:

approach resulting codec_tag_string
stream.options['tag'] = 'hvc1' hev1
stream.codec_tag = 'hvc1' hvc1

The tag is the muxer FourCC and needs to be set via video_stream_out.codec_tag = 'hvc1'. I opened #154 with that fix applied to all HEVC encoders (incl. hevc_videotoolbox), which supersedes this one.

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.

2 participants