HandyMKV

A MakeMKV + HandBrake productivity tool.

This is a fork of the original HandyMKV on GitHub.

Description

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

Features

• 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

How it differs from the original

• Uses Cobra for CLI commands, flags, and autocomplete
• Has handymkv redo for redoing already ripped titles.

Encoding Options

HandyMKV supports three encoding configurations:

• Simplified options — interactive prompts with sensible defaults for common use cases
• Built-in HandBrake preset — use any preset bundled with HandBrake
• Custom HandBrake preset file — full control via your own preset file

Prerequisites

Supported Operating Systems

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

Both makemkvcon and HandBrakeCLI must be in your system $PATH for HandyMKV to work.

MakeMKV

MakeMKV rips disc contents to MKV files. A license must be purchased for use. makemkvcon documentation.

A Note for Mac Users

makemkvcon is not in $PATH by default. The binary is bundled at /Applications/MakeMKV.app/Contents/MacOS/makemkvcon. Add it to your $PATH or create a symlink.

HandBrake

HandBrakeCLI encodes video files. HandBrake is free to use. CLI documentation.

Command Line Options

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

handymkv --help

╦ ╦┌─┐┌┐┌┌┬┐┬ ┬╔╦╗╦╔═╦  ╦
╠═╣├─┤│││ ││└┬┘║║║╠╩╗╚╗╔╝
╩ ╩┴ ┴┘└┘─┴┘ ┴ ╩ ╩╩ ╩ ╚╝

A MakeMKV + HandBrake productivity tool

Usage:
  handymkv [flags]
  handymkv [command]

Available Commands:
  automations List all saved automations
  completion  Generate the autocompletion script for the specified shell
  config      Show current configuration
  discs       List available discs
  help        Help about any command
  history     Show a summary list of past runs
  redo        Re-encode titles from a previous run using current config settings

Flags:
  -a, --automations strings   A comma delimited list of automation names to run after encoding. Example: -a move-to-plex,notify-discord
  -d, --discs ints            A comma delimited list of disc indexes to rip. Example: -d 0,1,2 (default [0])
  -h, --help                  help for handymkv
  -v, --version               version for handymkv

Use "handymkv [command] --help" for more information about a command.

Installation

Using pre-compiled binary

Select the version you want to install available releases and download it and add it to your $PATH or something similar.

Example:

wget https://src.timharek.no/tim/handymkv/releases/download/<release>/handymkv-<version>-linux-amd64.tar.gz
tar xf handymkv-<version>-linux-amd64.tar.gz
cd handymkv-<version>
cp handymkv /usr/local/bin

Using Go

go install src.timharek.no/tim/handymkv

Building from Source

Using Go directly

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

Basic Usage

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

handymkv config setup

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:

handymkv

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.

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.

Run History

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:

handymkv history

Inspect a specific run:

handymkv history 3

Clear all saved history:

handymkv history clear

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

Manifest File Location

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.

Disabling Run History

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

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.

Managing Automations

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.

Running Automations

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.

Parameter Sources

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

Source	Description
prompt	Asks the user for a value before the run starts (supports an optional default)
static	Uses a hardcoded value — never prompts the user
hmkv_output	Populated automatically from HandyMKV run data after encoding completes

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

hmkv_output Keys

Key	Value
hb_output_dir	Absolute path to the HandBrake output directory for this run
mkv_output_dir	Absolute path to the raw MKV output directory for this run
run_duration	Duration string, e.g. 12m34s
title_count	Number of titles processed (integer string)
raw_files_deleted	"true" or "false"
total_raw_size	Total size of raw MKV files in bytes (integer string)
total_encoded_size	Total size of encoded output files in bytes (integer string)

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.

Example: Move Encoded Files to a Media Directory

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.

Error Handling

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>.

Example Scripts

An example automation script is available in the repository under examples/automations/. It demonstrates all three parameter source types:

1. hmkv_output (encoded output directory)

2. prompt (destination media directory)

3. static (group name).

Multi-Disc Support

HandyMKV supports ripping and encoding multiple discs in a single run. This option is intended for when multiple 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.

Concurrency

Ripping and encoding pipelines run concurrently, but tasks within each pipeline run sequentially (encoding is CPU-intensive and ripping is bottlenecked by disc drive speed). In multi-disc runs, each drive's ripping process also runs concurrently.