handbrake runner (hbr)                      https://github.com/epakai/hbr
================================================================================

hbr is a tool for automating HandBrakeCLI runs. It takes a keyfile as input
and runs HandBrakeCLI to encode videos.

hbr-gen is a tool for generating partly filled keyfile templates for hbr.

This method makes it easy to check earlier encode settings. It also simplifies
modifying a single encode or your whole library to meet your requirements.

================================================================================
Building hbr
================================================================================

Build dependencies:     libglib2.0-dev (argp-standalone for non-glibc systems)

From release tarball:
    ./configure
    make
    make install

From git (requires autoconf/automake/libtool/autoconf-archive):
    ./autogen.sh
    ./configure
    make
    make install

================================================================================
Usage of hbr
================================================================================

Runtime dependencies:   HandBrakeCLI, ffmpegthumbnailer (optional)

hbr is a command line program that takes one or more keyfiles as input and runs
HandBrakeCLI for each OUTFILE section in the keyfile.

hbr has a global config keyfile at $XDG_CONFIG_HOME/hbr/hbr.conf or
$HOME/.config/hbr/hbr.conf. This file only has a CONFIG section. hbr generates
a default config if it does not exist.

Keyfiles are plaintext files with one CONFIG section, and one or more OUTFILE
sections. Each section has one or more keys. Here is an example <Akira.hbr>:

    [CONFIG]
    input_basedir=/path/to/input_files
    output_basedir=/path/to/output_files
    type=movie
    name=Akira
    year=1988

    [OUTFILE1]
    iso_filename=Akira.iso
    title=11
    crop=10:10:0:0
    chapters=1-18
    audio=1,2,3

    [OUTFILE2]
    iso_filename=Akira BD
    title=1
    markers=true
    specific_name=1080p
    chapters=1-23
    audio=2,4,6

When passed to hbr as in:

    hbr Akira.hbr

hbr runs these commands:

    HandBrakeCLI --title=11 --chapters=1-18 --audio=1,2,3 --crop=10:10:0:0
        -i '/path/to/input_files/Akira.iso'
        -o '/path/to/output_files/Akira (1988).mkv'
    HandBrakeCLI --title=1 --chapters=1-23 --audio=2,4,6 --markers
        -i '/path/to/input_files/Akira BD'
        -o '/path/to/output_files/Akira (1988) - 1080p.mkv'

Keys in the global hbr.conf also change the generated commands.  Redefining a
key in a more specific section overrides the more global setting. hbr tries to
warn about conflicting or dependent keys, but this is incomplete.

OUTFILE sections names must be unique, and must start with OUTFILE. I append
numbers to the section name in the above example, but you can use anything
(even whitespace) after OUTFILE.

================================================================================
Usage of hbr-gen
================================================================================

hbr-gen can generate a fixed number of OUTFILE sections (-n) or a set based on
an episode list (-l). Some keys can be prefilled by passing extra options. See
hbr-gen --help for a full list.  hbr-gen sends output to standard output.
Redirect it to a file.

An episode list consists of lines with season/episode number and a title. Any
of these example formats can be mixed in one file.

    s1e2 Hard Normal Daddy
    e3 Feed Me Weird Things
    4 Ultravisitor

Here are some example runs of hbr-gen:

    hbr-gen -n 12 --input-basedir=/video/iso > show.hbr

    hbr-gen -l list_of_episodes --input-basedir=/video/iso > show.hbr

Once you generate the keyfile edit it to complete all fields.

================================================================================
Key Names
================================================================================

Most of the key names come from the related HandBrakeCLI arguments. Some are
excluded because they do not make sense in the context of hbr. For a full list,
run HandBrakeCLI --help.

These keys take values exactly as specified by HandBrakeCLI except for boolean
arguments. For example, specify --markers/--no-markers as
markers=true/markers=false in the keyfile. Boolean keys do not always have a
corresponding negation value. For example, in older HandBrake versions
--no-markers did not exist. In cases where there is no negation argument
setting a key to false will not produce an argument to HandBrakeCLI, but it
overrides values set in the keyfile or global CONFIG section.

hbr has some special keys related to input and output file names. hbr tries to
follow the Plex media preparation guidelines documented at:
    https://support.plex.tv/articles/categories/media-preparation/

Here is an overview of the hbr specific keys:

    input_basedir  - Path that specifies where to find iso_filename. Optional.
                     iso_filename can specify a full path instead.
    iso_filename   - The input file or device. Combined with input_basedir
                     to make a full path.
    type           - set to series or movie. Controls filename format.
    output_basedir - Specifies the path for the output file. Path must already
                     exist.
    name           - Base name for the output file. Usually the title of the
                     series or the movie name.
    year           - 4-digit year used for movie filenames.
    season         - season number used in series filenames.
    episode        - episode number used in series filenames.
    specific_name  - extra name appended before the file extension. Useful for
                     episode names or file specific metadata.
    preview        - generate a preview image from the output file.
    add_year       - adds the year to the output_basedir when set true.
    extra          - Causes the output file to be placed in a subdirectory
                     for Plex to handle as an extra.
    debug          - Prints command that would be run instead of producing an
                     encode. Useful for testing or disabling certain encodes.

Filenames depend on the type specified.
For type=movie the output filename will be:

    name (year) - specific_name.mkv
    OR
    name (year).mp4

For type=series the output filename will be:

    name - s01e001 - specific_name.mkv

where season and episode give the values after s and e.

================================================================================
Troubleshooting
================================================================================

If things are not working out you can try checking the command hbr outputs with
debug mode:

    hbr -d Akira.hbr

hbr also logs HandBrakeCLI output to the output filename with .log appended. It
is a good idea to check it over to see how HandBrake is interpreting the
command, and for potential errors with the encode source. In the above example
the log filename would be:

    /path/to/output_files/Akira (1988).mkv.log

Finally, if you can isolate the problem to hbr's command generation please file
a bug at:

    https://github.com/epakai/hbr/issues