Wondering what’s next for npm?Check out our public roadmap! »

    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/handbrake-js package

    5.0.2 • Public • Published

    view on npm npm module downloads Build Status Gihub repo dependents Gihub package dependents js-standard-style Join the chat at https://gitter.im/75lb/handbrake-js

    Upgraders, please read the release notes.


    Handbrake-js is Handbrake (v1.3.3) 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.


    • 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.

    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.


    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 => {
          'Percent complete: %s, ETA: %s',

    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

    API Reference

    Handbrake for node.js.


    const 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

    Param Type Description
    [options] object Options to pass directly to HandbrakeCLI


    const hbjs = require('handbrake-js')
    const options = {
      input: 'something.avi',
      output: 'something.mp4',
      preset: 'Normal',
      rotate: 1
      .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
    [onComplete] function If passed, onComplete(err, stdout, stderr) will be called on completion, stdout and stderr being strings containing the HandbrakeCLI output.


    const hbjs = require('handbrake-js')
    hbjs.exec({ preset-list: true }, function(err, stdout, stderr){
      if (err) throw err

    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


    const hbjs = require('handbrake-js')
    async function start () {
      const result = await hbjs.run({ version: true })
      // prints 'HandBrake 1.3.0'

    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.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


    All operational errors are emitted via the error event.

    Kind: instance enum of Handbrake

    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.


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

    Kind: instance method of Handbrake


    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

    "progress" (progress)

    Fired at regular intervals passing a progress object.

    Kind: event emitted by Handbrake

    Param Type Description
    progress object details of encode progress
    progress.taskNumber number current task index
    progress.taskCount number total tasks in the queue
    progress.percentComplete number percent complete
    progress.fps number Frames per second
    progress.avgFps number Average frames per second
    progress.eta string Estimated time until completion
    progress.task string Task description, either "Encoding" or "Muxing"

    "output" (output)

    Kind: event emitted by Handbrake

    Param Type Description
    output string An aggregate of stdout and stderr output from the underlying HandbrakeCLI process.

    "error" (error)

    Kind: event emitted by Handbrake

    Param Type Description
    error Error All operational exceptions are delivered via this event.
    error.name eError The unique error identifier
    error.message string Error description
    error.errno string The 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


    If .cancel() was called, this event is emitted once the underlying HandbrakeCLI process has closed.

    Kind: event emitted by Handbrake

    © 2013-21 Lloyd Brookes <75pound@gmail.com>.

    Tested by test-runner. Documented by jsdoc-to-markdown.

    Handbrake (Authors) is licensed by GNU General Public License Version 2.


    npm i handbrake-js

    DownloadsWeekly Downloads






    Unpacked Size

    50.4 kB

    Total Files


    Last publish


    • avatar