Storyboard transforms your videos into other types of media.

Make a GIF of a favorite joke from a TV show, or make a book out of a movie you love. Starting with subtitles included in the video file or available online, Storyboard scans a video for scene changes and is able to put together a PDF that you can put onto your phone or e-reader, letting you read instead of watch. The Night of the Living Dead, made in 1968 and available in the public domain because of an oversight by the distributor, makes for a pretty good example of the sort of results you can get by using Storyboard.

You can download the 32MB PDF of the entire movie to read whenever you'd like.

Gifboard, another program included with Storyboard, can use those same subtitles to create a GIF based on a line of dialog in the video.


Storyboard is still early in development (check the changelog to see what's new or upcoming), and requires more involved setup than most programs. To run it, you should be comfortable using a terminal, and you must have Ruby 1.9.3, FFmpeg 1.1, and ImageMagick installed. For OS X, the INSTALL file has more step-by-step instructions, but if you've used homebrew before and can install Ruby on your own, all you have to do is update homebrew's recipes so that you know you're getting the latest version of FFmpeg.

brew update
brew install ffmpeg imagemagick ghostscript libtool

For linuxes, you can use your package manager to install Imagemagick, but you need to compile FFmpeg on your own until version 1.1 shows up in the repositories

tar xvf ffmpeg-1.1.1.tar.gz && cd ffmpeg-1.1.1
./configure && make && make install

Once you have those available, simply install the gem

gem install storyboard

Using Storyboard

Running Storyboard can be really simple:

$ storyboard "Night of the Living Dead (1968).avi"

Storyboard will first look for a file named Night of the Living Dead (1968).srt to use for subtitles, but if one doesn't exist, it will try and extract subtitles from the video, and if those don't exist, it will search online and present a list of subtitles to choose from

There are multiple subtitles that could work with this file. Please choose one!
1: 'NOTLD (1990) [Bassline]', added 2005-03-22
2: '', added 2009-12-28
3: 'Night of the Living Dead (1990).sub', added 2003-02-06
4: 'Night of the Living Dead (1990)', added 2008-02-14
5: 'night_of_the_living_dead_English.sub', added 2002-06-03

As it happens, "" is the one we want, because people are bad at naming things. Once it downloads and checks the subtitles, Storyboard will try to generate a file at "Night of the Living Dead (1968)pdf in the directory you ran Storyboard in.

To quickly test if the subtitles that are used look ok, you can use the --preview NUMBER option, which generates a PDF with as many pages as you specify. Storyboard skips scene detection when creating a preview, so you can see if the subtitles line up as quick as possible.

storyboard --preview 25 "Night of the Living Dead (1968).avi"

If it turns out that the subtitles are off by a few seconds, you can nudge them with the -n TIME option. This can be positive or negative, but right now if you make it too large it can cause Storyboard to throw an error. If you wanted to nudge the subtitles backward 2 seconds, and still get a preview, you could run the following

storyboard -n -2 --preview 10 "Night of the Living Dead (1968).avi"

If you have a subtitle file that you keep seperate from the video file, or you just don't follow the naming convention Storyboard expects right now, you can specify a file to use with the -s option.

storyboard -s "Night of the Living Dead (1968).avi"

You can see all the available options by using the help option:

storyboard -h

Using Gifboard

Gifboard has all the options that Storyboard uses, except for --preview, but with the addition of -t, which you use to search the subtitles. Any matches are shown along with the time that the line is spoken, and once selected, a GIF will be made containing only that bit of the video.

gifboard -t "wearing a cape" "Seinfeld 6x04.avi"

And then, after you choose which subtitle file to use,

Multiple matches found.. pick one!
1: he wearing a cape?
2:  I believe he is wearing a cape.
3:  Why was he wearing a cape?
4:  Was my father wearing a cape?
5:  They said you were with some guy
    who was wearing a cape.
6:  ...just because
    they're wearing a cape.
choice (default 1):

I will never claim to know what options and optimizations go into making a good GIF, and so the output for Gifboard is at a "good enough" point for me. If this is something you'd like to help improve, it would be very appreciated.


There are a lot of ways you can help improve Storyboard! If you're ambitious, you can write or fix up the code by forking the repository on github and submitting pull requests for your changes. I wrote a little bit more about the workings of Storyboard in a blog post, but more documentation could definitely help if that's more your thing.

Even just an email ( or tweet (@mark_olson) saying that it worked - or didn't - can be helpful.

Fork me on GitHub