node package manager


Handbrake watcher / converter utility

This app was created for personal use and so documentation errs toward non-existent.

There's no ongoing support for this. It works for me.™ PRs are always welcome, though.

What it does

Watches a pre-configured folder for new movies and then attempts to convert that file using Handbrake to a hard-coded preset.

On finding a new movie, it will also try to determine the movie's name and metadata using the Rotten Tomatoes API and if a match is found, then normalise the output filename to MOVIE_TITLE (MOVIE_YEAR).


Intended for use in conjunction with some download tool (like Transmission), where downloads can be moved to the watched folder on completion. This tool will then detect the new movie, convert it and move the converted file to a configured location.

This output directory could in turn be watched by other tools for further processing (e.g. for adding to a media server).


npm install handbrake-watch

Set config

API keys

Set your Rotten Tomatoes API key: * as an environment variable (ROTTEN_API_KEY) * in config/local.yml


The following folders need to be set in config/default.yml or config/local.yml:

  # The folder that should be watched for new files. i.e. the files to be converted. 
  input: ''
  # The folder where pending and currently converting videos are stored 
  pending: ''
  # The folder where the newly created converted file will be moved 
  output: ''
  # The folder where the original, un-converted file will be moved on conversion success 
  completed: ''
  # The folder where the origin, un-converted file will be moved on conversion failure 
  failed: ''


Once configured, run:

npm start

The application logs verbosely to logs/handbrake-watch.log, but for common events such as when starting and completing (or failing) a conversion, the application will make an audible noise. This won't be ideal in all cases, but... it suits me.