Command line interface
=======================

``svgsequencevideo`` exposes four subcommands: :ref:`render <cli-render>` and
:ref:`video <cli-video>` for the two steps of the generation, plus
:ref:`inspect <cli-inspect>` and :ref:`init <cli-init>` as helpers. There is
no single command running both render and video: a render is expensive and
done once, while video is cheap and tuned repeatedly, so combining them
would not match the actual workflow (see :doc:`overview`).

Every option can also be set in a TOML configuration file passed with
``--config``; any option given on the command line overrides the value from
that file.

.. code-block:: console

  (venv) $ svgsequencevideo --help

.. _cli-render:

render
------

Reads an SVG file and exports one PNG frame per revealed element into
``--output-dir``, together with a ``metadata.json`` describing the drawing
(used by ``video`` and ``inspect``). This is the long-running step.

.. code-block:: console

  # Render at the SVG own size
  (venv) $ svgsequencevideo render drawing.svg

  # Render at a specific width, height inferred to keep the aspect ratio
  (venv) $ svgsequencevideo render drawing.svg --width 1920 --output-dir build/

  # Resume a render that was interrupted, only missing frames are regenerated
  (venv) $ svgsequencevideo render drawing.svg --resume

.. typer:: svgsequencevideo.cli:app:render
   :prog: svgsequencevideo render
   :width: 100
   :make-sections:

.. _cli-video:

video
-----

Builds the ``.mp4`` reveal video from the frames and metadata produced by a
previous ``render``. This is the step you will run again and again while
adjusting timing and reveal order, it does not touch the frames.

The reveal order/duration of each element is controlled by ``--heuristic``
(``equal``, ``area`` or ``complex``, see :class:`svgsequencevideo.Heuristic`
for writing a custom one) and can be fine-tuned per element with
``--weight``, repeated as many times as needed. A weight applies to a named
Inkscape layer/object label, or to a raw SVG id when prefixed with ``id:``.

.. code-block:: console

  # Default heuristic and timings
  (venv) $ svgsequencevideo video

  # Slower reveal, a layer revealed twice as fast, an id revealed 3x as fast
  (venv) $ svgsequencevideo video --revealduration 30 --weight "Foreground=2" --weight "id:path1234=3"

.. typer:: svgsequencevideo.cli:app:video
   :prog: svgsequencevideo video
   :width: 100
   :make-sections:

Heuristics
~~~~~~~~~~

The three built-in heuristics decide, for every element, how big a share of
the reveal duration it gets. Same drawing, same options, only the heuristic
changes:

Equal
^^^^^

Every element gets the same reveal time, regardless of its size or how many
shapes it groups. Best when every shape carries roughly the same visual
weight.

.. raw:: html

   <figure class="demo-video">
      <video width="480" loop muted playsinline controls>
      <source src="_static/puppyTmMoonlight_FABV_equal.mp4" type="video/mp4">
      Your browser does not support the video tag.
      </video>
   </figure>

Area
^^^^

Reveal time is proportional to the visible area of the element: large
shapes stay longer before the next element appears, small details flash by quickly.

.. raw:: html

   <figure class="demo-video">
      <video width="480" loop muted playsinline controls>
      <source src="_static/puppyTmMoonlight_FABV_area.mp4" type="video/mp4">
      Your browser does not support the video tag.
      </video>
   </figure>

Complex
^^^^^^^

The default. Balances object count and area on a logarithmic scale, so
neither a handful of huge shapes nor a swarm of tiny ones dominates the
timing. Gives the most natural-looking reveal in most cases.

.. raw:: html

   <figure class="demo-video">
      <video width="480" loop muted playsinline controls>
      <source src="_static/puppyTmMoonlight_FABV_complex.mp4" type="video/mp4">
      Your browser does not support the video tag.
      </video>
   </figure>

.. note::

  When used in the heuristic to compute the reveal time of each element, the computation of the area of an element does not take into account clipping.

.. _cli-inspect:

inspect
-------

Prints the element count, size and computed reveal order/timing, either for
an SVG file passed directly, or, if no file is given, for the metadata of a
previous render found in ``--cache-dir``/``--output-dir``. Nothing is ever
written to disk, so it is the safe way to preview how ``--heuristic`` and
``--weight`` will behave before running ``render`` or ``video``.

.. code-block:: console

  # Preview an SVG directly, without rendering it, only showing elements with an Inkscape label
  (venv) $ svgsequencevideo inspect drawing.svg --labels-only

  # Preview the reveal order that `video` would currently produce
  (venv) $ svgsequencevideo inspect --heuristic area

.. typer:: svgsequencevideo.cli:app:inspect
   :prog: svgsequencevideo inspect
   :width: 100
   :make-sections:

.. _cli-init:

init
----

Writes a default TOML configuration file, documenting every ``render`` and
``video`` option, to fill in and pass to ``--config``.

.. code-block:: console

  (venv) $ svgsequencevideo init --config svgsequencevideo.toml

.. typer:: svgsequencevideo.cli:app:init
   :prog: svgsequencevideo init
   :width: 100
   :make-sections: