handbrake-js

System Requirements

• Mac and Windows: Only node.js is required; the binary is installed automatically.
• Linux (Ubuntu): You must install handbrake-cli manually:

  sudo apt install handbrake-cli

• Other Linux distros: Use flatpak to install the GUI and CLI together.

Specifying a custom HandbrakeCLI path

In environments like Docker where the binary might not be in the default location, you can specify the path in two ways:

1. Environment Variable: Set HANDBRAKECLI_PATH.

   HANDBRAKECLI_PATH="./example/HandbrakeCLI"

2. Programmatically: Pass HandbrakeCLIPath in the options object to any handbrake-js method.

You can use handbrake-js either as a library in your Node.js project or as a global command-line application.

As a library

Install it as a dependency in your project directory:

$ npm install handbrake-js --save

As a command-line app

Install it globally to use the handbrake command anywhere in your terminal:

$ npm install -g handbrake-js

The handbrake-js CLI allows you to run HandBrake encoding tasks directly from your terminal. When providing both an --input and an --output path, the CLI automatically attaches a progress reporter that displays real-time statistics including task name, percentage complete, current FPS, average FPS, and ETA.

To see raw output instead of the progress bar, use the --verbose flag.

# Example usage (assuming cli-options are configured)
# hbjs --input input.mp4 --output output.mp4

# To see full output instead of the progress bar:
# hbjs --input input.mp4 --output output.mp4 --verbose

Use hbjs.exec(options, [onComplete]) to run a HandbrakeCLI command and execute a callback once it finishes. This is best suited for quick tasks where you don't need progress updates.

Parameters:

• options: Object containing HandbrakeCLI options.
• onComplete: A callback function with the signature (err, stdout, stderr).

import hbjs from 'handbrake-js'

hbjs.exec({ 'preset-list': true }, function(err, stdout, stderr){
  if (err) throw err
  console.log(stdout)
})

Use hbjs.run(options) to run a HandbrakeCLI command and return a Promise. This is identical to hbjs.exec but uses the Promise pattern instead of callbacks. Use this when you don't need progress events.

Returns: Promise<{ stdout: string, stderr: string }>

import hbjs from 'handbrake-js'

async function start () {
  const result = await hbjs.run({ version: true })
  console.log(result.stdout)
  // prints 'HandBrake 1.3.0'
}

start().catch(console.error)

Errors emitted by the error event contain an error.name property which corresponds to the eError enum. Use these to identify the type of failure:

• VALIDATION: Input/output path conflicts or missing output paths.
• INVALID_INPUT: The input file is not a valid video file.
• INVALID_PRESET: The specified preset is invalid.
• NOT_FOUND: The HandbrakeCLI binary could not be found.
• OTHER: Handbrake crashed.

The Handbrake instance provides read-only access to the configuration used and the accumulated output from the CLI.

• handbrake.output (string): A cumulative string containing all stdout and stderr output produced by the HandbrakeCLI process.
• handbrake.options (object): A copy of the options object passed to hbjs.spawn() during initialization.

Use hbjs.run(options) for simple, asynchronous tasks where you only need the final output and do not require real-time progress events. It returns a Promise that fulfills with an object containing stdout and stderr strings. This is ideal for quick commands like checking the version or listing presets.

Options:

• options: An object containing HandbrakeCLI options.
• options.HandbrakeCLIPath: (Optional) A string to override the default HandbrakeCLI binary path.

import hbjs from 'handbrake-js'
async function start () {
  const result = await hbjs.run({ version: true })
  console.log(result.stdout)
  // prints 'HandBrake 1.3.0'
}
start().catch(console.error)