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

*Main documentation on Read the Docs:* http://storyboard.rtfd.org

``storyboard`` is an `FFmpeg <https://ffmpeg.org/>`__-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:* http://storyboard.rtfd.org/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 asn 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:* http://storyboard.rtfd.org/en/latest/install.html

Dependencies
~~~~~~~~~~~~

-  `FFmpeg <https://ffmpeg.org/>`__. Check the `official downloads
   page <https://www.ffmpeg.org/download.html>`__ for installation
   options. On OS X you may install FFmpeg via
   `Homebrew <http://brew.sh>`__ or
   `MacPorts <https://www.macports.org/>`__. The former is recommended.

-  `Pillow <https://python-pillow.github.io/>`__. 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 <https://pillow.readthedocs.org/installation.html>`__ 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:* http://storyboard.rtfd.org/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:
   `metadat-cli.html <http://storyboard.rtfd.org/en/latest/metadata-cli.html>`__;
-  ``storyboard`` CLI reference:
   `storyboard-cli.html <http://storyboard.rtfd.org/en/latest/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:* http://storyboard.rtfd.org/en/latest/sample.html

|image10|

|image11|

Issues
------

*Main article:* http://storyboard.rtfd.org/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 <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/
.. |Supported Python implementations| image:: https://pypip.in/implementation/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/
.. |Docs| image:: https://readthedocs.org/projects/storyboard/badge/?version=latest
   :target: https://storyboard.readthedocs.org/
.. |Build Status| image:: https://travis-ci.org/zmwangx/storyboard.svg?branch=master
   :target: https://travis-ci.org/zmwangx/storyboard
.. |Windows Build Status| image:: https://ci.appveyor.com/api/projects/status/github/zmwangx/storyboard?branch=master&svg=true
   :target: https://ci.appveyor.com/project/zmwangx/storyboard
.. |Coverage Status| image:: https://coveralls.io/repos/zmwangx/storyboard/badge.svg?branch=master
   :target: https://coveralls.io/r/zmwangx/storyboard?branch=master
.. |Code Health| image:: https://landscape.io/github/zmwangx/storyboard/master/landscape.svg?style=flat
   :target: https://landscape.io/github/zmwangx/storyboard/master
.. |image10| image:: https://i.imgur.com/OIx20KQ.jpg
   :target: https://i.imgur.com/gtBArx7.jpg
.. |image11| image:: https://i.imgur.com/WB2N0Rh.jpg
   :target: https://i.imgur.com/Ujgsznc.jpg

Changelog
---------

0.1.03
~~~~~~

* More lenient Unicode decoder

0.1.02
~~~~~~

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

0.1.01
~~~~~~

* 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: http://storyboard.rtfd.org
* 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
  <https://storyboard.readthedocs.org/en/latest/cli.html>`_); 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
  <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
