Overview
========

What is *svgsequencevideo*?
----------------------------

**svgsequencevideo** turns a static SVG drawing into a "reveal" video: every
shape appears one after another, in the order it is drawn in the SVG, as if
the artwork were being drawn live.

.. raw:: html

   <figure class="demo-video">
     <video width="480" autoplay loop muted playsinline controls>
       <source src="_static/puppyTmMoonlight_FABV.mp4" type="video/mp4">
       Your browser does not support the video tag.
     </video>
     <figcaption>
       Progressive reveal of an SVG illustration generated by svgsequencevideo.
     </figcaption>
   </figure>

It ships as a command line tool, ``svgsequencevideo``, and as a Python
library for anyone who wants to script the generation or plug in a custom
reveal heuristic.

Under the hood, `Inkscape <https://inkscape.org/>`_ exports the frames and
`FFmpeg <https://ffmpeg.org/>`_ assembles the video, so both must be
installed and reachable (in ``PATH``, in one of their usual install
locations, or configured explicitly, see :doc:`cli`).

Getting started
----------------

.. code-block:: console

  (venv) $ pip install svgsequencevideo

Typical workflow
-----------------

Generating a video is split into two independent steps:

1. :ref:`render <cli-render>` the SVG into a sequence of PNG frames. This is
   the slow part: from a few seconds to a few hours depending on the file
   and the export resolution.
2. :ref:`video <cli-video>` assembles those frames into an ``.mp4``,
   applying the reveal timing, heuristic and styling options. This is fast,
   so it is meant to be run many times while you tune the result.

.. code-block:: console

  (venv) $ svgsequencevideo render drawing.svg --width 1920
  (venv) $ svgsequencevideo video --revealduration 15 --heuristic complex

Use :ref:`inspect <cli-inspect>` at any point to preview the element count,
size and reveal order without writing anything to disk, which is the
quickest way to check how a heuristic or a ``--weight`` will behave before
spending time on a render or a video:

.. code-block:: console

  (venv) $ svgsequencevideo inspect drawing.svg

See :doc:`cli` for the full command reference, or :doc:`api` to drive
``svgsequencevideo`` from Python.