Command line interface

svgsequencevideo exposes four subcommands: render and video for the two steps of the generation, plus inspect and 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 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.

(venv) $ svgsequencevideo --help

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.

# 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

svgsequencevideo render

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 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:.

# 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"

svgsequencevideo video

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.

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.

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.

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.

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.

# 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

svgsequencevideo inspect

init

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

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