Skip to main content

Customizable video storyboard generator with metadata report

Project description

Latest Version Supported Python versions Download format License Development Status Docs Build Status Windows Build Status Coverage Status Code Health

Main documentation on Read the Docs:

storyboard is a customizable video storyboard generator with metadata reporting directly embedded in the generated images, based on FFmpeg. Reported metadata fields include, but are not limited to, title, filename, file size, SHA-1 digest, container format, duration, pixel dimension, display aspect ratio (DAR), scan type (progressive, interlaced, or telecined), frame rate, and per-stream metadata (type, codec, profile, dimensions, bitrate, etc.). See the samples below to get a feel for storyboard’s capabilities.

Structure of this document

  • Sample storyboards
  • Background
  • Installation and dependencies
  • Command-line usage
  • Issues
  • License
  • Changelog

Sample storyboards

Generated from 0.1b1 with default settings (click for full resolution):


(Proprietary video by Apple, available from


(CC0 video by FSF, available from


storyboard was inspired by the storyboards I frequently see on video-sharing Internet forums, mostly generated by proprietary video players. Those storyboards come with video/file metadata bundled, which is a great all-in-one solution for video sharing, saving one the labor of typing multiple console commands, copying and pasting output, and worrying about the forum’s crappy formatting. However, I, for one, dislike proprietary players. Also, those storyboards are usually ugly and uninformative, using stupid fonts and lacking crucial information that hackers look for (e.g., hash). Therefore, here I present a customizable storyboard generator for hackers.

Installation and dependencies

Main article on Read the Docs:


  • FFmpeg. Check the official downloads page for installation options. On OS X you may install FFmpeg via Homebrew or MacPorts. The former is recommended.
  • Pillow. This dependency will be picked up by pip when you install storyboard, but you also have to satisfy the external dependencies, especially libjpeg and libfreetype. See the official installation guide for details. (Satisfying external dependencies is very important on Linux, where no wheel distribution is provided on PyPI.)


pip install storyboard

Command-line usage

Main article on Read the Docs:

This package installs two console scripts, metadata and storyboard. You may find documentation of both using the -h,--help option. Extensive documentation is also available:

By the way, the default invocation is really simple (for both): just supply one or more video paths.



Please report issues or browse a list of known issues at See “Known issues” for instructions on how to report issues related to an unknown codec.

Known issues

  • storyboard uses PIL.ImageFont from Pillow to draw text, which is rather primitive and only allows one font at a time (no fallback). The default font packaged is Source Code Pro Regular, which only draws its supported code points, and leave unknown code points as boxes. In particular, there is no CJK support, so CJK characters in video filenames won’t come out very nice.

    You can specify your own font file that covers (part of) CJK code points, but the catch is that you should really use fixed-width fonts (unless you want to blow up the beautiful formatting, in which case you might as well use a proprietary player to generate a storyboard that’s bad-looking inside out). It’s basically impossible to have a truly fixed-width font that mixes CJK glyphs with Latin glyths, since they are so different — CJK glyphs are intrinsically square-shaped. This is just a sad fact of life and there’s nothing we can do about it. Therefore, there’s no CJK support in ``storyboard`` (CJK characters won’t break storyboard — they just come out as boxes). Hopefully you’re using ASCII filenames anyway; if you’re not, you really should.

  • treats each codec separately, and the list of supported codecs is far from complete. If you encounter an audio/video/subtitle codec that triggers stupid output, please report an issue or open a pull request. If it’s not a commonly seen codec, please link to a sample video with the relevant codec (cut it short with FFmpeg if possible) so that I can inspect and test.

  • ffprobe might report the wrong duration for certain VOB or other videos, which screws up the whole thing. See #3. As a fallback, you can use the optional parameter video_duration to storyboard.storyboard.StoryBoard or storyboard.metadata.Video (see source files for extensive API doc).


This package comes with SourceCodePro-Regular.otf as the default font, which is subject to the license of the Source Code Pro font family. See LICENSE.txt for details.

Source code in this package is released under the MIT license.



Date: 2015-05-08

  • CLI overhaul (be sure to check out the CLI reference); the CLI is stable now
  • Greatly improved docs (not finished yet, will be completed before the soon-to-be-released 0.1)


Date: 2015-04-21

  • Completely refactored API (API is much more extensible now, and should be relatively stable from this point onward, at least until 0.1 stable)
  • Almost complete rewrite under the hood – everything should be much more robust now
  • Support more formats and codecs, improve handling of existing formats and codecs
  • Much better error handling in many places (e.g., when duration is unavailable, it is just marked as unavailable in the output, rather than throws)
  • Upped the game for several orders of maginitude on the doc side – now you can build beautiful autodocs (I’ve yet to construct the manual part of the docs, so I won’t release the docs to RTD or just yet)
  • Integrated with Travis (Ubuntu), AppVeyor (Windows), (web interface for coverage), and (Python code quality check – basically linter as a CI) to ensure code quality


Date: 2015-04-14

  • Improved error handling at various places
  • Wrote a test suite (and successfully tested on Ubuntu 14.04 LTS)


Date: 2015-04-11

  • Reimplement scan type detection (now much more robust, and able to detect telecine)
  • Tested on Windows 8.1, and fixed progress bar printing issue within cmd.exe and PowerShell (see #14)


Date: 2015-04-09

  • Print progress information to console
  • Version info included in banner


Date: 2015-04-05

  • Initial release

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for storyboard, version 0.1b2
Filename, size File type Python version Upload date Hashes
Filename, size storyboard-0.1b2-py2.py3-none-any.whl (98.9 kB) File type Wheel Python version py2.py3 Upload date Hashes View
Filename, size storyboard-0.1b2.tar.gz (97.3 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page