|Latest Version| |Supported Python versions| |Download format| |License|
|Development Status| |Code Health|

``storyboard`` is a customizable video storyboard generator with
metadata reporting directly embedded in the generated images, based on
`FFmpeg <https://ffmpeg.org/>`__. 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
-  Dependencies
-  Installation
-  Command-line usage

   -  ``metadata``
   -  ``storyboard``

-  Reporting issues
-  Known issues
-  License
-  Changelog

Sample storyboards
------------------

Generated from
`58ba702 <https://github.com/zmwangx/storyboard/commit/58ba702>`__ with
default settings (click for full resolution):

|image6|

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

|image7|

(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 <https://ffmpeg.org/>`__, 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 <http://packages.ubuntu.com/vivid/ffmpeg>`__.

-  `Pillow <https://python-pillow.github.io/>`__. Python wheels of
   Pillow are provided for OS X and Windows on
   `PyPI <https://pypi.python.org/pypi/Pillow/>`__, 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 <https://pillow.readthedocs.org/installation.html>`__ 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 <http://podcasts.apple.com/apple_keynotes_1080p/2015/2015_mar_1080_cc.m4v>`__),

::

    Filename:               2015_mar_1080_cc.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 <https://gist.github.com/zmwangx/ee8986c2f0596f1ebbb0>`__).

``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 <https://github.com/zmwangx/storyboard/issues/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 <https://adobe-fonts.github.io/source-code-pro/>`__. See
``LICENSE.txt`` for details.

Source code in this package is released under `the MIT
license <http://opensource.org/licenses/MIT>`__.

.. |Latest Version| image:: https://pypip.in/version/storyboard/badge.svg
   :target: https://pypi.python.org/pypi/storyboard/
.. |Supported Python versions| image:: https://pypip.in/py_versions/storyboard/badge.svg
   :target: https://pypi.python.org/pypi/storyboard/
.. |Download format| image:: https://pypip.in/format/storyboard/badge.svg
   :target: https://pypi.python.org/pypi/storyboard/
.. |License| image:: https://pypip.in/license/storyboard/badge.svg
   :target: https://pypi.python.org/pypi/storyboard/
.. |Development Status| image:: https://pypip.in/status/storyboard/badge.svg
   :target: https://pypi.python.org/pypi/storyboard/
.. |Code Health| image:: https://landscape.io/github/zmwangx/storyboard/master/landscape.svg?style=flat
   :target: https://landscape.io/github/zmwangx/storyboard/master
.. |image6| image:: https://i.imgur.com/FEB56cq.jpg
   :target: http://i.imgur.com/9T2zM8R.jpg
.. |image7| image:: http://i.imgur.com/f8J5ZRJ.jpg
   :target: http://i.imgur.com/l5nrxKD.jpg

Changelog
---------

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
  <https://github.com/zmwangx/storyboard/issues/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
