lisamelton/video_transcoding: HandBrake and FFmpeg Wrappers for Blu-ray and DVD Rips

What lisamelton/video_transcoding solves, and for whom

The README states the author created these tools "to transcode my collection of Blu-ray Discs and DVDs into a smaller, more portable format while remaining high enough quality to be mistaken for the originals." That sentence is the whole scope. This is not a general video pipeline, not a service, and not a library you call from another program. It is a small set of Ruby scripts for one person at a terminal with a shelf of discs and a machine that can run HandBrakeCLI.

The repository holds three scripts. transcode-video.rb does the actual re-encode. detect-crop.rb reports the unused outside area of a video track as TOP:BOTTOM:LEFT:RIGHT crop values on standard output. convert-video.rb changes container without transcoding, moving Matroska .mkv to MP4 or other media to Matroska. The README describes most of the package as "intelligent wrappers around Open Source software like HandBrake and FFmpeg."

Who it is for: someone who already rips discs, wants a repeatable command rather than a GUI session, and accepts that the default output is an 8-bit H.264 MKV. Who it is not for: anyone who needs a hosted transcoding service, a web interface, or per-title tuning done for them. The README also warns that the project was redesigned and rewritten and re-released in early 2025 "with different behavior and incompatible APIs," so people arriving from the older tools should "manage your expectations accordingly." That is a direct statement that old command lines may no longer work.

How the scripts drive HandBrakeCLI, ffprobe and ffmpeg

The data flow is one-directional and easy to reason about. You pass one or more media files as arguments. The script inspects the input, decides on video and audio settings, and hands those settings to HandBrakeCLI, which writes a new file. The external programs it depends on are HandBrakeCLI, ffprobe and ffmpeg. The README notes that ffprobe ships inside the ffmpeg package.

The default behavior is documented precisely. transcode-video.rb writes a Matroska .mkv file into the current working directory, with video in 8-bit H.264 and audio in multichannel AAC. 4K inputs are scaled down to 1080p automatically. HDR is converted to SDR. Video is cropped automatically. The first audio track is selected if one exists. Any forced subtitle is burned into the video or kept as a separate text-only track, depending on its original format.

Rate control is where the design opinion lives. The default uses the x264 software encoder with two-pass ratecontrol to hit a constant bitrate. The README is blunt about the cost: "Using two passes is a bit slower than other methods but the output quality is worth the wait, as is the output size." The default bitrate table is 5000 Kbps for 1080p Blu-ray sources, 2500 Kbps for 720p, and 1250 Kbps for 480p DVD. Audio defaults are 384 Kbps for surround, 128 Kbps for stereo, and 80 Kbps for mono.

Everything above is a default, not a constraint. The --mode and --audio-mode options replace the video and audio behavior, --add-audio extends the audio selection, and --extra passes arguments straight through to the HandBrakeCLI API.

Installing the Ruby scripts and transcoding a first file

There is no gem install for the current version. The README carries a warning that older releases were packaged via RubyGems and installed with the gem command, and that if you had it installed that way you should remove it with gem uninstall video_transcoding before continuing.

The scripts are standalone Ruby files, installed and updated manually. Clone the repository:

git clone https://github.com/lisamelton/video_transcoding.git

On Linux and macOS, mark each script executable:

chmod +x transcode-video.rb
chmod +x detect-crop.rb
chmod +x convert-video.rb

Then move or copy them into a directory listed in your PATH environment variable. On Windows that variable is $env:PATH; on Linux and macOS it is $PATH. Ruby itself must be present, and the README points to the Installing Ruby page on ruby-lang.org for that. HandBrakeCLI, ffprobe and ffmpeg must also be installed. On macOS the README gives Homebrew as an optional route:

brew install handbrake
brew install ffmpeg

For Windows, the README points to a third-party guide, JMoVS/installing_video_transcoding_on_windows, which covers manual binary installation and Windows Subsystem for Linux.

With the dependencies in place, every tool lists its options through --help:

transcode-video.rb --help

A first transcode takes a single file as an argument. On Linux and macOS:

transcode-video.rb /Rips/Movie.mkv

On Windows the README gives the equivalent form:

transcode-video.rb C:\Rips\Movie.mkv

What you should see is a new .mkv in the current working directory, produced by HandBrakeCLI under the default 8-bit H.264 and AAC settings. Because the default is two-pass x264, expect the run to take a while. To check the crop values before committing to a long encode, run detect-crop.rb on the same file and read the TOP:BOTTOM:LEFT:RIGHT numbers it prints.

hevc, nvenc-hevc and av1: what each mode costs you

The default mode targets 1080p and smaller SDR video. The other modes are for 4K HDR sources, and each one trades something different.

--mode hevc uses the x265_10bit software encoder with constant quality ratecontrol instead of constant bitrate. The README does not soften this: the mode is "reeeeeally slow. I mean, really slow." The payoff is quality and format support, since x265_10bit can produce output compatible with HDR10, HDR10+ and Dolby Vision.

--mode nvenc-hevc uses the nvenc_h265_10bit Nvidia hardware encoder, also with constant quality ratecontrol. The README's framing is candid: "you can't always afford to wait on x265_10bit." Output is slightly larger and somewhat lower in quality, but much faster. The constraint to remember is that nvenc_h265_10bit can only produce HDR10-compatible output, so Dolby Vision and HDR10+ are off the table in this mode.

--mode av1 uses the svt_av1_10bit software encoder with constant quality ratecontrol. The README calls AV1 the future and then immediately qualifies it: other than desktop PCs, most devices cannot play it yet. The encoder is described as still a work in progress, though faster than x265_10bit and usually producing smaller output. It can produce HDR10 and HDR10+ compatible output and pass through some metadata.

The practical reading: pick hevc when output compatibility matters more than your time, nvenc-hevc when your time matters more than a little quality, and av1 when you are encoding for a desktop player and want to experiment.

Where the default pipeline is the wrong tool

The defaults encode to 8-bit H.264 in Matroska with AAC audio. That is a compatibility-first choice, and it is the wrong one in several concrete situations.

If your source is 4K HDR, the default path silently scales to 1080p and converts HDR to SDR. That is stated behavior, not a bug, but it means a default run discards the resolution and color space you may have wanted to keep. You have to choose hevc, nvenc-hevc or av1 deliberately.

If your player is a device that cannot decode Matroska, the default output will not help you. That is what convert-video.rb exists for, and it is worth noting that it converts the container "without transcoding," so it cannot fix a codec problem, only a container problem.

If your source has multiple audio tracks you care about, the default selects only the first one. The README is explicit that the first audio track in the input, if available, is automatically selected. Additional tracks require --add-audio or a different --audio-mode.

If you need fast turnaround, the default is the wrong mode by construction. Two-pass x264 is chosen for output size and quality, and the README acknowledges it is slower than other methods. There is no claim anywhere that this is a batch service; the scripts are run from a shell, one invocation at a time. Anyone expecting a queue, a watch folder or a server has picked the wrong project.

Alternatives and the difference in approach

The most direct alternative is HandBrakeCLI itself, and the honest comparison is that this project is a layer on top of it. HandBrakeCLI exposes encoder, ratecontrol, crop, audio and subtitle settings directly, and it is the program doing the work either way. Choosing the raw CLI means writing those arguments yourself and keeping them consistent across a disc collection. Choosing these scripts means accepting the author's defaults and the --mode presets in exchange for shorter command lines. The README even keeps an escape hatch open: --extra passes arguments directly to the HandBrakeCLI API, so the wrapper does not lock you out of the underlying tool.

FFmpeg is the other real option, and it is a different kind of tool rather than a drop-in replacement. FFmpeg exposes filters, muxers and encoders at a lower level, and building a Blu-ray-to-MKV pipeline with it means assembling crop detection, scaling, tone mapping and audio mapping yourself. This project already depends on ffmpeg and ffprobe for inspection, which tells you the two are complementary rather than competing. If you want a graphical application instead of a shell command, neither this project nor HandBrakeCLI is the answer; the README describes every tool in the package as designed to be executed from the command line shell.

Maintenance, upgrade cost and the MIT licence

The repository is not archived, and the last push was on 2026-08-30. The most recent tagged release is 2025.01.28, following 2025.01.24 and 2025.01.23 in the same month. That release cluster lines up with the README's note that the project was redesigned, rewritten and re-released in early 2025.

The upgrade cost is unusually explicit for a project this size. The README states the re-release came "with different behavior and incompatible APIs" and that "some old conveniences were removed but new features and flexibility were added." If you have shell scripts or notes built around a pre-2025 version, assume they need review rather than assuming they still run. There is no documented deprecation shim and no migration table in the README. The CHANGELOG.md file in the repository root is where that history would live, and it is the first thing to read before upgrading.

Installation itself is manual by design. The scripts are standalone files that "must be installed and updated manually," which means no package manager handles updates for you. Updating means pulling the repository again and copying the scripts back into your PATH. That is a low-ceremony model, but it also means version drift is entirely your responsibility.

The licence is MIT, per the LICENSE file in the repository root. MIT is permissive and places few conditions on reuse, but this article is not legal advice; read the LICENSE text and your own organisation's policy if you plan to redistribute the scripts or ship them inside a product. One practical point that follows from the architecture: the scripts themselves are MIT, while HandBrakeCLI, ffmpeg and ffprobe are separate programs with their own licences, and you are responsible for those independently.

Editorial conclusion

Adopt it if you rip your own discs, are comfortable on a command line, and want a small set of Ruby scripts that drive HandBrakeCLI with sensible defaults instead of writing HandBrake arguments by hand. Do not adopt it if you need a graphical interface, a cloud transcoding service, or something that installs through a package manager, since the README says the scripts are standalone and updated manually and that the older RubyGems package should be uninstalled. Before committing, verify that handbrake, ffmpeg and ffprobe are on your PATH, run transcode-video.rb --help to see which modes your build exposes, and check the CHANGELOG for the incompatible API changes the README warns about if you are carrying over scripts from the pre-2025 tools.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. lisamelton/video_transcoding on GitHub
4. README
5. Releases