A MakeMKV + HandBrake productivity tool.

HandyMKV is a tool that is designed to automate the process of ripping discs using MakeMKV and then encoding the resulting files using Handbrake.

I found the process of manually ripping using MakeMKV and then encoding using HandBrake to be time consuming, disjointed, and error prone. I wanted a tool that would automate the process and provide a more user-friendly experience. Additionally, I wanted to offload the process from my main desktop computer to my home server which is headless and does not have a GUI. HandyMKV was created to address these needs.

As I developed HandyMKV, I found that I was able to add features that I found useful and that made the process faster and easier. I hope that others will find HandyMKV useful and that it will save them time and effort.

• Rip titles from discs using MakeMKV
• Encode video files using HandBrake
• Flexible configuration options
• Clear and concise progress display
• Concurrency to reduce overall processing time
• Summary of space saved and time elapsed
• Automated cleanup of raw unencoded files
• Run history — browse and inspect past ripping/encoding sessions
• Automations — run custom scripts after encoding with parameters sourced from run data, environment variables, or user prompts
• Parsing of HandBrakeCLI and makemkvcon output to provide a more user-friendly experience

Its primary aim is to save time and effort by removing the disconnected nature of performing these tasks manually and/or sequentially. Concurrency is used to reduce the overall time taken to complete the process.

HandyMKV is designed to be easy to setup and use. Once a configuration has been created the process of ripping and encoding a disc is simplified to a single command and a few prompts.

Output from the process is displayed in a clear and concise manner to keep the user informed of the progress of the tasks.

HandyMKV is designed to be flexible. The user can select which titles to rip from the disc and can configure the encoding options to suit their needs. Encoding options can be setup in three ways:

• Using HandyMKV Simplified Encoding Options - Essentially a collection of settings which are meant to address the most common use cases. These settings are designed to be easy to use and understand. These are gathered via a series of prompts during the configuration process with sensible defaults (where possible).
• Using Built-in HandBrake Presets - HandyMKV can be setup to use a specific built-in HandBrake preset. This option is for users who are familiar with HandBrake and have a specific preset they want to use.
• Using a Custom HandBrake Preset File - HandyMKV can be setup to use a custom HandBrake preset file. This option offers the most granular control over the encoding process but requires the user to create a HandBrake preset file.

HandyMKV is designed to work on Windows, MacOS, and Linux.

MakeMKV is a tool that is used to rip the contents of a disc to a file on the local system. Note: this tool is not free and a license must be purchased for use.

Specifically the makemkvcon command is used to interact with MakeMKV from the command line. The makemkvcon command must be in the system path for HandyMKV to work.

MakeMKV can be downloaded from here.

Documentation for makemkvcon can be found here.

makemkvcon is not included in the $PATH by default when MakeMKV is installed. However, the binary is included in the MakeMKV.app bundle. The binary can be found at /Applications/MakeMKV.app/Contents/MacOS/makemkvcon. You can add this to your $PATH or create a symlink to it in a directory that is in your $PATH.

Handbrake is a tool that is used to encode video files. The HandBrakeCLI command is used to interact with Handbrake from the command line. The HandBrakeCLI command must be in the system path for HandyMKV to work.

The HandBrakeCLI can be installed from here. Note: HandBrake is free to use. See the HandBrake website for more information.

Documentation for the HandBrakeCLI can be found here. This is not needed for usage with HandyMKV but is useful for context.

HandyMKV has a number of command line options and subcommands that can be used to control its behavior.

Usage of handymkv:
  -a string
        Automations. A comma delimited list of automation names to run after encoding.
        Example: -a move-to-plex,notify-discord
  -d string
        Discs. A comma delimited list of disc indexes to rip. Example: -d 0,1,2 (default "0")
  -v    Version. Prints the version of the application.

Subcommands:
  config                Show the current configuration.
  config setup          Run the configuration wizard.
  config edit           Open the config file in the default editor.
  discs                 List available discs.
  history               Show a summary list of past runs.
  history <number>      Show details for a specific past run.
  history clear         Delete all manifest files from the run history directory.
  automations           List all saved automations.
  automations create    Create a new automation.
  automations show <name>   Show details of an automation.
  automations delete <name> Delete an automation.

The quickest way to install HandyMKV on Linux or macOS is with the install script:

curl -fsSL https://raw.githubusercontent.com/dmars8047/handymkv/release/install.sh | bash

The script automatically detects your OS and architecture, downloads the appropriate binary from the latest release, and installs it to /usr/local/bin (or ~/.local/bin if /usr/local/bin is not writable).

Pre-built binaries are available on the Releases page for the following platforms:

• Linux (AMD64, ARM64)
• macOS (Intel, Apple Silicon)
• Windows (AMD64, ARM64)

Download the appropriate binary for your system, place it in a directory on your $PATH, and you're ready to go.

HandyMKV can be installed using the go install command:

go install github.com/dmars8047/handymkv/cmd/handymkv@latest

This requires Go to be installed on the system. Go can be installed from here.

If you have cloned the repository, you can build HandyMKV using the provided Makefile or Go commands directly.

The Makefile provides convenient targets for building HandyMKV for various platforms:

Build for your current system:

This will create a binary in bin/handymkv (or bin/handymkv.exe on Windows).

Install to your GOPATH/bin:

This installs the binary to your Go bin directory, making it available system-wide.

Cross-compile for all supported platforms:

This builds binaries for Linux, macOS, and Windows (both AMD64 and ARM64 architectures) in separate subdirectories under bin/.

Cross-compile for a specific platform:

make linux-amd64      # Linux AMD64
make linux-arm64      # Linux ARM64
make darwin-amd64     # macOS Intel
make darwin-arm64     # macOS Apple Silicon
make windows-amd64    # Windows AMD64
make windows-arm64    # Windows ARM64

Clean build artifacts:

View all available targets:

Alternatively, you can build using Go commands:

# Build for current system
go build -o bin/handymkv ./cmd/handymkv

# Install to GOPATH/bin
go install ./cmd/handymkv

# Cross-compile (example for Linux AMD64)
GOOS=linux GOARCH=amd64 go build -o bin/linux-amd64/handymkv ./cmd/handymkv

The first step is to create a configuration file. This can be done by running the following command:

This will start the configuration wizard. It will prompt you for encode settings and various operational settings. Once saved, the configuration will be stored in a file called config.json. The location of that file depends on whether user-wide or directory-wide configuration is used.

• On Unix systems, the user-wide configuration file is stored at '~/.config/handymkv/config.json'.
• On Windows systems, the user-wide configuration file is stored at '%APPDATA%\handymkv\config.json'.

Then to rip and encode a disc, run the following command:

This will first read the titles on the disc and prompt you to select which titles to rip. Titles are selected by providing the index of each title. Multiple titles can be selected by providing a comma delimited list. Example: 0, 1, 3,4. Once you have selected the titles to rip, the process will begin. The progress of the process will be displayed in the terminal.

Once the process is complete, a summary will be displayed showing the space saved and the time taken to complete the process.

All output files will be stored in the directory specified in the configuration file.

Note: If there is a config.json file in the working directory at execution time, that file will be used instead of the user-wide configuration file.

After each run, HandyMKV writes a manifest file recording what was ripped and encoded, file sizes, durations, and whether raw MKV files were deleted. These manifests can be browsed at any time with the history subcommand.

List all past runs:

Inspect a specific run:

Clear all saved history:

This will show the number of files to be deleted and prompt for confirmation before proceeding.

By default, manifest files are stored alongside the main configuration:

• Unix: ~/.config/handymkv/manifests/
• Windows: %APPDATA%\handymkv\manifests\

A custom directory can be set during the configuration wizard (handymkv config setup), or by setting manifest_directory in config.json.

Run history can be disabled entirely via the configuration wizard or by setting "disable_manifests": true in config.json. When disabled, handymkv history and handymkv history clear will display an informational message rather than attempting to read or modify manifest files.

Automations let you run local scripts or commands after HandyMKV finishes encoding. Each automation is a standalone configuration that defines a command to run and the parameters it needs. Parameters can be sourced from different places: prompted at runtime, hardcoded static defaults, or populated automatically from HandyMKV run data.

Scripts receive their parameters as environment variables with the prefix HMKV_PARAM_. For example, a parameter named destination_dir becomes HMKV_PARAM_DESTINATION_DIR. Environment variables were chosen over command line arguments to maximize compatibility across programming languages and operating systems — argument parsing conventions vary widely between shells and runtimes (flag prefixes, quoting rules, whitespace handling), whereas environment variables are read the same way everywhere.

handymkv automations              # List all saved automations
handymkv automations create       # Create a new automation (interactive wizard)
handymkv automations show <name>  # Show details of an automation
handymkv automations delete <name># Delete an automation

Automation files are stored as JSON in:

• Unix: ~/.config/handymkv/automations/
• Windows: %APPDATA%\handymkv\automations\

Unix note: Scripts must be executable before HandyMKV can run them. Make sure to run chmod +x /path/to/your/script.sh after creating the script.

Use the -a flag to specify automations by name: handymkv -a move-to-plex,notify-discord

Automations run after encoding completes. If the same name is provided more than once, it will only run once.

When creating an automation, each parameter has a source that determines how its value is obtained:

Scripts inherit the full OS environment, so they can read environment variables (like API keys or webhook URLs) directly without needing a dedicated parameter.

Note: Automations run before raw MKV files are deleted. If your script needs to act on the raw files (e.g. inspect or move them), it will have access to them via mkv_output_dir.

Create an automation using the included example script:

handymkv automations create

Configure it with:

• Name: move-media
• Command: /path/to/examples/automations/move-media.sh
• Param 1: encoded_dir (source: hmkv_output, key: hb_output_dir)
• Param 2: media_dir (source: prompt)
• Param 3: group_name (source: static, value: media or your group name)

The script strips the trailing _t## identifier MakeMKV appends to filenames (e.g. My_Movie_t00.mkv → My_Movie.mkv), sets group ownership and permissions, then moves files to the destination directory.

If an automation script fails (non-zero exit code), HandyMKV prints a warning and continues with the next automation. Script failures never abort the pipeline.

Running automations...
  move-to-plex: OK
  notify-discord: FAILED (exit code 1)

Exit codes are recorded in the run manifest and are visible when inspecting history with handymkv history <number>.

An example automation script is available in the repository under examples/automations/. It demonstrates all three parameter source types: hmkv_output (encoded output directory), prompt (destination media directory), and static (group name).

HandyMKV supports ripping and encoding multiple discs in a single run. This option is intended for when mutliple disc drives are available and connected to the host.

During such multi-disc runs the output files will be sorted into subdirectories that indicate the disc they originated from.

To rip and encode multiple discs, simply provide a comma delimited list of disc indexes to the -d flag. Example: handymkv -d 0,1,2.

To see a list of available discs, use the discs subcommand. Example: handymkv discs.

HandyMKV will attempt to execute tasks concurrently to reduce the overall time taken to complete the process. However, encoding tasks are resource intensive and running multiple encoding tasks is likely to slow down the overall process. Likewise ripping tasks are bottle-necked by the speed of the disc drive. For this reason HandyMKV will execute ripping and encoding pipelines concurrently but each task in those pipelines will be executed sequentially. In multi-disc runs, each disc drive's ripping process will be processed concurrently.

If you find HandyMKV useful, please consider supporting the project:

Buy me a coffee on Ko-fi