Metadata-Version: 1.1
Name: storyboard
Version: 0.1a2
Summary: Customizable video storyboard generator with metadata report
Home-page: https://github.com/zmwangx/storyboard
Author: Zhiming Wang
Author-email: zmwangx@gmail.com
License: MIT
Description: |Latest Version| |Supported Python versions| |Download format| |License|
        |Development Status|
        
        ``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 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 <https://github.com/zmwangx/storyboard/commit/58ba702>`__ with
        default settings (click for full resolution):
        
        |image5|
        
        (Proprietary video by Apple, available from
        http://podcasts.apple.com/apple_keynotes_1080p/2015/2015_mar_1080_cc.m4v.)
        
        |image6|
        
        (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/>`__, which will be
           automatically installed when one installs ``storyboard`` via ``pip``.
           However, be advised that **some features of Pillow depend on external
           non-Python libraries; in particular, the ``libjpeg`` and
           ``libfreetype`` dependencies are required for ``storyboard``.**
           Homebrew users are encouraged to install Pillow by
        
           ::
        
               brew tap homebrew/python
               brew install Pillow --with-python3
        
           (which automatically satisfies the ``libjpeg`` and ``libfreetype``
           dependencies) and non-Homebrew users are encouraged to `check
           dependencies <https://pillow.readthedocs.org/installation.html#external-libraries>`__
           manually.
        
        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:               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 <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.
        Please wait for ``storyboard`` to finish before trying to move or open
        the image.
        
        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 covered to some extent, but I
           haven't tested this on Windows yet, not even once, so don't be
           surprised if it doesn't work on Windows. Please report 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/
        .. |image5| image:: https://i.imgur.com/FEB56cq.jpg
           :target: http://i.imgur.com/9T2zM8R.jpg
        .. |image6| image:: http://i.imgur.com/f8J5ZRJ.jpg
           :target: http://i.imgur.com/l5nrxKD.jpg
        
        Changelog
        ---------
        
        0.1a2
        ~~~~~
        
        *Date: 2015-04-09*
        
        * Print progress information to console
        * Version info included in banner
        
        0.1a1
        ~~~~~
        
        *Date: 2015-04-05*
        
        * Initial release
        
Keywords: video storyboard metadata thumbnail ffmpeg
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.2
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Topic :: Multimedia :: Video
