herostitcher, the command line video workflow tool

This project was actually born some years ago, after I got my first action camera and needed a tool to do image stabilization / deshaking in an automated way. This is my solution.

Update 2017-02-13: herostitcher has now been completely refactored and is now contained in one script. The project file format is unchanged.

Update 2017-07-27: a new audio compression feature has been added in order to manage varying dynamic range in the source material, such as better picking up speech from a distance.

After some research, I was not satisfied with existing solutions. Specifically, the best deshaker is designed only for VirtualDub on Windows. So I started writing some scripts to make working with VirtualDub through wine easy. This soon developed into a solution that enabled lossless and automated integration between any tools I want to use, and thus herostitcher was born.

Now I am making herostitcher available to anyone who wishes to use it. See the example.herostitcher for details and instructions. Essentially, it is a list of scenes to be stitched together, along with metadata and commonly used effects. The whole suite is public domain, and improvements are welcome.

You can download herostitcher here.

The main use for herostitcher is to automate the flow from after recording, to a finished encoded video. In other words from individual video files that can be of various sources, to the completed product that you can distribute as a file or upload on Youtube etc.

Key features of herostitcher:

  • Lossless editing at all stages, using avi container (raw video + pcm) files or named pipes
  • Chaining of thread-limited processes, making excellent use of multi-core CPUs
  • Two selectable containers are supported out of the box: webm (vp9 + opus) and mp4 (x264 + aac)
  • Two quality levels automates the creation of an additional version targeted at mobile and low bandwidth users, if desired
  • Adjustable quality settings for resolution,  CFR and audio bitrate
  • Automatic management of FPS, resolution, sample rate and sample format
  • Automatic creation of a label scene at the beginning, if desired
  • Easy adding of a soundtrack or background music mixed in

General design considerations for herostitcher:

  • Isn’t OpenShot/Kdenlive/Cinelerra much better?
    • For non-linear editing herostitcher can be used as a first extraction and deshaking stage
  • Herostitcher requires insane amounts of storage when deshaking!
    • Deshaker would require more research into how wine manages named pipes, 2-pass (piping the deshakedata file), and potential read timeouts when reading the slowly written first pass output
  • The whole system is modular
    • Plugging in scripts that act on scene symlinks should be easy
    • Each command can be run without arguments, taking defaults from herostitcher.list, or overridden with arguments on the command line for manual runs
  • On the choice of tools:
    • avidemux has severe bugs (corrupted AVI files over 4GB, avidemux2_cli segfaulting)
    • mencoder was used in earlier versions but was dropped due to a bug (launchpad 1329145) with large AVI files
    • ffmpeg seems to slowly become the de facto tool, so it replaced mencoder, mplayer, mkvtoolnix, sox (which is now in ffmpeg) and audio encoders
    • The only thing I miss is mencoder’s easy, single stage, multiple input file processing, which is now done in three stages using named pipes instead
  • VirtualDub is the only way to use Deshaker 3.1, which is the best image stabilizer out there, so there is some ugly hacking around wine, paths and parallelism, please let me know if this can be done smarter!
  • VirtualDub in wine runs mostly well with vdub.exe, but if it crashes or hangs for you, switch to VirtualDub.exe instead although you will have the GUI popping up on you
  • x265 will be a likely upgrade when it matures and is part of distros and players (year 2018?)