Skip to content

How to get Handbrake CLI on your Synology NAS

How to get Handbrake CLI on your Synology NAS published on 10 Comments on How to get Handbrake CLI on your Synology NAS

Sharing is caring!


You want to convert mkv movies to m4v for your iDevice but have no access to HandbrakeCLI on your Synology NAS.


Use docker πŸ™‚


  • Install in your docker console in DSM a handbrake-cli docker (I used supercoder/docker-handbrake-cli:latest).
  • After getting the image you don’t have to start it. That happens from the command line
  • ssh into your nas (if you don’t know how than you should probably not want to use this tutorial πŸ˜‰
  • On the Synology Nas docker runs under the root user so the command needs to be run with sudo rights.
  • Run docker command with the correct settings (see below)
  • Done

for the tech savvy under us this might already be enough but don’t worry I will expand on the above explanation…

In my home folder I created a bin folder that I put on the $PATH

  • login on your nas with ssh then:

  • Add this line to the .bashrc file in your home dir (create it if it does not exist)

  • cd bin
  • create a file called m4v in the bin folder and put the following content in it

This script does the following:

  • Get the first parameter and save it in the mkv variable
  • Also save a m4v variable with the same name but then with the m4v extension
  • Run the docker handbrake image and map the folder you are standing in to the image folder /input and a standard place where you want to save your m4v files to /output then execute the HandbrakeCLI command with all the options given mapping /input/$mkv as input file and wel the rest are handbrake options you can read the manual for πŸ™‚
  • This will in effect take the provided movie from the current directory and convert it to an m4v formatted movie in the mapped output folder. Most of the options given are what I found working great on my iDevice and most other devices.
  • After finishing the docker image will close and remove its state automatically
  • Change the rights to the script so it can execute

tips / troubleshooting

  • The command must be run as root (sudo) because docker runs as root
  • Run the command under a screen so that you can actually log off when running the “long running” command e.g…

If done like this you can leave the screen instance with ctrl+a+d and then log off from your ssh session. The command will keep on running…

  • change any and all options as you like πŸ™‚ but you should probably only have to change /volume1/video/m4v/inbox as that should be a location on you nas
  • if you get access rights errors, make sure that the folders you want to convert from and to have the correct rights.

Multiple files to convert…

create a file in ~/bin called something like m4vAll and give it execute rights (`chmod +x m4vAll) with the following content

This will find all mkv files from the current folder onwards and convert it with the m4v command. It will accept spaces in names… so just navigate to the folder you want to start from and call sudo m4vAll and it will do its thing πŸ˜‰

Have fun and drop a comment if you like the article. A beer is also good…


Thank you for your post, I was looking for a solution for that exact problem.

However, unfortunately handbrake isn’t working. I’ve set up everything like you described, but then and even if I run handbrake-cli from the terminal itself, I get the following error (shortened):

hb_init: starting libhb thread
HandBrake 0.10.1 (2015030800) – Linux x86_64 –
4 CPUs detected
Opening /var/services/homes/xxx/_inProgress/input/movie.mkv…
CPU: Intel(R) Atom(TM) CPU C2538 @ 2.40GHz
Intel microarchitecture Silvermont
logical processor count: 4
OpenCL: library not available
hb_scan: path=/var/services/homes/xxx/_inProgress/input/movie.mkv, title_index=1
libbluray/bdnav/index_parse.c:162: indx_parse(): error opening /var/services/homes/xxx/_inProgress/input/movie.mkv/BDMV/index.bdmv
libbluray/bdnav/index_parse.c:162: indx_parse(): error opening /var/services/homes/xxx/_inProgress/input/movie.mkv/BDMV/BACKUP/index.bdmv
libbluray/bluray.c:2182: nav_get_title_list(/var/services/homes/xxx/_inProgress/input/movie.mkv) failed
bd: not a bd – trying as a stream/file instead
libdvdnav: Using dvdnav version 5.0.1
libdvdread: Encrypted DVD support unavailable.
libdvdread: Can’t stat /var/services/homes/xxx/_inProgress/input/movie.mkv
No such file or directory
libdvdread: Could not open /var/services/homes/xxx/_inProgress/input/movie.mkv
libdvdnav: vm: failed to open/read the DVD
dvd: not a dvd – trying as a stream/file instead
hb_stream_open: open /var/services/homes/xxx/_inProgress/input/movie.mkv failed
scan: unrecognized file type
libhb: scan thread found 0 valid title(s)
No title found.
HandBrake has exited.

It seems to be unable to open the file. On my desktop everything works perfect.

Do you have an idea what to do?

It should only work if you use it from shell. If you just start it from DSM it will do nothing ?!

There are a lot of things that can go wrong. you have to take into account the virtual and the actual environment and the mapping between them.

The /input and /output directories in the command point to the locations in the virtual machine (docker image) these have to be mapped to actual volumes on your nas. But the Handbrake cli command executes on the /input and /output folders as it knows nothing of the nas environment. It only knows the virtual docker env. So you have to keep these separate in your mind. you need to navigate to the actual nas location and execute the command it will map you location -v $(pwd)... to the /input of the docker and handbrake will then be able to find the movie file. It will write to its /output directory and you need to map that folder again to a location on you actual drive.

The command I wrote down is very specific. e.g. in the -v ... section you should only change the /volume1/video/m4v/inbox to an actual location on you nas as this is a location on my nas πŸ™‚ the other values should stay the same because those relate to mappings in the docker vm. if you change these you are making stuff difficult to debug.

Hope this helps. Please let me know πŸ™‚

Thank you so much Ivo, everything is working now.

I had these issues:
– I tried to start the container in detached mode (-d) while still being able to remove it automatically when it stopped (-rm). This is not possible and probably the reason you mentioned the beautiful ‘screen’ command here πŸ˜‰ As always: reading the (here: Docker-)Docs helps a lot.
– I had a typo without noticing it. ‘outout’ sounds good, ‘output’ sounds better.

Thank you. I donated you a beer – cheers!

Great work ! Have on question. Have here .ts files. Work this script convert .ts files to .mkv files with this handbreakcli parameters ? Thanks for help.

I fail at the very first step.
I can’t find no .bashrc file in my home directory. (Had to activate User Homes in DSM first for cd~ to work), I’m on DSM 6.1.2

Using the Stock commands from dockerhub it works fine.
export HANDBRAKE_OPTIONS=”-e x264 -q 23.0 -a 1,1 -E ffaac,copy:ac3 -B 160,160 -6 dpl2,auto -R Auto,Auto -D 0.0,0.0 –audio-copy-mask aac,ac3,dtshd,dts,mp3 –audio-fallback ffac3 -f mp4 –decomb –loose-anamorphic –modulus 2 -m –x264-preset veryfast –h264-profile high –h264-level 4.0″
sudo docker run \
-v /volume1/Test/Videos/:/input \
-v /volume1/docker/Handbrake:/output \
–cpuset-cpus=”0-1″ \
–rm \
supercoder/docker-handbrake-cli:latest \ \
-i /input/test.mp4 \
-o /output/test3.mp4 \

You think it would be possible to add this in Task in Task Manager to run every X Minutes and automatically convert all files in a Folder?
Handbrake should stop automatically if it doesn’t find a file. What if it would be started twice while the file still exists?

If the .bashrc file does not exist you can of course create it πŸ™‚ I have added this to the post.

I see no reason why a scheduled job would not work. In the version described in this blog post it is not possible to start more instances of the script. Because it uses a named image but you could adjust that of course… Let me know what you did πŸ™‚

Leave a Reply

Your email address will not be published. Required fields are marked *

Primary Sidebar