Handbrake for node.js. Brings video encoding.


Handbrake-js is Handbrake (v0.10.2) for node.js, funnily enough. It aspires to provide a lean and stable foundation for building video transcoding software in node.js.

HandBrake is a tool for converting video from nearly any format to a selection of modern, widely supported codecs. It can process most common multimedia files and any DVD or BluRay sources that do not contain any copy protection.


  • File Containers: .MP4(.M4V) and .MKV
  • Video Encoders: H.264(x264), H.265(x265) MPEG-4 and MPEG-2 (libav), VP8 (libvpx) and Theora(libtheora)
  • Audio Encoders: AAC, CoreAudio AAC/HE-AAC (OS X Only), MP3, Flac, AC3, or Vorbis
  • Audio Pass-thru: AC-3, DTS, DTS-HD, AAC and MP3 tracks

Read more about the features.

Tested on Mac OSX, Ubuntu 14, Windows XP, Windows 7 and Windows 8.1.

Ubuntu 14.04 notice: Transcoding to MP4 fails on Ubuntu since 14.04 for this reason.

Just node.js. Every else is installed automatically.

Move into your project directory then run:

$ npm install handbrake-js --save

Mac / Linux users may need to run with sudo.

Now you can begin encoding from your app.

var hbjs = require("handbrake-js");
hbjs.spawn({ input: "dope shit.avi", output: "dope shit.m4v" })
  .on("error", function(err){
    // invalid user input, no video found etc 
  .on("progress", function(progress){
      "Percent complete: %s, ETA: %s", 

From any directory run the following:

$ npm install -g handbrake-js

Mac / Linux users may need to run with sudo.

Now, you can call handbrake as you would HandbrakeCLI, using all the usual options. By default, just statistics are output, passing --verbose prints the raw HandbrakeCLI output. This command will transcode an AVI to the more universal H.264 (mp4):

$ handbrake --input "some episode.avi" --output "some episode.mp4" --preset Normal
Task      % done     FPS       Avg FPS   ETA
Encoding  1.07       131.76    158.12    00h21m11s

API Reference

Handbrake for node.js.


var hbjs = require("handbrake-js");

hbjs.spawn(options) ⇒ Handbrake

Spawns a HandbrakeCLI process with the supplied options, returning an instance of Handbrake on which you can listen for events.

Kind: static method of handbrake-js

optionsObjectOptions to pass directly to HandbrakeCLI


var hbjs = require("handbrake-js");
    .on("error", console.error)
    .on("output", console.log);

Runs HandbrakeCLI with the supplied options calling the supplied callback on completion. The exec method is best suited for short duration tasks where you can wait until completion for the output.

Kind: static method of handbrake-js

optionsObjectOptions to pass directly to HandbrakeCLI
[onComplete]functionIf passed, onComplete(err, stdout, stderr) will be called on completion, stdout and stderr being strings containing the HandbrakeCLI output.


var hbjs = require("handbrake-js");
hbjs.exec({ preset-list: true }, function(errstdoutstderr){
    if (err) throw err;

hbjs~Handbrake ⇐ EventEmitter

A handle on the HandbrakeCLI process. Emits events you can monitor to track progress. An instance of this class is returned by spawn.

Kind: inner class of handbrake-js
Extends: EventEmitter
Emits: start, begin, progress, output, error, end, complete

A string containing all handbrakeCLI output

Kind: instance property of Handbrake

a copy of the options passed to spawn

Kind: instance property of Handbrake

All operational errors are emitted via the error event.

Kind: instance enum property of Handbrake

VALIDATIONValidationErrorThrown if you accidentally set identical input and output paths (which would clobber the input file), forget to specifiy an output path and other validation errors
INVALID_INPUTInvalidInputThrown when the input file specified does not appear to be a video file
OTHEROtherThrown if Handbrake crashes
NOT_FOUNDHandbrakeCLINotFoundThrown if the installed HandbrakeCLI binary has gone missing..

Fired as HandbrakeCLI is launched. Nothing has happened yet.

Kind: event emitted by Handbrake

Fired when encoding begins. If you're expecting an encode and this never fired, something went wrong.

Kind: event emitted by Handbrake

Fired at regular intervals passing a progress object.

Kind: event emitted by Handbrake

progressobjectdetails of encode progress
progress.taskNumbernumbercurrent task index
progress.taskCountnumbertotal tasks in the queue
progress.percentCompletenumberpercent complete
progress.fpsnumberFrames per second
progress.avgFpsnumberAverage frames per second
progress.etastringEstimated time until completion
progress.taskstringTask description, either "Encoding" or "Muxing"

Kind: event emitted by Handbrake

outputstringAn aggregate of stdout and stderr output from the underlying HandbrakeCLI process.

Kind: event emitted by Handbrake

errorErrorAll operational exceptions are delivered via this event.
error.nameeErrorThe unique error identifier
error.messagestringError description
error.errnostringThe HandbrakeCLI return code

Fired on successful completion of an encoding task. Always follows a begin event, with some progress in between.

Kind: event emitted by Handbrake

Fired when HandbrakeCLI exited cleanly. This does not necessarily mean your encode completed as planned..

Kind: event emitted by Handbrake

© 2015 Lloyd Brookes 75pound@gmail.com. Documented by jsdoc-to-markdown.