H.264 to HEVC Converter (Hardware Only)

Single script: hevc_converter.py
Modes: CLI + GUI (--gui)
Constraint: hardware encoding only (no CPU encoder fallback).

Target Hardware

1. Windows PC with AMD RX 7800 XT -> hevc_amf
2. MacBook Air M4 -> hevc_videotoolbox
3. Homelab with NVIDIA GTX 1070 -> hevc_nvenc

What The Tool Does

• Converts h264 sources (unless --force-non-h264 is set)
• Always outputs MP4 with -tag:v hvc1
• Copies audio tracks with -c:a copy
• Copies subtitle tracks by default with --subs copy
• Uses default target video bitrate ratio 0.50 (--target-ratio 0.50)
• Adapts tuning by resolution (360p to 2160p+)
• In --platform auto, tries hardware encoders in fallback order
• Skips conversion when computed target bitrate is greater than or equal to source bitrate

Quick Start

Single file:

python hevc_converter.py -i "D:\video\movie.mkv" -o "D:\video_hevc" --platform amd --quality quality_plus --target-ratio 0.50

Recursive folder:

python hevc_converter.py -i "D:\library" -o "D:\library_hevc" --recursive --platform auto --quality quality_plus --target-ratio 0.50

GUI:

python hevc_converter.py --gui

Dry-run (print commands only):

python hevc_converter.py -i "D:\video\movie.mp4" --dry-run --platform nvidia

Print ffmpeg command before each encode:

python hevc_converter.py -i "D:\video\movie.mp4" --platform amd --print-cmd

Encode and score quality vs original:

python hevc_converter.py -i "D:\video\movie.mp4" --platform amd --quality quality_plus --score all --score-sample-seconds 120

GUI Side-by-Side Comparison

In single-file mode, after conversion finishes, the GUI enables Open Side-by-Side. It launches:

video-compare -w 1920x1080 "<input_path>" "<output_path>"

video-compare must be available in your PATH.

Quality Profiles

Available profiles:

• archive
• quality_plus
• quality
• balanced
• compact

Objective Quality Scoring

Use --score to compare encoded output against the source after each conversion.

• --score none: disable scoring (default)
• --score ssim
• --score psnr
• --score vmaf (requires ffmpeg libvmaf filter)
• --score all (tries VMAF + SSIM + PSNR)

Use --score-sample-seconds N to score only the first N seconds (0 = full video).

The tool prints:

• overall score in 0..100
• individual metrics (vmaf, ssim, psnr)

Scoring fallback behavior:

• If libvmaf is missing, VMAF is skipped and the tool still reports SSIM/PSNR when requested.

Cross-Hardware Comparison Workflow

To compare AMD vs NVIDIA vs Apple quality at the same target ratio:

1. Use the same source clip on each machine.
2. Run the same profile and ratio (for example quality_plus, 0.50).
3. Use the same scoring settings (for example --score all --score-sample-seconds 120).
4. Compare overall, vmaf, ssim, and psnr from logs.

Recommended baseline command:

python hevc_converter.py -i "D:\video\sample.mp4" --platform auto --quality quality_plus --target-ratio 0.50 --score all --score-sample-seconds 120 --print-cmd

Encoder Tuning Summary

NVIDIA (hevc_nvenc)

• Preset mapping:
  • archive, quality_plus: p7
  • quality: p6
  • balanced: p5
  • compact: p4
• -tune hq, VBR + CQ, AQ enabled, lookahead by profile
• GOP around 2 seconds (-g fps*2), -bf 4

AMD (hevc_amf)

• archive:
  • -usage high_quality
  • -quality quality
  • -rc hqvbr
  • preanalysis + PA stack enabled
• quality_plus:
  • -usage high_quality
  • -quality quality
  • -rc qvbr
  • preanalysis enabled (lighter than archive)
• quality:
  • -usage high_quality
  • -quality quality
  • -rc qvbr
  • no heavy preanalysis stack
• balanced:
  • -usage transcoding
  • -quality balanced
  • -rc qvbr
• compact:
  • -usage transcoding
  • -quality speed
  • -rc qvbr

Practical guidance for 4K:

• archive: best quality, slowest (can approach realtime)
• quality_plus: near-archive quality, faster
• quality: strong middle ground
• balanced: much faster
• compact: fastest and most aggressive compression

Apple Silicon (hevc_videotoolbox)

• Uses bitrate-targeted hardware HEVC encode path
• Tries to disable software fallback where supported (-allow_sw 0)
• Uses quality-oriented options where available (-realtime 0, etc.)

Subtitles

• Default: --subs copy
• --subs copy: copy subtitle streams (may fail for unsupported subtitle codecs in MP4)
• --subs mov_text: convert subtitle streams to MP4 text subtitles
• --subs none: disable subtitle output

Requirements

• Python 3.10+
• ffmpeg and ffprobe in PATH
• ffmpeg build with hardware encoders:
  • hevc_nvenc
  • hevc_amf
  • hevc_videotoolbox

Official References

• FFmpeg encoder docs (NVENC/AMF/VideoToolbox):
  https://github.com/FFmpeg/FFmpeg/blob/master/doc/encoders.texi
• FFmpeg -tag[:stream_specifier] (-tag:v hvc1):
  https://ffmpeg.org/ffmpeg-doc.html
• NVIDIA FFmpeg usage (Video Codec SDK docs):
  https://docs.nvidia.com/video-technologies/video-codec-sdk/10.0/ffmpeg-with-nvidia-gpu/index.html
• NVIDIA Encode/Decode support matrix (GTX 1070):
  https://developer.nvidia.com/video-encode-and-decode-gpu-support-matrix-new
• AMD AMF tuning in FFmpeg:
  https://github.com/GPUOpen-LibrariesAndSDKs/AMF/wiki/AMF-Encoder-Settings-and-Tuning-in-FFmpeg
• Apple MacBook Air (M4) specs (hardware HEVC encode/decode):
  https://www.apple.com/macbook-air/specs/