h265ize

Maintenance Fork

This repository is a maintained fork of the original h265ize project by Ayrton Sparling. The fork exists because the original project has not been maintained for a long time and no longer works reliably with current ffmpeg versions. Our goal is to rebuild h265ize on a maintainable basis while preserving the familiar CLI workflow as much as practical.

h265ize is a fire and forget weapon. A nodejs utility utilizing ffmpeg to encode large quantities of videos with the hevc codec. For more information visit ayrton.sparling.us.

Current Release

The current stable fork release is 0.7.0.

Highlights:

• most historic wrapper dependencies have been replaced with local helpers, making the fork noticeably more self-contained and future-proof
• fixed deprecation warnings and trimmed obsolete dependencies
• added --probe, --explain, --dry-run, --ignore-err, and --crop-preview
• improved crop handling, progress reporting, and metadata fallbacks
• added bundled Matroska regression fixtures for repeatable testing

Fork Status

This fork is now maintained at Codeberg:

• Repository: https://codeberg.org/diwou/h265ize
• Issues: https://codeberg.org/diwou/h265ize/issues

Planned focus areas:

• restore compatibility with current system ffmpeg and ffprobe
• modernize the development baseline for local maintenance
• keep the CLI behavior as compatible as reasonably possible
• improve diagnostics and regression safety for future fixes

This checkout is the active maintenance branch for the fork.

Fork-only Additions

These features were added in the maintained fork and are not part of the original upstream h265ize behavior:

• --dry-run / --show-command to print the final ffmpeg command before encoding starts
• --probe to print a compact source report and health check without encoding
• --explain to print the chosen encoding plan and its main decision paths
• --crop-preview to save crop preview screenshots and print a small report before encoding starts
• --ignore-err to tolerate lightly corrupted sources with ffmpeg -err_detect ignore_err
• compact live progress output with separate frame, percent, timemark, ETA, and estimated-size fields
• crop decision reports that explain how the final crop was chosen
• settings.json validation on startup so unknown keys and invalid values fail fast
• --crop old and the updated default medium preset for better modern quality defaults

Origin

• Original project: FallingSnow/h265ize
• Original author: Ayrton Sparling
• Original license: MIT
• Fork intent: continue maintenance and repair compatibility with modern toolchains

h265ize will support AV1 once encoder support becomes stable & plex supports decoding it.

Features

• Works on Windows, OSX, and Linux
• Batch file processing (can process a whole folder)
• Automatically detects video files (only processes video files found within a folder)
• Detects all audio tracks
• Preserves audio codecs
• Preserves audio track titles
• Detects and preserves all subtitles
• Detects audio language, if audio language is not your native language and native language subtitles are provided, makes those subtitles default
• Automatically upconvert vobsub/dvdsubs to srt subtitles on mkv files
• Detects bit depth and uses appropriate encoder profile (10-bit is common in high quality anime, supports 8-bit, 10-bit, 12-bit)
• Verbose and preview mode
• File overwrite detection (doesn't accidentally write over a file that already exists, other than in preview mode)
• Detects if file is already encoded in x265 and skips it
• Ability to make encoding previews
• Take screenshots of a finished encode
• Faulty encoding detection based on before and after video durations
• Maintains file structure in output folder (So in theory you could just take your 3tb movie folder and throw it into the script and the output folder should look that same but with x265 videos)

Dependencies

• Node.js - Required in order to run h265ize.
• ffmpeg - Does the video conversion among other things.

Option Dependencies

• mkvtoolnix - Used for upconverting subs in MKVs.
• vobsub2srt - Used for upconverting subs.

Installation

The maintained source repository is available at https://codeberg.org/diwou/h265ize.

Global installation from npm:

npm install -g @diwou/h265ize

The installed CLI command remains:

h265ize

Local development and testing:

Typical local setup:

git clone https://codeberg.org/diwou/h265ize.git
cd h265ize
npm install
node ./h265ize --help

The original unscoped h265ize package name is not assumed to be available.

Usage

./h265ize [--help] [-d <string>] [-q <0-51>] [-m <string>] [-n <string>] [-f <string>{3}] [-g <string>] [-l <integer>] [-o] [-p] [-v] [--bitdepth (8|10|12)] [--accurate-timestamps] [--as-preset <preset>] [--disable-upconvert] [--debug] [--probe] [--explain] [--dry-run] [--crop-preview] [--crop-preview-dir <path>] [--video-bitrate <integer>] [--he-audio] [--force-he-audio] [--downmix-he-audio] [--screenshots] [--delete] <file|directory>

Options

-d :Destination folder

-f :Container format to output; Options: mkv, mp4, m4v; default: mkv.

-l :Milliseconds to be encoded in preview mode; default: 30000

-m :x265 encoder preset; Options: ultrafast, superfast, veryfast, faster, fast, medium, slow, slower, veryslow, placebo; default: medium. Use -m fast if you want the previous default.

-n :The native language used to select default audio and subtitles. You may use 3 letter or 2 letter ISO 639-2 Alpha-3/Alpha-2 codes or the full language name. Examples: [eng|en|English|jpn|ja|Japanese]

-o :Override mode; Allows conversion of videos that are already encoded by the hevc codec

-p :Preview mode; Only process a 30 second preview

-q :Sets the qp quality target; default: 19

-v :Verbose mode; Display extra output

-x :Extra x265 options. Options can be found on the x265 options page

--bitdepth :Forces the output bitdepth (bitdepths 8, 10, and 12 are supported)

--accurate-timestamps :Accurate Timestamps (substantially increases file size but sometimes fixes timestamps)

--as-preset :My personal presets; Possible values are listed below; I'll be adding more as time goes on

--debug :Debug mode; Print extra debugging information, including progress diagnostics Progress output shows fps, frame progress, percent, timemark, ETA, and estimated size as separate fields.

--probe :Analyze the source and print a compact report without starting the encode stage

--explain :Explain the chosen encoding plan, including preset, crop, bitdepth, and rate-control decisions

--dry-run / --show-command :Show the final ffmpeg command and stop before the encode stage runs

--crop-preview :Save crop preview screenshots and print a small report before encoding starts

--crop-preview-dir :Write crop preview screenshots to a specific directory instead of the default output-relative folder

--ignore-err :Tolerate lightly corrupted inputs by passing ffmpeg -err_detect ignore_err to the source decoder

--delete :Deletes source after encoding is complete and replaces it with new encode; STRONGLY NOT RECOMMENDED

--disable-upconvert :Disable Upconvert; Stop converting Vobsub subs to srt; Only works with mkv's

--force-he-audio :Force High Efficiency audio encoding even on lossless audio tracks

--he-audio :High Efficiency audio mode

--downmix-he-audio :If there are more than 2.1 audio channels, downmix them to stereo.

--normalize-level :Define a level of normalization to be applied. See Issue 56 for more info.

--crop :Crop detection profile. Options: normal, analog, old, strict. Normal is the default; old uses the analog profile for older recordings.

--screenshots :Take 6 screenshots at regular intervals throughout the finished encode

--stats: Creates a stats file in the current working directory named h265ize.csv

--watch: Watches a folder for new files and process the videos

--video-bitrate :Sets the video bitrate, set to 0 to use qp instead of a target bitrate

--test: Test mode; Runs as normal, but do not encode any files

--help :Help; Shows help page

--version: Show version information

Run h265ize --help for more info.

Development

Local development currently assumes:

• a recent Node.js version
• npm as the package manager for this fork
• ffmpeg and ffprobe available in PATH
• installation via npm install

Recommended current baseline for this fork:

• Node.js 20 or newer
• current system ffmpeg

Typical local workflow:

npm install
node ./h265ize --help

Current release target for the maintained fork:

• first maintained fork release: 0.6.0
• planned npm package name: @diwou/h265ize
• CLI command: h265ize

Issue tracking for this fork lives at https://codeberg.org/diwou/h265ize/issues.

Regression Fixtures

The repository includes a small bundled Matroska validation set under fixtures/matroska/. These files are copied from the upstream Matroska test file project and are used for automated regression and smoke testing.

They are useful for checking:

• basic Matroska parsing
• multi-audio and multi-subtitle handling
• missing duration metadata
• commentary and language-tag edge cases

Aspresets

Preset | Description :----------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- grain | x265 --tune grain; better for film grain and detailed source material. fastdecode | x265 --tune fastdecode; favors easier playback on weaker decoders. zerolatency | x265 --tune zerolatency; useful for live or low-latency workflows. animation | x265 --tune animation; tuned for animated material. anime-high | A very good preset for all types of anime. Produces very good quality for a very small size. anime-medium | Same as anime-high but uses debanding to produce better color gradients. testing-ssim | x265's native preset just in SSIM mode.

Examples

• h265ize -v big_buck_bunny_1080p_h264.mov
• h265ize -v -d /home -q 25 big_buck_bunny_folder
• h265ize -d /home -q 25 --watch videos/folder

Stats file

The stats file is located at the current working directory under the name h265ize.csv. This must be enabled using the --stats flag. The file is composed of several lines. Each line is in the format

[Finish Encoding Date],[File Path],[Original Size],[Encoded size],[Compression Precent],[Encoding Duration]

For example:

08/13 02:46:03 PM, videos/[deanzel] Noir - 08 [BD 1080p Hi10p Dual Audio FLAC][a436a4e8].mkv, 1964MB, 504MB, 25.66%, 2:51:16

Creating 10bit & 12bit encodes

To create 10 or 12bit encodes, simply pass the --bitdepth 10 or --bitdepth 12 parameters. Make sure you have the correct libraries or ffmpeg static build.