handbrake-js

Upgraders, please read the release notes.

handbrake-js

Handbrake-js is Handbrake (v1.6.1) for node.js. 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.

Outputs:

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

Compatible Platforms

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.

Installation

System Requirements

Just node.js. On Mac and Windows, every else is installed automatically. However on Linux, you must install HandbrakeCLI manually with these commands:

sudo add-apt-repository --yes ppa:stebbins/handbrake-releases
sudo apt-get update -qq
sudo apt-get install -qq handbrake-cli

As a library

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.

const hbjs = require('handbrake-js')

hbjs.spawn({ input: 'something.avi', output: 'something.m4v' })
  .on('error', err => {
    // invalid user input, no video found etc
  })
  .on('progress', progress => {
    console.log(
      'Percent complete: %s, ETA: %s',
      progress.percentComplete,
      progress.eta
    )
  })

As a command-line app

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

HandbrakeCLI Path

In some situations or environments (e.g. Docker) you may need to specify a custom HandbrakeCLI path. You can either specify the path in an environment variable:

HANDBRAKECLI_PATH="./example/HandbrakeCLI"

..or pass HandbrakeCLIPath as an option, programmatically. See the API documentation below for instructions. Also, see the examples folder for example code.

API Reference

Handbrake for node.js.

Example

const hbjs = require('handbrake-js')

handbrake-js
- static
  - .spawn([options]) ⇒ Handbrake
  - .exec(options, [onComplete])
  - .run(options) ⇒ Promise
- inner
  - ~Handbrake ⇐ EventEmitter
    - .output : string
    - .options : object
    - .eError
    - .cancel()
    - "start"
    - "begin"
    - "progress" (progress)
    - "output" (output)
    - "error" (error)
    - "end"
    - "complete"
    - "cancelled"

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

Param	Type	Description
[options]	`object`	Options to pass directly to HandbrakeCLI
[options.HandbrakeCLIPath]	`string`	Override the built-in `HandbrakeCLI` binary path.

Example

const hbjs = require('handbrake-js')

const options = {
  input: 'something.avi',
  output: 'something.mp4',
  preset: 'Normal',
  rotate: 1
}
hbjs.spawn(options)
  .on('error', console.error)
  .on('output', console.log)

hbjs.exec(options, [onComplete])

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

Param	Type	Description
options	`Object`	Options to pass directly to HandbrakeCLI
[options.HandbrakeCLIPath]	`string`	Override the built-in `HandbrakeCLI` binary path.
[onComplete]	`function`	If passed, `onComplete(err, stdout, stderr)` will be called on completion, `stdout` and `stderr` being strings containing the HandbrakeCLI output.

Example

const hbjs = require('handbrake-js')

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

hbjs.run(options) ⇒ `Promise`

Identical to hbjs.exec except it returns a promise, rather than invoke a callback. Use this when you don't need the progress events reported by hbjs.spawn. Fulfils with an object containing the output in two properties: stdout and stderr.

Kind: static method of handbrake-js

Param	Type	Description
options	`Object`	Options to pass directly to HandbrakeCLI
[options.HandbrakeCLIPath]	`string`	Override the built-in `HandbrakeCLI` binary path.

Example

const hbjs = require('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)

handbrake-js~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, cancelled

~Handbrake ⇐ EventEmitter
- .output : string
- .options : object
- .eError
- .cancel()
- "start"
- "begin"
- "progress" (progress)
- "output" (output)
- "error" (error)
- "end"
- "complete"
- "cancelled"

handbrake.output : `string`

A string containing all handbrakeCLI output

Kind: instance property of Handbrake

handbrake.options : `object`

a copy of the options passed to spawn

Kind: instance property of Handbrake

handbrake.eError

All operational errors are emitted via the error event.

Kind: instance enum of Handbrake
Properties

Name	Default	Description
VALIDATION	`ValidationError`	Thrown 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_INPUT	`InvalidInput`	Thrown when the input file specified does not appear to be a video file.
INVALID_PRESET	`InvalidPreset`	Thrown when an invalid preset is specified.
OTHER	`Other`	Thrown if Handbrake crashes.
NOT_FOUND	`HandbrakeCLINotFound`	Thrown if the installed HandbrakeCLI binary has gone missing.

handbrake.cancel()

Cancel the encode, kill the underlying HandbrakeCLI process then emit a cancelled event.

Kind: instance method of Handbrake