Video Transcoding

Tools to transcode, inspect and convert videos.

Hi, I'm Lisa Melton. I 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.

Most of the tools in this package are essentially intelligent wrappers around Open Source software like HandBrake and FFmpeg. And they're all designed to be executed from the command line shell:

• transcode-video.rb Transcode essential media tracks into a smaller, more portable format while remaining high enough quality to be mistaken for the original.

• detect-crop.rb Detect the unused outside area of video tracks and print TOP:BOTTOM:LEFT:RIGHT crop values to standard output.

• convert-video.rb Convert a media file from Matroska .mkv format to MP4 format or other media to Matroksa format without transcoding.

These tools work on Windows, Linux and macOS. They're standalone Ruby scripts which must be installed and updated manually. You can retrieve them via the command line by cloning the entire repository like this:

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

Or download it directly from the GitHub website here:

https://github.com/lisamelton/video_transcoding

On Linux and macOS, make sure each script is executable by setting their permissions like this:

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

And then move or copy them to a directory listed in your $env:PATH environment variable on Windows or $PATH environment variable on Linux and macOS.

Because they're written in Ruby, each script requires that language's runtime and interpreter. See "Installing Ruby" if you don't have it on your platform.

Additional software is required for all the scripts to function properly, specifically these command line programs:

• HandBrakeCLI
• ffprobe
• ffmpeg

See "HandBrake Downloads (Command Line)" and "Download FFmpeg to find versions for your platform.

On macOS, all of these programs can be easily installed via Homebrew, an optional package manager:

brew install handbrake
brew install ffmpeg

The ffprobe program is included within the ffmpeg package.

On Windows, it's best to follow one of the two methods described here, manually installing binaries or installing into the Windows Subsystem for Linux:

https://github.com/JMoVS/installing_video_transcoding_on_windows

For each tool in this package, use --help to list the options available for that tool along with brief instructions on their usage. For example:

transcode-video.rb --help

And since all of the tools take one or more media files as arguments, using them can be as simple as this on Windows:

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

Or this on Linux and macOS:

transcode-video.rb /Rips/Movie.mkv

The transcode-video.rb tool creates a Matroska .mkv format file in the current working directory with video in 8-bit H.264 format and audio in multichannel AAC format.

4K inputs are automatically scaled to 1080p and HDR is automatically converted to SDR color space.

Video is automatically cropped.

The first audio track in the input, if available, is automatically selected.

Any forced subtitles are automatically burned into the video track or included as separate text-only tracks depending on their original format.

The venerable x264 software-based encoder is used with two-pass ratecontrol to produce a constant bitrate. Using two passes is a bit slower than other methods but the output quality is worth the wait, as is the output size. This Is The Way™.

Video:

Audio:

All this behavior can easily be changed by selecting different video and audio modes via the --mode and --audio-mode options, using other options like --add-audio or by passing arguments directly to the HandBrakeCLI API via the --extra option. It's very, very flexible.

While the default behavior of transcode-video.rb is focused on creating high-quality 1080p and smaller-resolution SDR videos, other modes are available.

Designed for 4K HDR content, this mode uses the x265_10bit software-based encoder with a constant quality (instead of a constant bitrate) ratecontrol system. But it's reeeeeally slow. I mean, really slow. However, it does produce high-quality output. You just have to decide whether it's worth it.

One big selling point is that the x265_10bit encoder can produce output compatible with both the HDR10 and HDR10+ standards as well as Dolby Vision.

Also designed for 4K HDR content, this mode uses the nvenc_h265_10bit Nvidia hardware-based encoder, also with a constant quality ratecontrol system, because you can't always afford to wait on x265_10bit. The output will be slightly larger and somewhat lesser in quality but you'll get it a LOT faster. A lot.

But be aware that the nvenc_h265_10bit encoder can only produce HDR10-compatible output.

This Is The Future. Unfortunately, the AV1 video format is currently the Star Trek Future. Other than desktop PCs, most devices can't play it yet. This script uses the svt_av1_10bit software-based encoder with a constant quality ratecontrol system. Although the encoder is already quite good, it's still a work in progress. But it's faster than x265_10bit and usually produces smaller output. So it's certainly worth a try. Especially on 4K HDR content.

The svt_av1_10bit encoder can produce output compatible with the HDR10 and HDR10+ standards and pass through Dolby Vision metadata.

When using this mode, audio output is in Opus format at slightly lower bitrates. Why Opus? Because it's higher quality than AAC and if you can play AV1 format video then you can certainly play Opus format audio.

The transcode-video.rb tool has less than 20 options. But the HandBrakeCLI API has over 100. It's YUUUUUGE! And you can pass arguments directly to that API via the --extra option.

But use the -x shortcut because who wants to do all that work typing --extra.

Even though the convert-video.rb tool is included in this project, you can output to MP4 format from transcode-video.rb itself like this:

transcode-video.rb -x format=av_mp4 C:\Rips\Movie.mkv

What if you want to tweak a crop instead of relying on HandBrakeCLI's new and improved algorithm? It's as simple as:

transcode-video.rb -x crop=140:140:0:0 C:\Rips\Movie.mkv

If you want to get faster results and are willing to live dangerously when using x264, you can disable two-pass transcoding like this:

transcode-video.rb -x no-multi-pass C:\Rips\Movie.mkv

What about filters? Easy peasy. You can apply any of HandBrakeCLI's built-in filters this way:

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

Want to waste space? Then keep your original audio track in your output by changing the audio encoder:

transcode-video.rb -x aencoder=copy C:\Rips\Movie.mkv

And if you just want an excerpt of your input, you can specify a chapter range for your output:

transcode-video.rb -x chapters=3-5 C:\Rips\Movie.mkv

Please report bugs or ask questions by creating a new issue on GitHub. I always try to respond quickly but sometimes it may take as long as 24 hours.

This project would not be possible without my collaborators on the Video Transcoding Slack who spend countless hours reviewing, testing, documenting and supporting this software.

Video Transcoding is copyright Lisa Melton and available under an MIT license.