storyboard 0.1a3

Customizable video storyboard generator with metadata report

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 or interlaced), 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

• Dependencies

• Installation

• Command-line usage

  • metadata

  • storyboard

• Reporting issues

• Known issues

• License

• Changelog

Sample storyboards

Generated from 58ba702 with default settings (click for full resolution):

(Proprietary video by Apple, available from http://podcasts.apple.com/apple_keynotes_1080p/2015/2015_mar_1080_cc.m4v.)

(CC0 video by FSF, available from https://static.fsf.org/nosvn/FSF30-video/FSF_30_video.ogv.)

Background

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.

Dependencies

• FFmpeg, specifically ffmpeg and ffprobe. Homebrew users can install FFmpeg with

  brew install ffmpeg

  Be sure to review the list of options in brew info ffmpeg first. storyboard should not depend on any of the options to function, but FFmpeg is a great tool in its own right (several orders of magnitude greater than storyboard), so you might want to link against optional libraries to your own benefit.

  Unfortunately, avconv and avprobe have incompatible interfaces with their FFmpeg counterparts, so there is no plan to support Libav. Fortunately, FFmpeg is making its come back to Ubuntu in 15.04 vivid.

• Pillow. Python Wheels of Pillow are provided for OS X and Windows on PyPI, so it is usually enough to simply

  pip install Pillow

  However, it is recommended that you also satisfy the external dependencies, especially libjpeg and libfreetype, on OS X and Linux. See the official installation guide for details.

Installation

pip install storyboard

Make sure you satisfy the FFmpeg dependency and external library dependencies of Pillow, e.g., libjpeg and libfreetype.

Note that prereleases need to be installed with the --pre option, so be sure to try pip install --pre storyboard if the above fails.

Command-line usage

The package installs two console scripts, metadata and storyboard. Usage of both scripts can be found using the -h,--help option. Note that CLIs are currently extremely primitive. To generate customized storyboards, one needs to write one’s own wrapper around the API (which is well-documented in the source code). I plan to improve the CLI in future releases and expose more features.

metadata

metadata prints video metadata in a human-readable format, e.g. (for this video),

Filename:               20150309-apple-special-event__c343d40.m4v
File size:              6083965352 (5.67GiB)
Container format:       MPEG-4 Part 14 (M4V)
Duration:               01:34:45.27
Pixel dimensions:       1920x1080
Display aspect ratio:   16:9
Scan type:              Progressive scan
Frame rate:             29.97 fps
Streams:
#0: Audio (eng), AAC (Low Complexity), 99 kb/s
#1: Video, H.264 (Main Profile level 4.1), 1920x1080 (DAR 16:9), 29.97 fps, 8453 kb/s
#2: Subtitle (eng), closed caption (EIA-608 / CEA-708)

which is a good alternative to ffprobe’s basic functionality. Compare this to the mess that ffprobe -hide_banner prints (see this gist).

storyboard

Currently, storyboard prints the path of the generated image to the console, which by default resides in one’s $TMPDIR. One can then move it to a permanent place, or upload it to a image hosting site.

Reporting issues

Please report issues or browse a list of known issues at https://github.com/zmwangx/storyboard/issues. See “Known issues” for instructions on how to report issues related to an unknown codec.

Known issues

• Windows support is planned and already tested to some extent, but testing is limited since unlike OS X, Windows is not my primary platform. Please report any issue in the issue tracker — that’s very much appreciated.

• 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.

• metadata.py 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. This will be addressed later. See #3.

License

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.

Changelog

0.1a3

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)

0.1a2

Date: 2015-04-09

• Print progress information to console

• Version info included in banner

0.1a1

Date: 2015-04-05

• Initial release