storyboard 0.1.9

Customizable video storyboard generator with metadata report

Main documentation on Read the Docs: https://storyboard.readthedocs.io

Caution: Development has been deferred indefinitely as of July 23, 2015. However, contributions are welcome, and the maintainer will review pull requests in a timely manner.

storyboard is an FFmpeg-based customizable video storyboard generator with metadata reporting directly embedded in the generated images. 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.). Scroll down for a few sample storyboards.

Note that this README only provides an overview and summary of the topics listed below. For more details, follow the main article link in each section.

Structure of this document

• Background

• Installation and dependencies

• Command-line usage

• Sample storyboards

• Issues

• License

• Changelog

Background

Main article: https://storyboard.readthedocs.io/en/latest/index.html

storyboard was inspired by the storyboards I frequently encounter on video-sharing Internet forums, mostly generated by proprietary video players. Those storyboards often come with video/file metadata bundled, which I see as 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, I developed this customizable storyboard generator for hackers.

Installation and dependencies

Main article: https://storyboard.readthedocs.io/en/latest/install.html

Dependencies

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

Installation

End users should use pip:

pip install storyboard

Developers should clone the git repo for docs, tests, and more.

Command-line usage

Main article: https://storyboard.readthedocs.io/en/latest/cli.html

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 for both:

• metadata CLI reference: metadata-cli.html;

• storyboard CLI reference: storyboard-cli.html.

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

Sample storyboards

Main article: https://storyboard.readthedocs.io/en/latest/sample.html

Issues

Main article: https://storyboard.readthedocs.io/en/latest/issue.html

Reporting

Please use the GitHub issue tracker: https://github.com/zmwangx/storyboard/issues.

Known issues

• CJK support in filename and title? In short, no.

• Found a codec you need that has no binding in metadata.py and leads to stupid output? File an issue or open a pull request. Please link a sample file if it is not commonly seen and cannot be encoded by FFmpeg.

• ffprobe might report the wrong duration for certain VOB or other videos, which screws up the whole thing. As a fallback, you can use the option --video-duration of storyboard. Note however that this option is extremely slow, and improving it is on my list.

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

Date: 2017-10-29

• Add audio sample rate and channel layout to metadata.

0.1.8

Date: 2017-07-25

• Support Pillow 4.2.0+.

0.1.7

Date: 2017-04-09

• Add total bit rate field to metadata.

0.1.6

Date: 2017-03-19

• Upcase SHA-1 checksum in metadata;

• Add more codecs.

0.1.05

Date: 2016-02-14

• Support metadata tag TITLE;

• Refresh badges;

• Add notice about ceased development.

0.1.04

Date: 2015-06-14

• Better link to the project: git.io/storyboard

0.1.03

Date: 2015-05-20

• More lenient Unicode decoder

0.1.02

Date: 2015-05-10

• Added CPython classifier to metadata (previously I added the PyPy classifier but took CPython for granted)

0.1.01

Date: 2015-05-10

• Officially added support for PyPy2 and PyPy3 (although PyPy, especially PyPy2, is slower than CPython in this case)

• A few extremely minor bug fixes and improvements; nothing changed from a user’s perspective

0.1

Date: 2015-05-08

Hey, the stable is here!

• Completed documentation: https://storyboard.readthedocs.io

• Added --include-sha1sum option to console script storyboard (useful when SHA-1 digest is disabled from config file)

• Fixed frame extraction when video duration is missing or wrong in container metadata

0.1b2

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)

0.1b1

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 pythonhosted.org just yet)

• Integrated with Travis (Ubuntu), AppVeyor (Windows), Coveralls.io (web interface for coverage), and Landscape.io (Python code quality check – basically linter as a CI) to ensure code quality

0.1a4

Date: 2015-04-14

• Improved error handling at various places

• Wrote a test suite (and successfully tested on Ubuntu 14.04 LTS)

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