id       = "handbrake"
name     = "HandBrake"
homepage = "https://handbrake.fr"
description = "HandBrake is an open-source, GPL-licensed, multiplatform, multithreaded video transcoder."
# The HandBrake logo, from the project's own site.
icon     = "https://handbrake.fr/img/logo.png"
# HandBrakeCLI is the command line build (test/module.defs sets
# TEST.exe = $(HB.name)CLI); ghb is the GTK application
# (gtk/src/meson.build, executable('ghb', …)). The Windows GUI is HandBrake.exe
# and the macOS bundle identifier is fr.handbrake.HandBrake
# (macosx/Info.plist.m4).
executables   = ["HandBrakeCLI", "ghb"]

[dotfiles]

# libhb/preset.c picks the presets file per platform:
#   SYS_LINUX   "ghb/presets.json"
#   SYS_MINGW   "HandBrake\\presets.json"
#   SYS_DARWIN  "HandBrake/UserPresets.json"
# joined to hb_get_user_config_directory() (libhb/ports.c), which is
# FOLDERID_RoamingAppData on Windows, $XDG_CONFIG_HOME else $HOME/.config on
# Linux, and ~/Library/Application Support on macOS
# (HBUtilities.m, +appSupportURL). Three different file names in three
# different places, so each is written out rather than folded into one root.
#
# Beside the presets, each GUI keeps its own settings: the macOS app in the
# NSUserDefaults domain fr.handbrake.HandBrake, the GTK app in
# ~/.config/ghb/preferences.json (gtk/src/presets.c reads
# read_config_file("preferences.json") from ghb_get_user_config_dir()), and the
# Windows app in %APPDATA%\HandBrake\settings.json
# (win/CS/…/UserSettingService.cs over DirectoryUtilities.GetUserStoragePath()).
#
# The last entry is the Mac App Store build, which is sandboxed and so writes
# the same tree inside its container (libhb/platform/macosx/config.m).
paths = [
  "[preferences]/fr.handbrake.HandBrake.plist",
  "~/Library/Application Support/HandBrake/UserPresets.json",
  "~/Library/Containers/fr.handbrake.HandBrake/Data/Library/Application Support/HandBrake/UserPresets.json",
  "~/.config/ghb/presets.json",
  "~/.config/ghb/preferences.json",
  "%APPDATA%/HandBrake/presets.json",
  "%APPDATA%/HandBrake/settings.json",
]

# HandBrake's state and logs sit beside these files rather than inside them —
# QueueV2.hbqueue next to UserPresets.json on macOS (HBAppDelegate.m),
# EncodeLogs/ next to presets.json on Linux, logs/ next to settings.json on
# Windows — and none of them is named above, since this entry lists files
# rather than the directories that hold them.
exclude = []

# A video transcoder stores no credential.
secret = []

# No machine_lines. A preset is encoder, quality, filters, audio and subtitle
# behaviour, which is the whole reason to carry the file between machines. The
# settings files do hold a default output directory, an absolute path — but on
# macOS that lives in a property list, which this schema cannot parse, so a
# rule would cover Linux and Windows only and silently miss the Mac.

[commands]
format = 1
label = "Transcode video"
description = "Encode a video file or disc with HandBrakeCLI. Covers source, container, video encoder and quality, audio track selection and picture size; filters, subtitles and per-codec tuning are left out."
quality = "ai-draft"
parser = { end_of_options = "--", interleave = "permute", long_equals = true, short_attached = true, short_bundles = false }

[[commands.source]]
id = "help"
kind = "manual"
url = "https://manpages.debian.org/unstable/handbrake-cli/HandBrakeCLI.1.en.html"
revision = "2026-10-27"
evidence = """
Syntax: HandBrakeCLI [options] -i <device> -o <file>
  -Z. --preset <string>
  -i, --input <string>
  Set input device
  -t, --title <number>
  Select a title to encode (0 to scan all titles only, default: 1)
  -o, --output <string>
  Set output file name
  -f, --format <string>
  Set output format (mp4/mkv, default: autodetected from file name)
  -m, --markers
  Add chapter markers (mp4 and mkv output formats only)
  -e, --encoder <string>
  Set video library encoder Options: x264 / ffmpeg4 / ffmpeg2 / theora
  --x264-preset <string>
  ultrafast / superfast / veryfast / faster / fast / medium / slow / slower / veryslow / placebo
  -q, --quality <number>
  Set video quality
  -b, --vb <kb/s>
  Set video bitrate (default: 1000)
  -2, --two-pass
  Use two-pass mode
  -r, --rate
  -a, --audio <string>
  Select audio track(s), separated by commas ("none" for no audio,
  -w, --width <number>
  Set picture width
  -l, --height <number>
  Set picture height
  --crop <T:B:L:R>
  -v, --verbose <#>
  Be verbose (optional argument: logging level)
"""

[[commands.field]]
id = "input"
label = "Input file or device"
type = "path"
path = { kind = "any", role = "input" }
option = ["--input", "-i"]
sources = ["help"]

[[commands.field]]
id = "output"
label = "Output file"
type = "path"
path = { kind = "file", role = "output" }
option = ["--output", "-o"]
effect = "overwrite"
sources = ["help"]

[[commands.field]]
id = "preset"
label = "Preset"
description = "Built-in preset name; capitalization matters."
type = "string"
option = ["--preset", "-Z"]
sources = ["help"]

[[commands.field]]
id = "format"
label = "Container"
type = "enum"
choices = [{ value = "mp4", label = "MP4" }, { value = "mkv", label = "MKV" }]
option = ["--format", "-f"]
sources = ["help"]

[[commands.field]]
id = "encoder"
label = "Video encoder"
type = "string"
option = ["--encoder", "-e"]
suggestions = [{ value = "x264", label = "x264" }, { value = "ffmpeg4", label = "ffmpeg4" }, { value = "ffmpeg2", label = "ffmpeg2" }, { value = "theora", label = "Theora" }]
sources = ["help"]

[[commands.field]]
id = "x264_preset"
label = "x264 speed preset"
type = "string"
option = ["--x264-preset"]
suggestions = [{ value = "ultrafast", label = "ultrafast" }, { value = "veryfast", label = "veryfast" }, { value = "fast", label = "fast" }, { value = "medium", label = "medium" }, { value = "slow", label = "slow" }, { value = "veryslow", label = "veryslow" }]
sources = ["help"]

[[commands.field]]
id = "quality"
label = "Video quality"
type = "number"
option = ["--quality", "-q"]
sources = ["help"]

[[commands.field]]
id = "bitrate"
label = "Video bitrate (kb/s)"
type = "integer"
option = ["--vb", "-b"]
sources = ["help"]

[[commands.field]]
id = "two_pass"
label = "Two-pass"
type = "boolean"
option = ["--two-pass", "-2"]
sources = ["help"]

[[commands.field]]
id = "title"
label = "Title"
description = "0 scans all titles only."
type = "integer"
option = ["--title", "-t"]
sources = ["help"]

[[commands.field]]
id = "audio"
label = "Audio tracks"
description = "Comma separated track numbers, or none."
type = "string"
option = ["--audio", "-a"]
sources = ["help"]

[[commands.field]]
id = "width"
label = "Width"
type = "integer"
option = ["--width", "-w"]
sources = ["help"]

[[commands.field]]
id = "height"
label = "Height"
type = "integer"
option = ["--height", "-l"]
sources = ["help"]

[[commands.field]]
id = "markers"
label = "Chapter markers"
type = "boolean"
option = ["--markers", "-m"]
sources = ["help"]

[[commands.task]]
id = "preset"
label = "Encode with a preset"
fields = ["input", "output", "preset"]
required = ["input", "output", "preset"]

[[commands.task]]
id = "x264_crf"
label = "x264 constant quality"
fields = ["input", "output", "encoder", "quality", "x264_preset", "markers"]
required = ["input", "output", "quality"]
set = { encoder = ["x264"] }

[[commands.group]]
id = "basic"
label = "Basic"
fields = ["input", "output", "preset", "format", "quality", "markers"]

[[commands.group]]
id = "advanced"
label = "Advanced"
fields = ["encoder", "x264_preset", "bitrate", "two_pass", "title", "audio", "width", "height"]